Księga jako narzędzia — serwer MCP dla agentów AI

Serwer Model Context Protocol, który wystawia system księgowy (kolejkę faktur, kontrolę duplikatów, rejestr VAT, historię kontrahentów i dziennik decyzji) jako narzędzia dla dowolnego agenta AI — Claude Code, inspektora MCP czy skryptu testowego.

Czym jest MCP, po ludzku

MCP to „USB dla agentów": jeden standard wtyczki między modelem a systemami firmy. Zamiast pisać integrację szytą na miarę pod każdą parę „agent ↔ system", system wystawia narzędzia raz — a korzysta z nich każdy klient mówiący protokołem. Ten projekt pokazuje to w praktyce: te same narzędzia księgi obsługują sesję Claude Code i automatyczny harness testowy.

Narzędzia (7)

Narzędzie	Rola
queue_pending	kolejka niezaksięgowanych faktur
invoice_get	pełne dane dokumentu (nagłówek, strony, pozycje, sumy)
verify_totals	deterministyczna kontrola rachunkowa (grosze, per pozycja)
ledger_check	czy numer został już zaksięgowany (duplikaty)
contractor_history	dominujący format numeracji i granica kwot odstających
vat_registry	status podatnika (mock białej listy) + suma kontrolna NIP
book_invoice	decyzja auto/eskalacja z uzasadnieniem w dzienniku audytowym

Najciekawszy wynik: 9/10 → 10/10 → 40/40

Agent (Claude) przetwarzał 60 faktur z wstrzykniętymi wadami (7 typów — korpus i klucz odpowiedzi wspólne z projektem zespołu agentów n8n):

Partia	Wynik	Co się wydarzyło
inv_001–010	9/10	agent policzył arytmetykę „w głowie" i pomylił się o 90 zł — przepuścił wadę na inv_008
—	—	agent sam zaproponował narzędzie verify_totals; arytmetyka przeszła z modelu do deterministycznego kodu
inv_011–020	10/10	w tym wada stawki VAT wykryta poglądem na dane (8% i 23% na identycznym towarze)
inv_021–060	40/40	komplet: duplikaty, zły NIP, niezarejestrowany podatnik, obcy format numeru, kwoty odstające

Bilans: 59/60 trafnych decyzji, a jedyny błąd pochodzi sprzed narzędzia i dokładnie z tej klasy, którą narzędzie wyeliminowało. Lekcja projektu: model ma wnioskować i decydować — liczyć ma narzędzie. Dziennik decyzji z całego przebiegu: data/ledger-demo-60.db (tabela decisions).

Uruchomienie

npm install
npm run build-ledger   # księga SQLite z korpusu (60 faktur + rejestr VAT)
npm test               # harness MCP: 16 asercji wg klucza odpowiedzi

Podłączenie do Claude Code: repo zawiera .mcp.json — wystarczy otworzyć katalog i zatwierdzić serwer ledger. Serwer przy starcie sam zasila pustą księgę (stdio, node:sqlite — zero natywnych zależności).

Struktura

src/server.ts          # serwer MCP: 7 narzędzi na stdio
src/verify.ts          # kontrola rachunkowa (grosze, per pozycja) — wspólna dla MCP i CLI
scripts/build-ledger.ts# budowa księgi z korpusu
scripts/verify-totals.ts# to samo co narzędzie MCP, z linii poleceń
test/harness.ts        # skryptowy klient MCP: 16 asercji wg klucza
data/answer_key.json   # korpus 60 faktur z kluczem odpowiedzi
data/ledger-demo-60.db # dziennik 60 decyzji agenta z sesji demo (59/60)