zaim-mcp

Zaim家計簿APIのMCPサーバー（Model Context Protocol）。

Tech Stack

• Runtime: Bun (not Node.js) — use bun run / bun install
• Language: TypeScript (strict mode, ES2022, Node16 module resolution)
• Linter/Formatter: Biome (bun run check = lint + format + typecheck)
• Package manager: Bun (no package-lock.json, uses bun.lock)
• MCP SDK: @modelcontextprotocol/sdk, Zod for schema validation
• Auth: OAuth 1.0a (oauth-1.0a package)

Project Structure

• src/cli.ts — CLI entry point (zaim-mcp bin), dispatches init subcommand or starts MCP server
• src/index.ts — MCP server entry point, tool registrations
• src/helpers.ts — Pure helper functions (isValidDate, dateSchema, successResult, errorResult)
• src/zaim-client.ts — OAuth-authenticated Zaim API client, buildURL() SSRF guard
• src/init/ — Interactive setup wizard (zaim-mcp init)
  • index.ts — Main init flow: credential input, OAuth dance, client config writing
  • oauth.ts — OAuth 1.0a request/access token exchange with Zaim API
  • clients.ts — MCP client config writers (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code)
  • prompt.ts — Interactive CLI prompt helpers (input, single/multi choice)
• src/schemas/ — Zaim APIレスポンス用Zodスキーマ（互換性保証）
  • verify.ts, money.ts, category.ts, genre.ts, account.ts, currency.ts — エンドポイント別スキーマ
  • index.ts — barrel export + responseSchemas パス→スキーマ マップ
• src/__tests__/ — Unit tests (Bun built-in test runner)
• src/__integration__/ — 統合テスト（実Zaim APIを叩く、要クレデンシャル）
• scripts/capture-responses.ts — Zaim APIレスポンスキャプチャ（フィクスチャ生成用）
• .githooks/pre-commit — Biome check on staged files
• .github/workflows/ci.yml — CI: lint + typecheck + test on PR/push to master
• .github/workflows/integration.yml — 統合テスト: 週次スケジュール + 手動トリガー（GitHub Secrets必要）
• .github/workflows/publish.yml — CD: npm publish on GitHub Release (with provenance)

Commands

• bun run start — Start MCP server (stdio transport)
• bun run test — Run unit tests (Bun built-in test runner)
• bun run check — Lint + format + typecheck (all-in-one)
• bun run lint — Biome CI check only
• bun run lint:fix — Biome auto-fix
• bun run typecheck — TypeScript type check (tsc --noEmit)
• bun run test:integration — 統合テスト実行（要.envクレデンシャル）

Code Style

• Biome recommended rules, 2-space indent, 80 char line width
• Japanese descriptions for MCP tool titles/descriptions
• Helper pattern: registerSimpleGetTool() for parameter-less GET endpoints
• successResult() / errorResult() helpers in src/helpers.ts
• SSRF prevention: buildURL() in src/zaim-client.ts validates host before API calls

Testing

• Test runner: Bun built-in (bun:test), no additional dependencies
• Test files: src/__tests__/**/*.test.ts
• Scope: Pure functions + Zodスキーマ検証（no mocking, no API calls）
• Integration tests: src/__integration__/ — 実API呼び出しでスキーマ検証（CI: 週次 + 手動）
• Test names use Japanese (consistent with codebase conventions)

Environment

• OAuth credentials via env vars: ZAIM_CONSUMER_KEY, ZAIM_CONSUMER_SECRET, ZAIM_ACCESS_TOKEN, ZAIM_ACCESS_TOKEN_SECRET
• See .env.example for template

Git

• Main branch: master
• Pre-commit hook: bunx biome check --staged (set up via bun run prepare)
• CI runs lint + typecheck + test on push to master and PRs

Security

• Supply chain: Safe Chain (malware) + bun audit (CVE) + Dependabot (continuous monitoring)
• bun audit --audit-level=high — CI fails on high/critical vulnerabilities
• Dependabot: weekly scan (Monday), auto-PR for npm deps + GitHub Actions