PuppyGraph MCP 服务器

用于 PuppyGraph 的模型上下文协议 (MCP) 服务器，允许 Claude 通过 Claude Desktop 使用 Gremlin 和 Cypher 查询图。

功能

• 使用 Neo4j Bolt 协议（用于 Cypher）和 WebSocket（用于 Gremlin）连接到 PuppyGraph 实例
• 使用 Gremlin 和 Cypher 查询语言查询图数据
• 从多个端点检索图结构和模式信息
• 与 Claude Desktop 和其他 MCP 兼容的接口配合使用
• 具有多种连接方式的强大回退机制
• 连接失败时，使用示例数据进行优雅降级

前提条件

• Node.js 18+
• 正在运行的 PuppyGraph 实例（或用于测试的回退模式）

安装

1. 克隆此存储库
2. 安装依赖项：

npm install

3. 构建项目：

npm run build

用法

启动服务器：

npm start

使用环境变量：

# 连接到特定的 PuppyGraph 实例
PUPPYGRAPH_URL=bolt://your-puppygraph-server:7687 PUPPYGRAPH_USERNAME=neo4j PUPPYGRAPH_PASSWORD=your-password npm start

# 连接到 Neo4j 和 Gremlin 端点
PUPPYGRAPH_URL=bolt://your-neo4j-server:7687 PUPPYGRAPH_GREMLIN_URL=ws://your-gremlin-server:8182/gremlin npm start

Claude Desktop 配置

注意：如果您使用 Claude Desktop 访问工具，请确保服务器没有在单独的终端中运行。 Claude Desktop 将根据以下 MCP 配置中的命令自行启动服务器。

您可以在 Claude Desktop 配置中设置 MCP 服务器，并可以选择直接在配置中包含环境变量：

{
  "mcpServers": {
    "puppygraph": {
      "command": "node",
      "args": [
        "/path/to/puppygraph-mcp/build/index.js"
      ],
      "env": {
        "PUPPYGRAPH_URL": "bolt://your-neo4j-server:7687",
        "PUPPYGRAPH_USERNAME": "neo4j",
        "PUPPYGRAPH_PASSWORD": "your-password",
        "PUPPYGRAPH_DATABASE": "your-database",
        "PUPPYGRAPH_GREMLIN_URL": "ws://your-gremlin-server:8182/gremlin",
        "PUPPYGRAPH_GREMLIN_USERNAME": "your-username",
        "PUPPYGRAPH_GREMLIN_PASSWORD": "your-password"
      }
    }
  }
}

将路径和连接详细信息替换为您特定的值。 env 部分允许您直接在配置文件中指定所有环境变量。

可用工具

• puppygraph_query: 对 PuppyGraph 执行 Gremlin 或 Cypher 查询
• puppygraph_schema: 获取有关图的模式和结构信息
• puppygraph_status: 检查 PuppyGraph 连接状态

每个工具也都有一个 mcp__ 前缀（例如，mcp__puppygraph_query），以便与某些 LLM 平台兼容。

环境变量

图数据库连接

Neo4j 连接（Cypher 查询）

• PUPPYGRAPH_URL: PuppyGraph Neo4j 端点的 URL（默认值：bolt://localhost:7687）
• PUPPYGRAPH_USERNAME: PuppyGraph Neo4j 身份验证的用户名（默认值：neo4j）
• PUPPYGRAPH_PASSWORD: PuppyGraph Neo4j 身份验证的密码（默认值：password）
• PUPPYGRAPH_DATABASE: 要连接的数据库的名称（默认值：""）

Gremlin 连接（Gremlin 查询）

• PUPPYGRAPH_GREMLIN_URL: PuppyGraph Gremlin 端点的 URL（默认值：ws://localhost:8182/gremlin）
• PUPPYGRAPH_GREMLIN_USERNAME: PuppyGraph Gremlin 身份验证的用户名（默认值：puppygraph）
• PUPPYGRAPH_GREMLIN_PASSWORD: PuppyGraph Gremlin 身份验证的密码（默认值：puppygraph123）
• PUPPYGRAPH_GREMLIN_TRAVERSAL_SOURCE: 遍历源名称（默认值：g）

Schema API 连接

• PUPPYGRAPH_SCHEMA_URL: PuppyGraph schema 端点的 URL（默认值：http://localhost:8081/schemajson）
• PUPPYGRAPH_SCHEMA_USERNAME: PuppyGraph schema API 身份验证的用户名（默认值：puppygraph）
• PUPPYGRAPH_SCHEMA_PASSWORD: PuppyGraph schema API 身份验证的密码（默认值：puppygraph123）

常规设置

• 注意：已删除回退模式。服务器将报告实际连接错误，以提供更好的透明度。

连接故障排除

此 MCP 服务器包含用于处理各种连接问题的强大回退机制：

1. 首先尝试通过 Neo4j Bolt 协议连接到 PuppyGraph 以进行 Cypher 查询
2. 单独尝试通过 WebSocket 连接以进行 Gremlin 查询
3. 对于模式信息，首先尝试模式端点，然后回退到 Neo4j 查询，然后回退到 Gremlin 查询
4. 如果所有直接连接都失败，将报告明确的错误消息

一种协议中的连接失败不会阻止使用另一种协议 - 例如，如果 Neo4j 连接失败但 Gremlin 成功，您仍然可以运行 Gremlin 查询。

连接验证

您可以使用以下方法验证连接：

1. 检查服务器启动日志中的连接状态
2. 在 Claude 中使用 puppygraph_status 工具
3. 使用简单的查询进行测试：

使用 PuppyGraph 工具执行此 Cypher 查询：
MATCH (n) RETURN count(n)

故障排除

如果您遇到连接问题：

• 确保远程服务器正在运行并且可以从您的网络访问
• 检查防火墙规则是否允许连接到相应的端口
• 验证您的身份验证凭据是否正确
• 检查服务器日志以获取详细的错误信息
• 对于 Gremlin，请确保 WebSocket URL 以 ws:// 或 wss:// 开头

您可以随时使用 puppygraph_status 工具检查连接状态。

测试

PuppyGraph MCP 服务器包含一个全面的测试套件，该套件遵循测试 MCP 服务器的最佳实践：

# 运行所有测试
npm test

# 在开发期间以监视模式运行测试
npm run test:watch

# 运行带有覆盖率报告的测试
npm run test:coverage

测试结构

• 单元测试: 位于 tests/unit/ 目录中，这些测试使用模拟来隔离测试各个组件
• 集成测试: 位于 tests/integration/ 目录中，这些测试组件如何协同工作，包括 MCP 服务器的端到端测试

测试最佳实践

1. 模拟外部依赖项: 所有外部服务（Neo4j、Gremlin、HTTP 端点）都被模拟以避免测试不稳定
2. 测试 MCP 协议: 测试验证服务器是否符合模型上下文协议
3. 覆盖率: 争取高测试覆盖率，尤其是对于关键路径
4. 错误处理: 测试显式验证错误处理行为

许可证

Apache 2.0