mcp-chat

Сводка по реализации MCP-сервера чат-бота на базе Neo4j.

Принципы создания MCP-сервера

Проектирование инструментов — проектируйте поведение модели, а не API

• Не зеркалируйте REST API. Группируйте не по одному инструменту на эндпоинт, а по единицам работы, которые будет выполнять модель.

• Инструментов должно быть мало, описания — длинными. Описание — это документ, содержащий информацию о том, когда использовать/не использовать инструмент, примеры аргументов и формат возвращаемых данных. Описание и есть промпт.

• Проектируйте вывод с учетом токенового бюджета. Вместо сырого дампа JSON форматируйте данные в удобном для модели виде, для больших результатов используйте аргументы limit + пагинация.

Стандартный шаблон структуры

• Разделение транспорта — для локального использования stdio, для удаленного — Streamable HTTP. Разделение логики сервера и транспорта упрощает поддержку обоих вариантов.

• Валидация входных данных через схему — TS SDK использует схемы zod для объявления аргументов инструментов. Не пишите валидацию вручную.

• Ошибки возвращайте не через throw, а через результат с isError: true. В сообщении указывайте причину и способ решения, чтобы модель могла прочитать сообщение об ошибке и повторить попытку.

• В stdio stdout — это протокольный канал. Логи обязательно выводите в stderr. Один console.log может убить сервер.

• Опасные операции блокируйте кодом, а не промптом. Например, в инструменте только для чтения — запрет на запись, принудительное внедрение LIMIT.

Рабочий процесс разработки

1. Ручное тестирование с MCP Inspector — npx @modelcontextprotocol/inspector node dist/index.js

2. Проверка сценариев выбора инструментов на реальной модели — если модель выбирает неправильный инструмент, исправляйте описание, а не код.

3. Бизнес-логику (валидаторы запросов, форматтеры) проверяйте юнит-тестами, не связанными с MCP.

Related MCP server: Neo4j GraphRAG MCP Server

4 способа реализации

1. Использование официального MCP-сервера Neo4j как есть

Подключение через настройку официального MCP-сервера от Neo4j.

• mcp-neo4j-cypher — предоставляет инструменты (get_schema, read_cypher, write_cypher), позволяющие LLM запрашивать схему и самостоятельно генерировать и выполнять Cypher.

• mcp-neo4j-memory — сервер для долговременной памяти, сохраняющий сущности и отношения из диалога в виде графа знаний.

2. Собственный MCP-сервер по принципу Text2Cypher

Создание собственного MCP-сервера, где инструмент имеет универсальную структуру «естественно-языковой запрос → генерация Cypher → выполнение». Похож на официальный сервер, но позволяет напрямую контролировать:

• Внедрение описания схемы (предоставление структуры графа в промпте)

• Валидацию запросов (принудительное только чтение, принудительный LIMIT)

• Форматирование результатов

3. Специализированные предметно-ориентированные инструменты

Подход, при котором LLM не доверяется генерация Cypher, а заранее определяются инструменты, соответствующие предметной области. Внутри каждого инструмента выполняются только параметризованные Cypher-запросы.

search_person(name)          → 파라미터화된 Cypher 실행
get_relationships(id, depth) → 파라미터화된 Cypher 실행
find_path(from, to)          → shortestPath 쿼리 실행

4. Подход GraphRAG

Подход, при котором используется один инструмент retrieve(query), выполняющий поиск по векторному индексу Neo4j, а затем расширяющий контекст за счет графа (соседние узлы, отношения) на основе найденных узлов.

retrieve(query)
  1. query 임베딩 → 벡터 인덱스 유사도 검색
  2. 매칭된 노드에서 그래프 확장 (이웃 노드, 관계 수집)
  3. 수집된 서브그래프를 컨텍스트로 반환

Рекомендуемая комбинация

На практике распространенным шаблоном является гибрид 2 + 3. Часто задаваемые вопросы обрабатываются предметно-ориентированными инструментами, а для остальных используется Text2Cypher только для чтения в качестве запасного варианта.

Справочная информация по стеку

• TypeScript — @modelcontextprotocol/sdk

• Python — FastMCP