Перейти к содержанию

Panacea MCP Tool Server

Этот рецепт объясняет, как Panacea предоставляет свои примитивы документов/чата в виде стандартных Model Context Protocol (MCP) инструментов, чтобы любой совместимый с MCP клиент (Claude Desktop, другие хосты MCP) мог напрямую использовать возможности извлечения и истории чата Panacea.

Что вы узнаете

  • Разницу между этой MCP поверхностью и внутренней архитектурой регистрации агентов/инструментов из рецепта 04
  • Какие операции с документами и чатом представлены в виде MCP инструментов
  • Как ingestion документов остается неблокирующим с помощью удаленной задачи Ray
  • Почему инструмент прямой передачи сырых SQL является соображением безопасности, которое стоит отметить

Почему это важно

Рецепт 04 охватывает, как внутренний оркестратор Panacea регистрирует инструменты для вызова своими агентами. Это другая интеграционная поверхность: она упаковывает те же основные функции документов/чата как внешние, стандартизированные MCP инструменты, которые может вызывать любой клиент MCP — не требуется специфичный для Panacea SDK или API контракт, только протокол MCP.

Ключевые файлы Panacea

Файл Почему это важно
Panacea/backend/mcp/mcp_server.py FastMCP("Document Agent Server") — определяет все девять MCP инструментов
Panacea/backend/api_endpoints/financeGPT/chatbot_endpoints.py Основные функции, обращающиеся к БД, которые оборачивает каждый MCP инструмент (get_relevant_chunks, add_document_to_db, chunk_document и т.д.)
Panacea/backend/database/db.py get_db_connection — используется напрямую инструментом execute_database_query

Как это работает

  1. mcp_server.py инициализирует Ray (ray.init(...)) и экземпляр сервера FastMCP, названный "Document Agent Server".
  2. Каждая функция, украшенная @mcp.tool(), оборачивает существующую функцию Panacea и возвращает результат в виде обычного текста или строку ошибки — форму, которую ожидает вызов инструмента LLM:
  3. retrieve_relevant_chunks(query, chat_id, user_email, k=2) — семантический поиск по документам чата через get_relevant_chunks
  4. ingest_document(text, document_name, chat_id, chunk_size=1000) — регистрирует документ через add_document_to_db
  5. list_documents(chat_id, user_email) / delete_document(doc_id, user_email) — управление документами
  6. add_message / get_chat_history — чтение/запись истории чата
  7. add_sources_to_message — прикрепить цитаты к сохраненному сообщению
  8. extract_text_from_url(url) — извлечь и вернуть текстовое содержимое из URL
  9. execute_database_query(query, params) — прямая передача сырых SQL (см. примечание по безопасности ниже)
  10. ingest_document не блокирует на разбиении — он вызывает chunk_document.remote(text, chunk_size, doc_id), удаленную задачу Ray, так что большие документы обрабатываются асинхронно, в то время как вызов инструмента возвращается немедленно.
  11. Запуск python backend/mcp/mcp_server.py запускает mcp.run(), который обслуживает эти инструменты через стандартный транспорт MCP — готов к запуску и подключению клиента MCP.
  12. Клиент MCP (например, Claude Desktop), настроенный на запуск этого скрипта, получает доступ ко всем девяти инструментам автоматически, без написания какого-либо специфичного для Panacea интеграционного кода.

Примечание по безопасности

execute_database_query выполняет произвольную SQL строку против производственного соединения без списка разрешенных или ограничений только для чтения — запросы SELECT возвращают строки в формате JSON, все остальное коммитит и возвращает количество затронутых строк. Рассматривайте это как территорию с минимальными привилегиями: если вы открываете этот сервер для клиента MCP, которому вы не полностью доверяете, либо удалите этот инструмент, либо ограничьте его пользователя БД доступом только для чтения на не чувствительных таблицах.

Запустите это локально

Из корня рабочего пространства (anote/panacea):

bash cd Panacea cp backend/.env.example backend/.env docker compose up --build # запускает MySQL, Redis, Tika и бэкенд

Сервер MCP требует fastmcp (в данный момент не указан в backend/requirements.txt — установите его отдельно) и ray>=2.9.0 (уже в backend/requirements.txt):

bash pip install fastmcp cd Panacea/backend python mcp/mcp_server.py

Подключите клиент MCP

Укажите совместимый с MCP клиент на скрипт, например, в claude_desktop_config.json Claude Desktop:

json { "mcpServers": { "panacea-documents": { "command": "python", "args": ["/absolute/path/to/Panacea/backend/mcp/mcp_server.py"] } } }

Перезапустите клиент, и девять инструментов выше станут доступны для вызова из чата.

Заметки для кулинарной книги

Хорошее продолжение рецепта 04 — контраст внутренней регистрации инструментов (register_tool() внутри оркестратора) с этой внешней MCP поверхностью. Также стоит отметить как пробел для читателей: fastmcp еще не указан в backend/requirements.txt, поэтому его нужно установить вручную, пока это не будет исправлено на верхнем уровне.