mcp-shop-server

MCPサーバー。AIエージェントにオンラインストアのSQLiteデータベース（customers、products、orders、order_items）への読み取り専用アクセスを提供する。エージェントはこれを介してデータに関する分析的な質問（データベース構造、顧客・商品・カテゴリ別の集計、売上）に回答する。トランスポートはstdio。

データベースへの書き込みはby design不可能。3つの独立した保護レイヤー（mode=ro接続、実行前のクエリ検証（SELECT / WITH ... SELECTのみ）、sqlite3-authorizer）による。

計測結果、エビデンス、仕様からの逸脱は REPORT.md を参照。

使用方法

1. クローン

git clone https://github.com/andreykutsenko/mcp-shop-server.git
cd mcp-shop-server

リポジトリには既に shop.db（顧客150件、商品50件、注文750件、注文明細1900件）が含まれている。

2. 依存関係のインストール

uv venv .venv
uv pip install --python .venv/bin/python -r requirements.txt

uvを使わない場合も、標準的な手段で同じことを行う:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Python 3.11+が必要。依存関係: mcp（公式MCP SDK）とテスト用のpytest。データベース操作は標準ライブラリのsqlite3を使用。

3. エージェントの設定に記述

最小構成:

{
  "command": "python",
  "args": ["/absolute/path/to/mcp-shop-server/server.py"]
}

mcpServersブロックを持つクライアント（Claude Desktop、Cursor、および互換クライアント）向けの実用的な例:

{
  "mcpServers": {
    "shop-db": {
      "command": "/absolute/path/to/mcp-shop-server/.venv/bin/python",
      "args": ["/absolute/path/to/mcp-shop-server/server.py"],
      "env": {
        "MCP_SHOP_DB": "/absolute/path/to/mcp-shop-server/shop.db"
      }
    }
  }
}

Claude Codeの場合は1コマンドで十分:

claude mcp add shop-db -- /absolute/path/to/mcp-shop-server/.venv/bin/python /absolute/path/to/mcp-shop-server/server.py

MCP_SHOP_DBは任意: 環境変数が設定されていない場合、サーバーはserver.pyと同じディレクトリのshop.dbを使用する。データベースが別の場所にある場合は指定すること。インタープリタは.venv内のものを指定するのが望ましい。そうしないと、システムのpythonがmcpパッケージを見つけられない可能性がある。

4. 起動

サーバーはエージェントが起動する。手動で行うことは稀:

.venv/bin/python server.py

プロセスはstdinでJSON-RPCを静かに待機する。診断情報はstderrに出力され、stdoutはMCPプロトコルで占有される。

5. 確認とエージェントへの質問

.venv/bin/python -m pytest -q

接続後、エージェントは3つのツールを認識する。質問は自然言語で行う。

宿題のテキストにある8つのタスク — 確認のためにはこれらを実行するのが良い:

1. Show me all available tables and explain what information each table contains.
2. How many customers are from Germany?
3. Which country has the most customers?
4. Who is the customer who spent the most money?
5. What are the top 5 best-selling products?
6. What are the top 3 product categories by revenue?
7. How much revenue did we generate in 2025?
8. Which customer placed the most orders?

⚠️ タスク2、3、7は提供されたデータベースでは解がなく、これは想定どおりである。 customersには国を示すカラムがなく、150人の顧客全員がロシアの電話番号を持つ。 750件の注文はすべて2026年の日付で、2025年のデータは存在しない。

この場合、サーバーはデータを捏造しない: そのようなフィールドがスキーマに存在しないことを報告し、既存のカラムを列挙する。コードには何もハードコードされておらず、スキーマはデータベースから読み取られるため、countryが存在する別のデータベースでは、同じ質問は正常に機能する。

さらに、データベースが完全にカバーする質問も確認される: 注文金額上位5顧客、カテゴリ別売上、ステータス別注文分布、平均注文額、商品在庫。

書き込み保護の確認。 「Delete all cancelled orders」に対して、エージェントはエラーではなく明確な拒否を受け取る: サーバーは読み取り専用で動作し、102件のキャンセル済み注文はそのまま残る。

ツール

出力は制限される: デフォルトで100行、最大1000行。切り詰め時には、返された行数、見つかった総行数、次の読み取りに使用するoffsetが応答に含まれる。

要求されたフィールドがデータベースに存在しない場合（例: 顧客の国）、サーバーは正直にその旨を伝え、既存のカラムを列挙する。存在しないフィールドを推測することはない。

Related MCP server: Shop Analytics MCP Server

実装方法

プロジェクトは単一のプロンプトで生成された — ファイル SPEC-mcp-shop.md がエージェントに全体として送信され、その後の修正はなかった。

内部では、エージェントはスキル repo-task-proof-loop （Denis Shiryaev、Apache-2.0）に従ってループで作業した: スペックの凍結 → ビルド → エビデンスのパッケージ化 → 新しいセッションでの検証 → 最小限の修正 → 再検証、PASS判定が出るまで。

実行のエビデンスはリポジトリの .agent/tasks/mcp-shop-server/ にある:

• spec.md — 受け入れ基準AC1…AC17付きの凍結済みスペック;

• evidence.md / evidence.json — 各基準に対する判定と具体的なエビデンス;

• verdict.json — 新しいセッションによる独立検証の結果;

• problems.md — 検証者が見つけた相違点;

• raw/ — 実行の生ログ: テスト、実MCPセッション、stdoutのクリーン性チェック。

検証されるのはソースコードではなく、実エージェントを使ったサーバーの動作である: harness raw/mcp_session_check.py は、実際のMCPクライアントでstdio経由でserver.pyを起動し、全ツールを呼び出し、8つの分析タスクを実行し、削除要求に対する拒否を確認し、stdoutにJSON-RPCフレームのみが含まれることを照合する。

開発スキル自体はローカルの .claude/skills/ にあり、リポジトリにはコミットされない — これは他人のコードである。

仕様の曖昧さに対する決定事項