PuppyGraph MCP Server

PuppyGraph MCP 服务

适用于 PuppyGraph 的 Model Context Protocol（MCP）服务。它允许 Claude Code、Claude Desktop 和 Cursor 等 AI Agent 将 PuppyGraph 连接到你的数据、构建图架构，并使用 Cypher 或 Gremlin 查询图。

npx -y @puppygraph/mcp-server

工具

工具	功能
puppygraph_query	执行 Cypher 或 Gremlin 查询，并返回行、PuppyGraph 的查询警告；如果执行失败，还会返回 PuppyGraph 的错误消息
puppygraph_schema	返回图架构（节点和边标签、属性）；如果架构很大，则只返回其结构
puppygraph_status	报告连接状态以及是否启用了只读模式

为了兼容某些 LLM 平台，这三个工具也提供带 mcp__ 前缀的版本（例如 mcp__puppygraph_query）。

设置工具可帮助你从空的 PuppyGraph 开始，构建一个可查询的图。它们与 PuppyGraph 网页界面的 AI 助手功能相同：

工具	功能
puppygraph_guide	介绍如何使用这些工具：查询或构建图的步骤，以及正确使用键、类型和边的规则
puppygraph_catalog_spec	列出支持的目录类型，以及其中一种类型的连接字段及其确切名称
puppygraph_list_catalogs	列出已注册的数据源（目录），并对凭据进行遮蔽
puppygraph_create_catalog	将数据源（数据库、数据仓库、数据湖或 DuckDB 文件）注册为目录
puppygraph_test_catalog	检查 PuppyGraph 是否能通过目录读取数据
puppygraph_list_tables	列出目录的数据库，或其中一个数据库的表
puppygraph_describe_table	列出表的列及其 PuppyGraph 类型
puppygraph_sample_table	返回表中的几行数据
puppygraph_profile_column	分析一列：统计空值和不同值的数量，并判断它是否可作为 ID 或引用另一个表
puppygraph_table_row_count	统计表中的行数
puppygraph_check_join	根据数据检查一列中的多少个值存在于另一个表的列中
puppygraph_schema_template	返回带注释的 1.x 图架构示例
puppygraph_validate_schema	对架构进行试运行，不做任何更改：检查其结构、表和列是否存在、每种类型是否与源列匹配，以及边键是否与其指向的节点 ID 匹配
puppygraph_upload_schema	安装完整架构；替换已安装的架构需要设置 replace: true
puppygraph_search_schema	按关键字查找已安装架构中的节点和边类型
puppygraph_get_schema_element	显示一个节点或边的 ID、属性、源表、键，以及在 Cypher 中使用的关系标签
puppygraph_add_node、puppygraph_update_node、puppygraph_remove_node	更改已安装架构中的一种节点类型
puppygraph_add_edge、puppygraph_update_edge、puppygraph_remove_edge	更改已安装架构中的一种边类型
puppygraph_add_node_attribute、puppygraph_add_edge_attribute	为节点或边类型添加一个属性
puppygraph_check_edges	根据数据检查已安装的图：对于每种边类型，统计有多少行能关联到现有的源节点和目标节点，并检查节点 ID 是否唯一

puppygraph_create_catalog、puppygraph_upload_schema 和 add/update/remove 工具会更改 PuppyGraph，因此在只读模式下不可用。设置工具需要 PuppyGraph 1.x，并使用其 8081 端口上的 HTTP API。

一次添加一个元素来构建架构

添加／更新／删除工具会更改单个已安装架构节点或边，其余部分保持不变，类似 PuppyGraph Web UI 中的 AI 助手。PuppyGraph 只会将这些更改提供给自己的 UI，因此 MCP 服务会读取已安装的架构、更改元素、检查元素（列、类型、键），然后上传整个架构。如果期间已安装的架构发生变化，工具会拒绝操作；如果元素有问题，则不会做任何更改。

检查图

图可能有效却仍有错误：连接到错误列、边指向错误方向，或节点 ID 不唯一，这些情况都能在上传时不报错。puppygraph_check_edges 会统计每种边类型的边行数，以及其中能关联到现有源节点和目标节点的行数，并将每种节点类型的行数与其不同 ID 的数量进行比较。它适用于所有 PuppyGraph 1.x 版本，且不需要探测数据的权限。上传后，架构工具还会等待几秒，让新标签能够响应，因为 PuppyGraph 在上传后最初的几次查询可能会返回 0 行。

如果无法连接到 PuppyGraph，工具会返回错误，绝不会返回编造的数据。

数据探测

puppygraph_sample_table、puppygraph_profile_column、puppygraph_table_row_count 和 puppygraph_check_join 会读取源表，因此 Agent 会根据数据而非仅根据列名来选择 ID 和边。这些工具与 PuppyGraph Web UI 的 AI 助手使用的探测工具相同，需要高于 1.14 的 PuppyGraph 版本。在较旧版本上，它们会返回 error_type: "NOT_SUPPORTED"；此时 Agent 会退回到根据列名和类型进行判断，并应说明其键和连接未经验证。

• 样本行、样本值和最小值／最大值会进入与 Agent 模型的对话。
• PuppyGraph 用户需要 DATA:read 权限。
• 对于被启用行级安全的图使用的目录，只有管理员才能进行探测，因为探测会在不应用行筛选条件的情况下读取表。
• PuppyGraph 服务可以设置为仅返回计数：此时 puppygraph_sample_table 会被拒绝，其他探测工具会返回计数而不返回值。

这些工具只读取数据，因此在只读模式下仍可使用。

同一份指南也可通过 puppygraph_guide 工具、只读资源 puppygraph://guide 获取；其精简版则作为服务的 MCP instructions 提供；puppygraph://schema 是当前图架构。有些客户端不会查看资源或说明，因此工具描述也会指向 puppygraph_guide。

连接数据

• 数据库（PostgreSQL、MySQL、SQL Server、Oracle 等）：使用 jdbc_uri、username 和 password_env。PuppyGraph 不附带 MySQL 驱动：请传入 driver_url（工具会建议使用 Maven Central 上的官方连接器）。MySQL 8 通常还需要在 URI 中添加 ?allowPublicKeyRetrieval=true&useSSL=false。
• 数据湖和数据仓库（Iceberg、Delta Lake、Hive、Hudi、BigQuery、Snowflake 密钥对、Databricks 等）：字段名称与 PuppyGraph 目录表单中的名称相同。puppygraph_catalog_spec 会按类型列出这些字段，puppygraph_create_catalog 会在连接前根据这些字段检查 options。表单定义随 PuppyGraph 源代码打包；可使用 node scripts/update-catalog-spec.mjs <puppygraph>/frontend/control/chat/catalogform/definition.json 重新生成。
• CSV 和 Parquet 文件：在 DuckDB 文件中基于这些文件创建表或视图，将该文件挂载到 PuppyGraph 容器中，并使用 jdbc:duckdb:/path/in/container.duckdb 将其注册为 duckdb 类型。对于 S3 上的文件，请使用 Iceberg、Delta Lake 或 Hive 目录：DuckDB 的 S3 设置不会保存在文件中，因此通过该文件执行查询会失败。
• 常见连接错误会附带 hint（如果有，还会附带 suggested_jdbc_uri 或 suggested_driver_url）。PuppyGraph 启动期间，工具会返回 error_type: "STARTING"。

快速开始

1. 启动 PuppyGraph（Docker）：

   docker run -d --name puppy --pull=always \
     -p 8081:8081 -p 8182:8182 -p 7687:7687 \
     -e PUPPYGRAPH_PASSWORD=puppygraph123 \
     --add-host=host.docker.internal:host-gateway \
     puppygraph/puppygraph:latest
   

2. 将 MCP 服务添加到你的客户端（见下文）。PuppyGraph 在 localhost 上运行且使用默认凭据时，无需进行任何配置。

3. 让你的 Agent 根据数据构建图，例如：“使用 PuppyGraph 连接到我的 Postgres，地址为 jdbc:postgresql://db:5432/shop，并找出共用同一张支付卡的客户”，或者，如果已加载架构，则问：“我的 PuppyGraph 图中有什么？”

   PuppyGraph 会自行连接到你的数据库，因此 JDBC URI 必须使用 PuppyGraph 容器可以访问的地址（例如，数据库运行在你的机器上时使用 host.docker.internal，而不是 localhost；上面的 --add-host 标志可让该名称在 Linux 上生效）。如果 Agent 仍使用 localhost，puppygraph_create_catalog 会失败，并返回 error_type: HOST_UNREACHABLE_FROM_PUPPYGRAPH、提示信息以及可供重试的 suggested_jdbc_uri。你也可以在 Web 界面 http://localhost:8081 中连接数据并构建架构（使用 puppygraph / puppygraph123 登录）；请参阅 PuppyGraph 文档。

需要 Node.js 20 或更高版本。

客户端设置

Claude Code

claude mcp add puppygraph -- npx -y @puppygraph/mcp-server

使用远程 PuppyGraph 或其他凭据时，通过 -e 传递环境变量：

claude mcp add puppygraph \
  -e PUPPYGRAPH_URL=bolt://puppygraph.example.com:7687 \
  -e PUPPYGRAPH_GREMLIN_URL=ws://puppygraph.example.com:8182/gremlin \
  -e PUPPYGRAPH_SCHEMA_URL=http://puppygraph.example.com:8081/schemajson \
  -e PUPPYGRAPH_PASSWORD=your-password \
  -e PUPPYGRAPH_GREMLIN_PASSWORD=your-password \
  -e PUPPYGRAPH_SCHEMA_PASSWORD=your-password \
  -- npx -y @puppygraph/mcp-server

添加 --scope user，即可在所有项目中使用。

Claude Desktop

编辑 claude_desktop_config.json（Settings → Developer → Edit Config），然后重启 Claude Desktop：

{
  "mcpServers": {
    "puppygraph": {
      "command": "npx",
      "args": ["-y", "@puppygraph/mcp-server"],
      "env": {
        "PUPPYGRAPH_URL": "bolt://localhost:7687"
      }
    }
  }
}

env 块为可选项；可在其中添加任意环境变量。

Cursor

将服务添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

{
  "mcpServers": {
    "puppygraph": {
      "command": "npx",
      "args": ["-y", "@puppygraph/mcp-server"]
    }
  }
}

VS Code（GitHub Copilot）

将服务添加到 .vscode/mcp.json：

{
  "servers": {
    "puppygraph": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@puppygraph/mcp-server"]
    }
  }
}

其他 MCP 客户端

任何可启动 stdio MCP 服务的客户端均可使用：命令为 npx，参数为 -y @puppygraph/mcp-server，设置通过环境变量传递。Windsurf、Cline 及类似客户端使用与 Claude Desktop 相同的 mcpServers JSON 结构。

配置

所有设置均为环境变量。默认值与本地 PuppyGraph 容器相匹配。

变量	默认值	说明
PUPPYGRAPH_URL	bolt://localhost:7687	用于 Cypher 的 Bolt 端点
PUPPYGRAPH_USERNAME	puppygraph	Bolt 用户名
PUPPYGRAPH_PASSWORD	puppygraph123	Bolt 密码
PUPPYGRAPH_DATABASE	（空）	Bolt 数据库名称
PUPPYGRAPH_GREMLIN_URL	ws://localhost:8182/gremlin	Gremlin WebSocket 端点
PUPPYGRAPH_GREMLIN_USERNAME	puppygraph	Gremlin 用户名
PUPPYGRAPH_GREMLIN_PASSWORD	puppygraph123	Gremlin 密码
PUPPYGRAPH_GREMLIN_TRAVERSAL_SOURCE	g	Gremlin 遍历源
PUPPYGRAPH_SCHEMA_URL	http://localhost:8081/schemajson	架构端点
PUPPYGRAPH_SCHEMA_USERNAME	puppygraph	架构端点用户名
PUPPYGRAPH_SCHEMA_PASSWORD	puppygraph123	架构端点密码，也供设置工具使用
PUPPYGRAPH_HTTP_URL	PUPPYGRAPH_SCHEMA_URL 的源站	设置工具使用的 PuppyGraph HTTP API
PUPPYGRAPH_MCP_SECRET_ENV_ALLOWLIST	（空）	password_env / secret_env 可读取的额外变量名称（参见数据源凭据）
PUPPYGRAPH_READ_ONLY	false	拒绝写入查询（见下文）

如果更改了 PuppyGraph 密码，请为所有三个端点设置密码（PUPPYGRAPH_PASSWORD、PUPPYGRAPH_GREMLIN_PASSWORD、PUPPYGRAPH_SCHEMA_PASSWORD）。

只读模式

默认允许写入。要阻止 Agent 更改数据（例如在生产环境部署时），请将 PUPPYGRAPH_READ_ONLY=true 设为开启只读模式，或使用 --read-only 标志：

claude mcp add puppygraph -- npx -y @puppygraph/mcp-server --read-only

在只读模式下，puppygraph_query 会在 Cypher 查询到达 PuppyGraph 之前，拒绝使用 CREATE、MERGE、DELETE、SET、REMOVE、DROP、LOAD CSV 或 FOREACH 的查询；也会拒绝使用 addV、addE、mergeV、mergeE、property、drop、io、addVertex、addEdge 或 remove 的 Gremlin 查询。Agent 会收到错误，其中 error_type: "READ_ONLY" 会指出相关操作。字符串和注释中的关键字会被忽略。工具描述和 puppygraph_status（read_only: true）会告知 Agent 已开启该模式。

在只读模式下，puppygraph_create_catalog、puppygraph_upload_schema 以及添加／更新／移除架构的工具都不会提供给 Agent（即使调用也会被拒绝）。其他设置工具只执行读取操作，因此仍可使用。

只读模式是针对 Agent 的防护措施，并非访问控制。若要强制执行只读访问，请使用 PuppyGraph 的访问控制，并以没有写入权限的用户身份连接。

数据源凭据

设置工具绝不会返回或记录数据源密码：响应会将凭据字段遮蔽为 ******，错误消息也会清除其中发送的密码。若要让密码完全不出现在对话中，请将其放入 MCP 服务的环境中，并让 Agent 传递变量名（其他密钥可用 secret_env，密码则用 password_env）。变量名由 Agent 选择，因此若要阻止 Agent 将服务端的其他密钥传给数据库，只能使用以下变量：名称以 PUPPYGRAPH_SECRET_ 开头的变量，以及你在 PUPPYGRAPH_MCP_SECRET_ENV_ALLOWLIST 中列出的变量（以逗号分隔，名称必须完全匹配）。其他名称都会被拒绝。

claude mcp add puppygraph -e PUPPYGRAPH_SECRET_PG_PASSWORD=... -- npx -y @puppygraph/mcp-server

然后输入：“为 jdbc:postgresql://db:5432/shop 创建 PuppyGraph 目录，用户名为 app，密码存储在 PUPPYGRAPH_SECRET_PG_PASSWORD 中。”

替换架构

puppygraph_upload_schema 会先验证架构，然后让 PuppyGraph 检查每个映射的表和列，之后才进行任何更改，因此上传失败不会影响已安装的架构。如果已安装架构，除非 Agent 传入 replace: true，否则上传会被拒绝；拒绝消息会指出已安装的版本和标签。PuppyGraph 会在架构历史记录中保留早期版本。

故障排除

• 让 Agent 调用 puppygraph_status：它会显示服务是否已连接；如果未连接，也会指出原因是身份验证还是连接问题。
• 服务会将日志写入 stderr（绝不会写入承载 MCP 协议的 stdout）。Claude Desktop 会将日志写入其 MCP 日志文件。
• 如果 PuppyGraph 在另一台主机或客户端无法通过 localhost 访问的容器中运行，请将三个 URL 变量设为客户端可访问的地址。
• Gremlin URL 必须以 ws:// 或 wss:// 开头。
• Cypher 和 Gremlin 分别连接：如果其中一种连接失败，另一种语言仍可正常使用。

开发

git clone https://github.com/puppygraph/puppygraph-mcp-server.git
cd puppygraph-mcp-server
npm install        # also builds build/ through the prepare script
npm test           # unit and integration tests (mocked, no PuppyGraph needed)
npm run build
node build/index.js

若要在客户端中使用本地检出版本，请将 npx -y @puppygraph/mcp-server 替换为 node /path/to/puppygraph-mcp-server/build/index.js。

实时测试会使用实际的 PuppyGraph 运行已构建的服务：

PUPPYGRAPH_LIVE_TEST=true npm run test:live

设置工具有自己的实时测试。该测试会创建目录并替换已安装的架构，因此只能针对一次性 PuppyGraph 运行。将 tests/live/fixtures/setup.sql 加载到 PuppyGraph 可访问的 PostgreSQL 数据库中，然后：

PUPPYGRAPH_LIVE_SETUP_TEST=true \
PUPPYGRAPH_LIVE_JDBC_URI=jdbc:postgresql://<host>:5432/<db> \
PUPPYGRAPH_LIVE_JDBC_USER=<user> PUPPYGRAPH_LIVE_JDBC_PASSWORD=<password> \
npm run test:live

若要测试用户实际获取的程序包，请运行 npm pack 并安装生成的 tarball，或将其发布到 Verdaccio 等本地注册表，然后通过它运行 npx -y @puppygraph/mcp-server。

发布

维护者会手动发布到 npm；详情请参阅 RELEASING.md。

许可证

Apache 2.0