nocfo-cli 1.2.3__tar.gz → 1.3.0__tar.gz

{nocfo_cli-1.2.3 → nocfo_cli-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nocfo-cli
-Version: 1.2.3
+Version: 1.3.0
 Summary: NoCFO CLI, MCP server, and Cursor skill toolkit.
 License: MIT
 License-File: LICENSE

{nocfo_cli-1.2.3 → nocfo_cli-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "nocfo-cli"
-version = "1.2.3"
+version = "1.3.0"
 description = "NoCFO CLI, MCP server, and Cursor skill toolkit."
 authors = ["NoCFO"]
 readme = "README.md"

nocfo_cli-1.3.0/src/nocfo_toolkit/mcp/__init__.py

@@ -0,0 +1,13 @@
+"""MCP server package."""
+
+from nocfo_toolkit.mcp.contract_validation import (
+    MCPContractValidationResult,
+    assert_openapi_mcp_contract_valid,
+    validate_openapi_mcp_contract,
+)
+
+__all__ = [
+    "MCPContractValidationResult",
+    "assert_openapi_mcp_contract_valid",
+    "validate_openapi_mcp_contract",
+]

{nocfo_cli-1.2.3 → nocfo_cli-1.3.0}/src/nocfo_toolkit/mcp/auth.py

@@ -18,8 +18,9 @@ from fastmcp.server.auth import AccessToken, RemoteAuthProvider, TokenVerifier
 from fastmcp.server.auth.providers.introspection import IntrospectionTokenVerifier
 from fastmcp.server.auth.providers.jwt import JWTVerifier
 from fastmcp.server.dependencies import get_access_token
-from fastmcp.tools.tool import Tool
-from starlette.responses import JSONResponse
+from fastmcp.utilities.components import FastMCPComponent
+from starlette.datastructures import MutableHeaders
+from starlette.responses import JSONResponse, Response
 from starlette.routing import Route
 
 from nocfo_toolkit.config import AUTH_HEADER_SCHEME, ToolkitConfig
@@ -85,7 +86,7 @@ class RemoteOAuthConfig:
 
         authorization_servers = tuple(
             _split_csv(_env("NOCFO_MCP_AUTHORIZATION_SERVERS"))
-            or [f"{config.base_url.rstrip('/')}/auth"]
+            or [config.base_url.rstrip("/")]
         )
         required_scopes = tuple(_split_csv(_env("NOCFO_MCP_REQUIRED_SCOPES")))
         jwt_audience = tuple(_split_csv(_env("NOCFO_MCP_JWT_AUDIENCE")))
@@ -129,12 +130,21 @@ class RemoteOAuthConfig:
                 raise MCPAuthConfigurationError(
                     "Missing NOCFO_MCP_JWKS_URI for JWT verifier mode."
                 )
-            return JWTVerifier(
+            jwt_verifier = JWTVerifier(
                 jwks_uri=self.jwt_jwks_uri,
                 issuer=self.jwt_issuer,
                 audience=list(self.jwt_audience) if self.jwt_audience else None,
                 required_scopes=list(self.required_scopes) or None,
             )
+            if self.userinfo_url:
+                return FallbackTokenVerifier(
+                    primary=jwt_verifier,
+                    secondary=UserInfoTokenVerifier(
+                        userinfo_url=self.userinfo_url,
+                        required_scopes=list(self.required_scopes) or None,
+                    ),
+                )
+            return jwt_verifier
 
         if self.verifier_mode == "userinfo":
             if not self.userinfo_url:
@@ -224,6 +234,21 @@ class UserInfoTokenVerifier(TokenVerifier):
         )
 
 
+class FallbackTokenVerifier(TokenVerifier):
+    """Try primary verifier first, then fall back to secondary verifier."""
+
+    def __init__(self, *, primary: TokenVerifier, secondary: TokenVerifier) -> None:
+        super().__init__(required_scopes=primary.required_scopes)
+        self._primary = primary
+        self._secondary = secondary
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        primary_result = await self._primary.verify_token(token)
+        if primary_result is not None:
+            return primary_result
+        return await self._secondary.verify_token(token)
+
+
 class JwtExchangeAuth(httpx.Auth):
     """Exchange incoming OAuth bearer to NoCFO JWT for downstream API calls."""
 
@@ -397,35 +422,94 @@ class _CleanUrlAuthProvider(RemoteAuthProvider):
         routes = super().get_routes(mcp_path)
         return [self._clean_metadata_route(r) for r in routes]
 
+    @staticmethod
+    def _strip_slashes_from_metadata_body(body: dict[str, Any]) -> dict[str, Any]:
+        for key in ("resource", "authorization_servers"):
+            val = body.get(key)
+            if isinstance(val, str):
+                body[key] = val.rstrip("/")
+            elif isinstance(val, list):
+                body[key] = [
+                    str(item).rstrip("/") if item is not None else item for item in val
+                ]
+        return body
+
     @staticmethod
     def _clean_metadata_route(route: Route) -> Route:
         if "oauth-protected-resource" not in (route.path or ""):
             return route
 
         original = route.endpoint
-        # Some Starlette routes wrap endpoints as ASGI callables
-        # (scope, receive, send). Only wrap request-style endpoints.
         try:
-            if len(inspect.signature(original).parameters) != 1:
-                return route
+            signature_params = len(inspect.signature(original).parameters)
         except (TypeError, ValueError):
             return route
 
-        async def _strip_trailing_slashes(request):  # type: ignore[no-untyped-def]
-            response = await original(request)
-            body = json.loads(response.body)
-            for key in ("resource", "authorization_servers"):
-                val = body.get(key)
-                if isinstance(val, str):
-                    body[key] = val.rstrip("/")
-                elif isinstance(val, list):
-                    body[key] = [
-                        v.rstrip("/") if isinstance(v, str) else v for v in val
-                    ]
-            return JSONResponse(body, headers=dict(response.headers))
+        if signature_params == 1:
+
+            async def _strip_trailing_slashes(request):  # type: ignore[no-untyped-def]
+                response = await original(request)
+                body = json.loads(response.body)
+                cleaned = _CleanUrlAuthProvider._strip_slashes_from_metadata_body(body)
+                return JSONResponse(cleaned, headers=dict(response.headers))
+
+            wrapped_endpoint = _strip_trailing_slashes
+        elif signature_params == 3:
+
+            async def _strip_trailing_slashes_from_asgi(  # type: ignore[no-untyped-def]
+                request,
+            ):
+                start_message: dict[str, Any] | None = None
+                body_chunks: list[bytes] = []
+
+                async def _capture_send(message: dict[str, Any]) -> None:
+                    nonlocal start_message
+                    message_type = message.get("type")
+                    if message_type == "http.response.start":
+                        start_message = dict(message)
+                        return
+                    if message_type == "http.response.body":
+                        body_chunks.append(message.get("body", b""))
+
+                await original(request.scope, request.receive, _capture_send)
+                response_body = b"".join(body_chunks)
+                transformed_body = response_body
+                status_code = 200
+                headers_dict: dict[str, str] = {}
+
+                if start_message is not None:
+                    status_code = int(start_message.get("status", 200))
+                    headers = MutableHeaders(raw=start_message.get("headers", []))
+                    content_type = headers.get("content-type", "")
+                    if "application/json" in content_type:
+                        try:
+                            parsed_body = json.loads(response_body.decode("utf-8"))
+                        except (UnicodeDecodeError, json.JSONDecodeError):
+                            parsed_body = None
+                        if isinstance(parsed_body, dict):
+                            cleaned = (
+                                _CleanUrlAuthProvider._strip_slashes_from_metadata_body(
+                                    parsed_body
+                                )
+                            )
+                            transformed_body = json.dumps(cleaned).encode("utf-8")
+                            headers["content-length"] = str(len(transformed_body))
+                    headers_dict = dict(headers.items())
+
+                return Response(
+                    content=transformed_body,
+                    status_code=status_code,
+                    headers=headers_dict,
+                )
+
+            wrapped_endpoint = _strip_trailing_slashes_from_asgi
+        else:
+            return route
 
         return Route(
-            route.path, endpoint=_strip_trailing_slashes, methods=route.methods
+            route.path,
+            endpoint=wrapped_endpoint,
+            methods=route.methods,
         )
 
 
@@ -458,9 +542,12 @@ def build_remote_auth_provider(
 
 
 def apply_tool_auth_metadata(
-    component: Tool, *, required_scopes: tuple[str, ...]
+    component: FastMCPComponent, *, required_scopes: tuple[str, ...]
 ) -> None:
-    """Attach explicit auth metadata so connector UIs can trigger linking flows."""
+    """Attach explicit auth metadata so connector UIs can trigger linking flows.
+
+    Applies to tools, resources, and resource templates from the OpenAPI provider.
+    """
 
     meta: dict[str, Any] = dict(component.meta or {})
     scheme: dict[str, Any] = {"type": "oauth2"}

nocfo_cli-1.3.0/src/nocfo_toolkit/mcp/contract_validation.py

@@ -0,0 +1,198 @@
+"""Contract validation helpers for MCP OpenAPI compatibility."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+from fastmcp.server.providers.openapi import OpenAPIProvider
+
+from nocfo_toolkit.mcp.server import (
+    MCP_OPENAPI_ROUTE_MAPS,
+    apply_mcp_operation_metadata,
+    apply_mcp_namespace_names,
+)
+from nocfo_toolkit.openapi import filter_mcp_spec
+
+
+@dataclass(frozen=True)
+class MCPContractValidationResult:
+    """Result for validating OpenAPI-to-MCP component mapping."""
+
+    is_valid: bool
+    mcp_operation_count: int
+    tool_count: int
+    resource_count: int
+    resource_template_count: int
+    missing_in_provider: tuple[str, ...]
+    unexpected_in_provider: tuple[str, ...]
+    missing_operation_ids_in_schema: tuple[str, ...]
+    issues: tuple[str, ...]
+
+
+def _apply_component_mcp_metadata(route: Any, component: Any) -> None:
+    apply_mcp_namespace_names(route, component)
+    apply_mcp_operation_metadata(route, component)
+
+
+def _get_base_url(openapi_spec: dict[str, Any]) -> str:
+    servers = openapi_spec.get("servers")
+    if isinstance(servers, list):
+        for server in servers:
+            if isinstance(server, dict) and isinstance(server.get("url"), str):
+                return server["url"]
+    return "https://api.example.com"
+
+
+def _collect_operation_ids(
+    filtered_spec: dict[str, Any],
+) -> tuple[list[str], list[str]]:
+    operation_ids: list[str] = []
+    missing_operation_ids: list[str] = []
+
+    for path, methods in filtered_spec.get("paths", {}).items():
+        if not isinstance(methods, dict):
+            continue
+        for method, operation in methods.items():
+            if not isinstance(operation, dict):
+                continue
+            operation_id = operation.get("operationId")
+            if operation_id:
+                operation_ids.append(operation_id)
+            else:
+                missing_operation_ids.append(f"{str(method).upper()} {path}")
+
+    return operation_ids, missing_operation_ids
+
+
+def _collect_provider_operation_ids(provider: OpenAPIProvider) -> list[str]:
+    def _components(attr: str) -> dict[str, Any]:
+        for candidate in (attr.lstrip("_"), attr):
+            value = getattr(provider, candidate, None)
+            if isinstance(value, dict):
+                return value
+        return {}
+
+    ids: list[str] = []
+    for component in _components("_tools").values():
+        route = getattr(component, "_route", None)
+        operation_id = getattr(route, "operation_id", None)
+        if operation_id:
+            ids.append(operation_id)
+    for component in _components("_resources").values():
+        route = getattr(component, "_route", None)
+        operation_id = getattr(route, "operation_id", None)
+        if operation_id:
+            ids.append(operation_id)
+    for component in _components("_templates").values():
+        route = getattr(component, "_route", None)
+        operation_id = getattr(route, "operation_id", None)
+        if operation_id:
+            ids.append(operation_id)
+    return ids
+
+
+def _build_result(
+    *,
+    expected_operation_ids: list[str],
+    provider_operation_ids: list[str],
+    missing_operation_ids_in_schema: list[str],
+    provider: OpenAPIProvider,
+) -> MCPContractValidationResult:
+    def _components_count(attr: str) -> int:
+        for candidate in (attr.lstrip("_"), attr):
+            value = getattr(provider, candidate, None)
+            if isinstance(value, dict):
+                return len(value)
+        return 0
+
+    expected_set = set(expected_operation_ids)
+    provider_set = set(provider_operation_ids)
+
+    missing_in_provider = tuple(sorted(expected_set - provider_set))
+    unexpected_in_provider = tuple(sorted(provider_set - expected_set))
+
+    issues: list[str] = []
+    if missing_operation_ids_in_schema:
+        issues.append(
+            "Some MCP-tagged operations are missing operationId: "
+            + ", ".join(missing_operation_ids_in_schema)
+        )
+    if missing_in_provider:
+        issues.append(
+            "OperationIds missing in OpenAPIProvider: " + ", ".join(missing_in_provider)
+        )
+    if unexpected_in_provider:
+        issues.append(
+            "Unexpected operationIds in OpenAPIProvider: "
+            + ", ".join(unexpected_in_provider)
+        )
+
+    return MCPContractValidationResult(
+        is_valid=not issues,
+        mcp_operation_count=len(expected_operation_ids),
+        tool_count=_components_count("_tools"),
+        resource_count=_components_count("_resources"),
+        resource_template_count=_components_count("_templates"),
+        missing_in_provider=missing_in_provider,
+        unexpected_in_provider=unexpected_in_provider,
+        missing_operation_ids_in_schema=tuple(missing_operation_ids_in_schema),
+        issues=tuple(issues),
+    )
+
+
+def validate_openapi_mcp_contract(
+    openapi_spec: dict[str, Any],
+    *,
+    validate_output: bool = True,
+) -> MCPContractValidationResult:
+    """Validate that MCP-tagged operations map cleanly to FastMCP components.
+
+    This function is designed to be imported from external repos (like backend tests)
+    through the published ``nocfo-cli`` package.
+    """
+    filtered_spec = filter_mcp_spec(openapi_spec, mcp_tag="MCP")
+    expected_operation_ids, missing_operation_ids_in_schema = _collect_operation_ids(
+        filtered_spec
+    )
+
+    client = httpx.AsyncClient(base_url=_get_base_url(openapi_spec))
+    try:
+        provider = OpenAPIProvider(
+            openapi_spec=filtered_spec,
+            client=client,
+            route_maps=MCP_OPENAPI_ROUTE_MAPS,
+            mcp_component_fn=_apply_component_mcp_metadata,
+            validate_output=validate_output,
+        )
+        provider_operation_ids = _collect_provider_operation_ids(provider)
+    finally:
+        try:
+            asyncio.run(client.aclose())
+        except RuntimeError:
+            # If already running in event loop, closing can be skipped in this sync helper.
+            pass
+
+    return _build_result(
+        expected_operation_ids=expected_operation_ids,
+        provider_operation_ids=provider_operation_ids,
+        missing_operation_ids_in_schema=missing_operation_ids_in_schema,
+        provider=provider,
+    )
+
+
+def assert_openapi_mcp_contract_valid(
+    openapi_spec: dict[str, Any],
+    *,
+    validate_output: bool = True,
+) -> MCPContractValidationResult:
+    """Assert MCP contract validity and return the validation result."""
+    result = validate_openapi_mcp_contract(
+        openapi_spec,
+        validate_output=validate_output,
+    )
+    if not result.is_valid:
+        raise AssertionError("\n".join(result.issues))
+    return result

nocfo_cli-1.3.0/src/nocfo_toolkit/mcp/server.py

@@ -0,0 +1,284 @@
+"""NoCFO MCP server implementation."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+import httpx
+from pydantic import AnyUrl
+from fastmcp.server.providers.openapi.components import (
+    OpenAPIResource,
+    OpenAPIResourceTemplate,
+)
+from fastmcp.server.providers.openapi.routing import MCPType, RouteMap
+from fastmcp.tools.tool import Tool
+
+from nocfo_toolkit.config import AUTH_HEADER_SCHEME, ToolkitConfig
+from nocfo_toolkit.mcp.auth import (
+    MCPAuthOptions,
+    JwtExchangeAuth,
+    apply_tool_auth_metadata,
+    build_remote_auth_provider,
+)
+from nocfo_toolkit.mcp.http_error_capture import capture_http_error_response
+from nocfo_toolkit.mcp.middleware import MCPToolErrorMiddleware
+from nocfo_toolkit.openapi import (
+    MCP_RESOURCE_TAG,
+    MCP_TOOL_TAG,
+    filter_mcp_spec,
+    load_openapi_spec,
+)
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+# Semantic mapping for MCP-tagged routes (see FastMCP OpenAPI route maps):
+# https://gofastmcp.com/integrations/openapi#custom-route-maps
+MCP_OPENAPI_ROUTE_MAPS: list[RouteMap] = [
+    RouteMap(tags={MCP_RESOURCE_TAG}, mcp_type=MCPType.RESOURCE),
+    RouteMap(tags={MCP_TOOL_TAG}, mcp_type=MCPType.TOOL),
+    RouteMap(mcp_type=MCPType.EXCLUDE),
+]
+
+# Must match ``nocfo.spectacular_hooks.MCP_NAMESPACE_EXTENSION`` (set by ``mcp_extend_schema``).
+X_MCP_NAMESPACE = "x-mcp-namespace"
+_X_MCP_PREFIX = "x-mcp-"
+X_NOCFO_MCP_SERVER_INSTRUCTIONS = "x-nocfo-mcp-server-instructions"
+
+
+def _normalize_mcp_namespace_token(value: str) -> str:
+    """Normalize backend ``MCPNamespace`` string (allows accidental human-readable input)."""
+    normalized = value.strip()
+    if not normalized:
+        return ""
+    normalized = normalized.replace("-", "_").replace(" ", "_")
+    normalized = re.sub(r"(?<!^)(?=[A-Z])", "_", normalized)
+    normalized = re.sub(r"[^a-zA-Z0-9_]", "", normalized)
+    normalized = re.sub(r"_+", "_", normalized)
+    return normalized.strip("_").lower()
+
+
+def build_mcp_component_name(
+    operation_id: str, extensions: dict[str, Any] | None
+) -> str:
+    """Build MCP name ``<x-mcp-namespace>_<operation_id_with_dots_as_underscores>``.
+
+    Namespace is read from the OpenAPI operation extension ``x-mcp-namespace`` (set in
+    the backend via ``mcp_extend_schema``). If missing, ``operation_id`` is
+    returned unchanged.
+    """
+    if not operation_id or not str(operation_id).strip():
+        return operation_id
+    raw = (extensions or {}).get(X_MCP_NAMESPACE)
+    if not isinstance(raw, str) or not raw.strip():
+        return operation_id
+    ns = _normalize_mcp_namespace_token(raw)
+    if not ns:
+        return operation_id
+    # Avoid duplicating the namespace if operation_id already starts with it.
+    # Example: operation_id "invoicing.contact.create" with ns "invoicing"
+    # should become "invoicing_contact_create", not "invoicing_invoicing_contact_create".
+    if operation_id.startswith(f"{ns}."):
+        operation_id = operation_id[len(ns) + 1 :]
+    return f"{ns}_{operation_id.replace('.', '_')}"
+
+
+def _resource_uri_with_name(uri: str | AnyUrl, display_name: str) -> AnyUrl:
+    """Keep ``resource://`` prefix and optional ``/{param}`` suffix; replace the name segment."""
+    uri_str = str(uri)
+    return AnyUrl(re.sub(r"^(resource://)([^/]+)", rf"\1{display_name}", uri_str))
+
+
+def apply_mcp_namespace_names(route: Any, component: Any) -> None:
+    """Apply ``x-mcp-namespace``-based MCP names to a tool, resource, or template.
+
+    Used by :func:`create_server` and by tests that construct an
+    :class:`OpenAPIProvider` with the same ``NoCFO`` naming policy.
+    """
+    if not getattr(route, "operation_id", None):
+        return
+    ext = getattr(route, "extensions", None) or {}
+    display_name = build_mcp_component_name(route.operation_id, ext)
+    if isinstance(component, Tool):
+        component.name = display_name
+        component.title = display_name
+    elif isinstance(component, OpenAPIResource):
+        component.name = display_name
+        component.uri = _resource_uri_with_name(component.uri, display_name)
+    elif isinstance(component, OpenAPIResourceTemplate):
+        component.name = display_name
+        component.uri_template = str(
+            _resource_uri_with_name(component.uri_template, display_name)
+        )
+
+
+def apply_mcp_operation_metadata(route: Any, component: Any) -> None:
+    """Attach OpenAPI ``x-mcp-*`` operation extensions to component metadata."""
+    extensions = getattr(route, "extensions", None) or {}
+    mcp_extensions = {
+        key: value
+        for key, value in extensions.items()
+        if isinstance(key, str) and key.startswith(_X_MCP_PREFIX)
+    }
+    if not mcp_extensions:
+        return
+
+    meta: dict[str, Any] = dict(getattr(component, "meta", None) or {})
+    nocfo_meta: dict[str, Any] = dict(meta.get("nocfo") or {})
+    nocfo_meta["mcp"] = mcp_extensions
+    meta["nocfo"] = nocfo_meta
+    component.meta = meta
+
+
+def _get_server_instructions(openapi_spec: dict[str, Any]) -> str | None:
+    """Read backend-owned MCP server instructions from OpenAPI root extensions."""
+    instructions = openapi_spec.get(X_NOCFO_MCP_SERVER_INSTRUCTIONS)
+    if not isinstance(instructions, str):
+        return None
+    cleaned = instructions.strip()
+    return cleaned or None
+
+
+@dataclass(frozen=True)
+class MCPServerOptions:
+    """MCP server configuration options."""
+
+    name: str = "NoCFO"
+    timeout_seconds: float = 30.0
+    auth_mode: Literal["pat", "oauth"] = "pat"
+    mcp_base_url: str | None = None
+    jwt_exchange_path: str = "/auth/jwt/"
+    token_refresh_skew_seconds: int = 60
+    required_scopes: tuple[str, ...] = ()
+
+
+def _create_pat_client(
+    config: ToolkitConfig, timeout_seconds: float
+) -> httpx.AsyncClient:
+    resolved_token = config.jwt_token or config.api_token
+    if not resolved_token:
+        raise RuntimeError(
+            "Missing authentication token. Set NOCFO_JWT_TOKEN or NOCFO_API_TOKEN, "
+            "or run `nocfo auth configure` before starting MCP server in PAT mode."
+        )
+    return httpx.AsyncClient(
+        base_url=config.base_url,
+        headers={"Authorization": f"{AUTH_HEADER_SCHEME} {resolved_token}"},
+        timeout=timeout_seconds,
+        event_hooks={"response": [capture_http_error_response]},
+    )
+
+
+def _create_oauth_client(
+    config: ToolkitConfig,
+    *,
+    exchange_path: str,
+    timeout_seconds: float,
+    refresh_skew_seconds: int,
+) -> httpx.AsyncClient:
+    return httpx.AsyncClient(
+        base_url=config.base_url,
+        auth=JwtExchangeAuth(
+            exchange_path=exchange_path,
+            refresh_skew_seconds=refresh_skew_seconds,
+        ),
+        timeout=timeout_seconds,
+        event_hooks={"response": [capture_http_error_response]},
+    )
+
+
+def create_server(
+    config: ToolkitConfig,
+    *,
+    options: MCPServerOptions | None = None,
+) -> FastMCP:
+    """Create an MCP server from NoCFO OpenAPI specification."""
+
+    from fastmcp import FastMCP
+
+    opts = options or MCPServerOptions()
+    if opts.auth_mode == "oauth":
+        client = _create_oauth_client(
+            config,
+            exchange_path=opts.jwt_exchange_path,
+            timeout_seconds=opts.timeout_seconds,
+            refresh_skew_seconds=opts.token_refresh_skew_seconds,
+        )
+        server_auth = build_remote_auth_provider(
+            config=config,
+            options=MCPAuthOptions(
+                mode="oauth",
+                mcp_base_url=opts.mcp_base_url,
+                jwt_exchange_path=opts.jwt_exchange_path,
+                token_refresh_skew_seconds=opts.token_refresh_skew_seconds,
+                required_scopes=opts.required_scopes,
+            ),
+        )
+    else:
+        client = _create_pat_client(config, opts.timeout_seconds)
+        server_auth = None
+
+    spec = load_openapi_spec(base_url=config.base_url)
+    filtered_spec = filter_mcp_spec(spec, mcp_tag="MCP")
+    server_instructions = _get_server_instructions(spec)
+
+    def component_mapper(route: Any, component: Any) -> None:
+        apply_mcp_namespace_names(route, component)
+        apply_mcp_operation_metadata(route, component)
+        if opts.auth_mode == "oauth" and isinstance(
+            component, (Tool, OpenAPIResource, OpenAPIResourceTemplate)
+        ):
+            apply_tool_auth_metadata(
+                component,
+                required_scopes=opts.required_scopes,
+            )
+
+    return FastMCP.from_openapi(
+        openapi_spec=filtered_spec,
+        client=client,
+        name=opts.name,
+        instructions=server_instructions,
+        auth=server_auth,
+        middleware=[MCPToolErrorMiddleware()],
+        route_maps=MCP_OPENAPI_ROUTE_MAPS,
+        mcp_component_fn=component_mapper,
+        validate_output=True,
+    )
+
+
+def run_server(
+    config: ToolkitConfig,
+    *,
+    options: MCPServerOptions | None = None,
+) -> None:
+    """Run NoCFO MCP server over stdio transport."""
+
+    server = create_server(config, options=options)
+    server.run()
+
+
+def run_http_server(
+    config: ToolkitConfig,
+    *,
+    host: str = "0.0.0.0",  # nosec: B104
+    port: int = 8000,
+    path: str = "/mcp",
+    options: MCPServerOptions | None = None,
+) -> None:
+    """Run NoCFO MCP server over streamable HTTP transport."""
+
+    server = create_server(config, options=options)
+    server.run(transport="http", host=host, port=port, path=path)
+
+
+async def run_server_async(
+    config: ToolkitConfig,
+    *,
+    options: MCPServerOptions | None = None,
+) -> None:
+    """Async wrapper for environments requiring a coroutine entrypoint."""
+
+    await asyncio.to_thread(run_server, config, options=options)

{nocfo_cli-1.2.3 → nocfo_cli-1.3.0}/src/nocfo_toolkit/openapi.py

@@ -10,12 +10,16 @@ from typing import Any
 import httpx
 
 CACHE_PATH = Path.home() / ".cache" / "nocfo-cli" / "openapi.json"
+MCP_TAG = "MCP"
+MCP_RESOURCE_TAG = "MCP_RESOURCE"
+MCP_TOOL_TAG = "MCP_TOOL"
+X_MCP_COMPONENT_TYPE = "x-mcp-component-type"
 
 
 def load_openapi_spec(
     *,
     base_url: str,
-    openapi_path: str = "/openapi/",
+    openapi_path: str = "/openapi-mcp/",
     cache_path: Path | None = None,
     timeout: float = 30.0,
     max_attempts: int = 6,
@@ -48,8 +52,17 @@ def load_openapi_spec(
     ) from last_error
 
 
-def filter_mcp_spec(spec: dict[str, Any], mcp_tag: str = "MCP") -> dict[str, Any]:
-    """Return spec containing only operations tagged as MCP."""
+def _classify_mcp_operation(method: str, operation: dict[str, Any]) -> str:
+    component_type = operation.get(X_MCP_COMPONENT_TYPE)
+    if component_type == "resource":
+        return MCP_RESOURCE_TAG
+    if component_type == "tool":
+        return MCP_TOOL_TAG
+    return MCP_TOOL_TAG
+
+
+def filter_mcp_spec(spec: dict[str, Any], mcp_tag: str = MCP_TAG) -> dict[str, Any]:
+    """Return MCP-only OpenAPI with explicit resource/tool classification tags."""
 
     filtered_paths: dict[str, Any] = {}
     for path, methods in spec.get("paths", {}).items():
@@ -59,9 +72,17 @@ def filter_mcp_spec(spec: dict[str, Any], mcp_tag: str = "MCP") -> dict[str, Any
         for method, meta in methods.items():
             if not isinstance(meta, dict):
                 continue
-            tags = meta.get("tags", [])
-            if mcp_tag in tags:
-                kept_methods[method] = meta
+
+            tags = list(meta.get("tags", []))
+            if mcp_tag not in tags:
+                continue
+
+            classified_operation = dict(meta)
+            classification_tag = _classify_mcp_operation(method, classified_operation)
+            classified_operation["tags"] = list(
+                dict.fromkeys([*tags, classification_tag])
+            )
+            kept_methods[method] = classified_operation
         if kept_methods:
             filtered_paths[path] = kept_methods
 

nocfo_cli-1.2.3/src/nocfo_toolkit/mcp/__init__.py

@@ -1 +0,0 @@
-"""MCP server package."""

nocfo_cli-1.2.3/src/nocfo_toolkit/mcp/server.py

@@ -1,166 +0,0 @@
-"""NoCFO MCP server implementation."""
-
-from __future__ import annotations
-
-import asyncio
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Literal
-
-import httpx
-from fastmcp.tools.tool import Tool
-
-from nocfo_toolkit.config import AUTH_HEADER_SCHEME, ToolkitConfig
-from nocfo_toolkit.mcp.auth import (
-    MCPAuthOptions,
-    JwtExchangeAuth,
-    apply_tool_auth_metadata,
-    build_remote_auth_provider,
-)
-from nocfo_toolkit.mcp.http_error_capture import capture_http_error_response
-from nocfo_toolkit.mcp.middleware import MCPToolErrorMiddleware
-from nocfo_toolkit.openapi import filter_mcp_spec, load_openapi_spec
-
-if TYPE_CHECKING:
-    from fastmcp import FastMCP
-
-
-@dataclass(frozen=True)
-class MCPServerOptions:
-    """MCP server configuration options."""
-
-    name: str = "NoCFO"
-    timeout_seconds: float = 30.0
-    auth_mode: Literal["pat", "oauth"] = "pat"
-    mcp_base_url: str | None = None
-    jwt_exchange_path: str = "/auth/jwt/"
-    token_refresh_skew_seconds: int = 60
-    required_scopes: tuple[str, ...] = ()
-
-
-def _create_pat_client(
-    config: ToolkitConfig, timeout_seconds: float
-) -> httpx.AsyncClient:
-    resolved_token = config.jwt_token or config.api_token
-    if not resolved_token:
-        raise RuntimeError(
-            "Missing authentication token. Set NOCFO_JWT_TOKEN or NOCFO_API_TOKEN, "
-            "or run `nocfo auth configure` before starting MCP server in PAT mode."
-        )
-    return httpx.AsyncClient(
-        base_url=config.base_url,
-        headers={"Authorization": f"{AUTH_HEADER_SCHEME} {resolved_token}"},
-        timeout=timeout_seconds,
-        event_hooks={"response": [capture_http_error_response]},
-    )
-
-
-def _create_oauth_client(
-    config: ToolkitConfig,
-    *,
-    exchange_path: str,
-    timeout_seconds: float,
-    refresh_skew_seconds: int,
-) -> httpx.AsyncClient:
-    return httpx.AsyncClient(
-        base_url=config.base_url,
-        auth=JwtExchangeAuth(
-            exchange_path=exchange_path,
-            refresh_skew_seconds=refresh_skew_seconds,
-        ),
-        timeout=timeout_seconds,
-        event_hooks={"response": [capture_http_error_response]},
-    )
-
-
-def create_server(
-    config: ToolkitConfig,
-    *,
-    options: MCPServerOptions | None = None,
-) -> FastMCP:
-    """Create an MCP server from NoCFO OpenAPI specification."""
-
-    from fastmcp import FastMCP
-    from fastmcp.server.providers.openapi.routing import MCPType, RouteMap
-
-    opts = options or MCPServerOptions()
-    spec = load_openapi_spec(base_url=config.base_url)
-    filtered_spec = filter_mcp_spec(spec, mcp_tag="MCP")
-
-    if opts.auth_mode == "oauth":
-        client = _create_oauth_client(
-            config,
-            exchange_path=opts.jwt_exchange_path,
-            timeout_seconds=opts.timeout_seconds,
-            refresh_skew_seconds=opts.token_refresh_skew_seconds,
-        )
-        server_auth = build_remote_auth_provider(
-            config=config,
-            options=MCPAuthOptions(
-                mode="oauth",
-                mcp_base_url=opts.mcp_base_url,
-                jwt_exchange_path=opts.jwt_exchange_path,
-                token_refresh_skew_seconds=opts.token_refresh_skew_seconds,
-                required_scopes=opts.required_scopes,
-            ),
-        )
-    else:
-        client = _create_pat_client(config, opts.timeout_seconds)
-        server_auth = None
-
-    def component_mapper(_: Any, component: Any) -> None:
-        if opts.auth_mode != "oauth":
-            return
-        if isinstance(component, Tool):
-            apply_tool_auth_metadata(
-                component,
-                required_scopes=opts.required_scopes,
-            )
-
-    return FastMCP.from_openapi(
-        openapi_spec=filtered_spec,
-        client=client,
-        name=opts.name,
-        auth=server_auth,
-        middleware=[MCPToolErrorMiddleware()],
-        route_maps=[
-            RouteMap(tags={"MCP"}, mcp_type=MCPType.TOOL),
-            RouteMap(mcp_type=MCPType.EXCLUDE),
-        ],
-        mcp_component_fn=component_mapper,
-        validate_output=False,
-    )
-
-
-def run_server(
-    config: ToolkitConfig,
-    *,
-    options: MCPServerOptions | None = None,
-) -> None:
-    """Run NoCFO MCP server over stdio transport."""
-
-    server = create_server(config, options=options)
-    server.run()
-
-
-def run_http_server(
-    config: ToolkitConfig,
-    *,
-    host: str = "0.0.0.0",  # nosec: B104
-    port: int = 8000,
-    path: str = "/mcp",
-    options: MCPServerOptions | None = None,
-) -> None:
-    """Run NoCFO MCP server over streamable HTTP transport."""
-
-    server = create_server(config, options=options)
-    server.run(transport="http", host=host, port=port, path=path)
-
-
-async def run_server_async(
-    config: ToolkitConfig,
-    *,
-    options: MCPServerOptions | None = None,
-) -> None:
-    """Async wrapper for environments requiring a coroutine entrypoint."""
-
-    await asyncio.to_thread(run_server, config, options=options)