cloud-dog-api-kit 0.13.0__py3-none-any.whl

cloud_dog_api_kit/mcp/contract.py

@@ -0,0 +1,113 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — MCP contract registration helper
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: One-call registration helper enforcing MCP catalogue contract.
+# Related requirements: FR18.1
+# Related architecture: SA1
+
+"""MCP contract registration helper.
+
+Provides a single entry point that registers:
+- MCP transport routes (`/mcp`, `/messages`)
+- MCP tool catalogue + execution routes (`/mcp/tools`, `/mcp/tools/{tool_name}`)
+- Optional legacy read-only catalogue alias (`/tools`)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import FastAPI
+
+from cloud_dog_api_kit.mcp.session import McpSessionManager
+from cloud_dog_api_kit.mcp.tool_router import ToolContract, ToolRegistryType, register_tool_router
+from cloud_dog_api_kit.mcp.transport import register_mcp_routes
+
+
+@dataclass(slots=True)
+class MCPContractRegistration:
+    """Captured outputs from MCP contract registration."""
+
+    contracts: dict[str, ToolContract]
+    session_manager: McpSessionManager
+
+
+def _catalogue_payload(contracts: dict[str, ToolContract]) -> dict[str, list[dict[str, Any]]]:
+    return {
+        "tools": [
+            {
+                "name": contract.name,
+                "description": contract.description,
+                "input_schema": contract.input_schema,
+                "output_schema": contract.output_schema,
+            }
+            for contract in contracts.values()
+        ]
+    }
+
+
+def register_mcp_contract(
+    app: FastAPI,
+    tool_registry: ToolRegistryType | None,
+    transport_modes: list[str] | set[str] | tuple[str, ...] | None = None,
+    *,
+    include_legacy_tools_alias: bool = True,
+    legacy_tools_path: str = "/tools",
+    mcp_tools_path: str = "/mcp/tools",
+    session_manager: McpSessionManager | None = None,
+    transport_base_path: str | None = None,
+    transport_messages_path: str | None = None,
+) -> MCPContractRegistration:
+    """Register a complete MCP surface with canonical tool catalogue contract.
+
+    Canonical contract:
+    - `GET /mcp/tools` returns tool catalogue (required)
+    - `POST /mcp/tools/{tool_name}` executes a tool
+    - `POST /mcp` and `POST /messages` provide MCP transport compatibility
+
+    Optional compatibility:
+    - `GET /tools` read-only alias for catalogue payload
+
+    Route threading:
+    - `mcp_tools_path` controls the REST catalogue/tool surface
+    - `transport_base_path` and `transport_messages_path` control the MCP
+      transport registration forwarded into `register_mcp_routes(...)`
+    """
+
+    contracts = register_tool_router(app, tool_registry, base_path=mcp_tools_path)
+    manager = register_mcp_routes(
+        app,
+        contracts,
+        transport_modes=transport_modes,
+        session_manager=session_manager,
+        transport_base_path=transport_base_path,
+        transport_messages_path=transport_messages_path,
+    )
+
+    if include_legacy_tools_alias:
+        if not legacy_tools_path.startswith("/"):
+            raise ValueError("legacy_tools_path must start with '/'")
+        if legacy_tools_path == mcp_tools_path:
+            raise ValueError("legacy_tools_path must differ from mcp_tools_path")
+
+        @app.get(legacy_tools_path, tags=["mcp"])
+        async def _legacy_tools_alias() -> dict[str, list[dict[str, Any]]]:
+            return _catalogue_payload(contracts)
+
+    return MCPContractRegistration(contracts=contracts, session_manager=manager)

cloud_dog_api_kit/mcp/error_mapper.py

@@ -0,0 +1,84 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Legacy MCP error mapper
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Compatibility mapper for legacy MCP payloads that do not use
+#   standard PS-20 success/error envelopes.
+# Related requirements: FR18.1
+# Related architecture: SA1
+
+"""Legacy MCP payload mapping utilities."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cloud_dog_api_kit.envelopes import error_envelope, success_envelope
+
+
+def map_legacy_mcp_payload(
+    payload: Any,
+    *,
+    request_id: str = "",
+    correlation_id: str | None = None,
+) -> dict[str, Any]:
+    """Map legacy MCP payload shapes to standard envelopes."""
+    if isinstance(payload, dict) and "ok" in payload and ("data" in payload or "error" in payload):
+        mapped = dict(payload)
+        meta = dict(mapped.get("meta") or {})
+        meta.setdefault("request_id", request_id)
+        if correlation_id is not None:
+            meta.setdefault("correlation_id", correlation_id)
+        mapped["meta"] = meta
+        return mapped
+
+    if isinstance(payload, dict):
+        if payload.get("success") is False:
+            return error_envelope(
+                code=str(payload.get("code", "INTERNAL_ERROR")),
+                message=str(payload.get("message", "Request failed")),
+                details=payload.get("details"),
+                retryable=bool(payload.get("retryable", False)),
+                request_id=request_id,
+                correlation_id=correlation_id,
+            )
+        if "error" in payload:
+            error_value = payload.get("error")
+            if isinstance(error_value, dict):
+                code = str(error_value.get("code", payload.get("code", "INTERNAL_ERROR")))
+                message = str(error_value.get("message", payload.get("message", "Request failed")))
+                details = error_value.get("details", payload.get("details"))
+                retryable = bool(error_value.get("retryable", payload.get("retryable", False)))
+            else:
+                code = str(payload.get("code", "INTERNAL_ERROR"))
+                message = str(error_value)
+                details = payload.get("details")
+                retryable = bool(payload.get("retryable", False))
+            return error_envelope(
+                code=code,
+                message=message,
+                details=details,
+                retryable=retryable,
+                request_id=request_id,
+                correlation_id=correlation_id,
+            )
+
+    return success_envelope(
+        data=payload,
+        request_id=request_id,
+        correlation_id=correlation_id,
+    )

cloud_dog_api_kit/mcp/gateway.py

@@ -0,0 +1,117 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — MCP gateway helpers
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Helpers for mapping REST endpoints to MCP tool definitions.
+#   MCP tools MUST map directly to REST endpoints and share schemas.
+# Related requirements: FR14.1
+# Related architecture: CC1.18
+
+"""MCP gateway helpers for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class MCPToolDefinition:
+    """MCP tool definition mapped from a REST endpoint.
+
+    Attributes:
+        name: The tool name (derived from endpoint path).
+        description: Human-readable description.
+        endpoint_path: The REST endpoint path this tool maps to.
+        method: HTTP method. Defaults to ``POST``.
+        input_schema: JSON Schema for the tool's input parameters.
+        output_schema: JSON Schema for the tool's output.
+
+    Related tests: UT1.32_MCPGateway
+    """
+
+    name: str
+    description: str
+    endpoint_path: str
+    method: str = "POST"
+    input_schema: dict[str, Any] = field(default_factory=dict)
+    output_schema: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to a dictionary suitable for MCP tool registration.
+
+        MCP spec 2024-11-05: `outputSchema` is optional on tool definitions.
+        Emitting an empty `{}` forces strict MCP clients to expect
+        `structuredContent` in every tool-call response, which breaks
+        interoperability with tools that return plain text content only.
+        We therefore only emit `outputSchema` when a non-empty schema is
+        declared. See RF-02-F1 / W28A-RF-F1-APPLY.
+
+        Returns:
+            A dictionary with the tool definition.
+        """
+        payload: dict[str, Any] = {
+            "name": self.name,
+            "description": self.description,
+            "inputSchema": self.input_schema,
+        }
+        if self.output_schema:
+            payload["outputSchema"] = self.output_schema
+        return payload
+
+
+def create_mcp_tool_from_endpoint(
+    endpoint_path: str,
+    method: str = "POST",
+    description: str = "",
+    name: str | None = None,
+    input_schema: dict[str, Any] | None = None,
+    output_schema: dict[str, Any] | None = None,
+) -> MCPToolDefinition:
+    """Create an MCP tool definition from a REST endpoint.
+
+    The tool name is derived from the endpoint path if not provided
+    (e.g., ``/api/v1/users`` becomes ``users``).
+
+    Args:
+        endpoint_path: The REST endpoint path.
+        method: HTTP method. Defaults to ``POST``.
+        description: Tool description.
+        name: Override tool name. Derived from path if None.
+        input_schema: JSON Schema for inputs.
+        output_schema: JSON Schema for outputs.
+
+    Returns:
+        An MCPToolDefinition instance.
+
+    Related tests: UT1.32_MCPGateway
+    """
+    if name is None:
+        # Derive name from path: /api/v1/users/{id}:run -> users_run
+        parts = endpoint_path.strip("/").split("/")
+        # Skip version prefix
+        filtered = [p for p in parts if not p.startswith("{") and p not in ("api", "v1", "v2")]
+        name = "_".join(filtered).replace(":", "_")
+
+    return MCPToolDefinition(
+        name=name,
+        description=description,
+        endpoint_path=endpoint_path,
+        method=method,
+        input_schema=input_schema or {},
+        output_schema=output_schema or {},
+    )

cloud_dog_api_kit/mcp/legacy_sse.py

@@ -0,0 +1,129 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — MCP legacy SSE server helpers
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Legacy SSE server-side transport helpers for `/sse` + `/message`
+#   compatibility routes.
+# Related requirements: FR18.1
+# Related architecture: SA1
+
+"""Legacy SSE server helpers for MCP compatibility routes."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from cloud_dog_api_kit.mcp.session import SESSION_HEADER
+
+
+@dataclass
+class LegacySSEConfig:
+    """Configuration for server-side legacy SSE MCP compatibility routes.
+
+    The dataclass also keeps the common client-side fields so
+    `from cloud_dog_api_kit.mcp import LegacySSEConfig` remains useful for code
+    that pairs the root import with `LegacySSETransport`.
+    """
+
+    base_url: str = ""
+    sse_path: str = "/sse"
+    message_path: str = "/message"
+    messages_path: str = "/message"
+    session_header: str = SESSION_HEADER
+    api_key_header: str | None = None
+    api_key: str | None = None
+    accept_header: str | None = None
+    auth_bearer_token: str | None = None
+    protocol_version: str | None = None
+    timeout_seconds: float = 30.0
+    verify_tls: bool = True
+
+    def __post_init__(self) -> None:
+        self.sse_path = _normalise_path(self.sse_path, "/sse")
+        self.message_path = _normalise_path(self.message_path or self.messages_path, "/message")
+        self.messages_path = _normalise_path(self.messages_path or self.message_path, "/message")
+        self.session_header = str(self.session_header or SESSION_HEADER).strip() or SESSION_HEADER
+
+
+def _normalise_path(value: str | None, default: str) -> str:
+    raw = str(value or "").strip() or default
+    if not raw.startswith("/"):
+        return f"/{raw}"
+    return raw
+
+
+class LegacySSEBroker:
+    """Queue-backed broker for legacy SSE bootstrap and message delivery."""
+
+    def __init__(self, config: LegacySSEConfig) -> None:
+        self._config = config
+        self._queues: dict[str, asyncio.Queue[dict[str, Any]]] = {}
+        self._lock = asyncio.Lock()
+
+    async def open_session(self, session_id: str) -> asyncio.Queue[dict[str, Any]]:
+        """Create or reuse the queue for a legacy SSE session."""
+        async with self._lock:
+            queue = self._queues.get(session_id)
+            if queue is None:
+                queue = asyncio.Queue()
+                self._queues[session_id] = queue
+            return queue
+
+    async def push(self, session_id: str, payload: dict[str, Any]) -> bool:
+        """Push a JSON payload to an active legacy SSE stream."""
+        async with self._lock:
+            queue = self._queues.get(session_id)
+        if queue is None:
+            return False
+        await queue.put(dict(payload))
+        return True
+
+    async def close_session(self, session_id: str) -> None:
+        """Remove a legacy SSE session queue."""
+        async with self._lock:
+            self._queues.pop(session_id, None)
+
+    def bootstrap_payload(self, session_id: str) -> dict[str, Any]:
+        """Build the bootstrap payload sent on first SSE connect."""
+        endpoint = f"{self._config.message_path}?session_id={session_id}&sessionId={session_id}"
+        return {
+            "endpoint": endpoint,
+            "path": endpoint,
+            "messages_path": self._config.message_path,
+            "session_id": session_id,
+            "sessionId": session_id,
+        }
+
+    async def event_stream(self, request: Any, session_id: str) -> Any:
+        """Yield the bootstrap event and subsequent message events."""
+        queue = await self.open_session(session_id)
+        bootstrap = self.bootstrap_payload(session_id)
+        yield f"event: endpoint\ndata: {json.dumps(bootstrap, ensure_ascii=True)}\n\n"
+        try:
+            while True:
+                if hasattr(request, "is_disconnected") and await request.is_disconnected():
+                    break
+                try:
+                    payload = await asyncio.wait_for(queue.get(), timeout=0.25)
+                except asyncio.TimeoutError:
+                    continue
+                yield f"event: message\ndata: {json.dumps(payload, ensure_ascii=True)}\n\n"
+        finally:
+            await self.close_session(session_id)

cloud_dog_api_kit/mcp/session.py

@@ -0,0 +1,96 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — MCP session lifecycle
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Lightweight in-memory MCP session manager with create/resume/
+#   delete semantics for Mcp-Session-Id handling.
+# Related requirements: FR18.5
+# Related architecture: SA1
+
+"""MCP session lifecycle support."""
+
+from __future__ import annotations
+
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+SESSION_HEADER = "Mcp-Session-Id"
+
+
+@dataclass(slots=True)
+class McpSession:
+    """In-memory MCP session state."""
+
+    session_id: str
+    created_at: float
+    last_seen_at: float
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class McpSessionManager:
+    """Manage in-memory MCP sessions.
+
+    Related tests: UT1.41_MCPSessionLifecycle
+    """
+
+    def __init__(self, clock: Callable[[], float] | None = None) -> None:
+        self._clock = clock or time.time
+        self._lock = threading.Lock()
+        self._sessions: dict[str, McpSession] = {}
+
+    def create(self) -> McpSession:
+        """Create a new session."""
+        now = self._clock()
+        session = McpSession(session_id=uuid.uuid4().hex, created_at=now, last_seen_at=now)
+        with self._lock:
+            self._sessions[session.session_id] = session
+        return session
+
+    def resume(self, session_id: str) -> McpSession | None:
+        """Resume an existing session by ID."""
+        with self._lock:
+            session = self._sessions.get(session_id)
+            if session is None:
+                return None
+            session.last_seen_at = self._clock()
+            return session
+
+    def ensure(self, session_id: str | None) -> tuple[McpSession, bool]:
+        """Get an existing session or create a new one.
+
+        Returns:
+            Tuple of (session, created_new).
+        """
+        if session_id:
+            resumed = self.resume(session_id)
+            if resumed is not None:
+                return resumed, False
+        created = self.create()
+        return created, True
+
+    def delete(self, session_id: str) -> bool:
+        """Delete a session by ID."""
+        with self._lock:
+            return self._sessions.pop(session_id, None) is not None
+
+    def exists(self, session_id: str) -> bool:
+        """Check if a session exists."""
+        with self._lock:
+            return session_id in self._sessions