Shop MCP Server

ローカルMCPサーバー。ECサイトのSQLiteデータベースを分析するためのものです。AIエージェントがMCPツールを呼び出し、サーバーがリクエストを安全なSQL SELECT に変換し、shop.db を直接読み取り、構造化された結果を返します。

Host-приложение
├── AI-агент / LLM
└── MCP-клиент
        │ JSON-RPC / stdio
        ▼
    Shop MCP Server
        │ read-only SQLite
        ▼
    data/shop.db

機能

• HTTPや専用DBサーバーなしでSQLiteに直接接続。

• MCPトランスポート stdio。

• tools/list による query_shop と inspect_database の検出。

• 説明とツールのJSON Schemaに8つのサンプルタスク。

• プレーンテキスト、JSON intent、または準備済みの安全な SELECT。

• すべての分析から cancelled 注文を除外。

• ページネーションと結果の制限。

• 多層的な読み取り専用保護。

Related MCP server: Shop Analytics MCP Server

インストール

Python 3.11以降が必要です。

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

準備済みのデータベースは data/shop.db にあります。150人の顧客がおり、customers.country フィールドは全顧客に入力され、45人の顧客が Germany に属しています。

データベースの再準備

元のデータベースは変更されません。コマンドは新しい作業用コピーを作成し、再現可能な合成値を持つ country TEXT NOT NULL を追加します：

.venv/bin/shop-prepare-db /path/to/original/shop.db ./data/shop.db

分布は customers.id のみに依存するため、再準備しても同じ値になります。国はテストデータであり、顧客の実際の所在地を表すものではありません。

パスの設定

パスは次の順序で決定されます：

1. SHOP_DB_PATH。

2. SHOP_MCP_CONFIG または config/shop_mcp.json のJSONファイル。

3. 作業ディレクトリからの相対パス data/shop.db。

環境変数の例は .env.example にあり、MCPクライアントの設定は config/mcp.example.json にあります。/absolute/path/to/MCPDeveloper をプロジェクトの絶対パスに置き換えてください。

起動

通常、サーバーはMCPクライアントを自身の設定から起動します。プロセスを手動で起動する場合：

SHOP_DB_PATH=./data/shop.db .venv/bin/python -m shop_mcp.server

stdout はMCP JSON-RPC用に予約されています。診断情報はプロトコルストリームに出力されません。

ツール

inspect_database

引数：

{"action": "list_tables"}

または：

{"action": "describe_table", "table": "customers"}

query_shop

引数：

{
  "request": "Сколько клиентов из Германии?",
  "limit": 100,
  "offset": 0
}

tools/list で宣言される例：

1. データベースにはどのテーブルがあり、各テーブルにはどのフィールドがありますか？

2. ドイツからの顧客は何人ですか？

3. 最も顧客が多い国はどこですか？

4. 最も多く使った顧客は誰ですか？名前、メール、合計金額を返してください。

5. 販売数量と売上でトップ5の商品を表示してください。

6. 売上でトップ3のカテゴリを表示してください。

7. 2025年の売上はいくらでしたか？

8. 最も多くの注文をした顧客は誰ですか？

構造化されたintentを渡すこともできます：

{
  "request": "{\"intent\": \"revenue_by_year\", \"year\": 2025}"
}

または準備済みのクエリ：

{
  "request": "SELECT name, category FROM products ORDER BY name"
}

ビジネスルール

• orders.status = 'cancelled' はメトリクスに含まれません。

• 顧客の支出と年間売上は orders.total_amount で計算されます。

• 商品とカテゴリの売上は quantity * unit_price で計算されます。

• 年の間隔は半開区間です：1月1日を含み、翌年の1月1日を含みません。

• 提供されたデータベースでは、すべての注文が2026年に属するため、2025年の売上は 0 です。

セキュリティ

サーバーはSQLiteを mode=ro で開き、query_only を有効にし、SQLite authorizerを設定し、複数の式、DML、DDL、ATTACH、変更を伴う PRAGMA、拡張機能のロードを禁止し、実行時間を制限します。

SELECT 以外の操作を実行しようとすると、正確な応答が返されます：

Не доступный вариант запроса

SQLiteの内部エラー、スタックトレース、ローカルパスはクライアントに返されません。

検証

.venv/bin/pytest
.venv/bin/ruff check .
.venv/bin/ruff format --check .

テストには、MCPサーバーの実際のsubprocess起動、stdio を介した ClientSession 接続、tools/list、両方のツールの呼び出し、分析シナリオ、データベース変更の試みが含まれます。

完全な承認済み仕様は docs/specification.md にあります。