KnowledgeGraph MCP Server

Permite el almacenamiento persistente de conocimiento para Claude mediante un grafo de conocimiento con múltiples motores de base de datos como PostgreSQL y SQLite.

GitHub
26
Prueba este MCPPatrocinado

Documentación

MseeP.ai Security Assessment Badge

ADVERTENCIA

Me he desilusionado con las herramientas automatizadas de gestión de contexto como esta, ya que es casi imposible controlarlas. Después de un tiempo, siempre tengo que limpiar manualmente el desorden o corregir notas inapropiadas del LLM. En su lugar, creé una herramienta que le da al agente LLM acceso a contexto cargado dinámicamente. Sin embargo, el contexto en sí es creado por el usuario: https://github.com/n-r-w/agent-standards-mcp

KnowledgeGraph MCP Server

Una forma sencilla de dar a los LLMs memoria persistente entre conversaciones. Este servidor permite que Claude o vscode recuerden información sobre ti, tus proyectos y tus preferencias utilizando un grafo de conocimiento.

Características principales:

  • Múltiples backends de almacenamiento: PostgreSQL (recomendado) o SQLite (archivo local)
  • Separación de proyectos: Mantén diferentes proyectos aislados (detección automática mediante prompts)
  • Mejor búsqueda: Encuentra información con búsqueda difusa y paginación

Guía de configuración completa

Sigue estos pasos en orden para que el grafo de conocimiento funcione con Claude:

Paso 1: Elige tu método de instalación

Opción A: NPX (Más fácil - Sin necesidad de descarga)

# Test that it works
npx knowledgegraph-mcp --help

Opción B: Docker

# Clone and build
git clone https://github.com/n-r-w/knowledgegraph-mcp.git
cd knowledgegraph-mcp
docker build -t knowledgegraph-mcp .

Paso 2: Elige tu base de datos

SQLite (Predeterminado - Sin configuración necesaria):

  • No se requiere instalación de base de datos
  • El archivo de base de datos se crea automáticamente en [you home folder]/.knowledge-graph/
  • Perfecto para uso personal y la mayoría de escenarios
  • Este es el backend predeterminado

PostgreSQL (Para usuarios avanzados):

  • Instala PostgreSQL en tu sistema
  • Crea una base de datos: CREATE DATABASE knowledgegraph;
  • Mejor para uso en producción con múltiples usuarios concurrentes

Paso 3: Configura el cliente

Claude Desktop

Edita tu archivo de configuración de Claude Desktop:

Encuentra tu archivo de configuración:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Si elegiste NPX + SQLite (predeterminado y más fácil):

{
  "mcpServers": {
    "Knowledge Graph": {
      "command": "npx",
      "args": ["-y", "knowledgegraph-mcp"]
    }
  }
}

Nota: SQLite creará automáticamente la base de datos en [you home folder]/.knowledge-graph/knowledgegraph.db. Para usar una ubicación personalizada, añade: "KNOWLEDGEGRAPH_SQLITE_PATH": "/path/to/your/database.db"

Si elegiste Docker + SQLite (predeterminado):

{
  "mcpServers": {
    "Knowledge Graph": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "[you home folder]/.knowledge-graph:/app/.knowledge-graph",
        "knowledgegraph-mcp"
      ]
    }
  }
}

Nota: El montaje de volumen asegura que tus datos persistan entre ejecuciones de Docker. Para rutas personalizadas, añade: -e KNOWLEDGEGRAPH_SQLITE_PATH=/app/.knowledge-graph/custom.db

Si elegiste PostgreSQL:

{
  "mcpServers": {
    "Knowledge Graph": {
      "command": "npx",
      "args": ["-y", "knowledgegraph-mcp"],
      "env": {
        "KNOWLEDGEGRAPH_STORAGE_TYPE": "postgresql",
        "KNOWLEDGEGRAPH_CONNECTION_STRING": "postgresql://postgres:yourpassword@localhost:5432/knowledgegraph"
      }
    }
  }
}

VS Code

Si también quieres usar esto con VS Code, añade esto a tu Configuración de Usuario (JSON) o crea .vscode/mcp.json:

Usando NPX + SQLite (predeterminado):

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "npx",
        "args": ["-y", "knowledgegraph-mcp"],
      }
    }
  }
}

Usando Docker (SQLite predeterminado):

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=sqlite://./knowledgegraph.db",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

Usando Docker + PostgreSQL:

Primero, asegúrate de que tu base de datos PostgreSQL esté configurada:

# Create the database (run this once)
psql -h 127.0.0.1 -p 5432 -U postgres -c "CREATE DATABASE knowledgegraph;"

Luego configura VS Code:

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "--network", "host",
          "-e", "KNOWLEDGEGRAPH_STORAGE_TYPE=postgresql",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=postgresql://postgres:yourpassword@127.0.0.1:5432/knowledgegraph",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

Alternativa Docker + PostgreSQL (si --network host no funciona):

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "--add-host", "host.docker.internal:host-gateway",
          "-e", "KNOWLEDGEGRAPH_STORAGE_TYPE=postgresql",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=postgresql://postgres:yourpassword@host.docker.internal:5432/knowledgegraph",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

Notas importantes:

  • Reemplaza yourpassword con tu contraseña real de PostgreSQL
  • Asegúrate de que la base de datos knowledgegraph exista antes de comenzar
  • Si recibes errores de conexión, prueba la configuración alternativa anterior
  • Para solucionar problemas de Docker + PostgreSQL, consulta la sección Problemas comunes

Paso 4: Elige los prompts de sistema de tu LLM

Personalización:

  • Modifica los tipos de entidades según tu dominio
  • Ajusta las estrategias de búsqueda según tus patrones de datos
  • Añade etiquetas específicas del dominio y tipos de relaciones

Compatibilidad con LLM:

  • Todos los LLMs se comportan de manera diferente. Para algunos, las instrucciones generales son suficientes, mientras que otros necesitan describir todo en detalle
  • Usa el LLM para que explique por qué no usó el grafo de conocimiento. Pregunta a Explain STEP-BY-STEP why you didn't use the knowledge graph? DO NOT DO ANYTHING ELSE para obtener un informe detallado e identificar problemas con las instrucciones.

Prompts disponibles:

Paso 5: Reinicia Claude Desktop (o VS Code)

Cierra y vuelve a abrir Claude Desktop. Ahora deberías ver "Knowledge Graph" en tus herramientas disponibles.

Paso 6: Prueba que funciona

Comandos de prueba rápidos para LLMs:

  1. "Recuerda que prefiero reuniones por la mañana" → Crea una entidad de preferencia
  2. "John Smith trabaja en Google como ingeniero de software" → Crea persona + empresa + relación
  3. "Encuentra a todas las personas que trabajan en Google" → Prueba búsqueda y relaciones
  4. "Marca la preferencia de reuniones por la mañana como urgente" → Prueba etiquetas

Nota: El servicio incluye validación integral de entrada para prevenir errores. Si encuentras algún problema, consulta la Guía de solución de problemas para soluciones comunes.

Cómo funciona - Funciones avanzadas del LLM

El grafo de conocimiento permite consultas potentes a través de cuatro conceptos interconectados:

1. Entidades - Tus nodos de conocimiento

Almacena personas, proyectos, empresas, tecnologías como entidades buscables.

Ejemplo real - Gestión de proyectos:

{
  "name": "Sarah_Chen",
  "entityType": "person",
  "observations": ["Senior React developer", "Leads frontend team", "Available for urgent tasks"],
  "tags": ["developer", "team-lead", "available"]
}

Beneficio para el LLM: Encuentra "todos los líderes de equipo disponibles" al instante con búsqueda por etiquetas.

2. Relaciones - Habilitan consultas de descubrimiento

Conecta entidades para responder preguntas complejas como "¿Quién trabaja en qué?"

Ejemplo real - Estructura de equipo:

{
  "from": "Sarah_Chen",
  "to": "Project_Alpha",
  "relationType": "leads"
}

Beneficio para el LLM: Consulta "Encuentra todos los proyectos que lidera Sarah" o "¿Quién lidera el Proyecto Alpha?"

3. Observaciones - Hechos atómicos

Almacena hechos específicos y buscables sobre entidades.

Ejemplos reales - Información accionable:

  • "Disponible para tareas urgentes" → Encuentra personas disponibles
  • "Usa React 18.2" → Encuentra proyectos con tecnología específica
  • "Fecha límite: 15 de marzo de 2024" → Encuentra fechas límite próximas

4. Etiquetas - Filtrado instantáneo

Habilitan búsquedas inmediatas de estado y categoría.

Ejemplos reales - Flujo de trabajo de proyectos:

  • ["urgent", "in-progress", "frontend"] → Encuentra tareas urgentes de frontend
  • ["completed", "bug-fix"] → Rastrea correcciones de errores completadas
  • ["available", "senior"] → Encuentra personal senior disponible

Opciones de configuración

Variables de entorno

El servidor admite varias variables de entorno para personalización:

Configuración de base de datos

  • KNOWLEDGEGRAPH_STORAGE_TYPE: Tipo de base de datos (sqlite o postgresql, predeterminado: sqlite)
  • KNOWLEDGEGRAPH_CONNECTION_STRING: Cadena de conexión de base de datos
  • KNOWLEDGEGRAPH_SQLITE_PATH: Ruta personalizada de base de datos SQLite (opcional)
  • KNOWLEDGEGRAPH_PROJECT: Identificador de proyecto para aislamiento de datos (predeterminado: knowledgegraph_default_project)

Configuración de búsqueda

  • KNOWLEDGEGRAPH_SEARCH_MAX_RESULTS: Número máximo de resultados a devolver de búsquedas en base de datos (predeterminado: 100, máximo: 1000)
  • KNOWLEDGEGRAPH_SEARCH_BATCH_SIZE: Tamaño de lote para procesar matrices de consulta grandes (predeterminado: 10, máximo: 50)
  • KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES: Número máximo de entidades a cargar para búsqueda del lado del cliente (predeterminado: 10000, máximo: 100000)
  • KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE: Tamaño de fragmento para procesar conjuntos de datos grandes en búsqueda del lado del cliente (predeterminado: 1000, máximo: 10000)

Nota: Los límites de búsqueda se validan y ajustan automáticamente a rangos seguros para prevenir problemas de rendimiento.

Optimización del rendimiento

El sistema de búsqueda incluye varias optimizaciones de rendimiento:

Límites de carga de entidades:

  • KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES limita cuántas entidades se cargan para búsqueda del lado del cliente
  • Previene problemas de memoria con conjuntos de datos grandes
  • Se registra una advertencia cuando se alcanza el límite
  • Se aplica tanto a backends SQLite como PostgreSQL

Procesamiento por fragmentos:

  • KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE controla el tamaño de fragmento para conjuntos de entidades grandes
  • Se usa automáticamente cuando el número de entidades supera el tamaño de fragmento
  • Mejora el uso de memoria y el rendimiento de búsqueda
  • Mantiene la precisión de resultados con deduplicación

Valores recomendados según el tamaño del conjunto de datos:

  • Pequeño (< 1,000 entidades): Los valores predeterminados funcionan bien
  • Mediano (1,000 - 10,000 entidades): Considera KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES=5000, KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE=500
  • Grande (> 10,000 entidades): Usa búsqueda a nivel de base de datos cuando sea posible, o KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES=2000, KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE=200

Monitoreo del rendimiento:

  • Se registran advertencias cuando se aplican límites
  • El fragmentado se registra automáticamente para transparencia
  • La validación de configuración previene ajustes subóptimos

Herramientas disponibles

El servidor proporciona estas herramientas para gestionar tu grafo de conocimiento:

Herramientas de creación de datos

create_entities

CREA nuevas entidades (personas, conceptos, objetos) en el grafo de conocimiento.

  • CUÁNDO: Úsalo para entidades que aún no existen
  • RESTRICCIÓN: Cada entidad DEBE tener ≥1 observación no vacía
  • COMPORTAMIENTO: Ignora entidades con nombres existentes (usa add_observations para actualizar)

Entrada:

  • entities (Entity[]): Matriz de objetos de entidad. Cada uno REQUIERE:
    • name (string): Identificador único, no vacío
    • entityType (string): Categoría (ej., 'person', 'project'), no vacía
    • observations (string[]): Hechos sobre la entidad, DEBE contener ≥1 cadena no vacía
    • tags (string[], opcional): Etiquetas de coincidencia exacta para filtrado
  • project_id (string, opcional): Nombre del proyecto para aislar datos

create_relations

CONECTA entidades para habilitar consultas potentes y descubrimiento.

  • BENEFICIOS INMEDIATOS: Encuentra todas las personas en una empresa, todos los proyectos que usan una tecnología, todas las dependencias
  • CRÍTICO PARA: Estructuras de equipo, dependencias de proyectos, pilas tecnológicas
  • EJEMPLOS: 'John works_at Google', 'React depends_on JavaScript', 'Project_Alpha managed_by Sarah'

Entrada:

  • relations (Relation[]): Matriz de objetos de relación. Cada uno REQUIERE:
    • from (string): Nombre de entidad fuente (debe existir)
    • to (string): Nombre de entidad destino (debe existir)
    • relationType (string): Tipo de relación en voz activa (works_at, manages, depends_on, uses)
  • project_id (string, opcional): Nombre del proyecto para aislar datos

add_observations

AÑADE observaciones fácticas a entidades existentes.

  • REQUISITO: La entidad destino debe existir, ≥1 observación no vacía por actualización
  • MEJOR PRÁCTICA: Mantén las observaciones atómicas y específicas

Entrada:

  • observations (ObservationUpdate[]): Matriz de actualizaciones de observación. Cada una REQUIERE:
    • entityName (string): Nombre de entidad destino (debe existir)
    • observations (string[]): Nuevos hechos a añadir, DEBE contener ≥1 cadena no vacía
  • project_id (string, opcional): Nombre del proyecto para aislar datos

add_tags

AÑADE etiquetas de estado/categoría para FILTRADO instantáneo.

  • BENEFICIO INMEDIATO: Encuentra entidades por estado (urgente, completado, en progreso) o tipo (técnico, personal)
  • REQUERIDO: Para gestión eficiente de proyectos y recuperación rápida
  • EJEMPLOS: ['urgente', 'completado', 'error', 'característica', 'personal']

Entrada:

  • updates (TagUpdate[]): Matriz de actualizaciones de etiquetas. Cada una REQUIERE:
    • entityName (string): Nombre de entidad destino (debe existir)
    • tags (string[]): Etiquetas de estado/categoría a añadir (coincidencia exacta, sensible a mayúsculas)
  • project_id (string, opcional): Nombre del proyecto para aislar datos

Herramientas de recuperación de datos

read_graph

RECUPERA el grafo de conocimiento completo con todas las entidades y relaciones.

  • CASO DE USO: Visión general completa, comprensión del estado actual, ver todas las conexiones
  • ALCANCE: Devuelve todo en el proyecto especificado

Entrada:

  • project_id (string, opcional): Nombre del proyecto para aislar datos

search_knowledge

BUSCA entidades por texto o etiquetas. ADMITE MÚLTIPLES CONSULTAS para búsqueda por lotes.

  • ESTRATEGIA OBLIGATORIA: 1) Prueba searchMode='exact' primero 2) Si no hay resultados, usa searchMode='fuzzy' 3) Si sigue vacío, baja fuzzyThreshold a 0.1
  • MODO EXACTO: Coincidencias perfectas de subcadenas (rápido, preciso)
  • MODO DIFUSO: Términos similares/mal escritos (más lento, más amplio)
  • BÚSQUEDA POR ETIQUETAS: Usa exactTags para filtrado preciso por categoría
  • MÚLTIPLES CONSULTAS: Busca múltiples objetos en una sola llamada con deduplicación automática Entrada:
  • query (string | string[], opcional): Consulta de búsqueda para búsqueda de texto. Puede ser una sola cadena o un array de cadenas para búsqueda de múltiples objetos. OPCIONAL cuando se proporciona exactTags para búsquedas solo por etiquetas.
  • searchMode (string, opcional): "exact" o "fuzzy" (por defecto: "exact"). Use fuzzy solo si exact no devuelve resultados.
  • fuzzyThreshold (number, opcional): Umbral de similitud difusa. 0.3=por defecto, 0.1=muy amplio, 0.7=muy estricto. Valores más bajos encuentran más resultados.
  • exactTags (string[], opcional): Etiquetas para búsqueda de coincidencia exacta (sensible a mayúsculas). Use para filtrado por categoría.
  • tagMatchMode (string, opcional): Para exactTags: "any"=entidades con CUALQUIER etiqueta, "all"=entidades con TODAS las etiquetas (por defecto: "any").
  • page (number, opcional): Número de página para paginación (basado en 0, por defecto: 0).
  • pageSize (number, opcional): Número de resultados por página (1-1000, por defecto: 50).
  • project_id (string, opcional): Nombre del proyecto para aislar datos.

Ejemplos:

  • Búsqueda básica: search_knowledge(query="JavaScript", searchMode="exact")
  • Búsqueda paginada: search_knowledge(query="React", page=0, pageSize=20)
  • Conjunto de datos grande: search_knowledge(query="components", page=2, pageSize=100)
  • Múltiples consultas: search_knowledge(query=["JavaScript", "React"], page=0, pageSize=30)
  • Etiqueta + paginación: search_knowledge(query="React", exactTags=["frontend"], page=1, pageSize=25)
  • Búsqueda solo por etiquetas: search_knowledge(exactTags=["urgent", "bug"], tagMatchMode="all") - NO SE NECESITA CONSULTA

Beneficios de la paginación:

  • Rendimiento: Paginación a nivel de base de datos con OFFSET/LIMIT para manejo eficiente de grandes conjuntos de datos.
  • Memoria: Reduce el uso de memoria al limitar los resultados por solicitud.
  • Navegación: Los metadatos de paginación proporcionan totalPages, currentPage y sugerencias de navegación.
  • Escalabilidad: Maneja grafos de conocimiento con miles de entidades de manera eficiente.

open_nodes

RECUPERA entidades específicas por nombres exactos con sus interconexiones.

  • DEVUELVE: Las entidades solicitadas más las relaciones entre ellas.
  • CASO DE USO: Cuando conoce nombres de entidades exactos y desea información detallada.

Entrada:

  • names (string[]): Array de nombres de entidades a recuperar.
  • project_id (string, opcional): Nombre del proyecto para aislar datos.

Herramientas de Gestión de Datos

delete_entities

ELIMINA PERMANENTEMENTE entidades y todas sus relaciones.

  • ADVERTENCIA: No se puede deshacer, se propaga para eliminar todas las conexiones.
  • CASO DE USO: Entidades que ya no son relevantes o creadas por error.

Entrada:

  • entityNames (string[]): Array de nombres de entidades a eliminar.
  • project_id (string, opcional): Nombre del proyecto para aislar datos.

delete_observations

ELIMINA observaciones específicas de entidades manteniendo las entidades intactas.

  • CASO DE USO: Corregir información errónea o eliminar detalles obsoletos.
  • PRESERVACIÓN: La entidad y otras observaciones permanecen sin cambios.

Entrada:

  • deletions (ObservationDeletion[]): Array de solicitudes de eliminación. Cada una REQUIERE:
    • entityName (string): Nombre de la entidad objetivo.
    • observations (string[]): Observaciones específicas a eliminar.
  • project_id (string, opcional): Nombre del proyecto para aislar datos.

delete_relations

ACTUALIZA la estructura de relaciones cuando las conexiones cambian.

  • CRÍTICO PARA: Cambios de trabajo (eliminar 'works_at' antiguo), finalización de proyectos (eliminar 'assigned_to'), migración de tecnología (eliminar 'uses' antiguo).
  • MANTIENE: Estructura de red precisa y previene confusión.
  • FLUJO DE TRABAJO: Siempre elimine relaciones obsoletas al crear nuevas.

Entrada:

  • relations (Relation[]): Array de relaciones a eliminar. Cada una REQUIERE:
    • from (string): Nombre de la entidad fuente.
    • to (string): Nombre de la entidad objetivo.
    • relationType (string): Tipo de relación exacto a eliminar.
  • project_id (string, opcional): Nombre del proyecto para aislar datos.

remove_tags

ACTUALIZA el estado de la entidad eliminando etiquetas obsoletas.

  • CRÍTICO: Para seguimiento de estado: elimine 'in-progress' cuando se complete, 'urgent' cuando se resuelva.
  • MANTIENE: Resultados de búsqueda limpios y estado preciso.
  • FLUJO DE TRABAJO: Siempre elimine etiquetas de estado antiguas al agregar nuevas.

Entrada:

  • updates (TagUpdate[]): Array de solicitudes de eliminación de etiquetas. Cada una REQUIERE:
    • entityName (string): Nombre de la entidad objetivo.
    • tags (string[]): Etiquetas obsoletas a eliminar (coincidencia exacta, sensible a mayúsculas).
  • project_id (string, opcional): Nombre del proyecto para aislar datos.

Desarrollo y Pruebas

Pruebas Multi-Backend

Este proyecto incluye pruebas multi-backend integrales para garantizar compatibilidad tanto con SQLite como con PostgreSQL:

Ejecutar pruebas contra ambos backends:

npm run test:multi-backend

Ejecutar todas las pruebas (originales + multi-backend):

npm run test:all-backends

Usando Taskfile (si está instalado):

task test:multi-backend
task test:comprehensive

Configuración de Desarrollo

Clonar y configurar:

git clone https://github.com/n-r-w/knowledgegraph-mcp.git
cd knowledgegraph-mcp
npm install
npm run build

Ejecutar pruebas:

npm test                    # All tests including multi-backend
npm run test:unit          # Unit tests only
npm run test:performance   # Performance benchmarks

Solución de Problemas

Si encuentra algún problema durante la configuración o el uso, consulte nuestra Guía de Solución de Problemas integral, que cubre:

  • Errores de validación de entrada
  • Problemas de conexión a la base de datos
  • Problemas de configuración
  • Desafíos relacionados con Docker
  • Fallos en la ejecución de pruebas
  • Optimización del rendimiento

La guía incluye soluciones paso a paso para problemas comunes y comandos de diagnóstico para ayudar a identificar problemas.

Basado en MCP Memory Server

Esta es una versión mejorada del MCP Memory Server oficial con características adicionales:

  • Múltiples Opciones de Almacenamiento: PostgreSQL (recomendado) o SQLite (archivo local)
  • Separación de Proyectos: Mantenga diferentes proyectos aislados
  • Mejor Búsqueda: Encuentre información con búsqueda difusa
  • Configuración Fácil: Soporte para Docker e instalación simple

Licencia

Licencia MIT: siéntase libre de usar, modificar y distribuir este software.