Publish curated MobilityOps source snapshot

backend/app/api/routers/mcp_integrations.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import uuid
+from datetime import date
+
+from fastapi import APIRouter, Depends, Header, Query, Response
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.api.deps import McpClientContext, get_db, require_mcp_service_token
+from app.core.config import get_settings
+from app.core.errors import AppError
+from app.models.booking import Booking
+from app.models.data_quality import DataQualityIssue
+from app.models.vehicle import Vehicle
+from app.schemas import (
+    AttentionVehicleOut,
+    McpKnowledgeSearchRequest,
+    McpVehicleDetailOut,
+    OperationsSummaryOut,
+)
+from app.services.audit import record_audit_event
+from app.services.knowledge import GroundedAnswer, get_knowledge_provider
+from app.services.operations import compute_metrics, list_attention_vehicles
+
+router = APIRouter(prefix="/api/v1/integrations/mcp", tags=["mcp"])
+settings = get_settings()
+
+
+def get_correlation_id(
+    x_correlation_id: str | None = Header(default=None, alias="X-Correlation-Id"),
+) -> str:
+    """Preserve the Hub's own inbound correlation ID through MCP client -> Hub -> Fleet
+    Ops -> RAGcore -> Fleet Ops Audit; only mint a fresh one when none was supplied or
+    it isn't a valid UUID (per the task's own correlation-propagation contract)."""
+    if x_correlation_id:
+        try:
+            return str(uuid.UUID(x_correlation_id))
+        except ValueError:
+            pass
+    return str(uuid.uuid4())
+
+
+def _audit_service_request(
+    db: Session,
+    *,
+    reported_client_id: str,
+    tool: str,
+    status_label: str,
+    correlation_id: str,
+    metadata: dict[str, object] | None = None,
+) -> None:
+    record_audit_event(
+        db,
+        actor_type="service",
+        # The shared service token authenticates the Hub, not the caller identity that
+        # the Hub reports in a header. Keep attribution authoritative and retain the
+        # reported value only as explicitly non-authenticated diagnostic metadata.
+        actor_label="itworx-mcp-hub",
+        action="mcp_tool_request",
+        entity_type="mcp_tool",
+        correlation_id=uuid.UUID(correlation_id),
+        metadata={
+            "tool": tool,
+            "status": status_label,
+            "reported_client_id": reported_client_id,
+            **(metadata or {}),
+        },
+    )
+    db.commit()
+
+
+def _set_trace_headers(response: Response, correlation_id: str, tenant: str) -> None:
+    response.headers["X-Correlation-Id"] = correlation_id
+    response.headers["X-Tenant-Id"] = tenant
+    response.headers["Cache-Control"] = "no-store"
+
+
+@router.get("/operations-summary", response_model=OperationsSummaryOut)
+def operations_summary(
+    response: Response,
+    db: Session = Depends(get_db),
+    client: McpClientContext = Depends(require_mcp_service_token),
+    correlation_id: str = Depends(get_correlation_id),
+) -> OperationsSummaryOut:
+    metrics = compute_metrics(db)
+    _set_trace_headers(response, correlation_id, client.tenant)
+    _audit_service_request(
+        db,
+        reported_client_id=client.reported_client_id,
+        tool="fleet_ops_get_operations_summary",
+        status_label="ok",
+        correlation_id=correlation_id,
+    )
+    return OperationsSummaryOut(tenant=client.tenant, metrics=metrics)
+
+
+@router.get("/attention-vehicles", response_model=list[AttentionVehicleOut])
+def attention_vehicles(
+    response: Response,
+    minimum_severity: str = Query(default="medium", pattern="^(low|medium|high)$"),
+    date_filter: date | None = Query(default=None, alias="date"),
+    limit: int = Query(default=20, ge=1, le=50),
+    db: Session = Depends(get_db),
+    client: McpClientContext = Depends(require_mcp_service_token),
+    correlation_id: str = Depends(get_correlation_id),
+) -> list[AttentionVehicleOut]:
+    results = list_attention_vehicles(
+        db, minimum_severity=minimum_severity, on_or_before=date_filter, limit=limit
+    )
+    _set_trace_headers(response, correlation_id, client.tenant)
+    _audit_service_request(
+        db,
+        reported_client_id=client.reported_client_id,
+        tool="fleet_ops_list_attention_vehicles",
+        status_label="ok",
+        correlation_id=correlation_id,
+    )
+    return [AttentionVehicleOut(**r) for r in results]
+
+
+@router.get("/vehicles/{vehicle_ref}", response_model=McpVehicleDetailOut)
+def vehicle_details(
+    vehicle_ref: str,
+    response: Response,
+    db: Session = Depends(get_db),
+    client: McpClientContext = Depends(require_mcp_service_token),
+    correlation_id: str = Depends(get_correlation_id),
+) -> McpVehicleDetailOut:
+    _set_trace_headers(response, correlation_id, client.tenant)
+    vehicle = db.scalar(select(Vehicle).where(Vehicle.public_ref == vehicle_ref))
+    if vehicle is None:
+        _audit_service_request(
+            db,
+            reported_client_id=client.reported_client_id,
+            tool="fleet_ops_get_vehicle_details",
+            status_label="not_found",
+            correlation_id=correlation_id,
+        )
+        raise AppError("VEHICLE_NOT_FOUND", "Vehicle not found.", status_code=404)
+
+    open_issue_count = len(
+        db.scalars(
+            select(DataQualityIssue.id).where(
+                DataQualityIssue.entity_type == "vehicle",
+                DataQualityIssue.entity_id == vehicle.id,
+                DataQualityIssue.status == "open",
+            )
+        ).all()
+    )
+    current_booking = db.scalar(
+        select(Booking).where(Booking.vehicle_id == vehicle.id, Booking.status == "active")
+    )
+
+    _audit_service_request(
+        db,
+        reported_client_id=client.reported_client_id,
+        tool="fleet_ops_get_vehicle_details",
+        status_label="ok",
+        correlation_id=correlation_id,
+    )
+    return McpVehicleDetailOut(
+        public_ref=vehicle.public_ref,
+        make=vehicle.make,
+        model=vehicle.model,
+        model_year=vehicle.model_year,
+        location=vehicle.location,
+        operational_status=vehicle.operational_status,
+        odometer_km=vehicle.odometer_km,
+        next_service_km=vehicle.next_service_km,
+        open_quality_issue_count=open_issue_count,
+        current_booking_ref=current_booking.public_ref if current_booking else None,
+    )
+
+
+@router.post("/search-knowledge", response_model=GroundedAnswer)
+def search_knowledge(
+    body: McpKnowledgeSearchRequest,
+    response: Response,
+    db: Session = Depends(get_db),
+    client: McpClientContext = Depends(require_mcp_service_token),
+    correlation_id: str = Depends(get_correlation_id),
+) -> GroundedAnswer:
+    provider = get_knowledge_provider()
+    answer = provider.ask(body.question, correlation_id, language=body.locale)
+    source_count_available = len(answer.sources)
+    answer.sources = answer.sources[: body.max_sources]
+    _set_trace_headers(response, correlation_id, client.tenant)
+    response.headers["X-Sources-Available"] = str(source_count_available)
+    response.headers["X-Sources-Returned"] = str(len(answer.sources))
+    _audit_service_request(
+        db,
+        reported_client_id=client.reported_client_id,
+        tool="fleet_ops_search_knowledge",
+        status_label=answer.evidence_state,
+        correlation_id=correlation_id,
+        metadata={
+            "tenant": client.tenant,
+            "locale": body.locale,
+            "sources_available": source_count_available,
+            "sources_returned": len(answer.sources),
+        },
+    )
+    return answer