From 1f48585a29032f21f60188db4fe11a3bfeaebe19 Mon Sep 17 00:00:00 2001 From: Ricardo Canales Date: Tue, 23 Jun 2026 23:59:04 -0700 Subject: [PATCH] docs(mcp): sync mcp-tools-reference.md to the real 35-tool registry The reference documented ~15 tools that no longer exist (drift inherited from main, predating the consolidation). Align it with the registry: - Remove phantom sections: categorize_transaction, reset_transaction_category, batch_categorize_transactions, bulk_recategorize, import_categories, add_transaction_tag, remove_transaction_tag, add_transaction_comment, list_transaction_comments, create_session, trigger_sync, and the whole account-link + match family. - Drop the stale "call create_session first" Sessions guidance (sessions are automatic now) and the series `tags` mentions (series tags removed in #1918). - Add the missing set_transaction_metadata section. Documented tools now match the registry exactly (35/35). Docs-only. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01Y7qg4TN9ZPcHsXR714UrjG --- docs/mcp-tools-reference.md | 164 +++++------------------------------- 1 file changed, 21 insertions(+), 143 deletions(-) diff --git a/docs/mcp-tools-reference.md b/docs/mcp-tools-reference.md index 855a735b..46751f55 100644 --- a/docs/mcp-tools-reference.md +++ b/docs/mcp-tools-reference.md @@ -18,7 +18,7 @@ Every tool response is also subject to a **byte cap** (default ~100 KB ≈ 25K t ## Sessions -Before using any tools, agents should call `create_session` to establish a session. This provides the agent with dataset context and server instructions. +Audit sessions are automatic — there is **no** `create_session` tool. Every tool call is logged under a session keyed off your transport connection (the `MCP-Session-Id` header for HTTP, a per-process id for stdio), lazy-created on your first call. To label a specific call, pass an optional `reason` string in `tools/call._meta`. Read `get_overview` at the start of a session for dataset context. --- @@ -125,76 +125,9 @@ Read this to see what runs automatically before proposing new rules or reports --- -## Categorization Tools +## Transaction Writes & Annotations -### categorize_transaction (Write) - -Set a transaction's category. Creates a category override. - -| Parameter | Type | Description | -|-----------|------|-------------| -| `transaction_id` | string | Transaction ID (8-char short ID or UUID) | -| `category_slug` | string | Category slug (e.g., `food_and_drink_groceries`) | - -### reset_transaction_category (Write) - -Remove a transaction's category override, reverting to the provider's original category. - -| Parameter | Type | Description | -|-----------|------|-------------| -| `transaction_id` | string | Transaction ID | - -### batch_categorize_transactions (Write) - -Categorize multiple transactions at once. Max 500 items per call. - -| Parameter | Type | Description | -|-----------|------|-------------| -| `items` | array | Array of `{ transaction_id, category_slug }` pairs | - -### bulk_recategorize (Write) - -Server-side UPDATE of all transactions matching filters. Requires at least one filter for safety. Moves transactions matching `from_category` (and other filters) to `to_category`. - -| Parameter | Type | Description | -|-----------|------|-------------| -| `to_category` | string | Destination category slug (required) | -| `from_category` | string | Optional source category slug filter | -| Plus filters | | Same as `query_transactions` | -| `target_category_slug` | string | Deprecated — use `to_category` | -| `category_slug` | string | Deprecated — use `from_category` | - -### import_categories (Write) - -Import categories from TSV format. Creates or updates categories. - ---- - -## Tag & Annotation Tools - -### list_tags (Read) - -The tag vocabulary — see **Reference Data Tools → `list_tags`** above. - -### add_transaction_tag (Write) - -Attach a tag to a transaction. Auto-creates a persistent tag if the slug is unknown. Idempotent. - -| Parameter | Type | Description | -|-----------|------|-------------| -| `transaction_id` | string | UUID or short ID | -| `tag_slug` | string | Tag slug | -| `note` | string | Optional rationale (recorded on the `tag_added` annotation) | - -### remove_transaction_tag (Write) - -Remove a tag from a transaction. An optional `note` lands on the `tag_removed` annotation. Idempotent. - -| Parameter | Type | Description | -|-----------|------|-------------| -| `transaction_id` | string | UUID or short ID | -| `tag_slug` | string | Tag slug | -| `note` | string | Optional rationale for removal — recorded on the audit trail. | +Per-transaction writes — category, tags, comments, flags, and metadata — all flow through `update_transactions` and `set_transaction_metadata`. There are no single-purpose `categorize_transaction` / `add_transaction_tag` / `flag_transaction` tools; they were folded into `update_transactions`. ### update_transactions (Write) @@ -218,6 +151,19 @@ Each operation: Use this to close a review entry: `set category + remove needs-review (with note) + comment` in one call. +### set_transaction_metadata (Write) + +Write a transaction's free-form metadata JSONB store — household enrichment that isn't a first-class field (NOT a substitute for category or tags). Returned on every transaction read. Keys are slug-like (max 128 chars); values may be any JSON. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `transaction_id` | string | UUID or short ID. Required. | +| `set` | object | Key→value pairs to upsert. **Merged** by default — keys you don't list stay untouched. | +| `unset` | array | Keys to delete (no-op if absent). Applied after `set`. | +| `replace` | bool | When `true`, the result is **exactly** the `set` object (clears every pre-existing key first). `replace:true` with `set` omitted clears all metadata. | + +Folds the former `remove_transaction_metadata` / `replace_transaction_metadata` / `clear_transaction_metadata` tools. + ### list_annotations (Read) Return the activity timeline for a transaction. Rows are returned in a `{ "annotations": [...] }` envelope (the MCP `structuredContent` slot requires a JSON record, not a bare array — mirrors the REST `/transactions/{id}/annotations` shape). Each row carries a generic `kind` plus an `action` for the specific event: @@ -261,7 +207,7 @@ Branch on `action` when the add-vs-remove distinction matters (e.g. building a t ### create_tag / update_tag / delete_tag (Write) -Admin-only tag CRUD. Agents typically don't need these — `add_transaction_tag` auto-creates tags on demand. Use these to set display name, color, or cascade-delete a tag. +Admin-only tag CRUD. Agents typically don't need these — `update_transactions` auto-creates a tag when an operation's `tags_to_add` references an unknown slug. Use these to set display name, color, or cascade-delete a tag. --- @@ -269,11 +215,11 @@ Admin-only tag CRUD. Agents typically don't need these — `add_transaction_tag` ### list_series (Read) -List recurring series — thin, rule-maintained entities: each is a surrogate identity (`id`/`short_id`), a `name`, and a `type` (`subscription` | `bill` | `loan` | `other`), plus its `tags`. Membership comes from `assign_series` rules, not a shipped detector. **Lean by default** (`fields` omitted → `overview` projection: `name`, `type`, `tags`); pass `fields=all` for timestamps. Get a series' charges via `query_transactions(series_id=...)`. +List recurring series — thin, rule-maintained entities: each is a surrogate identity (`id`/`short_id`), a `name`, and a `type` (`subscription` | `bill` | `loan` | `other`). Membership comes from `assign_series` rules, not a shipped detector. **Lean by default** (`fields` omitted → `name`, `type`); pass `fields=all` for timestamps. Get a series' charges via `query_transactions(series_id=...)`. ### get_series (Read) -Get one series by short ID or UUID: its `name`, `type`, and `tags`. A series' linked charges come from `query_transactions(series_id=...)`; its governing rules (the `assign_series` rules that define its membership) are visible on the admin Recurring detail page. +Get one series by short ID or UUID: its `name` and `type`. A series' linked charges come from `query_transactions(series_id=...)`; its governing rules (the `assign_series` rules that define its membership) are visible on the admin Recurring detail page. ### assign_series (Write) @@ -281,7 +227,7 @@ Link transactions to a recurring series, creating it if needed — the agent's p ### update_series (Write) -Edit a recurring series in one call: its `name`, `type` (`subscription` | `bill` | `loan` | `other`), and tag membership (`tags_to_add` / `tags_to_remove`). Every field optional — omit to leave unchanged. Renaming onto an existing live series name is rejected (the name is the series' unique mint key). Tags must already exist (`create_tag`); an added tag is materialized onto every linked charge and applied to future members, a removed tag strips the series-inherited copies (a tag a user added directly to a charge survives). +Edit a recurring series' `name` and/or `type` (`subscription` | `bill` | `loan` | `other`). Both optional — omit to leave unchanged. Renaming onto an existing live series name is rejected (the name is the series' unique mint key). ### unlink_series_transactions (Write) @@ -447,63 +393,7 @@ Rule 2 sees rule 1's `coffee` tag mid-sync; rule 3 sees both the tag and (if we' --- -## Account Link Tools - -Account links connect authorized user cards to primary cardholder accounts for transaction deduplication. - -### list_account_links (Read) - -List all account links with match statistics. - -### create_account_link (Write) - -Create a link between a dependent and primary account. Auto-runs initial reconciliation. - -| Parameter | Type | Description | -|-----------|------|-------------| -| `dependent_account_id` | string | The authorized user's account | -| `primary_account_id` | string | The cardholder's account | - -### delete_account_link (Write) - -Delete an account link by ID. - -### reconcile_account_link (Write) - -Re-run matching for a specific link. - -### list_transaction_matches (Read) - -List matched transaction pairs for a link. - -| Parameter | Type | Description | -|-----------|------|-------------| -| `account_link_id` | string | Account link ID | - -### confirm_match (Write) - -Confirm a matched transaction pair is correct. - -### reject_match (Write) - -Reject a matched transaction pair. - ---- - -## Comment & Report Tools - -### add_transaction_comment (Write) - -Add a comment to a transaction. - -| Parameter | Type | Description | -|-----------|------|-------------| -| `transaction_id` | string | Transaction ID | -| `body` | string | Comment text | - -### list_transaction_comments (Read) — Deprecated - -Deprecated: prefer `list_annotations` with `kinds=['comment']`. Returns the same comment data with renamed fields (`author_*` instead of `actor_*`, `content` lifted out of `payload`). Will be removed in a future release. +## Reports ### submit_report (Write) @@ -516,18 +406,6 @@ Submit a report for human review. Reports appear on the admin dashboard. --- -## Sync & Session Tools - -### create_session (Write) - -Establish a session. Returns dataset context (users, accounts, connection status, pending transaction count) and server instructions. Call this first. - -### trigger_sync (Write) - -Trigger a manual sync for all active connections. - ---- - ## Resources Breadbox exposes **no MCP resources** — they were retired entirely (invisible on clients that can't `resources/list`). Everything is a tool: