Shop Database MCP Server

ローカルで動作し、読み取り専用の Model Context Protocol（MCP）サーバーです。同梱されている教育用 SQLite ショップフィクスチャを探索・分析するためのもので、公開されるツールは list_tables、describe_table、query_database のちょうど 3 つのみです。

コミット済みの shop.db には、教育用に合成された国名の値が含まれています。これらは決定論的なフィクスチャデータであり、推論された個人属性ではありません。

1. インストール

前提条件: Node.js 20 以降、npm、および better-sqlite3 がサポートするプラットフォーム（npm がビルド済みネイティブバイナリを取得できない場合は、ローカルの C/C++ ビルドツールチェーン）が必要です。

npm install

Related MCP server: db-mcp

2. 設定

同梱の shop.db を使用する場合、設定は不要です。別の互換性のあるデータベースを選択するには、絶対パスまたは相対パスを設定します:

export SHOP_DB_PATH=/path/to/shop.db

サーバーは、既定のデータベースを、呼び出し元のワーキング・デイレクトリではなく、自身のモジューるを基準に相対パスで解決します。存在しないデータベースを作成することはありません。.env.example を参照してください。環境ファイルは自動的に読み込まれません。

3. フィクスチャの準備または検証

npm run prepare-db

この明示的なセットアップコマンドは、決定的な合成 customers.country フィクスチャとそのインデックスを原子的に追加または検証します。既存の顧客フィールドと ID を保持し、冪等です。このコマンドは、start、dev、またはサーバーランタイムから呼び出されることはありません。リポジトリには既に準備済みのデータベースが含まれているため、通常は検証として機能します。

4. ビルド

npm run typecheck
npm run build

5. 実行

npm run start

プロセスは stdin/stdout で MCP を通信し、クライアントを待ちます。スタートアップバナーは表示されません。stdout は MCP メッセージ専用に予約されています。開発モードは npm run dev で利用できます。

6. 接続

一般的な stdio MCP 設定が configuration.example.json に提供されています:

{
  "mcpServers": {
    "shop_database": {
      "command": "node",
      "args": ["/absolute/path/to/project/dist/server.js"],
      "env": { "SHOP_DB_PATH": "/absolute/path/to/project/shop.db" }
    }
  }
}

Codex CLI の場合は、コマンドラインでサーバーを追加する:

codex mcp add shop_database --env SHOP_DB_PATH=/absolute/path/to/project/shop.db -- node /absolute/path/to/project/dist/server.js
codex mcp list

または、config/codex-config.example.toml のテンプレートを Codex 設定にコピーして、プレースホルダーを置き換えます:

[mcp_servers.shop_database]
command = "node"
args = ["/absolute/path/to/project/dist/server.js"]
tool_timeout_sec = 15
required = true
enabled_tools = ["list_tables", "describe_table", "query_database"]

[mcp_servers.shop_database.env]
SHOP_DB_PATH = "/absolute/path/to/project/shop.db"

codex mcp list を実行し、Codex を起動して、/mcp で shop_database と 3 つのツールがすべて利用可能であることを確認してください。

7. テスト

npm test

このスイートは、入力境界、SQLのトークン化おと拒否、シリアライゼーション、スキーマ発見、すべての受け入れ分析、ページネーション、名前付きバインド、stdio プロトコル動作、および破壊的クエリ行列全体でのデータベース不変性をカバーしています。

プロンプト例

1. 利用可能なすべてのテーブルを表示し、各テーブルに含まれる情報を説明してください。

2. ドイツからの顧客は何人いますか。

3. 最も多くの顧客がいる国はどこですか。

4. 最もお金を使った顧客は誰ですか。

5. ベストセラー上位5製品は何ですか。

6. 売上が最も多い上位3製品カテゴリは何ですか。

7. 2025年の売上はいくらですか。

8. 最も多くの注文を行った顧客は誰ですか。

クエリのルールと読み取り専用の保証

データベースは readonly: true と fileMustExist: true で開かれ、その後 SQLite のクエリ専用モードに置かれます。SQLポリシーは独立に、単一の SELECT または非再帰の WITH ... SELECT のみを許可します。データ変更、DDL、PRAGMA、アタッチ、メンテナンス、拡張機能の読み込み、再帰CTE、追加のステートメントは拒否されます。プリペアドステートメントも、リーダーとして識別される必要があります。ユーザーの値は、名前付きバインドでのみ渡されます。

各結果ページには最大 500 行が含まれます。決定的な ORDER BY を使用し、has_more が true の間、next_offset に続けてすすめてください。同期 SQLite ドライバーは、CPU 負荷の高いクエリをプロセス内で中断はできません。v1 は、サーバー側のハードな実行期限ではなく、クエリの制限、出力の制限、および推奨される 15 秒の MCP クライアントタイムアウトに依存しています。

売上、支出、販売数量、製品・カテゴリの売上は、キャンセルされた注文を除きます。注文数にはすべてのステータスが含まれます。注文全体の売上と顧客の支出は orders.total_amount を、過去の製品・カテゴリの売上は order_items.quantity * order_items.unit_price を使用します。日付はタイムゾーンに依存しないタイムゾーンであり、暦年のフィルタは半開区間を使用します。データベースは通貨を宣言していないため、金額は通貨単位として扱われます。

トラブルシューティング

• DATABASE_UNAVAILABLE: SHOP_DB_PATH、ファイルの存在、読み取り権限を確認してください。サーバーはデータベースを作成しません。

• DATABASE_SCHEMA_MISMATCH: コミット済みのフィクスチャを使用するか、npm run prepare-db を実行してください。カスタムデータベースには、必要なすべてのテーブル、列、記体キ、およびフィクスチャの前提件が存在しなければなりません。

• ネイティブ依存関係のインストールが失敗する: サポートラ Node.js のリリースを、お使いのプラットフォームのコンパイラ/ビルドツールをインストールしてから、npm install を再実行してください。

• MCP のフレーミングまたは JSON エラー: ラ行タイムコードに console.log やその他の stdout ログを追加しないでください。診断情報は stderr にのみ送信してください。

• クエリが SQL_ERROR を返す: まずテーブルを確認し、重複する結果列名にはユニークなエイリアスを使用し、プレースホルダー名と SQL 構文を確認してください。