Apache AGE MCP Server

Um servidor para Apache AGE, uma extensão de banco de dados gráfico para PostgreSQL.

Documentação

Servidor MCP AGE

Um servidor MCP para consultar grafos Apache AGE no PostgreSQL.

A versão 0.3.0 torna a operação somente leitura o padrão seguro, adiciona pool de conexões assíncronas, parâmetros Cypher seguros e paginação com cursor limitado, e retorna conteúdo estruturado MCP de todas as ferramentas.

Requisitos

Python 3.13 ou posterior
PostgreSQL com a extensão Apache AGE instalada e carregada
Um papel de banco de dados restrito aos grafos e operações que o cliente MCP precisa

Habilite o AGE no banco de dados de destino:

CREATE EXTENSION IF NOT EXISTS age CASCADE;

Instalação

Com uv:

uv init your_project
cd your_project
uv add age_mcp_server

Com um ambiente virtual Python:

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

Com Homebrew:

brew install rioriost/tap/age_mcp_server

Configurar um cliente MCP

Evite colocar uma senha de banco de dados em argumentos de linha de comando. Forneça uma string de conexão por meio de PG_CONNECTION_STRING e use um dos mecanismos de credenciais do libpq, como PGPASSWORD ou um arquivo de senha protegido do 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 a configuração do cliente MCP como um segredo se ela contiver PGPASSWORD. Um arquivo de senha do PostgreSQL ou o armazenamento de segredos do cliente é preferível.

A string de conexão ainda pode ser fornecida explicitamente quando necessário:

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

Para autenticação Microsoft Entra no Banco de Dados Azure para PostgreSQL, primeiro faça login com a CLI do Azure e depois opte pela aquisição de token:

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

Ferramentas

O modo somente leitura é o padrão:

Ferramenta	Finalidade
`read-age-cypher`	Executar uma consulta Cypher somente leitura validada, parametrizada e paginada
`list-age-graphs`	Listar grafos Apache AGE
`get-age-schema`	Inspecionar contagens, direções e tipos de propriedades amostrados

As ferramentas de escrita só são anunciadas e aceitas quando o servidor inicia com --allow-write:

Ferramenta	Finalidade
`write-age-cypher`	Executar Cypher contendo uma cláusula de mutação
`create-age-graph`	Criar um grafo
`drop-age-graph`	Remover permanentemente um grafo

age_mcp_server --allow-write

Use um papel de banco de dados separado, com privilégios mínimos, para o modo de escrita. Habilitar a flag não concede privilégios PostgreSQL que o papel configurado já não possua.

Limites de segurança

Cypher, nomes de grafos, aliases de retorno e argumentos de gerenciamento de grafos são citados ou parametrizados com segurança antes de chegar ao PostgreSQL.
As ferramentas de leitura são executadas dentro de transações somente leitura do PostgreSQL.
CALL é considerado com efeitos colaterais e requer modo de escrita.
As páginas de leitura contêm no máximo 50 linhas. Cursores opacos autenticados por HMAC são vinculados ao grafo, à consulta e aos parâmetros, com um deslocamento máximo de 100.000.
Cypher $parameters são aceitos somente quando os nomes dos placeholders correspondem exatamente a um objeto de parâmetros JSON. O objeto é limitado a 100.000 bytes e passado ao AGE por meio de uma instrução preparada.
As consultas de escrita são executadas integralmente e retornam uma contagem de linhas afetadas em vez de linhas de resultado.
As instruções expiram após 30 segundos por padrão.
As consultas são limitadas a 100.000 caracteres e devem conter uma cláusula RETURN explícita por ramo de consulta.
Erros brutos do banco de dados, conteúdos de consulta e credenciais de conexão não são retornados aos clientes MCP nem gravados em logs normais.

Altere o tempo limite quando necessário:

age_mcp_server --statement-timeout-ms 60000

O tempo limite deve estar entre 1 milissegundo e 1 hora.

Ajuste o pool de conexões assíncronas ou carregue a biblioteca AGE para cada conexão recém-aberta no pool:

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

O pool deve atender a 1 <= min <= max <= 64. RETURN * permanece sem suporte; liste os valores de retorno explicitamente para que os tipos de resultado SQL do Apache AGE possam ser declarados.

Exemplo de entrada de ferramenta com parâmetros e paginação:

{
  "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
}

Passe o nextCursor retornado como cursor para buscar a próxima página.

OpenTelemetry

Instale as dependências opcionais do exportador e habilite a exportação OTLP:

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

O exportador segue as variáveis de ambiente padrão de OTEL_EXPORTER_OTLP_*. Rastreamentos e métricas registram latência de operação, contagens e falhas. Detalhes de conexão, texto Cypher, valores de parâmetros e erros brutos do banco de dados são excluídos.

Desenvolvimento

Instale todas as dependências de desenvolvimento e execute o portão de liberação:

make sync
make check

make check executa Ruff, o portão de cobertura de 80%, Bandit, a auditoria de dependências bloqueadas e builds de pacotes. A suíte de testes inclui um teste de integração ao vivo com Apache AGE:

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

O CI executa este teste contra o contêiner oficial Apache AGE PostgreSQL. Consulte a revisão 0.3.0 para a revisão concluída de segurança e recursos.

Licença

MIT