PuppyGraph MCP服务器
模型上下文协议（MCP）服务器 PuppyGraph，允许Claude通过Claude Desktop使用Gremlin和Cypher查询图形。
特性
- 使用Neo4j Bolt协议（用于Cypher）和WebSocket（用于Gremlin）连接到PuppyGraph实例
- 使用Gremlin和Cypher查询语言查询图形数据
- 从多个端点检索图结构和模式信息
- 可与Claude Desktop和其他MCP兼容接口配合使用
- 具有多种连接方法的强大回退机制
- 连接失败时，样本数据会出现良好的降级
先决条件
- Node.js 18+
- 正在运行的PuppyGraph实例（或用于测试的回退模式）
安装
- 克隆此存储库
- 安装依赖项：
npm install- 构建项目：
npm run build用法
启动服务器：
npm start使用环境变量：
# Connect to a specific PuppyGraph instance
PUPPYGRAPH_URL=bolt://your-puppygraph-server:7687 PUPPYGRAPH_USERNAME=neo4j PUPPYGRAPH_PASSWORD=your-password npm start
# Connect to both Neo4j and Gremlin endpoints
PUPPYGRAPH_URL=bolt://your-neo4j-server:7687 PUPPYGRAPH_GREMLIN_URL=ws://your-gremlin-server:8182/gremlin npm startClaude桌面配置
注意：如果您使用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连接（密码查询）
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)
架构API连接
PUPPYGRAPH_SCHEMA_URL：PuppyGraph架构终结点的URL（默认值：http://localhost:8081/schemajson)PUPPYGRAPH_SCHEMA_USERNAME：PuppyGraph架构API身份验证的用户名（默认值：puppygraph)PUPPYGRAPH_SCHEMA_PASSWORD：PuppyGraph架构API身份验证的密码（默认值：puppygraph123)
通用设置
- 注意：回退模式已被删除。服务器将报告实际的连接错误，以提供更好的透明度。
连接故障排除
此MCP服务器包括用于处理各种连接问题的强大回退机制：
- 首次尝试通过Neo4j Bolt协议连接到PuppyGraph进行Cypher查询
- 分别尝试通过WebSocket连接Gremlin查询
- 对于模式信息，首先尝试模式端点，然后回退到Neo4j查询，然后是Gremlin查询
- 如果所有直接连接都失败，将报告明确的错误消息
一种协议中的连接失败不会阻止使用另一种协议——例如，如果Neo4j连接失败，但Gremlin成功，您仍然可以运行Gremlin查询。
连接验证
您可以使用以下方法验证连接：
- 检查服务器启动日志中的连接状态
- 使用
puppygraph_statusClaude中的工具 - 用一个简单的查询进行测试：
Use the PuppyGraph tool to execute this Cypher query:
MATCH (n) RETURN count(n)故障排除
如果您遇到连接问题：
- 确保远程服务器正在运行，并且可以从您的网络访问
- 检查防火墙规则是否允许连接到相应的端口
- 验证您的身份验证凭据是否正确
- 检查服务器日志以获取详细的错误信息
- 对于Gremlin，确保WebSocket URL以开头
ws://或wss://
您可以使用检查连接状态 puppygraph_status 工具在任何时候。
测试
PuppyGraph MCP服务器包括一个全面的测试套件，该套件遵循测试MCP服务器的最佳实践：
# Run all tests
npm test
# Run tests in watch mode during development
npm run test:watch
# Run tests with coverage report
npm run test:coverage测试结构
- 单元测试：位于
tests/unit/目录中，这些测试使用依赖关系的模拟单独测试单个组件 - 集成测试：位于
tests/integration/目录，这些测试组件如何协同工作，包括MCP服务器的端到端测试
测试最佳实践
- 模拟外部依赖关系：所有外部服务（Neo4j、Gremlin、HTTP端点）都被模拟，以避免测试不稳定
- 测试MCP协议：测试验证服务器是否遵守模型上下文协议
- 覆盖：以高测试覆盖率为目标，特别是关键路径
- 错误处理：测试明确验证错误处理行为
许可证
Apache 2.0