AGE-MCP-Server

AGE MCP Server

用于查询 PostgreSQL 中 Apache AGE 图的 MCP 服务。

0.3.0 版将只读操作设为安全默认值，新增异步连接池、安全的 Cypher 参数和有界游标分页，并让每个工具都返回 MCP 结构化内容。

要求

• Python 3.13 或更高版本
• 已安装并加载 Apache AGE 扩展的 PostgreSQL
• 仅对 MCP 客户端所需的图和操作开放权限的数据库角色

在目标数据库中启用 AGE：

CREATE EXTENSION IF NOT EXISTS age CASCADE;

安装

使用 uv：

uv init your_project
cd your_project
uv add age_mcp_server

使用 Python 虚拟环境：

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

使用 Homebrew：

brew install rioriost/tap/age_mcp_server

配置 MCP 客户端

避免将数据库密码放入命令行参数。通过 PG_CONNECTION_STRING 提供连接字符串，并使用 libpq 的凭据机制之一，例如 PGPASSWORD 或受保护的 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"
      }
    }
  }
}

如果 MCP 客户端配置中包含 PGPASSWORD，请将其视为机密。更推荐使用 PostgreSQL 密码文件或客户端的机密存储。

必要时仍可显式提供连接字符串：

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

要对 Azure Database for PostgreSQL 使用 Microsoft Entra 身份验证，请先通过 Azure CLI 登录，然后选择启用令牌获取：

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

工具

默认采用只读模式：

工具	用途
read-age-cypher	执行经过验证、参数化且带分页的只读 Cypher 查询
list-age-graphs	列出 Apache AGE 图
get-age-schema	检查计数、方向和抽样属性类型

只有在服务启动时使用 --allow-write，才会公布并接受写入工具：

工具	用途
write-age-cypher	执行包含变更子句的 Cypher
create-age-graph	创建图
drop-age-graph	永久删除图

age_mcp_server --allow-write

写入模式应使用单独的、遵循最小权限原则的数据库角色。启用该标志不会授予配置角色原本不具备的 PostgreSQL 权限。

安全限制

• Cypher、图名称、返回别名和图管理参数在传递给 PostgreSQL 前都会经过安全引用或参数化处理。
• 读取工具在 PostgreSQL 只读事务中运行。
• CALL 被视为有副作用，必须启用写入模式。
• 每页最多包含 50 行。经过不透明 HMAC 身份验证的游标会绑定图、查询和参数，偏移量上限为 100,000。
• 仅当占位符名称与 JSON 参数对象完全匹配时，才接受 Cypher $parameters。该对象大小上限为 100,000 字节，并通过预处理语句传递给 AGE。
• 写入查询会完整执行，并返回受影响的行数，而不是结果行。
• 语句默认在 30 秒后超时。
• 查询长度限制为 100,000 个字符，并且每个查询分支都必须包含一个显式的 RETURN 子句。
• 原始数据库错误、查询内容和连接凭据不会返回给 MCP 客户端，也不会写入常规日志。

必要时可更改超时时间：

age_mcp_server --statement-timeout-ms 60000

超时时间必须在 1 毫秒到 1 小时之间。

调整异步连接池，或为每个新打开的池化连接加载 AGE 库：

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

连接池必须满足 1 <= min <= max <= 64。RETURN * 仍不受支持；请显式列出返回值，以便声明 Apache AGE 的 SQL 结果类型。

包含参数和分页的工具输入示例：

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

将返回的 nextCursor 作为 cursor 传入，以获取下一页。

OpenTelemetry

安装可选的导出器依赖项并启用 OTLP 导出：

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

导出器遵循标准的 OTEL_EXPORTER_OTLP_* 环境变量。 跟踪和指标会记录操作延迟、计数和失败情况。不会包含连接 详情、Cypher 文本、参数值和原始数据库错误。

开发

安装所有开发依赖项并运行发布检查：

make sync
make check

make check 会运行 Ruff、80% 覆盖率门槛、Bandit、锁定依赖项审计 和软件包构建。测试套件包含一项 Apache AGE 实时集成测试：

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

CI 会针对官方 Apache AGE PostgreSQL 容器运行此测试。请参阅 0.3.0 版本评审，了解已完成的安全性和 功能评审。

许可证

MIT