Servidor MCP Neo4j

Esta es una implementación de servidor del Protocolo de Control de Memoria (MCP) que utiliza Neo4j como almacenamiento backend para la gestión de grafos de conocimiento. Proporciona una interfaz basada en stdio para almacenar y recuperar conocimiento en un formato de base de datos de grafos.

Prerrequisitos

Python 3.8+
Base de datos Neo4j (local o remota)
Poesía (gestor de paquetes de Python)
Docker y Docker Compose (para ejecutar Neo4j)
Go Task (opcional, para automatización de tareas)

Instalación

Clonar el repositorio:

git clone <repository-url>
cd neo4j_mcp_server

Instala Poetry si aún no lo has hecho:

curl -sSL https://install.python-poetry.org | python3 -

Instalar dependencias:

poetry install

Configuración

Configuración del escritorio de Claude

Para los usuarios de Ubuntu que ejecutan Claude Desktop, pueden configurar el servidor MCP agregándolo a su archivo de configuración de Claude Desktop en:

~/.config/Claude/claude_desktop_config.json

Antes de configurar, debe crear el ejecutable independiente:

task build

Esto creará un binario en dist/neo4j_mcp_server . Asegúrate de actualizar la ruta en tu configuración para que apunte a este ejecutable compilado.

Se proporciona un ejemplo de configuración en example_mcp_config.json . Puede copiar y modificar este archivo:

cp example_mcp_config.json ~/.config/Claude/claude_desktop_config.json

Luego edite la ruta command en el archivo de configuración para que apunte al ejecutable creado:

{
  "mcpServers": [
    {
      "name": "neo4j-knowledge-graph",
      "command": ["/path/to/your/dist/neo4j_mcp_server"],
      ...
    }
  ]
}

La configuración incluye:

Nombre y descripción del servidor
Comando para iniciar el servidor (ruta al ejecutable compilado)
Herramientas disponibles y sus parámetros
Campos obligatorios y tipos de datos

Ejecución del servidor

Uso de la tarea (recomendado)

Si tiene Go Task instalado, puede utilizar el Taskfile proporcionado para administrar el servidor:

# Show available tasks
task

# Start everything (Docker + Server)
task run

# Start development environment (Docker + Server + Test)
task dev

# Stop all services
task down

Usando Docker Compose directamente

Inicie el contenedor Neo4j:

docker-compose up -d

Espere a que Neo4j esté listo (el contenedor se mostrará como "saludable" en docker ps )

Ejecutar el servidor MCP directamente

Inicie el servidor con:

poetry run python mcp_neo4j_knowledge_graph/mcp/server.py

El servidor se iniciará en modo stdio, listo para aceptar mensajes del protocolo MCP.

Herramientas disponibles

1. Crear entidades

Crea nuevas entidades en el grafo de conocimiento. Cada entidad debe tener un tipo y propiedades. El ID se establecerá automáticamente a partir de la propiedad de nombre si no se proporciona explícitamente.

Parámetros:

entities : Lista de objetos de entidad, cada uno conteniendo:
- type : Cadena - El tipo de entidad (por ejemplo, Persona, Organización)
- properties : Objeto - Pares clave-valor de propiedades de entidad (debe incluir 'id' o 'name')

Ejemplo de entrada:

{
    "entities": [{
        "type": "Person",
        "properties": {
            "name": "John Doe",
            "occupation": "Developer",
            "age": 30
        }
    }]
}

2. Crear relaciones

Crea relaciones entre entidades existentes en el grafo de conocimiento. Todas las entidades referenciadas deben existir antes de crear relaciones.

Parámetros:

relations : Lista de objetos de relación, cada uno conteniendo:
- type : Cadena - El tipo de relación (por ejemplo, SABE, TRABAJA_PARA)
- from : Cadena - ID de la entidad de origen
- to : Cadena - ID de la entidad de destino

Ejemplo de entrada:

{
    "relations": [{
        "type": "KNOWS",
        "from": "john_doe",
        "to": "jane_smith"
    }]
}

3. Entidades de búsqueda

Busca entidades en el grafo de conocimiento con potentes funciones de coincidencia y filtrado de texto. Permite buscar por texto, listar entidades por tipo, encontrar entidades con propiedades específicas o cualquier combinación de estos filtros.

Parámetros:

search_term : Cadena (opcional) - Texto de búsqueda en las propiedades de la entidad. Si no se proporciona, devuelve las entidades según otros filtros.
entity_type : Cadena (opcional) - Filtra los resultados por tipo de entidad (p. ej., Persona, Organización). Si se proporciona solo, devuelve todas las entidades de ese tipo.
properties : List[String] (opcional) - Lista de nombres de propiedades para filtrar por:
- Con search_term: busca estas propiedades para el término
- Sin término de búsqueda: Devuelve entidades que tienen alguna de estas propiedades definidas
include_relationships : Booleano (opcional, predeterminado: falso) - Si se deben incluir entidades y relaciones conectadas
fuzzy_match : Booleano (opcional, valor predeterminado: verdadero) - Si se debe utilizar una coincidencia parcial sin distinción entre mayúsculas y minúsculas cuando se proporciona search_term

Entradas de ejemplo:

// Search by text with type filter
{
    "search_term": "John",
    "entity_type": "Person",
    "properties": ["name", "occupation"],
    "include_relationships": true
}

// List all entities of a type
{
    "entity_type": "Person"
}

// Find entities with specific properties
{
    "properties": ["email", "phone"],
    "entity_type": "Contact"
}

// Combine filters
{
    "entity_type": "Person",
    "properties": ["email"],
    "search_term": "example.com",
    "fuzzy_match": true
}

// Return all entities (no filters)
{}

Devoluciones:

{
    "results": [
        {
            "id": "john_doe",
            "type": ["Entity", "Person"],
            "properties": {
                "name": "John Doe",
                "email": "john@example.com"
            },
            "relationships": [  // Only included if include_relationships is true
                {
                    "type": "WORKS_AT",
                    "direction": "outgoing",
                    "node": {
                        "id": "tech_corp",
                        "type": "Company",
                        "properties": {
                            "name": "Tech Corp"
                        }
                    }
                }
            ]
        }
    ]
}

Notas:

Cuando no se proporcionan filtros, devuelve todas las entidades
El filtrado de tipo de entidad es de coincidencia exacta (no difusa)
La comprobación de existencia de la propiedad se realiza con IS NOT NULL
La búsqueda de texto admite coincidencias parciales sin distinción entre mayúsculas y minúsculas cuando fuzzy_match es verdadero
Los resultados vacíos se devuelven como una matriz vacía, no como un error.
Consideraciones de rendimiento:
- Filtrar por tipo es más eficiente que la búsqueda de texto
- Se optimizan las comprobaciones de existencia de propiedades
- Considere utilizar propiedades específicas en lugar de buscar todas las propiedades
- Es posible que los conjuntos de resultados grandes se paginaran en versiones futuras

4. Actualizar entidades

Actualiza las entidades existentes en el grafo de conocimiento. Permite añadir o eliminar propiedades y etiquetas.

Parámetros:

updates : Lista de objetos de actualización, cada uno conteniendo:
- id : cadena (obligatoria) - ID de la entidad a actualizar
- properties : Objeto (opcional) - Propiedades para actualizar o agregar
- remove_properties : List[String] (opcional) - Nombres de propiedades para eliminar
- add_labels : List[String] (opcional) - Etiquetas para agregar a la entidad
- remove_labels : List[String] (opcional) - Etiquetas para eliminar de la entidad

Ejemplo de entrada:

{
    "updates": [{
        "id": "john_doe",
        "properties": {
            "occupation": "Senior Developer",
            "salary": 100000
        },
        "remove_properties": ["temporary_note"],
        "add_labels": ["Verified"],
        "remove_labels": ["Pending"]
    }]
}

5. Eliminar entidades

Elimina entidades del gráfico de conocimiento con eliminación en cascada opcional de relaciones.

Parámetros:

entity_ids : List[String] (obligatorio) - Lista de ID de entidades para eliminar
cascade : booleano (opcional, predeterminado: falso): si se deben eliminar las relaciones conectadas
dry_run : Booleano (opcional, predeterminado: falso) - Vista previa del impacto de la eliminación sin realizar cambios

Ejemplo de entrada:

{
    "entity_ids": ["john_doe", "jane_smith"],
    "cascade": true,
    "dry_run": true
}

Devoluciones:

success : Booleano: si la operación fue exitosa
deleted_entities : Lista de entidades eliminadas
deleted_relationships : Lista de relaciones eliminadas
errors : Lista de mensajes de error (si los hay)
impacted_entities : Lista de entidades que se verían afectadas (solo ejecución en seco)
impacted_relationships : Lista de relaciones que se verían afectadas (solo ejecución en seco)

6. Esquema de introspección

Recupera información completa sobre el esquema de la base de datos Neo4j, incluidas las etiquetas de los nodos, los tipos de relación y sus propiedades.

Parámetros: No se requiere ninguno

Devoluciones:

schema : Objeto que contiene:
- node_labels : Lista de todas las etiquetas de nodo en la base de datos
- relationship_types : Lista de todos los tipos de relaciones
- node_properties : Mapa de la etiqueta a la lista de nombres de propiedades
- relationship_properties : Mapa del tipo de relación a la lista de nombres de propiedades

Ejemplo de entrada:

{}

Pruebas

Scripts de prueba

El proyecto incluye varios scripts de prueba para diferentes aspectos del sistema:

mcp_neo4j_knowledge_graph/test_mcp_client.py : prueba la funcionalidad del cliente MCP
- Verifica el inicio del servidor
- Listado de herramientas de prueba
- Prueba la introspección del esquema
- Prueba la creación de entidades GXP18
mcp_neo4j_knowledge_graph/test_mcp_config.py - Prueba la configuración de MCP
- Valida la carga del archivo de configuración
- Prueba la conexión del servidor utilizando el SDK oficial de MCP
- Verifica que todas las herramientas necesarias estén disponibles GXP19
mcp_neo4j_knowledge_graph/test_neo4j_connection.py - Prueba la conexión a la base de datos Neo4j
- Verifica la conectividad de la base de datos
- Prueba la funcionalidad básica de consulta
- Comprueba la configuración del entorno GXP20

Ejecución de pruebas

Puedes ejecutar las pruebas de varias maneras:

Ejecute todas las pruebas juntas:
task test # Runs all tests including pytest and integration tests
Ejecutar tipos de pruebas individuales:
task test-client # Run MCP client test task test-config # Run MCP config test task test-db # Run Neo4j connection test task test-integration # Run integration tests
Ejecute pruebas con pytest directamente:
poetry run pytest # Run all pytest-compatible tests

Desarrollo

Uso de la tarea

El proyecto incluye varias tareas de desarrollo:

# Format code
task format

# Run linter
task lint

# Run tests
task test

# Start development environment
task dev

Corriendo directamente

Este proyecto utiliza varias herramientas de desarrollo que se instalan automáticamente con Poetry:

black para formato de código
isort para la clasificación de importaciones
flake8 para quitar pelusa
pytest para pruebas

Puedes ejecutar estas herramientas usando Poetry:

# Format code
poetry run black .

# Sort imports
poetry run isort .

# Run linter
poetry run flake8

# Run tests
poetry run pytest

Manejo de errores

El servidor incluye un manejo integral de errores para:

Problemas de conexión a la base de datos
Consultas no válidas
Nodos faltantes
Formatos de solicitud no válidos
Errores de validación del esquema
Fracasos en la creación de relaciones
Conflictos de actualización de entidades

Todos los errores se devuelven con mensajes de error apropiados en el formato del protocolo MCP.

Configuración de Docker

El contenedor Neo4j está configurado con las siguientes configuraciones:

Puertos: 7474 (HTTP) y 7687 (Bolt)
Credenciales predeterminadas: neo4j/contraseña
Complemento APOC habilitado
Importación/exportación de archivos habilitada
Comprobación de estado configurada

Puede modificar estas configuraciones en el archivo docker-compose.yml .

Referencia de comandos de tarea

task - Mostrar tareas disponibles
task run : iniciar Docker y el servidor MCP
task dev - Iniciar entorno de desarrollo (Docker + Servidor + Prueba)
task docker : iniciar la base de datos de Neo4j
task server : ejecutar el servidor MCP
task test - Ejecutar todas las pruebas
task test-client : ejecutar pruebas de cliente MCP
task test-config : ejecuta pruebas de configuración de MCP
task test-db - Ejecutar pruebas de base de datos
task test-integration - Ejecutar pruebas de integración
task down : detenga todos los servicios de Docker
task format : Formatear código usando black e isort
task lint - Ejecutar flake8 linter
task help : muestra ayuda detallada para todas las tareas

Neo4j Knowledge Graph

Integrations

Servidor MCP Neo4j

Prerrequisitos

Instalación

Configuración

Configuración del escritorio de Claude

Ejecución del servidor

Uso de la tarea (recomendado)

Usando Docker Compose directamente

Ejecutar el servidor MCP directamente

Herramientas disponibles

1. Crear entidades

2. Crear relaciones

3. Entidades de búsqueda

4. Actualizar entidades

5. Eliminar entidades

6. Esquema de introspección

Pruebas

Scripts de prueba

Ejecución de pruebas

Desarrollo

Uso de la tarea

Corriendo directamente

Manejo de errores

Configuración de Docker

Referencia de comandos de tarea

Appeared in Searches