fix(mcp): tag legacy provider calls with audit context

apps/api/src/services/mcp_audit_context.py

@@ -0,0 +1,49 @@
+"""MCP audit context helpers.
+
+Legacy production callers still use the provider registry directly while
+AwoooP MCP Gateway is rolled in by lane. These helpers make those calls
+observable without changing execution semantics.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_mcp_audit_context(
+    *,
+    session_id: str | None = None,
+    incident_id: str | None = None,
+    flywheel_node: str | None = None,
+    agent_role: str | None = None,
+    gateway_path: str = "legacy_registry_provider",
+    operator_user_id: int | str | None = None,
+) -> dict[str, Any]:
+    """Build the `_mcp_audit` metadata object carried beside tool params."""
+
+    context: dict[str, Any] = {
+        "gateway_path": gateway_path,
+    }
+    optional_values = {
+        "session_id": session_id,
+        "incident_id": incident_id,
+        "flywheel_node": flywheel_node,
+        "agent_role": agent_role,
+        "operator_user_id": operator_user_id,
+    }
+    context.update({key: value for key, value in optional_values.items() if value is not None})
+    return context
+
+
+def with_mcp_audit_context(
+    parameters: dict[str, Any],
+    **audit_kwargs: Any,
+) -> dict[str, Any]:
+    """Return a shallow copy of provider parameters with merged audit context."""
+
+    audited = dict(parameters)
+    existing = audited.get("_mcp_audit")
+    merged = dict(existing) if isinstance(existing, dict) else {}
+    merged.update(build_mcp_audit_context(**audit_kwargs))
+    audited["_mcp_audit"] = merged
+    return audited