Jakob WennbergandClaude Sonnet 5
ec27228a8e
Em dashes (—) and en dashes (–) had spread across comments, docs, tests, and a few UI strings, reading as AI-generated boilerplate rather than house style. Replaced each with punctuation matching its context: colon for explanatory clauses, comma for asides, plain hyphen for numeric/legal ranges (e.g. "21-23§"), "to"/"till" for date ranges, parentheses for paired-dash asides. messages/en.json and messages/sv.json were fixed by hand together to keep sv/en in sync. Left untouched where the dash is the functional subject rather than decorative punctuation: date-range-parser.ts's separator regex, charset-repair.ts's CP1252 byte-mapping table (and its test), the SIE encoding mojibake docs, generic-csv.ts's minus-sign normalizer, the agent system-prompt files that already instruct against em dashes, and a golden iXBRL test fixture compared byte-for-byte. Also fixes two bugs surfaced along the way: an off-by-one in ApiKeysPanel's scope-label split (a leftover from an earlier partial pass), and a charset-repair test that had lost the literal en-dash it exists to verify. Regenerated the agent atom seed migration (skills:generate) since 27 SKILL.md files changed. Added a CLAUDE.md rule against em/en dashes, with an explicit carve-out for the functional-dash cases above. Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
4.9 KiB
4.9 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. - Qualified identifiers: no bare
idin tool OUTPUT schemas: every identifier is fully qualified (transaction_id,journal_entry_id,fact_id,dimension_value_id, …) so agents never guess which entity an id belongs to. Guarded by__tests__/qualified-ids.test.ts(a shrinking grandfathered list carries the deprecatedidaliases; new tools must use qualified names only). - Error envelope: every tool failure flows through the single dispatch point (
toToolError→getStructuredError) and returns{ error: { code, message_sv, message_en, retryable, remediation? } }.retryableis ALWAYS an explicit boolean:truemeans transient (back off and retry the identical call, pairing withidempotency_keywhere the tool accepts one);falsemeans permanent for these inputs (fix arguments/state, never blind-retry). Unclassified transient failures (deadlock, statement timeout, connection drop, upstream 429/5xx) surface as codeTRANSIENT_ERROR. Don't wrap errors in ad-hoc shapes inside tools: throw (typed errors or plainError; SQLSTATE/message inference handles classification) and let the dispatch layer build the envelope. Client-side failures (e.g. the claude.ai approval elicitation's "No approval received") never reach this envelope: idempotency keys are what make those blind retries safe.