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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nocfo-cli
-Version: 1.2.1
+Version: 1.2.3
 Summary: NoCFO CLI, MCP server, and Cursor skill toolkit.
 License: MIT
 License-File: LICENSE
@@ -119,7 +119,7 @@ Open Claude Desktop config and add:
       "command": "uvx",
       "args": ["--from", "nocfo-cli", "nocfo", "mcp"],
       "env": {
-        "NOCFO_API_TOKEN": "your_token_here"
+        "NOCFO_JWT_TOKEN": "your_jwt_here"
       }
     }
   }
@@ -149,7 +149,7 @@ Add the following to your Cursor MCP config (`~/.cursor/mcp.json`):
       "command": "uvx",
       "args": ["--from", "nocfo-cli", "nocfo", "mcp"],
       "env": {
-        "NOCFO_API_TOKEN": "your_token_here"
+        "NOCFO_JWT_TOKEN": "your_jwt_here"
       }
     }
   }
@@ -188,6 +188,8 @@ nocfo --output json businesses list
 
 - `nocfo mcp` = local stdio mode
 - `nocfo mcp --transport http --auth-mode oauth --mcp-base-url mcp.nocfo.io` = remote HTTP mode
+- Local stdio auth order: `NOCFO_JWT_TOKEN` first, then `NOCFO_API_TOKEN`
+- `NOCFO_API_TOKEN` is optional for stdio when `NOCFO_JWT_TOKEN` is set
 
 Detailed auth contract and troubleshooting are in `MCP_AUTHENTICATION.md`.
 

{nocfo_cli-1.2.1 → nocfo_cli-1.2.3}/README.md

@@ -94,7 +94,7 @@ Open Claude Desktop config and add:
       "command": "uvx",
       "args": ["--from", "nocfo-cli", "nocfo", "mcp"],
       "env": {
-        "NOCFO_API_TOKEN": "your_token_here"
+        "NOCFO_JWT_TOKEN": "your_jwt_here"
       }
     }
   }
@@ -124,7 +124,7 @@ Add the following to your Cursor MCP config (`~/.cursor/mcp.json`):
       "command": "uvx",
       "args": ["--from", "nocfo-cli", "nocfo", "mcp"],
       "env": {
-        "NOCFO_API_TOKEN": "your_token_here"
+        "NOCFO_JWT_TOKEN": "your_jwt_here"
       }
     }
   }
@@ -163,6 +163,8 @@ nocfo --output json businesses list
 
 - `nocfo mcp` = local stdio mode
 - `nocfo mcp --transport http --auth-mode oauth --mcp-base-url mcp.nocfo.io` = remote HTTP mode
+- Local stdio auth order: `NOCFO_JWT_TOKEN` first, then `NOCFO_API_TOKEN`
+- `NOCFO_API_TOKEN` is optional for stdio when `NOCFO_JWT_TOKEN` is set
 
 Detailed auth contract and troubleshooting are in `MCP_AUTHENTICATION.md`.
 

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

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

{nocfo_cli-1.2.1 → nocfo_cli-1.2.3}/src/nocfo_toolkit/cli/app.py

@@ -104,7 +104,11 @@ def run_mcp_server(
         help="Comma-separated OAuth scopes required for MCP tools.",
     ),
 ) -> None:
-    """Run NoCFO MCP server over stdio or HTTP transport."""
+    """Run NoCFO MCP server over stdio or HTTP transport.
+
+    Stdio mode accepts either NOCFO_JWT_TOKEN or NOCFO_API_TOKEN.
+    HTTP oauth mode uses connector bearer verification + JWT exchange flow.
+    """
 
     from nocfo_toolkit.mcp.server import MCPServerOptions, run_http_server, run_server
 

{nocfo_cli-1.2.1 → nocfo_cli-1.2.3}/src/nocfo_toolkit/config.py

@@ -43,14 +43,15 @@ class TokenSource(str, Enum):
 class ToolkitConfig:
     """Resolved toolkit configuration."""
 
-    api_token: str | None
-    token_source: TokenSource
-    base_url: str
-    output_format: OutputFormat
+    api_token: str | None = None
+    token_source: TokenSource = TokenSource.MISSING
+    base_url: str = DEFAULT_BASE_URL
+    output_format: OutputFormat = OutputFormat.TABLE
+    jwt_token: str | None = None
 
     @property
     def is_authenticated(self) -> bool:
-        return bool(self.api_token)
+        return bool(self.api_token or self.jwt_token)
 
 
 class ConfigStore:
@@ -116,6 +117,19 @@ def sanitize_api_token(value: str | None) -> str | None:
     return token
 
 
+def sanitize_jwt_token(value: str | None) -> str | None:
+    """Normalize JWT token from environment."""
+
+    if value is None:
+        return None
+    token = value.strip()
+    if not token:
+        return None
+    if any(ch.isspace() for ch in token):
+        raise ValueError("JWT token cannot contain whitespace characters.")
+    return token
+
+
 def _resolve_token(
     *,
     cli_token: str | None,
@@ -151,6 +165,7 @@ def load_config(
         stored_token=stored.get("api_token"),
     )
     resolved_token = sanitize_api_token(raw_token)
+    resolved_jwt_token = sanitize_jwt_token(os.getenv("NOCFO_JWT_TOKEN"))
     resolved_base_url = (
         base_url
         or os.getenv("NOCFO_BASE_URL")
@@ -166,4 +181,5 @@ def load_config(
         token_source=token_source if resolved_token else TokenSource.MISSING,
         base_url=resolved_base_url,
         output_format=resolved_output,
+        jwt_token=resolved_jwt_token,
     )

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

@@ -2,10 +2,12 @@
 
 from __future__ import annotations
 
+import asyncio
 import base64
 import hashlib
 import inspect
 import json
+import logging
 import os
 import time
 from dataclasses import dataclass
@@ -22,6 +24,8 @@ from starlette.routing import Route
 
 from nocfo_toolkit.config import AUTH_HEADER_SCHEME, ToolkitConfig
 
+logger = logging.getLogger(__name__)
+
 
 class MCPAuthConfigurationError(RuntimeError):
     """Raised when MCP auth env configuration is incomplete."""
@@ -181,10 +185,19 @@ class UserInfoTokenVerifier(TokenVerifier):
                         "Accept": "application/json",
                     },
                 )
-        except httpx.HTTPError:
+        except httpx.HTTPError as exc:
+            logger.info(
+                "OAuth userinfo token verification failed transport_error=%s",
+                type(exc).__name__,
+            )
             return None
 
         if response.status_code != 200:
+            logger.info(
+                "OAuth userinfo token verification failed status=%s detail=%s",
+                response.status_code,
+                _extract_error_detail(response),
+            )
             return None
 
         payload = response.json() if response.content else {}
@@ -227,6 +240,7 @@ class JwtExchangeAuth(httpx.Auth):
         )
         self._refresh_skew_seconds = max(0, refresh_skew_seconds)
         self._cache: dict[str, tuple[str, int | None]] = {}
+        self._locks: dict[str, asyncio.Lock] = {}
 
     @staticmethod
     def _cache_key(access_token: str, claims: dict[str, Any]) -> str:
@@ -255,6 +269,13 @@ class JwtExchangeAuth(httpx.Auth):
             return True
         return time.time() < float(expires_at - self._refresh_skew_seconds)
 
+    def _get_lock(self, cache_key: str) -> asyncio.Lock:
+        lock = self._locks.get(cache_key)
+        if lock is None:
+            lock = asyncio.Lock()
+            self._locks[cache_key] = lock
+        return lock
+
     async def async_auth_flow(self, request: httpx.Request):
         access = get_access_token()
         bearer_token = access.token if access else None
@@ -267,43 +288,99 @@ class JwtExchangeAuth(httpx.Auth):
         jwt_token = cached[0] if cached and self._is_fresh(cached[1]) else None
 
         if jwt_token is None:
-            exchange_request = httpx.Request(
-                method="POST",
-                url=request.url.copy_with(path=self._exchange_path, query=b""),
-                headers={
-                    "Authorization": f"Bearer {bearer_token}",
-                    "Content-Type": "application/json",
-                    "Accept": "application/json",
-                },
-                content=b"{}",
+            lock = self._get_lock(cache_key)
+            async with lock:
+                cached = self._cache.get(cache_key)
+                jwt_token = cached[0] if cached and self._is_fresh(cached[1]) else None
+                if jwt_token is None:
+                    exchange_request = httpx.Request(
+                        method="POST",
+                        url=request.url.copy_with(path=self._exchange_path, query=b""),
+                        headers={
+                            "Authorization": f"Bearer {bearer_token}",
+                            "Content-Type": "application/json",
+                            "Accept": "application/json",
+                        },
+                        content=b"{}",
+                    )
+
+                    exchange_response = yield exchange_request
+                    await exchange_response.aread()
+                    if exchange_response.status_code >= 400:
+                        detail = _extract_error_detail(exchange_response)
+                        logger.warning(
+                            "JWT exchange failed status=%s detail=%s",
+                            exchange_response.status_code,
+                            detail,
+                        )
+                    if exchange_response.status_code == 401:
+                        raise RuntimeError(
+                            "JWT exchange failed: incoming bearer token is missing or "
+                            f"invalid. {_format_error_detail(exchange_response)}"
+                        )
+                    if exchange_response.status_code == 403:
+                        raise RuntimeError(
+                            "JWT exchange failed: authenticated user is not allowed to "
+                            f"get JWT. {_format_error_detail(exchange_response)}"
+                        )
+                    if exchange_response.status_code >= 500:
+                        raise RuntimeError(
+                            "JWT exchange failed due to backend server error. "
+                            f"{_format_error_detail(exchange_response)}"
+                        )
+                    if exchange_response.status_code >= 400:
+                        raise RuntimeError(
+                            "JWT exchange failed with status "
+                            f"{exchange_response.status_code}. "
+                            f"{_format_error_detail(exchange_response)}"
+                        )
+
+                    payload = exchange_response.json()
+                    value = payload.get("token") if isinstance(payload, dict) else None
+                    if not isinstance(value, str) or not value:
+                        raise RuntimeError(
+                            "JWT exchange succeeded without token payload."
+                        )
+                    jwt_token = value
+                    self._cache[cache_key] = (jwt_token, self._decode_exp(jwt_token))
+
+        request.headers["Authorization"] = f"{AUTH_HEADER_SCHEME} {jwt_token}"
+        yield request
+
+
+def _extract_error_detail(response: httpx.Response) -> str | None:
+    try:
+        payload = response.json() if response.content else None
+    except ValueError:
+        payload = None
+
+    if isinstance(payload, dict):
+        for key in (
+            "detail",
+            "message",
+            "error_description",
+            "error_message",
+            "error",
+        ):
+            value = payload.get(key)
+            if isinstance(value, str) and value.strip():
+                return value
+        if "non_field_errors" in payload and isinstance(
+            payload["non_field_errors"], list
+        ):
+            return "; ".join(
+                item.strip()
+                for item in payload["non_field_errors"]
+                if isinstance(item, str) and item.strip()
             )
 
-            exchange_response = yield exchange_request
-            await exchange_response.aread()
-            if exchange_response.status_code == 401:
-                raise RuntimeError(
-                    "JWT exchange failed: incoming bearer token is missing or invalid."
-                )
-            if exchange_response.status_code == 403:
-                raise RuntimeError(
-                    "JWT exchange failed: authenticated user is not allowed to get JWT."
-                )
-            if exchange_response.status_code >= 500:
-                raise RuntimeError("JWT exchange failed due to backend server error.")
-            if exchange_response.status_code >= 400:
-                raise RuntimeError(
-                    f"JWT exchange failed with status {exchange_response.status_code}."
-                )
+    text = response.text.strip() if response.text else ""
+    return text or None
 
-            payload = exchange_response.json()
-            value = payload.get("token") if isinstance(payload, dict) else None
-            if not isinstance(value, str) or not value:
-                raise RuntimeError("JWT exchange succeeded without token payload.")
-            jwt_token = value
-            self._cache[cache_key] = (jwt_token, self._decode_exp(jwt_token))
 
-        request.headers["Authorization"] = f"{AUTH_HEADER_SCHEME} {jwt_token}"
-        yield request
+def _format_error_detail(response: httpx.Response) -> str:
+    detail = _extract_error_detail(response)
+    return f"Reason: {detail}" if detail else "Reason unavailable."
 
 
 class _CleanUrlAuthProvider(RemoteAuthProvider):

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

@@ -0,0 +1,135 @@
+"""Helpers for normalizing backend HTTP errors for MCP clients."""
+
+from __future__ import annotations
+
+from typing import Any
+
+_KNOWN_MESSAGE_KEYS = {
+    "detail",
+    "message",
+    "error",
+    "error_description",
+    "error_code",
+    "error_message",
+    "non_field_errors",
+}
+
+_STATUS_DEFAULT_SUMMARY: dict[int, str] = {
+    400: "Request validation failed.",
+    401: "Authentication failed.",
+    403: "Permission denied.",
+    404: "Resource not found.",
+    409: "Request conflicts with current resource state.",
+    412: "Request precondition failed.",
+    423: "Requested resource is locked.",
+    426: "Upgrade required for this operation.",
+    429: "Too many requests.",
+}
+
+_STATUS_HINTS: dict[int, str] = {
+    400: "Review the tool arguments and required fields.",
+    401: "Reconnect the MCP integration and retry the tool call.",
+    403: "Confirm your account has required permissions for this action.",
+    404: "Verify identifiers (business, invoice, contact) are correct.",
+    409: "Refresh data and retry once the conflicting state is resolved.",
+    412: "Resolve dependent records before retrying this operation.",
+    423: "Unlock the resource or close the related locking period before retrying.",
+    426: "Operation requires an upgraded plan or additional quota.",
+    429: "Wait briefly and retry the request.",
+}
+
+
+def normalize_http_error(
+    *,
+    tool_name: str,
+    status_code: int | None,
+    payload: Any | None,
+    fallback_message: str,
+) -> dict[str, Any]:
+    """Build a stable user-facing MCP error payload from structured HTTP context."""
+
+    summary = _extract_summary_from_payload(payload, status_code) or fallback_message
+    result: dict[str, Any] = {
+        "tool": tool_name,
+        "error_type": _error_type_from_status(status_code),
+        "summary": summary,
+    }
+
+    if status_code is not None:
+        result["status_code"] = status_code
+
+    if isinstance(payload, dict):
+        error_code = payload.get("error_code")
+        if isinstance(error_code, str) and error_code.strip():
+            result["backend_error_code"] = error_code
+
+    field_errors = _extract_field_errors(payload)
+    if field_errors:
+        result["field_errors"] = field_errors
+
+    if status_code in _STATUS_HINTS:
+        result["hint"] = _STATUS_HINTS[status_code]
+
+    return result
+
+
+def _extract_summary_from_payload(payload: Any, status_code: int | None) -> str | None:
+    if isinstance(payload, dict):
+        for key in ("detail", "message", "error_message", "error_description"):
+            value = payload.get(key)
+            if isinstance(value, str) and value.strip():
+                return value
+        error_value = payload.get("error")
+        if isinstance(error_value, str) and error_value.strip():
+            return error_value
+    elif isinstance(payload, list):
+        parts = [
+            item.strip() for item in payload if isinstance(item, str) and item.strip()
+        ]
+        if parts:
+            return "; ".join(parts[:3])
+    elif isinstance(payload, str) and payload.strip():
+        return payload
+
+    if status_code is not None:
+        return _STATUS_DEFAULT_SUMMARY.get(status_code)
+    return None
+
+
+def _extract_field_errors(payload: Any) -> dict[str, Any] | None:
+    if not isinstance(payload, dict):
+        return None
+
+    field_errors = {
+        key: value
+        for key, value in payload.items()
+        if key not in _KNOWN_MESSAGE_KEYS
+        and (isinstance(value, (list, dict, str, int, float, bool)) or value is None)
+    }
+    return field_errors or None
+
+
+def _error_type_from_status(status_code: int | None) -> str:
+    if status_code is None:
+        return "tool_error"
+    if status_code == 400:
+        return "bad_request"
+    if status_code == 401:
+        return "authentication_error"
+    if status_code == 403:
+        return "permission_error"
+    if status_code == 404:
+        return "not_found"
+    if status_code == 409:
+        return "conflict"
+    if status_code == 412:
+        return "precondition_failed"
+    if status_code == 423:
+        return "locked"
+    if status_code == 426:
+        return "upgrade_required"
+    if status_code == 429:
+        return "rate_limited"
+    if status_code >= 500:
+        return "server_error"
+    return "tool_error"

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

@@ -0,0 +1,45 @@
+"""Context-local capture of recent downstream HTTP errors."""
+
+from __future__ import annotations
+
+import contextvars
+from typing import Any
+
+import httpx
+
+_LAST_HTTP_ERROR: contextvars.ContextVar[
+    dict[str, Any] | None
+] = contextvars.ContextVar("nocfo_last_http_error", default=None)
+
+
+def clear_last_http_error() -> None:
+    _LAST_HTTP_ERROR.set(None)
+
+
+def get_last_http_error() -> dict[str, Any] | None:
+    return _LAST_HTTP_ERROR.get()
+
+
+async def capture_http_error_response(response: httpx.Response) -> None:
+    """Store status/payload for the latest non-success HTTP response."""
+
+    if response.status_code < 400:
+        _LAST_HTTP_ERROR.set(None)
+        return
+
+    try:
+        await response.aread()
+    except httpx.HTTPError:
+        pass
+
+    try:
+        payload: Any = response.json() if response.content else None
+    except (ValueError, httpx.ResponseNotRead):
+        payload = (response.text or "").strip()[:1000] or None
+
+    _LAST_HTTP_ERROR.set(
+        {
+            "status_code": response.status_code,
+            "payload": payload,
+        }
+    )

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

@@ -0,0 +1,98 @@
+"""MCP middleware for tool logging and error normalization."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any
+
+from fastmcp.exceptions import ToolError
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+from mcp.types import CallToolRequestParams
+
+from nocfo_toolkit.mcp.error_handling import normalize_http_error
+from nocfo_toolkit.mcp.http_error_capture import (
+    clear_last_http_error,
+    get_last_http_error,
+)
+
+logger = logging.getLogger(__name__)
+
+_SENSITIVE_KEYS = {
+    "authorization",
+    "token",
+    "access_token",
+    "refresh_token",
+    "secret",
+    "password",
+    "api_key",
+}
+
+
+def _sanitize_for_logs(value: Any, *, depth: int = 0) -> Any:
+    if depth > 3:
+        return "<truncated>"
+    if isinstance(value, dict):
+        sanitized: dict[str, Any] = {}
+        for key, item in value.items():
+            if key.lower() in _SENSITIVE_KEYS:
+                sanitized[key] = "<redacted>"
+            else:
+                sanitized[key] = _sanitize_for_logs(item, depth=depth + 1)
+        return sanitized
+    if isinstance(value, list):
+        return [_sanitize_for_logs(item, depth=depth + 1) for item in value[:30]]
+    return value
+
+
+class MCPToolErrorMiddleware(Middleware):
+    """Logs MCP tool calls and normalizes backend-facing tool errors."""
+
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[CallToolRequestParams],
+        call_next,
+    ):
+        tool_name = context.message.name
+        arguments = _sanitize_for_logs(context.message.arguments or {})
+        started = time.monotonic()
+        logger.info(
+            "MCP tool call started tool=%s args=%s",
+            tool_name,
+            json.dumps(arguments, ensure_ascii=True, default=str),
+        )
+
+        try:
+            result = await call_next(context)
+        except ToolError as exc:
+            captured = get_last_http_error()
+            if not captured:
+                raise
+            normalized = normalize_http_error(
+                tool_name=tool_name,
+                status_code=captured.get("status_code"),
+                payload=captured.get("payload"),
+                fallback_message=str(exc),
+            )
+            logger.warning(
+                "MCP tool call failed tool=%s status=%s error_type=%s summary=%s",
+                tool_name,
+                normalized.get("status_code"),
+                normalized.get("error_type"),
+                normalized.get("summary"),
+            )
+            raise ToolError(json.dumps(normalized, ensure_ascii=True)) from exc
+        except Exception:
+            logger.exception("MCP tool call crashed tool=%s", tool_name)
+            raise
+        finally:
+            clear_last_http_error()
+
+        duration_ms = int((time.monotonic() - started) * 1000)
+        logger.info(
+            "MCP tool call succeeded tool=%s duration_ms=%d",
+            tool_name,
+            duration_ms,
+        )
+        return result

{nocfo_cli-1.2.1 → nocfo_cli-1.2.3}/src/nocfo_toolkit/mcp/server.py

@@ -16,6 +16,8 @@ from nocfo_toolkit.mcp.auth import (
     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:
@@ -38,15 +40,17 @@ class MCPServerOptions:
 def _create_pat_client(
     config: ToolkitConfig, timeout_seconds: float
 ) -> httpx.AsyncClient:
-    if not config.api_token:
+    resolved_token = config.jwt_token or config.api_token
+    if not resolved_token:
         raise RuntimeError(
-            "Missing API token. Set NOCFO_API_TOKEN or run `nocfo auth configure` "
-            "before starting MCP server in PAT mode."
+            "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} {config.api_token}"},
+        headers={"Authorization": f"{AUTH_HEADER_SCHEME} {resolved_token}"},
         timeout=timeout_seconds,
+        event_hooks={"response": [capture_http_error_response]},
     )
 
 
@@ -64,6 +68,7 @@ def _create_oauth_client(
             refresh_skew_seconds=refresh_skew_seconds,
         ),
         timeout=timeout_seconds,
+        event_hooks={"response": [capture_http_error_response]},
     )
 
 
@@ -116,6 +121,7 @@ def create_server(
         client=client,
         name=opts.name,
         auth=server_auth,
+        middleware=[MCPToolErrorMiddleware()],
         route_maps=[
             RouteMap(tags={"MCP"}, mcp_type=MCPType.TOOL),
             RouteMap(mcp_type=MCPType.EXCLUDE),