MCP Data Agent

販売データベース上でデータアナリスト向けツールを公開する、本格的なModel Context Protocol (MCP) サーバーです。さらに、実行時にそれらのツールを発見し、質問に答えるためにどのツールを呼び出すかを決定するLLMエージェント（Gemini）も備えています。MCPの本質は、ツール定義がサーバー側に存在し、エージェントにハードコードされていないことです。

これがモックではなく本物のMCP実装である理由

• src/mcp_server.py は、公式の mcp Python SDK 上に構築された本物のMCPサーバーであり、標準のstdioトランスポートを介して4つのツール（list_tables、run_sql_query、get_column_stats、plot_bar_chart）を公開しています。

• src/smoke_test_client.py は、LLMを一切関与させないプロトコルレベルのテストです。サーバーを実際のサブプロセスとして起動し、stdio経由で接続して list_tools() を呼び出し、実際のMCPワイヤプロトコルを通じて run_sql_query を呼び出します。これこそが、その上で動くエージェントが機能するかどうかとは無関係に、サーバーが機能することを証明するものです。

• src/mcp_client_agent.py はエージェントです。サーバーのツールを一覧表示し、そのJSONスキーマを直接Geminiの関数宣言に変換し（parameters_json_schema=tool.input_schema — 手動でのスキーマ変換は不要）、標準的なツール呼び出しループを実行します。モデルに問い合わせる → 実際のMCPセッションを介して要求されたツール呼び出しを実行する → 結果をフィードバックする → モデルが最終回答を返すまで繰り返します。

Related MCP server: agente-ecommerce-mcp-memoria

Python 3.10+ が必要です

mcp パッケージはPython 3.9をサポートしていません。デフォルトの python が古い場合は、以下のすべてのコマンドで py -3.12（またはお持ちの3.10以降のインタープリタ）を使用してください。

パイプライン

pip install -r requirements.txt
python src/generate_data.py          # -> data/sales.db (3,000 synthetic orders)
python src/smoke_test_client.py      # protocol-only sanity check, no LLM
python src/mcp_client_agent.py "Which category has the highest revenue?"

GEMINI_API_KEY が設定されていない場合、mcp_client_agent.py は手動フォールバックを実行します。稼働中のサーバーから発見したツールを一覧表示し、そのうちの1つを直接呼び出すため、APIキーがゼロでもMCPの配管を実演できます。キーを設定すると（.env.example を .env にコピー）、完全なエージェントループが実行されます。

テスト

tests/test_pipeline.py は、サーバーのツール関数を直接呼び出します（スキーマのイントロスペクション、非SELECT文のSQL拒否、統計）。そして、これが機能するMCP実装であることの本当の証明として、smoke_test_client.py を実行します。これはサーバーを実際のサブプロセスとして起動し、実際のstdioプロトコルで通信します。APIキーは不要なので、Python 3.12でプッシュのたびにCIで実行されます。

pip install -r requirements.txt pytest
pytest tests/ -v

サーバーが公開するツール

検証済み vs. 独立検証は未実施

• 検証済み: MCPサーバーとプロトコルの配線（ツール発見、stdio経由のツール実行）— smoke_test_client.py はLLMをループに含めずにエンドツーエンドで実行し、mcp_client_agent.py の手動フォールバックパスも同じ実際のプロトコルを実行します。

• 現在の google-genai SDK に対して実装済みだが、この環境ではライブキーで実行されていない: Geminiのツール呼び出しループ自体です。関数宣言と関数応答の型はインストール済みSDKに対して直接確認しましたが、実際のマルチターン呼び出しにはこの環境にはないAPIキーが必要です。ご自身の GEMINI_API_KEY で実行して、そのパスを試してください。

プロジェクト構成

data/     generated sales.db
src/      mcp_server, smoke_test_client, mcp_client_agent, generate_data
reports/  charts saved by plot_bar_chart

スタック

Python 3.12 · mcp（公式Model Context Protocol SDK）· google-genai · SQLite · matplotlib

ライセンス

MIT — LICENSE を参照してください。