MCP Data Agent

一个真实的 Model Context Protocol (MCP) 服务器，通过销售数据库暴露数据分析师工具，外加一个 LLM 代理（Gemini），该代理在运行时发现这些工具并决定调用哪些来回答问题——MCP 的真正意义在于工具定义位于服务器上，而不是硬编码到代理中。

为什么这是真正的 MCP 实现，而不是模拟

• src/mcp_server.py 是一个真正的 MCP 服务器，基于官方 mcp Python SDK 构建，通过标准 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 运行手动回退：它列出从实时服务器发现的工具并直接调用其中一个，因此无需任何 API 密钥即可演示 MCP 管道。有密钥时（将 .env.example 复制为 .env），它会运行完整的代理循环。

测试

tests/test_pipeline.py 直接调用服务器的工具函数（模式自省、拒绝非 SELECT 语句的 SQL、统计），并且——这是真正 MCP 实现有效工作的证明——运行 smoke_test_client.py，该脚本将服务器作为实际子进程启动，并通过真实的 stdio 协议与之通信。无需 API 密钥，因此每次推送时都会在 CI 中、在 Python 3.12 上运行。

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

服务器暴露的工具

已验证与未独立验证

• 已验证：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。