ai-books — Servidor MCP de Contabilidade para IA
knishioka/ai-books
Contabilidade orientada a agentes IA com MCP nativo
Ver no GitHubServidor MCP que expõe primitivos de contabilidade em partidas dobradas (plano de contas, lançamentos, balanço de verificação, demonstrações financeiras) como ferramentas para agentes de IA. Inverte o paradigma tradicional: a interface principal é orientada a máquina (MCP), enquanto o painel humano é apenas leitura. Armazena dados em Postgres (Supabase) e oferece visualizador em Vercel.
Instalação
npx convez-ai knishioka/ai-books1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de lançamentos contábeis por agentes IA
- Validação em tempo real de partidas dobradas
- Geração de relatórios fiscais (青色申告決算書 + e-Tax)
- Importação e conciliação de extratos bancários e cartão de crédito
- Consultas ad-hoc de saldos e demonstrações financeiras
Veredito

Projeto ambicioso em fase bootstrap (M0) que reimagina contabilidade com IA como cidadão de primeira classe. Arquitetura sólida (MCP + Postgres + Vercel), mas ainda com apenas ferramenta smoke-test implementada — adequado para exploradores técnicos e construtores de sistemas contábeis, não para produção imediata.
README
A tradução para o português deste README ainda está na fila.
ai-books
AI-first accounting MCP server — an interface for AI agents, not for humans.
ai-books exposes double-entry bookkeeping primitives (chart of accounts, journal entries, trial balance, financial statements) as Model Context Protocol tools. The premise: if your accounting system has a great machine interface, the human UI is just a thin read-only aggregation dashboard.
Architecture in one line: MCP = the write/validation interface · Supabase (Postgres) = storage · Vercel = read-only viewer. See ADR 0001 for the rationale.
📚 All docs are indexed in the documentation hub — human-facing vs AI/developer-facing split, plus the SSOT map (what is the source of truth for each domain).
🧭 New here? Read the 能力マップ & 使い方ガイド — what ai-books can do today (capabilities map) and how to use it (MCP tools, connecting a client, the read-only viewer, end-to-end walkthroughs, and honest scope boundaries) in one page.
Why
Most accounting software puts a heavy web UI front and center, with the API as an afterthought. ai-books inverts this — the MCP is the primary interface. AI agents (Claude, ChatGPT, Codex, …) can:
- create and validate journal entries (借方貸方 balance enforced at the validation layer)
- query account balances, trial balance, P/L, B/S
- import bank / CC CSV via tool calls
- run ad-hoc aggregations
Humans just look at the read-only Vercel viewer (no data entry there — all writes flow through MCP). The end goal is producing the 青色申告決算書 + e-Tax import data (the tax-amount computation itself stays in downstream tools).
Status
🚧 M0 — bootstrap. Only a hello smoke-test tool is implemented. The project has just pivoted (see ADR 0001): storage moves from local SQLite to Supabase (Postgres), a read-only Vercel viewer is added, and 青色申告決算書 + e-Tax 取込データ output is now an in-scope goal. Schema, accounting tools, viewer, and reports land in the roadmap issues.
Quick start (M0)
Requires Python 3.12+ and uv.
git clone https://github.com/knishioka/ai-books.git
cd ai-books
uv sync
uv run pre-commit install # enable pre-commit hooks (first time only)
uv run python -m ai_books.server # starts MCP server on stdio
Run the verification suite (lint / format / typecheck / e-Tax layout sync / test):
./scripts/verify.sh
./scripts/verify.sh --web # also run web lint/typecheck/unit tests
AI agents (Claude Code) can invoke the /verify, /test and /test-all slash
commands (in .claude/commands/) — thin wrappers over
./scripts/verify.sh and ./scripts/test.sh (/test-all → ./scripts/test.sh --all, the
single one-command local guarantee; see below).
Pre-commit hooks (ruff + hygiene checks) run automatically on git commit.
To run them across the whole repo:
uv run pre-commit run --all-files
MCP transport: stdio (default) / Streamable HTTP
The server speaks stdio by default — a local Claude Desktop / CLI client launches the process and talks over stdio (above). To expose the same tools over the network, opt in to Streamable HTTP with environment variables (a deliberate operator choice — never enabled implicitly; see ADR 0008):
AI_BOOKS_MCP_TRANSPORT=http \
AI_BOOKS_MCP_HOST=127.0.0.1 \
AI_BOOKS_MCP_PORT=8000 \
AI_BOOKS_MCP_AUTH_ALLOWLIST=owner@example.com \
SUPABASE_URL=https://your-project.supabase.co \
AI_BOOKS_MCP_BASE_URL=http://127.0.0.1:8000 \
uv run python -m ai_books.server # serves MCP at http://127.0.0.1:8000/mcp
AI_BOOKS_MCP_HOST / AI_BOOKS_MCP_PORT default to 127.0.0.1 / 8000. The host
defaults to loopback so an http launch never opens a public listener by accident.
ℹ️ Current posture (#142 / ADR 0009): remote MCP is dormant. The HTTP transport and Supabase JWT + single-user allowlist gate are retained for a future restart, but the active operating mode is local
stdio. IfAI_BOOKS_MCP_TRANSPORT=httpis set without the auth variables above, startup fails closed rather than opening an unauthenticated endpoint. Do not expose it publicly unless the remote track is explicitly reactivated.
Manual boundary verification (HTTP auth gate). Start the server as above, then in another shell send an unauthenticated MCP initialize request:
uv run python -c "
import httpx
payload = {
'jsonrpc': '2.0',
'id': 1,
'method': 'initialize',
'params': {
'protocolVersion': '2025-06-18',
'capabilities': {},
'clientInfo': {'name': 'probe', 'version': '0'},
},
}
response = httpx.post(
'http://127.0.0.1:8000/mcp',
json=payload,
headers={'Accept': 'application/json, text/event-stream'},
)
print(response.status_code, response.headers.get('www-authenticate'))
"
This should print 401 with a Bearer challenge, confirming the remote auth boundary
runs before any tool. Authenticated tool calls require a real Supabase-issued JWT and
owner allowlist match; the same fail-closed path is covered automatically by
tests/test_server_http.py.
Local Postgres (Supabase)
Storage is Supabase (Postgres) (see ADR 0001). For local development, the Supabase CLI runs Postgres + Studio on Docker — so local and production share the same engine (no "SQLite locally, Postgres in prod" drift).
Requires Docker and the Supabase CLI (brew install supabase/tap/supabase).
supabase start # boots Postgres + Studio on Docker
supabase start prints connection details. Copy the DB URL into your .env
(create it from .env.example — .env is gitignored):
cp .env.example .env
# Set AI_BOOKS_DB_URL to the "DB URL" from `supabase start`. The CLI default is:
# AI_BOOKS_DB_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres
# Also set SUPABASE_URL / SUPABASE_ANON_KEY / SUPABASE_SERVICE_ROLE_KEY from the
# `API URL` / `anon key` / `service_role key` lines of the same output.
Connectivity smoke test (SELECT 1):
uv run python -c "from ai_books import db; print(db.ping())" # -> 1
supabase stop tears the stack down. The smoke test in tests/test_db.py runs
only when AI_BOOKS_DB_URL is set, so ./scripts/verify.sh stays green even
without a running database; CI runs it against a Postgres service container.
Running the full test suite locally
./scripts/verify.sh runs lint/format/typecheck/e-Tax layout sync/pytest but
skips the DB-backed tests (about half the suite) unless AI_BOOKS_DB_URL is set.
To run everything locally you only need Postgres — not the full supabase start stack. Tests use
plain Postgres and isolate each test in a throwaway schema, so a single lightweight
container (compose.yaml, postgres:17-alpine) is reused across
runs:
./scripts/test.sh # boot postgres:17-alpine + run the full suite (DB tests included)
./scripts/test.sh -k etax # extra args are forwarded to pytest
./scripts/test.sh --web # also cross-check the viewer's numbers against golden
./scripts/test.sh --pooler # run the suite THROUGH a pgbouncer pooler (Supabase parity, #52)
./scripts/test.sh --e2e # supabase start + Playwright browser smoke for the viewer (#162)
./scripts/test.sh --all # ONE command, every guarantee — see below (#59)
./scripts/test.sh --down # stop the test containers
./scripts/test.sh --all — the one-command local guarantee (#59)
--all is the single, mechanical "everything works locally" check. It brings up
Postgres + the pgbouncer pooler once, runs every guarantee block, and ends with a
PASS/FAIL summary. Unlike the other modes it does not stop at the first failure —
every block runs so the summary shows the full picture, and the command exits non-zero if
any block failed:
| Block | What it proves | Issues |
|---|---|---|
| Python full suite + coverage gate (direct DB) | All DB-backed pytest (MCP, property-based, read-only role) + the line 80 / branch 70 gate | #50/#56/#57/#54/#58 |
| Web unit layer + coverage gate (vitest) | Fast DB-free lib/reports + lib/etax unit layer under its v8 gate | #55/#58 |
| Web Vercel parity build (isolated web root) | Production build passes with only web/ visible, catching repo-root reads such as ../src | #140 |
| e-Tax layout sync check | Python-side layout SSOT and committed web layout copies remain byte-for-byte in sync | #154 |
| Viewer golden cross-check (direct DB) | The viewer's numbers reproduce the report-layer golden byte-for-byte | #17/#25 |
| Pooler safety suite + golden (through pgbouncer) | The same write path + golden, plus tests/test_pooler_db.py, all routed through the transaction pooler | #52 |
| Viewer E2E smoke + fail-closed auth (Playwright) | All 10 screens render in a real browser, and unauthenticated / non-allowlisted access fails closed to /login (boots its own supabase start stack for real GoTrue auth) | #162 |
CI ↔ local guarantee mapping
Each --all block maps 1:1 onto a CI job, so the local command reproduces CI's guarantee
surface. lint / format / typecheck stay with ./scripts/verify.sh (the static layer); the
two together cover every CI job:
./scripts/test.sh --all block | CI job |
|---|---|
| Python full suite + coverage gate | verify (3.12 / 3.13) |
| Web unit layer + coverage gate | web |
| Web Vercel parity build | web-vercel-build |
| e-Tax layout sync check | verify / local |
| Viewer golden cross-check (direct DB) | web-golden |
| Pooler safety suite + golden (through pgbouncer) | pooler |
| Viewer E2E smoke + fail-closed auth (Playwright) | web-e2e |
e-Tax .xtx validated against the official .xsd (#79) | etax-xsd |
./scripts/verify.sh (lint/format/typecheck/layout sync) + secret scan | pre-commit / gitleaks |
Remote-auth boundary tests (#110)
The auth boundary is fixed mechanically so "公開したが認証が効いていない" cannot regress.
The DB- and network-free guarantees run in verify / ./scripts/verify.sh; the
end-to-end actor assertion needs Postgres and runs in the Python full suite row above
(verify job / ./scripts/test.sh):
| Guarantee (#110 スコープ) | Test | Runs in |
|---|---|---|
| HTTP 未認証アクセスが 401 で拒否される | tests/test_server_http.py | verify.sh (DB/network-free) |
| http は auth 未設定なら起動拒否 (fail-closed, ADR 0008) | tests/test_server_http.py | verify.sh (DB/network-free) |
| allowlist 外 / 失効・改竄トークンが拒否される | tests/test_auth.py | verify.sh (DB/network-free) |
| stdio 経路の非退行 (認証なしで従来通り boot / tools) | tests/test_server_stdio.py | verify.sh (DB/network-free) |
有効トークンで主要ツールが通り audit_logs.actor = 認証ユーザー | tests/test_auth_audit_db.py | test.sh (Python full suite, DB) |
--pooler stands a pgbouncer (transaction mode) in front of Postgres — mirroring Supabase's
production pooler, which routes each transaction to a possibly-different backend and so cannot
preserve prepared statements. It runs the migrate + seed write path, the report/aggregation/
ledger/e-Tax queries and the viewer golden cross-check all over the pooler, proving the viewer's
prepare: false path and the prepared-statement-free Python client stay pooler-safe. A regression
that re-enables prepared statements fails tests/test_pooler_db.py (and the CI pooler job).
--e2e boots the full local Supabase stack (supabase start — GoTrue auth + Postgres,
not the lightweight db container the other modes use), seeds it, then runs the web/
Playwright specs against a production viewer build: all 10 screens render, and unauthenticated
/ non-allowlisted access fails closed to /login. It deliberately exercises real Supabase
Auth — there is no test-only auth bypass (AGENTS.md invariant #1 / ADR-0008 fail-closed), so a
regression that serves data anonymously fails here (and in the CI web-e2e job). The numbers
themselves stay the golden cross-check's job; this is a browser-render + auth-gate smoke. Requires
the Supabase CLI; extra args are forwarded to
playwright test.
The container is left running between invocations for fast reuse. If AI_BOOKS_DB_URL
is already set (e.g. in CI), it is used as-is and no container is started. This mirrors
the verify / web-golden CI jobs, which run the same tests against a postgres:17
service.
Web viewer (Vercel, read-only)
A read-only aggregation viewer lives in web/ (Next.js, deployed on
Vercel). It renders Supabase/Postgres data — chart of accounts, 試算表 / 月次推移,
仕訳帳 / 総勘定元帳, 損益計算書 / 貸借対照表 / 精算表, 青色申告決算書プレビュー, and
e-Tax 取込データのダウンロード — and has no data-entry UI (writes flow through MCP;
see AGENTS.md invariant #1). Every figure reproduces the report layer's
golden output (#17) exactly; data is queried server-side, so no database credential ever
reaches the browser. See web/README.md for the full screen list.
Run it against your local Supabase (supabase start must be running):
cd web
npm install
cp .env.example .env.local # set AI_BOOKS_DB_URL (the `DB URL` from supabase start)
npm run dev # http://localhost:3000
Full local + Vercel deployment instructions are in web/README.md.
For Production, point AI_BOOKS_DB_URL at the SELECT-only viewer_ro role from the
committed supabase/roles/viewer_readonly.sql:
tests/test_readonly_db.py enforces that the role runs every viewer read (golden
match included) yet is denied every write (./scripts/test.sh -k readonly).
Schema & migrations
The system of record is defined by forward-only SQL migrations under
supabase/migrations/. They establish the double-entry
schema: accounts (chart of accounts, with a CHECK that keeps 科目区分 ↔ 正常残高
consistent), journal_entries / journal_lines (amounts are NUMERIC, never
float), fiscal_years / periods, and an append-only audit_logs table
(UPDATE/DELETE/TRUNCATE are rejected by trigger).
Apply pending migrations with the runner (idempotent — re-running is a no-op):
uv run python -m ai_books.db.migrate # uses AI_BOOKS_DB_URL
uv run python -m ai_books.db.migrate --help # --migrations-dir / --database-url
The runner records each applied file in a schema_migrations table and applies
only the ones not yet recorded, in filename order.
Forward-only — no rollback step. Applied migration files are never edited or deleted (AGENTS.md "Never touch" / invariant #3). To undo or change something, add a new migration that counteracts it (e.g. a later file that drops a column or adjusts a constraint). This keeps every environment reproducible by replaying the same ordered list from a clean database.
Seed: chart of accounts
The standard 個人事業/青色申告 chart of accounts (科目区分・表示区分・正常残高・内訳
親子, plus the 製造原価 accounts) is seeded by a loader. It validates the data —
区分 ↔ 正常残高 consistency and 表示区分 coverage — before writing, and is
idempotent (ON CONFLICT (code) DO NOTHING), so re-running never duplicates:
uv run python -m ai_books.seed.accounts # uses AI_BOOKS_DB_URL (run after migrate)
Read it back over MCP with list_accounts (filter by 区分 / 表示区分 / 有効),
get_account (by 勘定科目コード), and search_accounts (code/名称 substring) —
all returning typed Account rows.
Synthetic seed + golden snapshots (tests)
検証コストを集中投資する土台。架空の製造業個人事業主の 1 会計年度 分の合成仕訳
(売上 / 仕入 / 製造原価 / 経費 / 固定資産 / 減価償却 / 借入 / 家事按分 / 期末整理) と、
それを通したレポートの ゴールデンスナップショット (期待値 JSON) を
tests/fixtures/seed_fy/ に置く。集計 (#18) 以降の
レポートは、この seed/golden を再利用して差分だけで自動検証できる。
uv run python -m tests.fixtures.seed_fy # ゴールデン確認 (dry-run)
uv run python -m tests.fixtures.seed_fy --update # 更新は明示フラグでのみ (誤上書き防止)
ゴールデンは DB 不要で生成でき、pytest ハーネスは DB ロード結果を SQL 集計してゴールデンと 比較する。設計意図と手計算で追える期末残高は上記 README に記載。
e-Tax 取込データ出力 (電子申告)
最終出力。青色申告決算書 (#23) の数値を e-Tax 取込データ (CSV / XML) に変換する
(export_etax MCP tool)。様式は年度で変わるため、決算書 → e-Tax のマッピングは
src/ai_books/etax/spec.py に データ駆動の様式仕様
(EtaxFormatSpec、バージョン管理) として外出しし、年度追従は仕様の差し替えだけで済む。
出力前に必須項目・桁数・勘定科目コード・月をスキーマ検証し、欠落や不正コードは
EtaxValidationError で全件まとめてエラーにする (金額は整数円、端数は不可)。
⚠️ 生成物はコミットしない。 e-Tax 取込データは事業者の確定数値 (秘密情報) を含む。 出力をファイルに保存する場合もリポジトリには絶対に置かないこと (
.ai-books/配下や gitignore 済みのパスを使う)。テストの架空データに対する期待値 (ゴールデン) のみコミット対象。
Use with Claude Desktop
A reference claude-desktop-config.json lands in Issue #5. The shape will be:
{
"mcpServers": {
"ai-books": {
"command": "uv",
"args": [
"--directory",
"/path/to/ai-books",
"run",
"python",
"-m",
"ai_books.server",
],
},
},
}
Roadmap
Direction is set by ADR 0001. The original SQLite-oriented plan is re-scoped onto Supabase (Postgres) + a Vercel read-only viewer:
| # | Title | Status after ADR 0001 |
|---|---|---|
| 1 | feat: bootstrap schema and forward-only migration runner | Re-scoped → Supabase (Postgres) |
| 2 | feat: read-side MCP tools (accounts, journal entries, balances) | Retained |
| 3 | feat: write-side MCP tools with debit/credit validation | Retained |
| 4 | feat: aggregation tools (trial balance, P/L, B/S) | Retained / extended toward 青色申告決算書 |
| 5 | docs: README, Claude Desktop integration, synthetic seed data | Retained / extended (Vercel viewer + Supabase setup) |
Supabase provisioning, the Vercel viewer, and 青色申告決算書 + e-Tax export are tracked by issues #9, #10, #11 and later. Track progress: open issues.
Design influences
simple-bookkeeping(archived) — DB schema design (chart of accounts, debit/credit normalization, audit log)ib-sec-mcp— Python + FastMCP + SQLite reference pattern
Non-goals (forever)
- Web UI for data entry / editing — writes flow exclusively through MCP; the Vercel viewer is read-only
- Multi-tenant SaaS / RLS — single-user; Supabase (Postgres) is for durable storage, not multi-tenancy
- Tax-amount computation / filing engine —
ai-booksproduces the ledger and the 青色申告決算書 + e-Tax import data; computing the tax owed and submitting it belong in downstream tools
License
MIT — see LICENSE.