admin/accounted
3
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
dfed55cb6c34e976ac63009d06bed2cc848ca2b2
accounted/extensions/general/mcp-server
T
History
Jakob WennbergClaude Fable 5Jakob Wennberg
 dae0aac26a fix(mcp): reconcile_match callable + two-phase efterkontroll + instant value for web-onboarded users (#1967) 
* docs(plugin): starter prompt nudges the connector's onboarding guide

Several E2E runs composed the first reply from tool descriptions before
the skill loaded (questionnaire instead of the guided round). Four words
in the published prompt point the agent at the guide from message one;
the rest of the prompt stays memory-first and universal.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(mcp): reconcile_match into the default catalog + two-phase efterkontroll + instant value for web-onboarded users

E2E #12 (the smoothest run yet) surfaced three things:

1. gnubok_reconcile_match was search-only, so Claude.ai could not call
   it: the agent misread the uncallable tool as a missing
   reconciliation:write scope and punted the entire dont-double-book
   matching step to the web app. Promoted to the default catalog
   (the standing rule: skill-instructed tools must be callable);
   ceiling 63K to 63.4K documented.

2. Skill: efterkontroll split into two phases per founder direction.
   Step 3b runs DIRECTLY after the import commits: verify the trial
   balance, sanity-read the content, and PREPARE the chart (create
   1630/8423/8314/6992 when the SIE lacks them) so the bank and
   Skatteverket connections land in a book that is ready for them.
   Step 4b after the connections: match SIE-covered bank rows with
   reconcile_match (never re-categorize), reconcile skattekontot to the
   öre, names, underlag, in a prioritized numbered list.

3. Skill: users who onboarded via the web app and connect the MCP with
   everything already set up get the reconciliation pass and Att
   göra-list as the FIRST reply instead of setup steps: immediate value
   regardless of onboarding path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-26 23:04:57 +02:00
..
__tests__
fix(mcp): reconcile_match callable + two-phase efterkontroll + instant value for web-onboarded users (#1967)
2026-08-26 23:04:57 +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
fix(mcp): reconcile_match callable + two-phase efterkontroll + instant value for web-onboarded users (#1967)
2026-08-26 23:04:57 +02:00
widgets
fix(bank): 90-day lookback is the default: long PSD2 requests make some banks kill the session (#1964)
2026-08-26 22:36:06 +02:00
arg-guard.ts
fix(mcp): bulk-book titles that say what is approved, reject unknown parameters (#1856)
2026-08-25 10:44:30 +02:00
company-routing.ts
feat(mcp): org-number-first onboarding: gnubok_lookup_company prefills the company from the registry (#1940)
2026-08-26 13:03:02 +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
fix(mcp): honest tool text and build-derived server version (#1923)
2026-08-26 13:35:15 +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
public-tools.ts
feat(mcp): lazy authentication so a client can connect before an account exists (#1814 PR 2) (#1892)
2026-08-25 11:38:29 +02:00
README.md
docs(api,mcp): tool counts, changelog backfill, version-header honesty, lazy auth, endpoint map (#1929)
2026-08-26 13:35:54 +02:00
recommended-tools.ts
feat(mcp): gnubok_reconcile_residual stages residual booking + link on a bank account (#1872)
2026-08-25 09:03:43 +02:00
server.ts
fix(mcp): reconcile_match callable + two-phase efterkontroll + instant value for web-onboarded users (#1967)
2026-08-26 23:04:57 +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 (the SDK is called from lib/ai/provider.ts and lib/ai/services/anthropic-family.ts; features such as extensions/general/invoice-inbox/lib/extract-invoice-fields.ts go through getAiService() in lib/ai rather than the SDK directly): 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, registered in resources/index.ts: company/current, period/active, recent-activity, capabilities, attention, chart-of-accounts, settings/vat-treatments, booking-templates, ledger/context, reconciliation/summary
  • widgets/: inline HTML widgets (receipt-matcher, vat-review, pending-operations)
  • prompts/: slash-command-style prompts
  • skills/: domain-knowledge skill bodies served via gnubok_load_skill
  • public-tools.ts: lazy authentication (issue #1814). ANONYMOUS_METHODS (initialize, ping, tools/prompts/resources listing) and the three PUBLIC_TOOLS (gnubok_search_tools, gnubok_list_skills, gnubok_load_skill) answer without credentials, rate-limited per truncated IP; every other tools/call gets a transport-level 401 + WWW-Authenticate from handleMcpRequest in server.ts, which is the challenge clients turn into their Connect prompt
  • tasks.ts: MCP Tasks extension (io.modelcontextprotocol/tasks): durable handles for long-running tool calls, rows in mcp_tasks (service-role writes only)
  • origin-guard.ts: Origin-header validation on the Streamable HTTP endpoint (DNS-rebinding defence required by the MCP spec)
  • staging-pii-guard.ts: refuses a plaintext personnummer in staged pending_operations params/preview, so every staging tool inherits the encrypt-at-staging rule
  • tool-namespace.ts: ?tool_namespace=accounted handling (accounted_* aliases for the canonical gnubok_* ids)
  • __tests__/: strictness guards + per-tool coverage
Reference in New Issue View Git Blame Copy Permalink