Apache AGE MCP Server

Un servidor para Apache AGE, una extensión de base de datos de grafos para PostgreSQL.

Documentación

Servidor MCP de AGE

Un servidor MCP para consultar grafos de Apache AGE en PostgreSQL.

La versión 0.3.0 hace que la operación de solo lectura sea el valor predeterminado seguro, añade agrupación de conexiones asíncronas, parámetros Cypher seguros y paginación con cursor acotada, y devuelve contenido estructurado MCP desde cada herramienta.

Requisitos

Python 3.13 o posterior
PostgreSQL con la extensión Apache AGE instalada y cargada
Un rol de base de datos restringido a los grafos y operaciones que el cliente MCP necesite

Habilite AGE en la base de datos de destino:

CREATE EXTENSION IF NOT EXISTS age CASCADE;

Instalación

Con uv:

uv init your_project
cd your_project
uv add age_mcp_server

Con un entorno virtual de Python:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install age_mcp_server

Con Homebrew:

brew install rioriost/tap/age_mcp_server

Configurar un cliente MCP

Evite colocar una contraseña de base de datos en los argumentos de línea de comandos. Proporcione una cadena de conexión a través de PG_CONNECTION_STRING y use uno de los mecanismos de credenciales de libpq, como PGPASSWORD o un archivo de contraseñas protegido de PostgreSQL.

{
  "mcpServers": {
    "age_manager": {
      "command": "age_mcp_server",
      "env": {
        "PG_CONNECTION_STRING": "host=db.example port=5432 dbname=postgres user=age_reader sslmode=require",
        "PGPASSWORD": "replace-with-a-secret"
      }
    }
  }
}

Trate la configuración del cliente MCP como un secreto si contiene PGPASSWORD. Un archivo de contraseñas de PostgreSQL o el almacén de secretos del cliente es preferible.

La cadena de conexión aún puede proporcionarse explícitamente cuando sea necesario:

age_mcp_server --pg-con-str "host=db.example dbname=postgres user=age_reader sslmode=require"

Para la autenticación de Microsoft Entra en Azure Database for PostgreSQL, primero inicie sesión con la CLI de Azure y luego opte por la adquisición de tokens:

age_mcp_server \
  --pg-con-str "host=server.postgres.database.azure.com dbname=postgres user=identity sslmode=require" \
  --azure-identity

Herramientas

El modo de solo lectura es el predeterminado:

Herramienta	Propósito
`read-age-cypher`	Ejecutar una consulta Cypher de solo lectura validada, parametrizada y paginada
`list-age-graphs`	Listar grafos de Apache AGE
`get-age-schema`	Inspeccionar conteos, direcciones y tipos de propiedades muestreados

Las herramientas de escritura solo se anuncian y aceptan cuando el servidor se inicia con --allow-write:

Herramienta	Propósito
`write-age-cypher`	Ejecutar Cypher que contenga una cláusula de mutación
`create-age-graph`	Crear un grafo
`drop-age-graph`	Eliminar permanentemente un grafo

age_mcp_server --allow-write

Use un rol de base de datos separado con privilegios mínimos para el modo de escritura. Habilitar la bandera no otorga privilegios de PostgreSQL que el rol configurado no tenga ya.

Límites de seguridad

Cypher, nombres de grafos, alias de retorno y argumentos de gestión de grafos se citan o parametrizan de forma segura antes de llegar a PostgreSQL.
Las herramientas de lectura se ejecutan dentro de transacciones de solo lectura de PostgreSQL.
CALL se considera con efectos secundarios y requiere modo de escritura.
Las páginas de lectura contienen como máximo 50 filas. Los cursores opacos autenticados con HMAC están vinculados al grafo, consulta y parámetros, con un desplazamiento máximo de 100,000.
Los $parameters de Cypher se aceptan solo cuando los nombres de los marcadores de posición coinciden exactamente con un objeto de parámetros JSON. El objeto está limitado a 100,000 bytes y se pasa a AGE mediante una declaración preparada.
Las consultas de escritura se ejecutan completamente y devuelven un conteo de filas afectadas en lugar de filas de resultados.
Las declaraciones agotan el tiempo de espera después de 30 segundos de forma predeterminada.
Las consultas están limitadas a 100,000 caracteres y deben contener una RETURN explícita por rama de consulta.
Los errores crudos de la base de datos, el contenido de las consultas y las credenciales de conexión no se devuelven a los clientes MCP ni se escriben en registros normales.

Cambie el tiempo de espera cuando sea necesario:

age_mcp_server --statement-timeout-ms 60000

El tiempo de espera debe estar entre 1 milisegundo y 1 hora.

Ajuste el grupo de conexiones asíncronas o cargue la biblioteca AGE para cada conexión agrupada recién abierta:

age_mcp_server --pool-min-size 2 --pool-max-size 8 --load-age

El grupo debe satisfacer 1 <= min <= max <= 64. RETURN * sigue sin ser compatible; enumere los valores de retorno explícitamente para que los tipos de resultados SQL de Apache AGE puedan declararse.

Ejemplo de entrada de herramienta con parámetros y paginación:

{
  "graph_name": "people",
  "query": "MATCH (n:Person) WHERE n.age >= $minimum RETURN n.name AS name ORDER BY name",
  "parameters": {"minimum": 18},
  "page_size": 25
}

Pase el nextCursor devuelto como cursor para obtener la siguiente página.

OpenTelemetry

Instale las dependencias opcionales del exportador y habilite la exportación OTLP:

python3 -m pip install "age_mcp_server[telemetry]"
age_mcp_server --enable-telemetry --otel-service-name age-production

El exportador sigue las variables de entorno estándar de OTEL_EXPORTER_OTLP_*. Los traces y métricas registran latencia de operaciones, conteos y fallos. Los detalles de conexión, el texto Cypher, los valores de parámetros y los errores crudos de la base de datos están excluidos.

Desarrollo

Instale todas las dependencias de desarrollo y ejecute la compuerta de lanzamiento:

make sync
make check

make check ejecuta Ruff, la compuerta de cobertura del 80%, Bandit, la auditoría de dependencias bloqueadas y las compilaciones de paquetes. El conjunto de pruebas incluye una prueba de integración en vivo de Apache AGE:

AGE_TEST_CONNECTION_STRING="host=127.0.0.1 dbname=postgres user=postgres password=postgres" \
  make integration

CI ejecuta esta prueba contra el contenedor oficial de Apache AGE PostgreSQL. Consulte la revisión 0.3.0 para la revisión de seguridad y características completada.

Licencia

MIT