nocfo-cli 1.4.7__tar.gz → 1.5.3__tar.gz

{nocfo_cli-1.4.7 → nocfo_cli-1.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nocfo-cli
-Version: 1.4.7
+Version: 1.5.3
 Summary: NoCFO CLI, MCP server, and Cursor skill toolkit.
 License: MIT
 License-File: LICENSE
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: fastmcp (>=2.0)
+Requires-Dist: fastmcp[code-mode] (>=3.1,<3.2)
 Requires-Dist: httpx (>=0.27)
 Requires-Dist: python-dotenv (>=1.0)
 Requires-Dist: rich (>=13.0)
@@ -184,6 +184,31 @@ nocfo --output json businesses list
 
 ## Advanced / Technical
 
+### MCP tool surface
+
+The MCP server exposes a curated workflow surface instead of mirroring the
+backend API one-to-one. Tool names keep the NoCFO namespaces (`common_*`,
+`bookkeeping_*`, `invoicing_*`, `reporting_*`, `constants_*`, `docs_*`), but
+arguments prefer user-facing identifiers:
+
+- use account numbers such as `1910`, not account IDs
+- use document and invoice numbers when users refer to documents or invoices
+- use tag names and contact names/emails for search and filtering
+- use `business="current"` unless the user explicitly chooses another business
+
+List tools return Linear-style pagination with `limit` and opaque `cursor`
+arguments. Responses include `page_info.has_next_page` and
+`page_info.next_cursor`.
+
+Permission checks are not exposed as planning tools. If an API call is rejected,
+the MCP returns a structured error with `error_type`, `message`, `hint`, and,
+when available for `403`, the current user's permissions for that business.
+
+For bookkeeping documents, `blueprint` means the editable posting plan used for
+create/update workflows. `entries` are the realized journal lines generated from
+the blueprint and are read-only through MCP. Use `docs_blueprint` for a concise
+schema guide before mutating document bookkeeping.
+
 ### MCP server modes
 
 - `nocfo mcp` = local stdio mode
@@ -229,12 +254,6 @@ poetry run pytest             # run tests
 poetry run nocfo --help       # run CLI locally
 ```
 
-Regenerate OpenAPI-based command stubs:
-
-```bash
-poetry run python scripts/generate_cli_commands.py
-```
-
 <details>
 <summary>Publishing to PyPI</summary>
 

{nocfo_cli-1.4.7 → nocfo_cli-1.5.3}/README.md

@@ -159,6 +159,31 @@ nocfo --output json businesses list
 
 ## Advanced / Technical
 
+### MCP tool surface
+
+The MCP server exposes a curated workflow surface instead of mirroring the
+backend API one-to-one. Tool names keep the NoCFO namespaces (`common_*`,
+`bookkeeping_*`, `invoicing_*`, `reporting_*`, `constants_*`, `docs_*`), but
+arguments prefer user-facing identifiers:
+
+- use account numbers such as `1910`, not account IDs
+- use document and invoice numbers when users refer to documents or invoices
+- use tag names and contact names/emails for search and filtering
+- use `business="current"` unless the user explicitly chooses another business
+
+List tools return Linear-style pagination with `limit` and opaque `cursor`
+arguments. Responses include `page_info.has_next_page` and
+`page_info.next_cursor`.
+
+Permission checks are not exposed as planning tools. If an API call is rejected,
+the MCP returns a structured error with `error_type`, `message`, `hint`, and,
+when available for `403`, the current user's permissions for that business.
+
+For bookkeeping documents, `blueprint` means the editable posting plan used for
+create/update workflows. `entries` are the realized journal lines generated from
+the blueprint and are read-only through MCP. Use `docs_blueprint` for a concise
+schema guide before mutating document bookkeeping.
+
 ### MCP server modes
 
 - `nocfo mcp` = local stdio mode
@@ -204,12 +229,6 @@ poetry run pytest             # run tests
 poetry run nocfo --help       # run CLI locally
 ```
 
-Regenerate OpenAPI-based command stubs:
-
-```bash
-poetry run python scripts/generate_cli_commands.py
-```
-
 <details>
 <summary>Publishing to PyPI</summary>
 

{nocfo_cli-1.4.7 → nocfo_cli-1.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "nocfo-cli"
-version = "1.4.7"
+version = "1.5.3"
 description = "NoCFO CLI, MCP server, and Cursor skill toolkit."
 authors = ["NoCFO"]
 readme = "README.md"
@@ -20,7 +20,7 @@ Documentation = "https://api-prd.nocfo.io/docs"
 
 [tool.poetry.dependencies]
 python = ">=3.10,<4.0"
-fastmcp = ">=2.0"
+fastmcp = { version = ">=3.1,<3.2", extras = ["code-mode"] }
 httpx = ">=0.27"
 typer = ">=0.12"
 rich = ">=13.0"

{nocfo_cli-1.4.7 → nocfo_cli-1.5.3}/src/nocfo_toolkit/cli/app.py

@@ -18,7 +18,6 @@ from nocfo_toolkit.cli.commands import (
     products,
     purchase_invoices,
     reports,
-    schema,
     tags,
     user,
 )
@@ -88,7 +87,10 @@ def run_mcp_server(
     auth_mode: str = typer.Option(
         "pat",
         "--auth-mode",
-        help="Server auth mode: pat (legacy) or oauth (Claude/OpenAI remote).",
+        help=(
+            "Server auth mode: pat (static token), oauth (remote connector), "
+            "or passthrough (forward incoming Authorization header)."
+        ),
     ),
     mcp_base_url: str | None = typer.Option(
         None,
@@ -111,10 +113,27 @@ def run_mcp_server(
             "load balancers with multiple MCP tasks)."
         ),
     ),
+    tool_search: bool = typer.Option(
+        True,
+        "--tool-search/--no-tool-search",
+        help=(
+            "Enable FastMCP Tool Search transform to reduce tool-catalog "
+            "context by exposing search_tools + call_tool."
+        ),
+    ),
+    skip_confirmation: bool = typer.Option(
+        False,
+        "--skip-confirmation/--require-confirmation",
+        help=(
+            "Skip interactive mutation confirmation elicitation. "
+            "Use only in trusted automation environments."
+        ),
+    ),
 ) -> None:
     """Run NoCFO MCP server over stdio or HTTP transport.
 
     Stdio mode accepts either NOCFO_JWT_TOKEN or NOCFO_API_TOKEN.
+    Optional NOCFO_CLIENT overrides default `nocfo-mcp` x-nocfo-client.
     HTTP oauth mode uses connector bearer verification + JWT exchange flow.
     """
 
@@ -122,8 +141,10 @@ def run_mcp_server(
 
     command_ctx = get_context(ctx)
     auth_mode_normalized = auth_mode.strip().lower()
-    if auth_mode_normalized not in {"pat", "oauth"}:
-        raise typer.BadParameter("--auth-mode must be either 'pat' or 'oauth'.")
+    if auth_mode_normalized not in {"pat", "oauth", "passthrough"}:
+        raise typer.BadParameter(
+            "--auth-mode must be one of 'pat', 'oauth', or 'passthrough'."
+        )
 
     transport_normalized = transport.strip().lower()
     if transport_normalized not in {"stdio", "http"}:
@@ -132,18 +153,40 @@ def run_mcp_server(
         raise typer.BadParameter(
             "OAuth mode requires --transport http because remote connectors use HTTP."
         )
+    if auth_mode_normalized == "passthrough" and transport_normalized != "http":
+        raise typer.BadParameter(
+            "Passthrough mode requires --transport http because it forwards "
+            "incoming HTTP Authorization headers."
+        )
 
     scope_items = tuple(
         value.strip() for value in required_scopes.split(",") if value.strip()
     )
-    auth_mode_value: Literal["pat", "oauth"] = (
-        "oauth" if auth_mode_normalized == "oauth" else "pat"
+    auth_mode_value: Literal["pat", "oauth", "passthrough"] = (
+        "oauth"
+        if auth_mode_normalized == "oauth"
+        else ("passthrough" if auth_mode_normalized == "passthrough" else "pat")
+    )
+    env_tool_search = os.getenv("NOCFO_MCP_TOOL_SEARCH", "").strip().lower()
+    tool_search_enabled = (
+        env_tool_search in {"1", "true", "yes", "on"}
+        if env_tool_search
+        else tool_search
     )
+    env_skip_confirmation = os.getenv("NOCFO_MCP_SKIP_CONFIRMATION", "").strip().lower()
+    skip_confirmation_enabled = (
+        env_skip_confirmation in {"1", "true", "yes", "on"}
+        if env_skip_confirmation
+        else skip_confirmation
+    )
+
     options = MCPServerOptions(
         auth_mode=auth_mode_value,
         mcp_base_url=mcp_base_url or os.getenv("NOCFO_MCP_BASE_URL"),
         required_scopes=scope_items,
         stateless_http=stateless_http,
+        tool_search=tool_search_enabled,
+        skip_confirmation=skip_confirmation_enabled,
     )
 
     if transport_normalized == "http":
@@ -177,7 +220,6 @@ app.add_typer(files.app, name="files")
 app.add_typer(tags.app, name="tags")
 app.add_typer(user.app, name="user")
 app.add_typer(reports.app, name="reports")
-app.add_typer(schema.app, name="schema")
 
 
 if __name__ == "__main__":

{nocfo_cli-1.4.7 → nocfo_cli-1.5.3}/src/nocfo_toolkit/config.py

@@ -18,7 +18,6 @@ except ModuleNotFoundError:  # pragma: no cover - fallback for minimal environme
 
 
 DEFAULT_BASE_URL = "https://api-prd.nocfo.io"
-DEFAULT_OPENAPI_PATH = "/openapi/"
 AUTH_HEADER_SCHEME = "Token"
 MIN_PAT_LENGTH = 8
 
@@ -48,6 +47,7 @@ class ToolkitConfig:
     base_url: str = DEFAULT_BASE_URL
     output_format: OutputFormat = OutputFormat.TABLE
     jwt_token: str | None = None
+    nocfo_client: str | None = None
 
     @property
     def is_authenticated(self) -> bool:
@@ -130,6 +130,11 @@ def sanitize_jwt_token(value: str | None) -> str | None:
     return token
 
 
+def sanitize_nocfo_client(value: str | None) -> str | None:
+    """Pass through optional x-nocfo-client value as-is."""
+    return value
+
+
 def _resolve_token(
     *,
     cli_token: str | None,
@@ -166,6 +171,7 @@ def load_config(
     )
     resolved_token = sanitize_api_token(raw_token)
     resolved_jwt_token = sanitize_jwt_token(os.getenv("NOCFO_JWT_TOKEN"))
+    resolved_nocfo_client = sanitize_nocfo_client(os.getenv("NOCFO_CLIENT"))
     resolved_base_url = (
         base_url
         or os.getenv("NOCFO_BASE_URL")
@@ -182,4 +188,5 @@ def load_config(
         base_url=resolved_base_url,
         output_format=resolved_output,
         jwt_token=resolved_jwt_token,
+        nocfo_client=resolved_nocfo_client,
     )

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

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

{nocfo_cli-1.4.7 → nocfo_cli-1.5.3}/src/nocfo_toolkit/mcp/auth.py

@@ -17,7 +17,7 @@ import httpx
 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.server.dependencies import get_access_token, get_http_headers
 from fastmcp.utilities.components import FastMCPComponent
 from starlette.datastructures import MutableHeaders
 from starlette.responses import JSONResponse, Response
@@ -46,6 +46,12 @@ def _split_csv(raw: str | None) -> list[str]:
     return [item.strip() for item in raw.split(",") if item.strip()]
 
 
+def _incoming_mcp_client() -> str | None:
+    headers = get_http_headers(include={"x-nocfo-client"})
+    nocfo_client = (headers.get("x-nocfo-client") or "").strip()
+    return nocfo_client or None
+
+
 @dataclass(frozen=True)
 class MCPAuthOptions:
     """Runtime auth settings used by the MCP server."""
@@ -306,6 +312,7 @@ class JwtExchangeAuth(httpx.Auth):
         bearer_token = access.token if access else None
         if not bearer_token:
             raise RuntimeError("Missing OAuth bearer token for MCP request.")
+        incoming_nocfo_client = _incoming_mcp_client()
 
         claims = access.claims if access and isinstance(access.claims, dict) else {}
         cache_key = self._cache_key(bearer_token, claims)
@@ -325,6 +332,11 @@ class JwtExchangeAuth(httpx.Auth):
                             "Authorization": f"Bearer {bearer_token}",
                             "Content-Type": "application/json",
                             "Accept": "application/json",
+                            **(
+                                {"x-nocfo-client": incoming_nocfo_client}
+                                if incoming_nocfo_client
+                                else {}
+                            ),
                         },
                         content=b"{}",
                     )
@@ -370,6 +382,23 @@ class JwtExchangeAuth(httpx.Auth):
                     self._cache[cache_key] = (jwt_token, self._decode_exp(jwt_token))
 
         request.headers["Authorization"] = f"{AUTH_HEADER_SCHEME} {jwt_token}"
+        if incoming_nocfo_client:
+            request.headers["x-nocfo-client"] = incoming_nocfo_client
+        yield request
+
+
+class PassthroughAuth(httpx.Auth):
+    """Forward incoming HTTP Authorization header to downstream API requests."""
+
+    async def async_auth_flow(self, request: httpx.Request):
+        headers = get_http_headers(include={"authorization", "x-nocfo-client"})
+        authorization = headers.get("authorization")
+        if not authorization:
+            raise RuntimeError("Missing Authorization header for MCP passthrough mode.")
+        request.headers["Authorization"] = authorization
+        nocfo_client = (headers.get("x-nocfo-client") or "").strip()
+        if nocfo_client:
+            request.headers["x-nocfo-client"] = nocfo_client
         yield request
 
 
@@ -546,7 +575,7 @@ def apply_tool_auth_metadata(
 ) -> None:
     """Attach explicit auth metadata so connector UIs can trigger linking flows.
 
-    Applies to tools, resources, and resource templates from the OpenAPI provider.
+    Applies to tools, resources, and resource templates exposed by MCP.
     """
 
     meta: dict[str, Any] = dict(component.meta or {})

nocfo_cli-1.5.3/src/nocfo_toolkit/mcp/curated/__init__.py

@@ -0,0 +1,6 @@
+"""Curated NoCFO MCP tool package."""
+
+from nocfo_toolkit.mcp.curated.client import CuratedNocfoClient
+from nocfo_toolkit.mcp.curated.instructions import SERVER_INSTRUCTIONS
+
+__all__ = ["CuratedNocfoClient", "SERVER_INSTRUCTIONS"]

nocfo_cli-1.5.3/src/nocfo_toolkit/mcp/curated/bookkeeping/account.py

@@ -0,0 +1,202 @@
+"""Bookkeeping account MCP tools."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastmcp.tools import tool
+from nocfo_toolkit.mcp.curated.confirmation import confirm_mutation
+from nocfo_toolkit.mcp.curated.runtime import business_slug, get_client
+from nocfo_toolkit.mcp.curated.schemas import (
+    AccountActionInput,
+    AccountListItem,
+    AccountListInput,
+    AccountNumberInput,
+    AccountPayloadInput,
+    AccountRetrieveInput,
+    AccountSummary,
+    ActionResponse,
+    DeletedResponse,
+    ListEnvelope,
+    PayloadInput,
+    dump_model,
+    dump_model_from_backend,
+)
+from nocfo_toolkit.mcp.curated.utils import decode_tool_handle
+
+
+account_fields = (
+    "number",
+    "name",
+    "type",
+    "description",
+    "is_shown",
+    "is_used",
+    "balance",
+    "header_id",
+    "header_path",
+    "default_vat_code",
+    "default_vat_rate",
+)
+
+
+@tool(
+    name="bookkeeping_accounts_list",
+    description="List bookkeeping accounts by account number, account range, name query, type, usage, or visibility. Use account numbers when talking with users.",
+    output_schema=ListEnvelope[AccountListItem].model_json_schema(),
+)
+async def bookkeeping_accounts_list(params: AccountListInput) -> dict[str, Any]:
+    args = params
+    slug = await business_slug(args.business)
+    return await get_client().list_page(
+        f"/v1/business/{slug}/account/",
+        params=args.query_params(),
+        cursor=args.cursor,
+        limit=args.limit,
+        business_slug=slug,
+        fields=account_fields,
+        item_model=AccountListItem,
+        handle_resource="bookkeeping_account",
+        usage_hint="For account number lookup (e.g. 1910), set number filter and then use tool_handle with bookkeeping_account_retrieve.",
+    )
+
+
+@tool(
+    name="bookkeeping_account_retrieve",
+    description="Retrieve one account from bookkeeping_accounts_list.items[].tool_handle.",
+)
+async def bookkeeping_account_retrieve(
+    params: AccountRetrieveInput,
+) -> dict[str, Any]:
+    args = params
+    slug = await business_slug(args.business)
+    account_id = decode_tool_handle(
+        args.tool_handle,
+        expected_resource="bookkeeping_account",
+    )
+    result = await get_client().request(
+        "GET",
+        f"/v1/business/{slug}/account/{account_id}/",
+        business_slug=slug,
+    )
+    return dump_model_from_backend(AccountSummary, result)
+
+
+@tool(
+    name="bookkeeping_account_create",
+    description="Create a bookkeeping account. Use account numbers and account names that match the user request.",
+)
+async def bookkeeping_account_create(params: PayloadInput) -> dict[str, Any]:
+    args = params
+    slug = await business_slug(args.business)
+    path = f"/v1/business/{slug}/account/"
+    await confirm_mutation(
+        business=slug,
+        tool_name="bookkeeping_account_create",
+        target_resource={
+            "type": "account",
+            "id": str(args.payload.get("number") or args.payload.get("name") or "new"),
+        },
+        parameters=args.payload,
+    )
+    result = await get_client().request(
+        "POST",
+        path,
+        json_body=args.payload,
+        business_slug=slug,
+    )
+    return dump_model_from_backend(AccountSummary, result)
+
+
+@tool(
+    name="bookkeeping_account_update",
+    description="Update a bookkeeping account selected by account_number.",
+)
+async def bookkeeping_account_update(params: AccountPayloadInput) -> dict[str, Any]:
+    args = params
+    slug = await business_slug(args.business)
+    account_id = await get_client().resolve_id(
+        f"/v1/business/{slug}/account/",
+        lookup_field="number",
+        lookup_value=args.account_number,
+        business_slug=slug,
+    )
+    path = f"/v1/business/{slug}/account/{account_id}/"
+    await confirm_mutation(
+        business=slug,
+        tool_name="bookkeeping_account_update",
+        target_resource={
+            "type": "account",
+            "id": account_id,
+        },
+        parameters=args.payload,
+    )
+    result = await get_client().request(
+        "PATCH",
+        path,
+        json_body=args.payload,
+        business_slug=slug,
+    )
+    return dump_model_from_backend(AccountSummary, result)
+
+
+@tool(
+    name="bookkeeping_account_delete",
+    description="Delete a bookkeeping account selected by account_number.",
+)
+async def bookkeeping_account_delete(params: AccountNumberInput) -> dict[str, Any]:
+    args = params
+    slug = await business_slug(args.business)
+    account_id = await get_client().resolve_id(
+        f"/v1/business/{slug}/account/",
+        lookup_field="number",
+        lookup_value=args.account_number,
+        business_slug=slug,
+    )
+    path = f"/v1/business/{slug}/account/{account_id}/"
+    await confirm_mutation(
+        business=slug,
+        tool_name="bookkeeping_account_delete",
+        target_resource={
+            "type": "account",
+            "id": account_id,
+        },
+    )
+    await get_client().request(
+        "DELETE",
+        path,
+        business_slug=slug,
+    )
+    return dump_model(DeletedResponse(account_number=args.account_number))
+
+
+@tool(
+    name="bookkeeping_account_action",
+    description="Show or hide a bookkeeping account selected by account_number.",
+)
+async def bookkeeping_account_action(params: AccountActionInput) -> dict[str, Any]:
+    args = params
+    slug = await business_slug(args.business)
+    account_id = await get_client().resolve_id(
+        f"/v1/business/{slug}/account/",
+        lookup_field="number",
+        lookup_value=args.account_number,
+        business_slug=slug,
+    )
+    path = f"/v1/business/{slug}/account/{account_id}/{args.action.value}/"
+    await confirm_mutation(
+        business=slug,
+        tool_name="bookkeeping_account_action",
+        target_resource={
+            "type": "account",
+            "id": account_id,
+        },
+    )
+    await get_client().request(
+        "POST",
+        path,
+        business_slug=slug,
+    )
+    return dump_model(
+        ActionResponse(account_number=args.account_number, action=args.action.value)
+    )