MCPサーバー shop-db

Read-only MCP サーバー（stdio トランスポート）で、AI エージェントにオンラインショップの SQLite データベース shop.db へのアクセスを提供します：顧客、商品、注文、注文明細。

公式 MCP Python SDK（v2）に基づいています。

開発メタデータ

プロジェクトは AI コーディングエージェント（Claude Code、モデル Fable 5）が仕様 SPEC.md に従って完全に生成したものです。

Related MCP server: db-mcp

ツール (tools)

セキュリティ

このサーバー経由でデータベースを変更することはできません。独立した 3 つの保護レイヤーがあります：

1. リクエスト検証 — 単一の SELECT／WITH ではないもの（INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, PRAGMA,ATTACH、連続した複数ステートメント、コメントで隠された書き込み）は、実行前にわかりやすいメッセージで拒否されます。

2. Read-only 接続 — ファイルは mode=ro の SQLite URI で開かれます。

3. PRAGMA query_only = ON を各接続に対して設定します。

検証を通過した書き込み（例：WITH ... INSERT）でも、接続レベルの read-only に阻まれます。

SQL エラーは stack trace を含まず、ヒント付きの短く明確なメッセージで返されます。

インストール

Python 3.10+ が必要です。

uv の場合（推奨 — 初回起動で自動インストールされます）：

uv sync

または pip の場合：

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

設定

サーバーは server.py の隣にある shop.db ファイルをデータベースとして探します — 課題で提供されたデータベースはリポジトリに含まれています。別のファイルを使うには、環境変数 SHOP_DB_PATH を設定します：

export SHOP_DB_PATH=/path/to/shop.db

seed_db.py は似たスキーマのデモデータベースを生成する補助ユーティリティです（一時的なデータ用です。明示的に指定しない限り shop.db には触れません）：

python seed_db.py /tmp/demo.db

起動

サーバーは stdio で通信します — 手動ではなく、MCP クライアントによって起動されます。エラーなく起動することを確認するには：

uv run python server.py

（サーバーは stdin で MCP メッセージを待ちます。終了は Ctrl+C）

エージェントへの接続

Claude Code

リポジトリに .mcp.json があるので、プロジェクトのディレクトリからサーバーが自動的に検出されます。手動で登録する場合：

claude mcp add shop-db -- uv run --directory /absolute/path/to/sqlite-mcp python server.py

Claude Desktop（または JSON 設定を使うクライアント）

claude_desktop_config.json に追加します（examples/claude_desktop_config.example.json を参照）— pip でインストールする場合は、依存関係を設定ファイルで指定されたインタプリタにインストールする必要があります：

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

または、uv を使用する場合（手動インストール不要）：

{
  "mcpServers": {
    "shop-db": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/sqlite-mcp", "python", "server.py"]
    }
  }
}

Docker

docker build -t shop-db-mcp .

{
  "mcpServers": {
    "shop-db": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "shop-db-mcp"]
    }
  }
}

エージェントが回答できる質問の例

• Show me all available tables and explain what information each table contains.

• How many customers are from Germany?

• Which country has the most customers?

• Who is the customer who spent the most money?

• What are the top 5 best-selling products?

• What are the top 3 product categories revenue?

• How much revenue did we generate in 2025?

• Which customer placed the most orders?

破壊的なリクエスト（「Delete all cancelled orders」）はサーバーが拒否します。

提供されたデータに関する注意：customers には国名の列がありません（所在地は電話番号のコード — 全番号 +7 — またはメールのドメインからのみ推定可能）。またすべての注文は 2026 年 2 月〜8 月の日付です。スキーマツールは、エージェントがそれを見て正直に回答するために必要なすべてを提供します。

実際のエージェントによる検証結果

仕様のすべてのタスクを｢実際の headless エージェント（claude -p "<вопрос>" --mcp-config .mcp.json、モデル Sonnet）を使って検証し、サーバーの 3 つの MCP ツールのみを利用可能にしました — Bash やファイルアクセスはなしで。回答は SQLite から直接計算した期待値と照合しました。結果：9/9.

トランスクリプトからの観察：エージェントはほとんどの場合、list_tables + 1 つの集約で間に合っていました。ツールの応答内のテーブル説明（国がないことのヒントや収益の式を含む）が期待通りに機能しました。

データベーススキーマ

customers ──< orders ──< order_items >── products

• customers（150 行）— id, first_name, last_name, email, phone, created_at

• products（50 行）— id, name, category, price, stock_quantity, created_at

• orders（750 行）— id, customer_id → customers, order_date, status (new/processing/shipped/completed/cancelled), total_amount

• order_items（1900 行）— id, order_id → orders, product_id → products, quantity, unit_price

テスト

uv run pytest

36 のテストが、3 つのツールすべて、ページング、エラー処理、read-only の保証（複数ステートメントとコメントで隠された書き込みを含む）、およびデモデータの生成をカバーしています。

プロジェクト構造

server.py        # MCP-сервер (3 инструмента, read-only защита)
shop.db          # выданная в задании база данных
SPEC.md          # спецификация, по которой сгенерирован проект
seed_db.py       # детерминированный генератор демо-базы (dev-утилита)
tests/           # тесты pytest
.mcp.json        # конфиг проекта для Claude Code
examples/        # пример конфига для Claude Desktop
Dockerfile       # опциональный запуск в контейнере