Shop Analytics MCP Server

読み取り専用の MCP サーバー（stdio 経由）です。AI エージェントがオンラインストアの SQLite データベース（customers、products、orders、order_items）に関する分析的な質問に答えられるようにしますが、データベースを変更することは一切できません。

設計の全体的な根拠（決定ログ、スキーマ、セキュリティモデル、テスト戦略）については、SPEC.md を参照してください。

要件

• Node.js >= 24.10.0（下記の読み取り専用保証に使用する node:sqlite の setAuthorizer に必要）。node --version で確認してください。

• 実行時の依存関係は、npm ci がインストールするもの以外にはありません。

Related MCP server: db-mcp

インストール → 設定 → 実行 → 接続

npm ci
npm run build
SHOP_DB_PATH=./shop.db npm start

• shop.db はこのリポジトリに同梱されており、すぐに使用できます。スキーマから決定的に再生成する必要がある場合は、npm run seed を実行してください（下記の データベース を参照）。

• SHOP_DB_PATH はオプションです。デフォルトは、カレントワーキングディレクトリ内の shop.db です。ソース内のどこにも絶対パスはハードコードされていません。

• サーバーは stdio のみ で MCP を話します。HTTP サーバーは存在せず、他に起動するものはありません。

AI エージェントを接続する

2つのクライアントの設定例が config/ にあります。

• config/claude-code.mcp.json — これをプロジェクトの .mcp.json にコピーするか、その shop-analytics エントリを使って claude mcp add-json を実行します。最初に args/env に絶対パスを設定してください。

• config/codex.mcp.toml — [mcp_servers.shop-analytics] テーブルを ~/.codex/config.toml（またはプロジェクトスコープの .codex/config.toml）にコピーするか、ファイルの冒頭コメントにある codex mcp add コマンドを使用してください。

特定のエージェントを使わずにサーバーを手動で試すには、ツールに依存しない MCP Inspector を使用してください：

SHOP_DB_PATH=$(pwd)/shop.db npx @modelcontextprotocol/inspector node dist/src/index.js

ツール

このサーバーは、専門化された読み取り専用ツールを正確に8つ公開します。どのツールも任意の SQL を受け取ったり実行したりすることはありません。成功したレスポンスは常に { "data": [...], "meta": {...} } であり、エラーは常に、シンプルで安全な人間が読めるメッセージ（SQL、ファイルパス、スタックトレースを含まない）になり、isError: true が付けられます。

from/to は YYYY-MM-DD 形式で、UTC の半開区間 [from, to) を定義します。from は to より厳密に前でなければなりません。すべての財務・件数メトリクスは、ステータスが cancelled の注文を除外します。ツールごとの完全な契約（正確なレスポンス形状、タイブレーク規則）は、SPEC.md §4 にあります。

安全性

3つの独立した多層防御レイヤーにより、"Delete all cancelled orders" のような敵対的なプロンプトであっても、データベースが変更されないことが保証されます。

1. SQLite の接続は readOnly: true で開かれます。

2. 開いた直後に PRAGMA query_only = ON が設定されます。

3. SQLite の authorizer が、すべての書き込み/DDL アクション（INSERT、UPDATE、DELETE、DROP、ALTER、CREATE、ATTACH、DETACH、トランザクション、...）を明示的に拒否します。

その上、どのツールも生の SQL、テーブル名、カラム名を入力として受け取りません。すべてのクエリは固定されたプリペアドステートメントで、すべての入力は zod で検証されてバインドパラメータとして渡され、文字列埋め込みは行われません。

データベース

shop.db は、database/schema.sql から決定論的なシードスクリプトによって生成されます。これを再実行すると、毎回バイト単位で同じデータが生成されます（固定の PRNG シード、実時間に依存しない）：

npm run seed   # builds, then (re)writes ./shop.db from schema.sql + the seed script

このシードスクリプトはまた、生成時に、データセットに曖昧なリーダーボード（例：一意なトップ国、一意なトップ支出者）がないことと、2025年の売上がゼロでないことを検証します — SPEC.md §3 を参照してください。

開発

npm run build           # tsc + copy database/schema.sql into dist/
npm run test:unit        # business logic, in isolation, against fixture databases
npm run test:integration # spawns the built server over stdio via the MCP SDK client
npm test                 # both

このプロジェクトは TDD で構築されました。各モジュールに対して、まず失敗するテストを書き、その後ツールごとに実装を行いました。統合テストスイートは、8つの受け入れシナリオすべてをエンドツーエンドで、SQL インジェクション形式の入力、無効なパラメータの組み合わせをカバーし、毎回の実行後にデータベースファイルの SHA-256 ハッシュが変更されていないことを検証します。

プロジェクト構造

database/       schema.sql + the deterministic seed generator
src/
  db.ts          read-only SQLite connection (see Safety above)
  errors.ts      error taxonomy, safe error formatting
  validation.ts  zod schemas shared across tools (dates, limits, periods)
  period.ts      half-open period SQL clause builder
  tools/         one module per tool: pure query function + types
  server.ts      registers all 8 tools on the MCP server
  index.ts       stdio entrypoint
test/
  unit/          one file per module/tool, fixture-based
  integration/   spawns dist/src/index.js over stdio via the MCP SDK client
config/         example client configuration (Claude Code, Codex CLI)