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

Serwer [Model Context Protocol](https://modelcontextprotocol.io), 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](../agent-team-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

```bash
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)
```