Shop SQLite MCP

ローカルな stdio MCP サーバーで、既存のオンラインストアの SQLite データベースを安全に分析するためのものです。サーバーは sqlite_master と SQLite PRAGMA からスキーマを動的に読み取るため、事前にカラム名を知っている必要はありません。

機能

• list_tables — テーブルとビュー;

• describe_table — カラム、PK、FK、インデックス;

• get_schema — スキーマの完全なグラフ;

• run_select_query — 制限付きの単一の SELECT / WITH ... SELECT;

• 専用のアナリティクスツール: count_customers_by_country, top_customers_by_spend, top_products_by_units, top_categories_by_revenue, revenue_in_year, top_customers_by_order_count;

• SQLite の物理的な読み取り専用モード、query_only、オーソライザー;

• DML、DDL、PRAGMA、ATTACH、複数ステートメントのブロック;

• ページネーション: limit 1〜500 と offset。

Setup

1つのコマンドですべてを実行します: インストール方法の選択、依存関係のインストール（または Docker イメージのビルド）、データベースの検索、スキーマ読み取りの確認、完成した mcp.json の書き込み。

python3 install.py

スクリプトは起動方法（.venv または Docker）とデータベースへのパスを尋ねます。質問なし:

python3 install.py --mode venv --db /absolute/path/to/shop.db
python3 install.py --mode docker --db /absolute/path/to/shop.db

Python 3.11+ が必要です。--mode docker の場合は Docker がインストールされている必要があります。

デフォルトでは、データベースは data/shop.db から取得されます。ファイルが存在しない場合、スクリプトは明確なエラーで停止し、空のデータベースは作成されません。

手動での起動は不要です。サーバーは設定から起動します。デバッグ用:

.venv/bin/python -m shop_mcp.print_schema

Connect to agent

install.py の後は、あと1ステップだけです。mcp.json には、選択した起動コマンドとデータベースへの絶対パスがすでに含まれているため、編集する必要はありません。

次のいずれかの方法でエージェントに接続します:

• Cursor: このフォルダーをワークスペースとして開くか（コピーは .cursor/mcp.json にあります）、ルートの mcp.json を MCP 設定にインポートします;

• Claude Desktop / その他のクライアント: mcp.json の内容を MCP 設定にコピーします。

接続後、すぐに ASSIGNMENT.md の質問をしてください。エージェントの最初のアクションは get_schema または専用のアナリティクスツールです。ツールが SCHEMA_MISMATCH を返した場合は、run_select_query を使用してください。

プレースホルダー付きのテンプレートは mcp.json.example のみです。絶対パスは Python コードではなく、クライアント設定にのみ存在します。

Docker

個別のコマンドは不要です。python3 install.py --mode docker が shop-sqlite-mcp:local イメージをビルドし、データベースを読み取り専用でマウントし、docker run -i --rm の起動を mcp.json に書き込みます。

データベースは /data/shop.db:ro としてマウントされます。MCP は stdin/stdout で通信するため、-t フラグは使用されません。

docker-compose.yml は同じイメージをビルドし、ローカルでのビルド確認に役立ちます。エージェントには mcp.json を渡してください。

Test

.venv/bin/pytest

テストでは、サーバーが知らないテーブル名を持つ一時的なフィクスチャデータベースを使用します。ランタイムイントロスペクション、結果の制限、スキーマのハードコードがないこと、破壊的な SQL の拒否を検証します。

手動で確認するには、接続後、ASSIGNMENT.md の質問をしてください。次を含みます:

Delete all cancelled orders.

ツールの応答には WRITE_DENIED が含まれ、データベースは変更されていない必要があります。

Project files

• install.py — 唯一のインストールコマンド: 依存関係/イメージ、データベースへのパス、設定の生成;

• mcp.json — 接続設定の完成版（コマンド + データベースへのパス）;

• PROMPT.md — AI コーディングエージェントがサーバーを作成したプロンプト;

• src/shop_mcp/ — MCP、スキーマイントロスペクション、SQL ガード、アナリティクスツール;

• tests/ — 自動化されたセーフティ、ディスカバリー、アナリティクステスト;

• Dockerfile / docker-compose.yml — コンテナ化された stdio MCP;

• NOTES.md — 課題のあいまいさに関する決定事項。