Apache AGE MCP

age-mcp

Servidor MCP para bases de datos de grafos Apache AGE. Permite a los asistentes de IA (Claude, ChatGPT, Copilot, etc.) consultar y modificar datos de grafos a través del Model Context Protocol.

Construido con F# en .NET 10 -- 1,300 líneas, 21 herramientas, cero dependencias de Python.

Inicio Rápido

# 1. Start the database
docker compose up -d

# 2. Install the tool
dotnet tool install --global AgeMcp

# 3. Run
AGE_CONNECTION_STRING="Host=localhost;Port=5435;Database=agemcp;Username=agemcp;Password=agemcp" age-mcp

Claude Desktop / Claude Code

{
  "mcpServers": {
    "age-mcp": {
      "type": "stdio",
      "command": "age-mcp",
      "env": {
        "AGE_CONNECTION_STRING": "Host=localhost;Port=5435;Database=agemcp;Username=agemcp;Password=agemcp",
        "TENANT_ID": "default"
      }
    }
  }
}

Herramientas (21)

Gestión de Grafos

Herramienta	Descripción
get_or_create_graph	Obtener o crear un grafo por nombre
list_graphs	Listar todos los grafos (con ámbito de inquilino)
drop_graphs	Eliminar uno o más grafos

Vértices y Aristas

Herramienta	Descripción
upsert_vertex	Insertar o actualizar un vértice (fusionar por ident)
upsert_edge	Insertar o actualizar una arista dirigida
upsert_graph	Inserción o actualización por lotes de vértices + aristas (transaccional)
drop_vertex	Eliminar un vértice y todas sus aristas
drop_edge	Eliminar una arista por ident

Consulta

Herramienta	Descripción
cypher_query	Ejecutar una consulta Cypher de lectura
cypher_write	Ejecutar una consulta Cypher de escritura, devuelve el recuento de afectados
search_vertices	Buscar por etiqueta y/o propiedad
search_edges	Buscar aristas por etiqueta
get_neighbors	Recorrido de N saltos (1-5 saltos, direccional)
get_schema	Todas las etiquetas de nodos y recuentos

Exportar / Importar

Herramienta	Descripción
export_graph	Exportar grafo como JSON
import_graph	Importar desde JSON (crea el grafo si es necesario)

Visualización y Búsqueda

Herramienta	Descripción
generate_visualization	Grafo HTML interactivo de vis.js
semantic_search	Búsqueda de similitud vectorial (pgvector)
graph_context	Graph RAG: semillas semánticas + expansión de N saltos

Puente OpenBrain

Herramienta	Descripción
sync_to_openbrain	Exportar vértices como recuerdos de OpenBrain
import_from_openbrain	Construir grafo a partir de recuerdos de OpenBrain

Configuración

Variable	Requerido	Predeterminado	Descripción
AGE_CONNECTION_STRING	sí	base de datos de prueba local	Cadena de conexión Npgsql
TENANT_ID	no	default	Prefijo de inquilino para nombres de grafos
EMBEDDING_API_URL	no	--	API de incrustación compatible con OpenAI
EMBEDDING_API_KEY	no	--	Clave API para incrustaciones
EMBEDDING_MODEL	no	text-embedding-3-small	Nombre del modelo de incrustación
EMBEDDING_DIMENSIONS	no	384	Dimensiones del vector

Docker

La configuración de Docker incluida ejecuta PostgreSQL 17 + Apache AGE 1.6.0 + pgvector:

docker compose up -d

Las versiones y credenciales son configurables mediante .env (ver .env.example):

PG_MAJOR=17  AGE_VERSION=1.6.0  DB_PORT=5435  docker compose up -d

Compatibilidad de Datos

Diseñado como reemplazo directo de agemcp (Python). Mismo prefijo de inquilino (t_{TENANT_ID}__), misma propiedad de vértice ident, mismas propiedades de arista start_ident/end_ident. Los datos existentes funcionan sin migración.

Rendimiento

BenchmarkDotNet en Apple M1 Pro, .NET 10.0.5:

Operación	Latencia	Asignado
list_graphs	62 ns	216 B
get_schema	117 ns	344 B
cypher_query (1 vertex)	1.0 ms	58 KB
search_vertices	1.0 ms	36 KB
get_neighbors (depth=1)	92 ms	233 KB
export_graph (40 entities)	71 ms	472 KB

Compilación desde el Código Fuente

git clone https://github.com/Neftedollar/age-mcp.git
cd age-mcp
dotnet build

# Run directly
dotnet run

# Or install as tool
dotnet pack -c Release
dotnet tool install --global AgeMcp

Las dependencias (FsMcp.Core, FsMcp.Server, Fyper) se restauran automáticamente desde NuGet.

Licencia

MIT