Jakob WennbergandClaude Opus 4.8
43007fa869
* feat(mcp): make the agent surface self-describing (staging _meta, company identity, clean summaries)
A pass over the MCP server's agent-facing surface so an agent can act
correctly without parsing description prose:
- Machine-readable staging contract: deriveToolMeta() attaches _meta to
tools/list (and search detail=full) — { requires_approval, approve_tool,
preflight? } — keyed off the STAGED_OPERATION_SCHEMA output schema. Literal
_meta (e.g. UI widget hints) wins on collision. TOOL_PREFLIGHT_MAP names the
read-only pre-flight for the few writes that have one (year-end readiness,
VAT validate, depreciation proposal). Guarded by staging-meta.test.ts.
- Company identity in gnubok_get_agent_briefing: returns a `company` block
(id, name, org_number, entity_type, accounting_method) so the agent can
confirm WHICH entity it operates on and pick the right settlement account
(accrual = credit 1510; cash = debit 19xx) before any write. Best-effort —
a missing row never blocks the briefing. Covered by agent-briefing.test.ts.
- toSummary(): trims the long, keyword-stuffed SKILL.md frontmatter into clean
one-liners for gnubok_list_skills / gnubok_get_agent_briefing so the client
never truncates one mid-sentence; full bodies stay in gnubok_load_skill.
Covered by to-summary.test.ts.
- bank-reconciliation skill: a match/link decision tree (what you have x
whether a verifikat exists) and kontant- vs faktureringsmetoden settlement
accounts.
- Prose/description clarifications: "Stages"/"Stages for approval" on the
link tools; propose_dispositioner/accruals note there is no dedicated MCP
poster; server-info documents _meta and the legacy gnubok_ tool prefix.
All 34 touched MCP tests pass. Merged cleanly on top of #759/#760 (server.ts).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(mcp): make accounting_method description state the full settlement posting
Review (swedish-accounting-compliance): the agent-briefing schema described
accrual as "credit 1510 on payment", which reads as a one-sided entry. Spell
out both sides (payment debits 19xx AND credits 1510) so an agent can't infer a
single-leg posting that violates BFL 5 kap double-entry. Mirrors the precision
already in the bank-reconciliation skill body. Payload-size guard still passes.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
3.6 KiB
3.6 KiB
paths
| paths | ||
|---|---|---|
|
MCP Server
Accounted exposes its bookkeeping engine as an MCP server for Claude Desktop/Code.
MCP extension (extensions/general/mcp-server/): 90+ tools covering transactions, categorization, customers/suppliers, invoices, accounts, fiscal periods, reports (trial balance, GL, BS, IS, AR/supplier ledger, VAT, KPI), reconciliation, salary runs, AGI, year-end, document upload, and loadable skills. JSON-RPC 2.0. Endpoint: /api/extensions/ext/mcp-server/mcp.
OAuth 2.1 for Claude connectors: .well-known/oauth-protected-resource + .well-known/oauth-authorization-server discovery; /api/mcp-oauth/authorize, /token (PKCE), /register. Stateless AES-256-GCM auth codes (lib/auth/oauth-codes.ts). Single-use via oauth_used_codes. Allowlist: claude.ai/api/*, claude.com/api/*, localhost.
npm package (packages/gnubok-mcp): Stdio-to-HTTP bridge; users run npx gnubok-mcp with API key.
Tool authoring conventions (enforced by tests)
- Every
inputSchemamust declareadditionalProperties: falseat the top level. Guarded byextensions/general/mcp-server/__tests__/strict-schemas.test.ts. - Tool descriptions must be ≤ 280 chars (guarded by
output-schema.test.ts). NoArgs:/Returns:/Examples:blocks — those belong in JSON Schema, not description prose. Use agent-native hints like "Use to…" / "Call X first" instead. - Completion-signal pattern: tools that stage operations return
STAGED_OPERATION_SCHEMA—{ staged, risk_level, actor, message, preview, period_status?, next? }. Thestaged: trueboolean is the explicit completion signal; agents must not infer completion from prose. Do NOT introduce a parallel{ success, shouldContinue, output }envelope. - Machine-readable staging contract:
tools/list(andgnubok_search_toolsdetail=full) attach a derived_metato staging writes so an agent knows the contract WITHOUT reading prose.deriveToolMeta()keys offoutputSchema === STAGED_OPERATION_SCHEMAand emits{ requires_approval: true, approve_tool: 'gnubok_approve_pending_operation', preflight? }; it merges under any literal_meta(e.g. UI widget hints), which wins on collision. Add toTOOL_PREFLIGHT_MAPwhen a write has a genuine read-only pre-flight (e.g.gnubok_run_year_end→gnubok_year_end_readiness). A new staging tool inherits_metafor free — just keep its description declaring it stages (guarded by__tests__/staging-meta.test.ts).confirmed=truebelongs on the APPROVE call for high-risk ops, never on the staging tool; only some tools acceptdry_run/idempotency_key— never imply they are universal. - Skill/atom summaries:
gnubok_list_skillsandgnubok_get_agent_briefingpass registrydescriptionfields throughtoSummary()(skills/atoms.ts) — the raw SKILL.md frontmatter is a long keyword-stuffed trigger list authored for CLI matching, not display copy, and gets truncated mid-sentence otherwise. Full bodies are fetched viagnubok_load_skill. The local.claude/skills/*are the Claude-Code surface; theagent_atom_registryrows seeded from the same bodies are the canonical connector surface — when they overlap, the connector atom is authoritative for MCP users. - Tools that touch a fiscal-period-bound date (categorize, mark paid, create voucher, correct/reverse entry, approve supplier invoice) pass
dateForPeriodChecktostagePendingOperationso the response includesperiod_status: { period_id, status: open|locked|closed, lock_date }. Widgets and agents use this to disable writes without round-trips.