convez.ai
MCP ServerFinanceiroAvançado
knishioka

ai-books — Servidor MCP de Contabilidade para IA

knishioka/ai-books

Contabilidade orientada a agentes IA com MCP nativo

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-books

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 meses
Versão
—
Issues abertas
1
Contribuidores
1

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. If AI_BOOKS_MCP_TRANSPORT=http is 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:

BlockWhat it provesIssues
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 checkPython-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 blockCI job
Python full suite + coverage gateverify (3.12 / 3.13)
Web unit layer + coverage gateweb
Web Vercel parity buildweb-vercel-build
e-Tax layout sync checkverify / 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 scanpre-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 スコープ)TestRuns in
HTTP 未認証アクセスが 401 で拒否されるtests/test_server_http.pyverify.sh (DB/network-free)
http は auth 未設定なら起動拒否 (fail-closed, ADR 0008)tests/test_server_http.pyverify.sh (DB/network-free)
allowlist 外 / 失効・改竄トークンが拒否されるtests/test_auth.pyverify.sh (DB/network-free)
stdio 経路の非退行 (認証なしで従来通り boot / tools)tests/test_server_stdio.pyverify.sh (DB/network-free)
有効トークンで主要ツールが通り audit_logs.actor = 認証ユーザーtests/test_auth_audit_db.pytest.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:

#TitleStatus after ADR 0001
1feat: bootstrap schema and forward-only migration runnerRe-scoped → Supabase (Postgres)
2feat: read-side MCP tools (accounts, journal entries, balances)Retained
3feat: write-side MCP tools with debit/credit validationRetained
4feat: aggregation tools (trial balance, P/L, B/S)Retained / extended toward 青色申告決算書
5docs: README, Claude Desktop integration, synthetic seed dataRetained / 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-books produces the ledger and the 青色申告決算書 + e-Tax import data; computing the tax owed and submitting it belong in downstream tools

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados