admin/accounted
3
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2e669a64e3ec0fac4d4d37ae98055bf223890c22
accounted/extensions/general/mcp-server
T
History
Jakob WennbergJakob WennbergClaude Fable 5
 2860cd51b1 fix(mcp): vat_amount in transaction currency + nullable matched_supplier_id (#1842) 
Two MCP-agent-reported bugs (feedback seq 254607, 261972; also reported
by mail):

- categorize_transaction validated vat_amount against the transaction-
  currency gross but posted the raw figure as SEK: a 15.87 USD override
  on a 79.34 USD Stripe payment booked 15.87 kr to 2611 instead of
  ~150.92 kr, and the entry still balanced so nothing could catch it.
  buildMappingResultFromCategory now resolves the same SEK value the
  line builder uses for the gross and books ALL VAT figures off it:
  the override (scaled by the settlement ratio), the auto-derived rate
  VAT, and reverse-charge fiktiv moms, which had the same defect for
  every foreign-currency transaction. SEK transactions are unchanged.
  The vat_amount schema now states the denomination; the override
  bound error names the currency.

- complete_document_upload / upload_document declared
  matched_supplier_id as a bare string while unmatched uploads
  correctly return null, so strict clients failed every successful
  unmatched upload and tripped the caller's circuit breaker. The
  schema is now ['string', 'null'], matching the runtime.

Catalog token ceiling 59.9K -> 59.95K per the documented ratchet
protocol (prose trimmed to the floor first; headroom was ~19 tokens).


Claude-Session: https://claude.ai/code/session_01ScVhg6XsDtNXkiEQNV7LaZ

Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-24 14:43:52 +02:00
..
__tests__
fix(mcp): vat_amount in transaction currency + nullable matched_supplier_id (#1842)
2026-08-24 14:43:52 +02:00
prompts
style: remove em/en dashes repo-wide, add CLAUDE.md rule against them (#890)
2026-07-04 15:58:06 +02:00
resources
feat(reconciliation): agent surfaces, skattekonto notice, bank icons and fair sync order (#1836)
2026-08-24 14:08:53 +02:00
skills
feat(reconciliation): agent surfaces, skattekonto notice, bank icons and fair sync order (#1836)
2026-08-24 14:08:53 +02:00
widgets
feat(mcp): approval-queue MCP Apps widget for staged operations (#1278)
2026-07-29 18:02:17 +02:00
company-routing.ts
feat(reconciliation): sign-off, period picker, Hem row and the three doors for it (#1835)
2026-08-24 14:07:58 +02:00
dimensions.ts
style: remove em/en dashes repo-wide, add CLAUDE.md rule against them (#890)
2026-07-04 15:58:06 +02:00
index.ts
style: remove em/en dashes repo-wide, add CLAUDE.md rule against them (#890)
2026-07-04 15:58:06 +02:00
manifest.json
Bug/invalid imports (#1146)
2026-07-24 15:03:50 +02:00
origin-guard.ts
style: remove em/en dashes repo-wide, add CLAUDE.md rule against them (#890)
2026-07-04 15:58:06 +02:00
README.md
Bug/invalid imports (#1146)
2026-07-24 15:03:50 +02:00
recommended-tools.ts
feat(reconciliation): agent surfaces, skattekonto notice, bank icons and fair sync order (#1836)
2026-08-24 14:08:53 +02:00
server.ts
fix(mcp): vat_amount in transaction currency + nullable matched_supplier_id (#1842)
2026-08-24 14:43:52 +02:00
staging-pii-guard.ts
fix(customers): personnummer via MCP lands in personal_number, masked everywhere; MCP payment terms follow settings (#1788)
2026-08-21 18:32:17 +02:00
supplier-candidates.ts
fix(inbox): match suppliers on VAT number, not just org-nr and name (#1630)
2026-08-17 14:52:50 +02:00
tasks.ts
feat(mcp): Tasks extension (io.modelcontextprotocol/tasks) (#1283)
2026-07-29 18:15:06 +02:00
tool-namespace.ts
Bug/invalid imports (#1146)
2026-07-24 15:03:50 +02:00
tool-result.ts
style: remove em/en dashes repo-wide, add CLAUDE.md rule against them (#890)
2026-07-04 15:58:06 +02:00

README.md

Accounted MCP server

JSON-RPC 2.0 server exposing the Accounted bookkeeping engine to MCP clients (Claude Desktop, Claude Code, etc.). Endpoint: /api/extensions/ext/mcp-server/mcp. Add ?tool_namespace=accounted for the Accounted tool names. Requests without it retain the legacy Gnubok namespace. OAuth and stdio bridges live alongside the API surface: see app/api/mcp-oauth/, packages/accounted-mcp/, and the compatibility package in packages/gnubok-mcp/.

Tool authoring contract

Enforced by tests in __tests__/: these are not style preferences, they're guard rails.

  1. additionalProperties: false on every inputSchema. Guarded by strict-schemas.test.ts. Forces clear rejections on hallucinated fields instead of silent ignores.
  2. Descriptions ≤ 280 chars. Guarded by output-schema.test.ts. No Args: / Returns: / Examples: prose: those belong in JSON Schema. Use agent-native hints ("Use to…", "Call X first", "HIGH risk").
  3. Staged-operation envelope for write tools: outputSchema: STAGED_OPERATION_SCHEMA (server.ts). Fields: staged, risk_level, actor, message, preview, period_status?, next?. The staged: true boolean is the explicit completion signal; agents must not infer completion from prose. Do NOT introduce a parallel { success, shouldContinue, output } envelope.
  4. period_status threading: any tool that ties to a fiscal-period-bound date (categorize, mark paid, create voucher, correct/reverse entry, approve supplier invoice) passes dateForPeriodCheck to stagePendingOperation. Response then includes period_status: { period_id, status: open|locked|closed, lock_date } so widgets and agents disable writes without round-trips.
  5. Scope mapping: every new tool needs an entry in lib/auth/api-keys.ts TOOL_SCOPE_MAP. Missing entries default to deny.
  6. Tests for new write tools: add staging-gate coverage to __tests__/voucher-tools.test.ts (or a sibling) plus executor coverage to lib/pending-operations/__tests__/voucher-executors.test.ts if the tool stages a new operation_type.

Determinism / cache stability

Tool definitions (name, description, inputSchema, outputSchema, annotations) are declared as static object literals at module load: no timestamps, no UUIDs, no Date/Math.random in the definition layer. This makes the tools/list JSON payload byte-stable across requests, which lets agent-side prompt caches stay warm. Do not introduce per-request non-determinism into the definitions block. Anything time-bound or random belongs inside execute().

For internal Anthropic API usage (today only extensions/general/invoice-inbox/lib/extract-invoice-fields.ts): annotate stable prefixes with cache_control: { type: 'ephemeral' } and log usage.cache_read_input_tokens for hit-ratio observability. The 1h TTL from the agent-native API plan (item 10) requires the direct Anthropic API; Accounted's Bedrock path defaults to a shorter TTL.

Payload-size watchdog

payload-size.bench.test.ts enforces a tools/list JSON payload ceiling. If the test fires, the right answer is rarely "raise the ceiling". Instead, trim descriptions or set specialized wide tools to catalogVisibility: 'search'. Those tools remain discoverable with full schemas through gnubok_search_tools and callable through tools/call without bloating the default catalog.

Where things live

  • server.ts: the tools array + JSON-RPC dispatcher
  • tool-result.ts: withNext(), toToolError() response helpers
  • resources/: read-only Accounted:// URIs (active company, period, recent activity, capabilities, attention items, voucher gaps, chart of accounts, VAT treatments)
  • widgets/: inline HTML widgets (receipt-matcher, vat-review)
  • prompts/: slash-command-style prompts
  • skills/: domain-knowledge skill bodies served via gnubok_load_skill
  • __tests__/: strictness guards + per-tool coverage
Reference in New Issue View Git Blame Copy Permalink