MCP Data Agent

Реальный сервер Model Context Protocol (MCP), предоставляющий инструменты аналитика данных для работы с базой данных продаж, а также LLM-агент (Gemini), который обнаруживает эти инструменты во время выполнения и решает, какой из них вызвать для ответа на вопрос — суть MCP в том, что определения инструментов живут на сервере, а не захардкожены в агенте.

Почему это настоящая реализация MCP, а не имитация

• src/mcp_server.py — это настоящий MCP-сервер, построенный на официальном Python SDK mcp, предоставляющий 4 инструмента (list_tables, run_sql_query, get_column_stats, plot_bar_chart) через стандартный транспорт stdio.

• src/smoke_test_client.py — это тест на уровне протокола без участия LLM — он запускает сервер как реальный подпроцесс, подключается через stdio, вызывает list_tools() и вызывает run_sql_query через реальный протокол MCP. Это доказывает, что сервер работает, независимо от того, работает ли агент поверх него.

• 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 работает в ручном режиме отката: он перечисляет инструменты, обнаруженные на живом сервере, и вызывает один из них напрямую, так что механику MCP можно продемонстрировать без каких-либо API-ключей. С ключом (скопируйте .env.example в .env) он выполняет полный цикл агента.

Тесты

tests/test_pipeline.py вызывает функции инструментов сервера напрямую (интроспекция схем, отклонение SQL-запросов, не являющихся SELECT, статистика), а также — настоящее доказательство того, что это рабочая реализация MCP — запускает smoke_test_client.py, который запускает сервер как реальный подпроцесс и общается с ним через реальный протокол stdio. API-ключ не нужен, поэтому это выполняется в CI при каждом пуше, на Python 3.12.

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

Инструменты, предоставляемые сервером

Проверено vs. не проверено независимо

• Проверено: MCP-сервер и протокольная обвязка (обнаружение инструментов, выполнение инструментов через stdio) — smoke_test_client.py запускает это от начала до конца без LLM в цикле, а ручной путь отката в mcp_client_agent.py использует тот же реальный протокол.

• Реализовано на основе текущего SDK google-genai, но не запускалось с живым ключом в этом окружении: сам цикл вызова инструментов 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 (официальный SDK Model Context Protocol) · google-genai · SQLite · matplotlib

Лицензия

MIT — см. LICENSE.