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

cloud_dog_api_kit/mcp/sync_handler.py

@@ -0,0 +1,269 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+# SPDX-License-Identifier: Apache-2.0
+"""PS-95 three-mode sync_class handler for MCP tool dispatch.
+
+Mode 1 (sync-default):
+    Submit to jobs queue, block until complete or sync_budget exhausted.
+    If budget exhausted, return error with job_id for recovery.
+
+Mode 2 (sync-with-progress):
+    Submit to jobs queue, stream MCP progress notifications, return result.
+    Falls back to Mode 1 for clients without progressToken support.
+
+Mode 3 (async-only):
+    Return job_id immediately. Client must poll via jobs/get.
+    Every external async-only tool MUST have a _blocking sibling.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Awaitable, Callable
+
+from cloud_dog_api_kit.mcp.tool_router import (
+    DEFAULT_SYNC_BUDGET_SECONDS,
+    MAX_SYNC_BUDGET_SECONDS,
+    SYNC_CLASS_ASYNC,
+    SYNC_CLASS_DEFAULT,
+    SYNC_CLASS_PROGRESS,
+    ToolContract,
+)
+
+# JSON-RPC error code for budget exceeded (PS-95 §5.4)
+BUDGET_EXCEEDED_CODE = -32000
+
+
+def validate_blocking_siblings(contracts: dict[str, ToolContract]) -> list[str]:
+    """Validate that every async-only tool has a mandatory _blocking sibling.
+
+    PS-95 §2 Mode 3: "Every external-facing async-only tool MUST have a
+    <tool>_blocking sibling (Mode 1 wrapper that submits and polls internally)."
+
+    Returns a list of error messages for missing siblings. Empty = valid.
+    """
+    errors: list[str] = []
+    for name, contract in contracts.items():
+        if contract.sync_class != SYNC_CLASS_ASYNC:
+            continue
+        # async-only tools ending in _async need a _async_blocking sibling
+        if name.endswith("_async"):
+            blocking_name = f"{name}_blocking"
+        else:
+            blocking_name = f"{name}_blocking"
+        if blocking_name not in contracts:
+            errors.append(
+                f"Tool {name!r} is sync_class=async-only but missing mandatory "
+                f"blocking sibling {blocking_name!r} (PS-95 §2 Mode 3)"
+            )
+    return errors
+
+
+async def dispatch_with_sync_class(
+    contract: ToolContract,
+    runner: Callable[[], Any],
+    *,
+    async_job_store: Any | None = None,
+    tool_name: str = "",
+    arguments: dict[str, Any] | None = None,
+    context: dict[str, Any] | None = None,
+    client_supports_progress: bool = False,
+    progress_callback: Callable[[float, float | None, str | None], Awaitable[None]] | None = None,
+) -> dict[str, Any]:
+    """Dispatch a tool call according to its sync_class.
+
+    Returns a dict with either:
+        {"mode": "sync", "result": <tool_result>}
+        {"mode": "async", "job_id": <id>, "status": "submitted"}
+        {"mode": "budget_exceeded", "job_id": <id>, "status": "running"}
+    """
+    sc = contract.sync_class
+    name = tool_name or contract.name
+    args = arguments or {}
+
+    if sc == SYNC_CLASS_ASYNC:
+        return await _dispatch_async(contract, runner, async_job_store, name, args, context)
+
+    if sc == SYNC_CLASS_PROGRESS and client_supports_progress and progress_callback:
+        return await _dispatch_with_progress(contract, runner, async_job_store, name, args, context, progress_callback)
+
+    # Mode 1: sync-default (also Mode 2 fallback for non-progress clients)
+    return await _dispatch_sync_default(contract, runner, async_job_store, name, args, context)
+
+
+async def _dispatch_sync_default(
+    contract: ToolContract,
+    runner: Callable[[], Any],
+    async_job_store: Any | None,
+    tool_name: str,
+    arguments: dict[str, Any],
+    context: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """Mode 1: submit and block within sync_budget."""
+    budget = min(contract.sync_budget_seconds, MAX_SYNC_BUDGET_SECONDS)
+
+    if async_job_store is None:
+        # No job store — run inline with timeout
+        try:
+            result = await asyncio.wait_for(_run(runner), timeout=budget)
+            return {"mode": "sync", "result": result}
+        except asyncio.TimeoutError:
+            return {
+                "mode": "budget_exceeded",
+                "error": {
+                    "code": BUDGET_EXCEEDED_CODE,
+                    "message": f"Tool exceeded sync budget ({budget}s). No job store configured.",
+                    "data": {"tool_name": tool_name, "budget_seconds": budget},
+                },
+            }
+
+    # Submit to job store, then poll until budget
+    job_id = _submit_to_store(async_job_store, tool_name, arguments, context, runner)
+    start = time.monotonic()
+    while (time.monotonic() - start) < budget:
+        status = _get_store_status(async_job_store, job_id)
+        s = status.get("status", "")
+        if s == "completed":
+            return {"mode": "sync", "result": status.get("result")}
+        if s == "failed":
+            return {"mode": "sync", "result": status}
+        await asyncio.sleep(0.1)
+
+    # Budget exhausted — job still running
+    return {
+        "mode": "budget_exceeded",
+        "job_id": job_id,
+        "status": "running",
+        "error": {
+            "code": BUDGET_EXCEEDED_CODE,
+            "message": f"Tool exceeded sync budget ({budget}s). Job is still running.",
+            "data": {"job_id": job_id, "status": "running", "poll_url": f"/api/v1/jobs/{job_id}"},
+        },
+    }
+
+
+async def _dispatch_with_progress(
+    contract: ToolContract,
+    runner: Callable[[], Any],
+    async_job_store: Any | None,
+    tool_name: str,
+    arguments: dict[str, Any],
+    context: dict[str, Any] | None,
+    progress_callback: Callable[[float, float | None, str | None], Awaitable[None]],
+) -> dict[str, Any]:
+    """Mode 2: run with progress notifications."""
+    if async_job_store is None:
+        # Run inline, emit progress at start/end
+        await progress_callback(0.0, 1.0, f"Starting {tool_name}")
+        result = await _run(runner)
+        await progress_callback(1.0, 1.0, f"Completed {tool_name}")
+        return {"mode": "sync", "result": result}
+
+    job_id = _submit_to_store(async_job_store, tool_name, arguments, context, runner)
+    await progress_callback(0.0, None, f"Submitted {tool_name} as {job_id}")
+
+    poll_count = 0
+    while True:
+        status = _get_store_status(async_job_store, job_id)
+        s = status.get("status", "")
+        if s == "completed":
+            await progress_callback(1.0, 1.0, "Completed")
+            return {"mode": "sync", "result": status.get("result")}
+        if s == "failed":
+            await progress_callback(1.0, 1.0, "Failed")
+            return {"mode": "sync", "result": status}
+
+        poll_count += 1
+        if poll_count % 10 == 0:
+            await progress_callback(float(poll_count), None, f"Running ({poll_count}s)")
+        await asyncio.sleep(1.0)
+
+
+async def _dispatch_async(
+    contract: ToolContract,
+    runner: Callable[[], Any],
+    async_job_store: Any | None,
+    tool_name: str,
+    arguments: dict[str, Any],
+    context: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """Mode 3: return job_id immediately."""
+    if async_job_store is None:
+        raise RuntimeError(
+            f"Tool {tool_name!r} is sync_class=async-only but no async_job_store is configured"
+        )
+    job_id = _submit_to_store(async_job_store, tool_name, arguments, context, runner)
+    return {"mode": "async", "job_id": job_id, "status": "submitted"}
+
+
+def _submit_to_store(
+    store: Any,
+    tool_name: str,
+    arguments: dict[str, Any],
+    context: dict[str, Any] | None,
+    runner: Callable[[], Any],
+) -> str:
+    """Submit a job to the async job store."""
+    import inspect
+
+    ctx = dict(context or {})
+    ctx["runner"] = runner
+    result = store.submit(tool_name, arguments, ctx)
+    if inspect.isawaitable(result):
+        raise TypeError("Synchronous submit path received awaitable — use async store")
+    return str(result)
+
+
+def _get_store_status(store: Any, job_id: str) -> dict[str, Any]:
+    """Get job status from store."""
+    import inspect
+
+    result = store.get_status(job_id)
+    if inspect.isawaitable(result):
+        raise TypeError("Synchronous status path received awaitable — use async store")
+    return dict(result) if isinstance(result, dict) else {"status": "unknown"}
+
+
+async def _run(runner: Callable[[], Any]) -> Any:
+    """Execute runner, awaiting if needed."""
+    import inspect
+
+    result = runner()
+    if inspect.isawaitable(result):
+        return await result
+    return result
+
+
+def format_async_rest_response(job_id: str) -> tuple[int, dict[str, str], dict[str, Any]]:
+    """Format REST 202 Accepted response for async jobs (PS-95 §5.2).
+
+    Returns (status_code, headers, body). The Location header points to the
+    polling endpoint per PS-95 §5.2.
+    """
+    return (
+        202,
+        {"Location": f"/api/v1/jobs/{job_id}"},
+        {"job_id": job_id, "status": "submitted"},
+    )
+
+
+def format_budget_exceeded_mcp_error(job_id: str, budget: float) -> dict[str, Any]:
+    """Format MCP JSON-RPC error for budget-exceeded (PS-95 §5.4)."""
+    return {
+        "code": BUDGET_EXCEEDED_CODE,
+        "message": f"Tool exceeded sync budget ({budget}s). Job is still running.",
+        "data": {"job_id": job_id, "status": "running", "poll_url": f"/api/v1/jobs/{job_id}"},
+    }
+
+
+def format_a2a_task_response(job_id: str, status: str = "submitted") -> dict[str, Any]:
+    """Format A2A task response with 1:1 job/task ID mapping (PS-95 §5.2).
+
+    A2A task ID = job ID. This ensures callers can use standard A2A getTask
+    flow to poll job completion.
+    """
+    return {
+        "id": job_id,
+        "status": {"state": "working" if status in ("submitted", "running", "pending") else status},
+        "metadata": {"job_id": job_id},
+    }

cloud_dog_api_kit/mcp/tool_audit.py

@@ -0,0 +1,136 @@
+# 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.
+
+"""MCP tool audit middleware for PS-50 compliance.
+
+License: Apache 2.0
+Ownership: Cloud-Dog, Viewdeck Engineering Limited
+Description: Wraps MCP tool handlers with structured audit logging.
+Requirements: PS-50.AUD1
+Tasks: W28A-737
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Callable, Optional
+
+_DEFAULT_REDACT_FIELDS = frozenset({
+    "password", "secret", "token", "api_key", "credential", "auth",
+    "access_token", "refresh_token", "key_hash",
+})
+
+
+def _redact_params(
+    params: dict[str, Any],
+    redact_fields: frozenset[str] = _DEFAULT_REDACT_FIELDS,
+) -> dict[str, Any]:
+    """Redact sensitive parameter values.
+
+    Args:
+        params: The raw parameter dict from the tool call.
+        redact_fields: Field names whose values should be replaced.
+
+    Returns:
+        A copy of the dict with sensitive values replaced by ``[REDACTED]``.
+    """
+    cleaned: dict[str, Any] = {}
+    for key, value in params.items():
+        if key.lower() in redact_fields:
+            cleaned[key] = "[REDACTED]"
+        else:
+            cleaned[key] = value
+    return cleaned
+
+
+def mcp_tool_audit_middleware(
+    tool_name: str,
+    handler: Callable,
+    *,
+    service: str,
+    logger: Optional[logging.Logger] = None,
+    redact_fields: Optional[frozenset[str]] = None,
+) -> Callable:
+    """Wrap an MCP tool handler to emit audit log entries for every tool call.
+
+    Args:
+        tool_name: The name of the MCP tool being wrapped.
+        handler: The original tool handler callable.
+        service: The emitting service name (e.g. ``"file-mcp-server"``).
+        logger: Optional logger instance. Falls back to stdlib logging.
+        redact_fields: Additional field names to redact from parameters.
+
+    Returns:
+        A wrapped handler that logs audit entries before and after execution.
+
+    Audit record fields:
+        - correlation_id (from request context or generated)
+        - service (the emitting service name)
+        - tool_name (which tool was called)
+        - actor (user/API key identity from auth context)
+        - parameters (redacted — no secrets/tokens/passwords)
+        - outcome ("success" | "error")
+        - duration_ms (wall clock time)
+        - timestamp (ISO 8601)
+        - error_detail (if outcome is "error")
+    """
+    effective_redact = redact_fields or _DEFAULT_REDACT_FIELDS
+    log = logger or logging.getLogger(f"cloud_dog_api_kit.mcp.audit.{service}")
+
+    def _wrapped(**kwargs: Any) -> Any:
+        correlation_id = str(uuid.uuid4().hex[:16])
+        ts = datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+        safe_params = _redact_params(kwargs, effective_redact)
+        t0 = time.monotonic()
+        try:
+            result = handler(**kwargs)
+            duration_ms = round((time.monotonic() - t0) * 1000, 2)
+            log.info(
+                "mcp_tool_call",
+                extra={
+                    "event_type": "mcp_tool_call",
+                    "correlation_id": correlation_id,
+                    "service": service,
+                    "tool_name": tool_name,
+                    "parameters": safe_params,
+                    "outcome": "success",
+                    "duration_ms": duration_ms,
+                    "timestamp": ts,
+                },
+            )
+            return result
+        except Exception as exc:
+            duration_ms = round((time.monotonic() - t0) * 1000, 2)
+            log.warning(
+                "mcp_tool_call",
+                extra={
+                    "event_type": "mcp_tool_call",
+                    "correlation_id": correlation_id,
+                    "service": service,
+                    "tool_name": tool_name,
+                    "parameters": safe_params,
+                    "outcome": "error",
+                    "duration_ms": duration_ms,
+                    "timestamp": ts,
+                    "error_detail": str(exc),
+                },
+            )
+            raise
+
+    _wrapped.__name__ = handler.__name__ if hasattr(handler, "__name__") else tool_name
+    _wrapped.__doc__ = handler.__doc__
+    return _wrapped

cloud_dog_api_kit/mcp/tool_router.py

@@ -0,0 +1,180 @@
+# 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 tool router
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Tool registry router for typed MCP tool calls and metadata.
+# Related requirements: FR18.1
+# Related architecture: SA1
+
+"""MCP tool router helpers."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable
+
+from fastapi import FastAPI, Request
+from starlette.responses import JSONResponse
+
+from cloud_dog_api_kit.envelopes import error_envelope, success_envelope
+from cloud_dog_api_kit.errors import APIError
+from cloud_dog_api_kit.mcp.error_mapper import map_legacy_mcp_payload
+
+ToolCallable = Callable[[dict[str, Any], Request], Awaitable[Any] | Any]
+ToolRegistryType = dict[str, "ToolContract | ToolCallable | dict[str, Any]"]
+
+
+SYNC_CLASS_DEFAULT = "sync-default"
+SYNC_CLASS_PROGRESS = "sync-with-progress"
+SYNC_CLASS_ASYNC = "async-only"
+SYNC_CLASSES = frozenset({SYNC_CLASS_DEFAULT, SYNC_CLASS_PROGRESS, SYNC_CLASS_ASYNC})
+
+DEFAULT_SYNC_BUDGET_SECONDS = 50
+MAX_SYNC_BUDGET_SECONDS = 55
+
+
+@dataclass(slots=True)
+class ToolContract:
+    """Contract for a tool exposed via MCP transport.
+
+    PS-95 sync_class values:
+        ``sync-default``       Mode 1 — block within sync_budget, return result or job_id on timeout.
+        ``sync-with-progress`` Mode 2 — stream progress notifications, return result on completion.
+        ``async-only``         Mode 3 — return job_id immediately; mandatory ``_blocking`` sibling.
+    """
+
+    name: str
+    handler: ToolCallable
+    description: str = ""
+    input_schema: dict[str, Any] = field(default_factory=dict)
+    output_schema: dict[str, Any] = field(default_factory=dict)
+    sync_class: str = SYNC_CLASS_DEFAULT
+    sync_budget_seconds: float = DEFAULT_SYNC_BUDGET_SECONDS
+
+
+def normalise_tool_registry(tool_registry: ToolRegistryType | None) -> dict[str, ToolContract]:
+    """Normalise different registry value shapes into ToolContract values."""
+    contracts: dict[str, ToolContract] = {}
+    for name, value in (tool_registry or {}).items():
+        if isinstance(value, ToolContract):
+            contracts[name] = value
+            continue
+        if callable(value):
+            contracts[name] = ToolContract(name=name, handler=value)
+            continue
+        if isinstance(value, dict) and callable(value.get("handler")):
+            sc = str(value.get("sync_class", SYNC_CLASS_DEFAULT))
+            if sc not in SYNC_CLASSES:
+                raise ValueError(f"Invalid sync_class {sc!r} for tool {name!r}. Must be one of {SYNC_CLASSES}")
+            contracts[name] = ToolContract(
+                name=name,
+                handler=value["handler"],
+                description=str(value.get("description", "")),
+                input_schema=dict(value.get("input_schema") or {}),
+                output_schema=dict(value.get("output_schema") or {}),
+                sync_class=sc,
+                sync_budget_seconds=float(value.get("sync_budget_seconds", DEFAULT_SYNC_BUDGET_SECONDS)),
+            )
+            continue
+        raise TypeError(f"Unsupported tool registry entry for {name!r}")
+    return contracts
+
+
+async def _invoke_tool(contract: ToolContract, payload: dict[str, Any], request: Request) -> Any:
+    """Invoke tool handler with best-effort signature compatibility."""
+    parameter_count = len(inspect.signature(contract.handler).parameters)
+    if parameter_count <= 1:
+        result = contract.handler(payload)  # type: ignore[call-arg]
+    else:
+        result = contract.handler(payload, request)
+    if inspect.isawaitable(result):
+        return await result
+    return result
+
+
+def register_tool_router(
+    app: FastAPI,
+    tool_registry: ToolRegistryType | None,
+    *,
+    base_path: str = "/mcp/tools",
+) -> dict[str, ToolContract]:
+    """Register MCP tool routes on a FastAPI app."""
+    contracts = normalise_tool_registry(tool_registry)
+
+    @app.get(base_path, tags=["mcp"])
+    async def list_tools() -> dict[str, Any]:
+        """List tools."""
+        return success_envelope(
+            data=[
+                {
+                    "name": contract.name,
+                    "description": contract.description,
+                    "input_schema": contract.input_schema,
+                    "output_schema": contract.output_schema,
+                }
+                for contract in contracts.values()
+            ],
+        )
+
+    @app.post(f"{base_path}/{{tool_name}}", tags=["mcp"])
+    async def call_tool(tool_name: str, request: Request) -> JSONResponse:
+        """Handle call tool."""
+        request_id = getattr(request.state, "request_id", "")
+        correlation_id = getattr(request.state, "correlation_id", None)
+        contract = contracts.get(tool_name)
+        if contract is None:
+            return JSONResponse(
+                status_code=404,
+                content=error_envelope(
+                    code="NOT_FOUND",
+                    message=f"Unknown MCP tool: {tool_name}",
+                    request_id=request_id,
+                    correlation_id=correlation_id,
+                ),
+            )
+        payload = await request.json() if request.headers.get("content-type", "").startswith("application/json") else {}
+        try:
+            result = await _invoke_tool(contract, payload, request)
+        except APIError as exc:
+            return JSONResponse(
+                status_code=exc.status_code,
+                content=error_envelope(
+                    code=exc.code,
+                    message=exc.message,
+                    details=exc.details,
+                    retryable=exc.retryable,
+                    request_id=request_id,
+                    correlation_id=correlation_id,
+                ),
+            )
+        except Exception:
+            return JSONResponse(
+                status_code=500,
+                content=error_envelope(
+                    code="INTERNAL_ERROR",
+                    message="Tool execution failed",
+                    request_id=request_id,
+                    correlation_id=correlation_id,
+                ),
+            )
+
+        mapped = map_legacy_mcp_payload(result, request_id=request_id, correlation_id=correlation_id)
+        status_code = 200 if mapped.get("ok", True) else 400
+        return JSONResponse(status_code=status_code, content=mapped)
+
+    return contracts