mcp-chat

Resumen de la implementación del servidor MCP para chatbot basado en Neo4j.

Principios de creación del servidor MCP

Diseño de herramientas — No diseñes una API, diseña el comportamiento del modelo

• No reflejes una API REST. No se trata de una herramienta por endpoint, sino de agruparlas por unidad de trabajo que el modelo realizará.

• Pocas herramientas, descripciones largas. La descripción es un documento que incluye cuándo usarla / cuándo no usarla, ejemplos de argumentos y formato de retorno. La descripción es el prompt.

• Diseña la salida dentro del presupuesto de tokens. En lugar de un volcado JSON en bruto, formatea de manera legible para el modelo y, para resultados grandes, incluye argumentos de limit + paginación.

Patrón estándar de estructura

• Separación del transporte — local con stdio, remoto con Streamable HTTP. Separar la lógica del servidor del transporte facilita el soporte de ambos.

• Validación de entrada mediante esquemas — el SDK de TypeScript declara los argumentos de las herramientas con esquemas zod. No escribas validación manualmente.

• Los errores no se lanzan, se devuelven como resultado con isError: true. Para que el modelo lea el mensaje de error y reintente, incluye en el mensaje la causa y la solución.

• En stdio, stdout es el canal del protocolo. Los registros deben ir siempre a stderr. Un solo console.log mata el servidor.

• Las operaciones peligrosas se bloquean con código, no con prompts. Por ejemplo, en una herramienta de solo lectura, rechazar sentencias de escritura, inyección forzada de LIMIT.

Flujo de trabajo de desarrollo

1. Pruebas manuales con MCP Inspector — npx @modelcontextprotocol/inspector node dist/index.js

2. Validación de escenarios de selección de herramientas con el modelo real — si el modelo elige una herramienta incorrecta, corrige la descripción, no el código.

3. La lógica de negocio (validador de consultas, formateador) se valida con pruebas unitarias independientes de MCP.

Related MCP server: Neo4j GraphRAG MCP Server

4 formas de implementación

1. Usar el servidor MCP oficial de Neo4j tal cual

Forma de conectar el servidor MCP proporcionado oficialmente por Neo4j solo con configuración.

• mcp-neo4j-cypher — Proporciona herramientas (get_schema, read_cypher, write_cypher) para que el LLM consulte el esquema y genere y ejecute Cypher directamente.

• mcp-neo4j-memory — Servidor de memoria a largo plazo que almacena entidades/relaciones extraídas de la conversación como un grafo de conocimiento.

2. Servidor MCP propio con enfoque Text2Cypher

Crear tu propio servidor MCP, pero con herramientas de estructura general de "pregunta en lenguaje natural → generación de Cypher → ejecución". Similar al servidor oficial, pero con control directo sobre:

• Inyección de descripción del esquema (proporcionar estructura del grafo en el prompt)

• Validación de consultas (forzar solo lectura, forzar LIMIT)

• Formateo de resultados

3. Enfoque de herramientas especializadas por dominio

No delegar la generación de Cypher al LLM, sino definir herramientas adaptadas al dominio. Cada herramienta internamente solo ejecuta Cypher parametrizado.

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

4. Enfoque GraphRAG

Realizar una búsqueda de similitud con el índice vectorial de Neo4j y luego expandir el grafo desde los nodos coincidentes (vecinos, relaciones) para construir contexto, exponiendo una única herramienta retrieve(query).

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

Combinación recomendada

En la práctica, la combinación 2 + 3 es un patrón común. Las preguntas frecuentes se manejan con herramientas especializadas por dominio, y el resto se usa como fallback con Text2Cypher de solo lectura.

Referencia de stack

• TypeScript — @modelcontextprotocol/sdk

• Python — FastMCP