nocfo-cli 1.7.2__tar.gz → 1.9.0__tar.gz

{nocfo_cli-1.7.2 → nocfo_cli-1.9.0}/PKG-INFO

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

{nocfo_cli-1.7.2 → nocfo_cli-1.9.0}/pyproject.toml

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

nocfo_cli-1.9.0/src/nocfo_toolkit/mcp/curated/batch.py

@@ -0,0 +1,95 @@
+"""Sequential, best-effort batch runner for mutating curated MCP tools.
+
+One tool call targets many resources, so one confirmation covers the whole batch.
+Each target runs the tool's existing single-target logic; a failing target is
+captured as a failed result instead of aborting the batch.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any
+
+from fastmcp.exceptions import ToolError
+
+from nocfo_toolkit.mcp.curated.errors import raise_tool_error
+from nocfo_toolkit.mcp.curated.schemas import (
+    BatchItemResult,
+    BatchResponse,
+    ToolErrorPayload,
+    dump_model,
+)
+
+
+def _error_payload(exc: ToolError) -> ToolErrorPayload:
+    raw = exc.args[0] if exc.args else str(exc)
+    try:
+        data = json.loads(raw)
+    except (TypeError, ValueError):
+        data = None
+    if isinstance(data, dict):
+        try:
+            return ToolErrorPayload.model_validate(data)
+        except Exception:  # noqa: BLE001 - fall back to a plain message payload
+            pass
+    return ToolErrorPayload(error_type="tool_error", message=str(raw))
+
+
+async def run_batch(
+    targets: Sequence[Any],
+    handler: Callable[[Any], Awaitable[dict[str, Any]]],
+    *,
+    label: Callable[[Any], Any] = lambda target: target,
+) -> dict[str, Any]:
+    """Run ``handler`` for each target, aggregating per-target results.
+
+    ``handler`` returns the same dict a single-target tool would return.
+    ``label`` maps a target to the value echoed back in ``results[].target``.
+    """
+    if not targets:
+        raise_tool_error(
+            "invalid_request",
+            "No targets provided for this batch operation.",
+            "Provide at least one target (id, number, tool_handle, or payload).",
+            status_code=400,
+        )
+    results: list[BatchItemResult] = []
+    for target in targets:
+        # Resolve the echo key once, fault-isolated, so a misbehaving label callable
+        # can never abort the batch or mislabel a target across branches.
+        try:
+            key = label(target)
+        except Exception:  # noqa: BLE001 - labelling must never abort the batch
+            key = None
+        try:
+            payload = await handler(target)
+            results.append(BatchItemResult(ok=True, target=key, result=payload))
+        except ToolError as exc:
+            results.append(
+                BatchItemResult(ok=False, target=key, error=_error_payload(exc))
+            )
+        except Exception as exc:  # noqa: BLE001 - isolate unexpected per-target failures
+            # Keep the batch best-effort: a non-ToolError (e.g. response validation
+            # or transport error) on one target must not discard the results of the
+            # targets already processed. CancelledError/KeyboardInterrupt are
+            # BaseException and intentionally still propagate.
+            results.append(
+                BatchItemResult(
+                    ok=False,
+                    target=key,
+                    error=ToolErrorPayload(
+                        error_type="internal_error",
+                        message=str(exc) or exc.__class__.__name__,
+                    ),
+                )
+            )
+    succeeded = sum(1 for item in results if item.ok)
+    return dump_model(
+        BatchResponse(
+            total=len(results),
+            succeeded=succeeded,
+            failed=len(results) - succeeded,
+            results=results,
+        )
+    )

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

@@ -0,0 +1,228 @@
+"""Bookkeeping account MCP tools."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastmcp.tools import tool
+from fastmcp.tools.tool import ToolAnnotations
+from nocfo_toolkit.mcp.curated.batch import run_batch
+from nocfo_toolkit.mcp.curated.runtime import business_slug, get_client
+from nocfo_toolkit.mcp.curated.schemas import (
+    AccountListItem,
+    AccountListInput,
+    AccountNumbersActionInput,
+    AccountNumbersInput,
+    AccountNumbersPayloadInput,
+    AccountRetrieveInput,
+    AccountSummary,
+    ActionResponse,
+    BatchResponse,
+    DeletedResponse,
+    ListEnvelope,
+    PayloadsInput,
+    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",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    ),
+    description="List bookkeeping accounts by account number, account range, name query, type, usage, or visibility. Use this first to ground exact account numbers/tool_handles before updating, deleting, showing, or hiding accounts. 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. Before update/delete/show/hide actions, ground the exact targets here "
+            "first and then batch the confirmed account numbers into one mutation call."
+        ),
+    )
+
+
+@tool(
+    name="bookkeeping_account_retrieve",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    ),
+    description="Retrieve one account from bookkeeping_accounts_list.items[].tool_handle. Use this to verify an account before updating, deleting, showing, or hiding it.",
+)
+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",
+    annotations=ToolAnnotations(
+        readOnlyHint=False,
+        destructiveHint=False,
+        idempotentHint=False,
+        openWorldHint=False,
+    ),
+    description="Create one or more bookkeeping accounts in a single call — pass each new account as an entry in payloads. Use account numbers and names that match the user request.",
+    output_schema=BatchResponse.model_json_schema(),
+)
+async def bookkeeping_account_create(params: PayloadsInput) -> dict[str, Any]:
+    slug = await business_slug(params.business)
+    path = f"/v1/business/{slug}/account/"
+
+    async def _create(payload: dict[str, Any]) -> dict[str, Any]:
+        result = await get_client().request(
+            "POST", path, json_body=payload, business_slug=slug
+        )
+        return dump_model_from_backend(AccountSummary, result)
+
+    return await run_batch(
+        params.payloads,
+        _create,
+        label=lambda payload: payload.get("number") or payload.get("name"),
+    )
+
+
+@tool(
+    name="bookkeeping_account_update",
+    annotations=ToolAnnotations(
+        readOnlyHint=False,
+        destructiveHint=False,
+        idempotentHint=False,
+        openWorldHint=False,
+    ),
+    description="Update one or more bookkeeping accounts selected by account_numbers; the same payload is applied to every account. Ground the exact account numbers first, then batch all confirmed targets into one call.",
+    output_schema=BatchResponse.model_json_schema(),
+)
+async def bookkeeping_account_update(
+    params: AccountNumbersPayloadInput,
+) -> dict[str, Any]:
+    slug = await business_slug(params.business)
+
+    async def _update(account_number: int) -> dict[str, Any]:
+        account_id = await get_client().resolve_id(
+            f"/v1/business/{slug}/account/",
+            lookup_field="number",
+            lookup_value=account_number,
+            business_slug=slug,
+        )
+        result = await get_client().request(
+            "PATCH",
+            f"/v1/business/{slug}/account/{account_id}/",
+            json_body=params.payload,
+            business_slug=slug,
+        )
+        return dump_model_from_backend(AccountSummary, result)
+
+    return await run_batch(params.account_numbers, _update)
+
+
+@tool(
+    name="bookkeeping_account_delete",
+    annotations=ToolAnnotations(
+        readOnlyHint=False,
+        destructiveHint=True,
+        idempotentHint=False,
+        openWorldHint=False,
+    ),
+    description="Delete one or more bookkeeping accounts in a single call — pass every target in account_numbers. Ground the exact account numbers first with bookkeeping_accounts_list and/or bookkeeping_account_retrieve, then batch all confirmed targets into one call. Never call this with guessed placeholders or an empty target set. Prefer one batched call over repeated single-target calls (each call needs its own confirmation).",
+    output_schema=BatchResponse.model_json_schema(),
+)
+async def bookkeeping_account_delete(params: AccountNumbersInput) -> dict[str, Any]:
+    slug = await business_slug(params.business)
+
+    async def _delete(account_number: int) -> dict[str, Any]:
+        account_id = await get_client().resolve_id(
+            f"/v1/business/{slug}/account/",
+            lookup_field="number",
+            lookup_value=account_number,
+            business_slug=slug,
+        )
+        await get_client().request(
+            "DELETE",
+            f"/v1/business/{slug}/account/{account_id}/",
+            business_slug=slug,
+        )
+        return dump_model(DeletedResponse(account_number=account_number))
+
+    return await run_batch(params.account_numbers, _delete)
+
+
+@tool(
+    name="bookkeeping_account_action",
+    annotations=ToolAnnotations(
+        readOnlyHint=False,
+        destructiveHint=False,
+        idempotentHint=False,
+        openWorldHint=False,
+    ),
+    description="Show or hide one or more bookkeeping accounts in a single call — pass every target in account_numbers and the same action applies to all. First obtain the exact account numbers from bookkeeping_accounts_list or bookkeeping_account_retrieve, then pass those values unchanged here. Prefer one batched call over repeated single-account calls.",
+    output_schema=BatchResponse.model_json_schema(),
+)
+async def bookkeeping_account_action(
+    params: AccountNumbersActionInput,
+) -> dict[str, Any]:
+    slug = await business_slug(params.business)
+
+    async def _act(account_number: int) -> dict[str, Any]:
+        account_id = await get_client().resolve_id(
+            f"/v1/business/{slug}/account/",
+            lookup_field="number",
+            lookup_value=account_number,
+            business_slug=slug,
+        )
+        await get_client().request(
+            "POST",
+            f"/v1/business/{slug}/account/{account_id}/{params.action.value}/",
+            business_slug=slug,
+        )
+        return dump_model(
+            ActionResponse(account_number=account_number, action=params.action.value)
+        )
+
+    return await run_batch(params.account_numbers, _act)