MCP Toolbox for Databases 接入 Dgraph 图数据库Source 配置与 dgraph-dql 工具实战指南【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolboxMCP Toolbox for Databases 通过dgraph类型的 Source 将 Dgraph 图数据库接入 MCPModel Context Protocol服务器使 LLM Agent 能够直接对图数据执行 DQL 查询与变更。本文以 Dgraph Source 文档 为主体结合 dgraph-dql 工具文档 与仓库源码完整讲解 Source 的 YAML 配置、认证方式、参数含义以及底层实现原理帮助你在自托管 Dgraph 集群或 Dgraph Cloud 上快速落地一套可供 LLM 调用的图数据库工具集。关于 Dgraph 与 MCP Toolbox 集成Dgraph 是一款开源的分布式图数据库专为实时工作负载、水平扩展和灵活的数据建模而设计。它实现为分布式系统查询会在多个节点上并行执行从而在大规模图数据上获得更快的响应速度因此在图遍历、知识图谱、推荐系统等 Gen AI 工作负载中常被用作数据底座。在本项目中Dgraph 以「Source」的形式接入 MCP Toolbox一个 Source 代表一个可被工具引用的数据连接而工具如dgraph-dql在运行时被调用经由该 Source 与 Dgraph 实例通信。按 MCP Toolbox 的注册机制Source 类型字符串dgraph在包初始化阶段通过sources.Register(SourceType, newConfig)注册到全局注册表见 dgraph.go配置解析、连接初始化与查询执行均围绕这一类型展开。支持的连接方式与前置要求Dgraph Source 支持两类部署形态的连接Dgraph Cloud托管服务使用API key进行访问认证如果你使用的是专用环境dedicated environment还需要提供该环境对应的namespace与用户凭据。本地或自托管 Dgraph 集群直接使用namespace 与用户凭据用户名 密码进行认证。需要注意的是本项目将 Dgraph 集成标记为Best Effort Maintenance尽力维护由项目团队/社区在资源允许时提供问题修复与规避方案不承诺固定的响应时间且该模块的自动化集成测试目前处于不可用或失败状态。在投入生产使用前建议充分进行自测并评估维护风险。Source 配置示例在 MCP Toolbox 的配置文件中工具与服务端共用的 YAML 结构一个 Dgraph Source 的最小完整配置如下kind: source name: my-dgraph-source type: dgraph dgraphUrl: https://xxxx.cloud.dgraph.io user: ${USER_NAME} password: ${PASSWORD} apiKey: ${API_KEY} namespace : 0关键约定kind: source声明这是一个数据源配置name是该 Source 在后续工具引用中的唯一标识强烈建议使用${ENV_NAME}形式的环境变量替换来注入user、password、apiKey等敏感信息而非把密钥硬编码进配置文件避免凭据随配置文件泄露。从 dgraph_test.go 的解析测试可以看到dgraphUrl是唯一必填字段缺失时校验器报Field validation for DgraphUrl failed on the required tag其余字段均可省略同时配置解析是严格模式出现foo: bar之类的未知字段会直接报错unknown field foo。字段参考表FieldTypeRequiredDescriptiontypestringtrue固定为dgraph声明 Source 类型。dgraphUrlstringtrueDgraph 连接 URI例如https://xxx.cloud.dgraph.io、https://localhost:8080。userstringfalse要连接的 Dgraph 用户名例如groot。passwordstringfalse该 Dgraph 用户的密码例如password。apiKeystringfalse连接 Dgraph Cloud 实例所用的 API key。namespaceuint64falseDgraph namespaceDgraph Cloud Shared Cluster 不需要提供。上述字段与源码中Config结构体一一对应dgraph.go其中Name与Type也带有validate:required标签DgraphUrl带validate:required在解析阶段即完成必填校验。认证与连接初始化原理Source 初始化时Initialize方法会调用initDgraphHttpClient建立 HTTP 客户端并执行健康检查dgraph.go其认证逻辑可以归纳为三条路径用户凭据登录当配置了user或password时客户端会向{dgraphUrl}/login发送userid、password、namespace三元组loginWithCredentials见 dgraph.go换取accessJWT与refreshJWTAPI key 认证配置了apiKey时每次请求都会在 Header 中附带Dg-Auth: apiKey适用于 Dgraph CloudToken 自动续期doReq检测到响应报错包含Token is expired时会利用refreshJWT调用loginWithToken刷新令牌并重放原请求dgraph.go对上层调用方透明。正常请求中access token 通过X-Dgraph-AccessToken请求头携带。连接建立前还会请求{dgraphUrl}/health端点检查实例状态任一实例状态非healthy都会导致初始化失败healthCheck见 dgraph.go。查询与变更的底层执行链路Source 对外暴露RunSQL(statement, params, isQuery, timeout)方法dgraph.goisQuery参数决定请求走哪条路径查询isQuerytrue向{dgraphUrl}/query?timeouttimeout发送POST请求体为{query: ..., variables: {...}}postDqlQuery见 dgraph.go参数以 Dgraph 查询变量的形式传递变更isQueryfalse向{dgraphUrl}/mutate?commitNowtrue发送POSTContent-Type 为application/rdf参数被直接嵌入 RDF 变更语句后立即提交mutate与embedParamsIntoMutation见 dgraph.go。响应解析后工具只返回data字段对应的 JSON 内容便于 LLM 直接消费。值得一提的是dgraph-dql工具层使用参数化语句设计查询以变量方式传递参数防止将用户输入拼接进语句造成注入风险但需要注意参数只能替代任意表达式/值不能用于替代标识符、列名、表名等语句结构部分。配套工具 dgraph-dql 的配置实战Dgraph Source 需要与dgraph-dql类型工具配合才能真正被 LLM 调用。工具配置同样位于 MCP Toolbox 配置文件中通过source字段引用上面定义的 Source 名称kind: tool声明这是一个工具。工具的完整字段对应 dgraph.go 中Config结构如下fieldtyperequireddescriptiontypestringtrue固定为dgraph-dql。sourcestringtrue该 DQL 语句要执行的 Source 名称。descriptionstringtrue传给 LLM 的工具描述。statementstringtrue要执行的 DQL 语句。isQuerybooleanfalse为true时按查询执行否则按变更执行。timeoutstringfalse查询超时时间。parameterslistfalse与 DQL 语句配合使用的参数列表。查询型工具示例kind: tool name: search_user type: dgraph-dql source: my-dgraph-source statement: | query all($role: string){ users(func: has(name)) filter(eq(role, $role) AND ge(age, 30) AND le(age, 50)) { uid name email role age } } isQuery: true timeout: 20s description: | Use this tool to retrieve the details of users who are admins and are between 30 and 50 years old. The query returns the users name, email, role, and age. parameters: - name: $role type: string description: admin该工具执行一个带$role参数与年龄过滤的 DQL 查询timeout: 20s会作为?timeout查询参数传给 Dgraph 的/query端点。description会随工具清单暴露给 LLM因此应写明工具的用途、返回字段与典型调用场景帮助模型正确选择工具。变更型工具示例kind: tool name: dgraph-manage-user-instance type: dgraph-dql source: my-dgraph-source isQuery: false statement: | { set { _:user1 name $user1 . _:user1 email $email1 . _:user1 role admin . _:user1 age 35 . _:user2 name $user2 . _:user2 email $email2 . _:user2 role admin . _:user2 age 45 . } } description: | Use this tool to insert or update user data into the Dgraph database. The mutation adds or updates user details like name, email, role, and age. parameters: - name: user1 type: string description: Alice - name: email1 type: string description: aliceemail.com - name: user2 type: string description: Bob - name: email2 type: string description: bobemail.com该工具以 RDF mutation 的形式批量写入/更新用户数据。注意变更型语句中的$user1、$email1等参数会在源码层被替换为带引号的字符串值后提交embedParamsIntoMutation因此 Dgraph Cloud 场景下请谨慎评估对工具开放变更能力的安全性。工具与 Source 的类型校验在 dgraph.go 中工具通过ValidateSource检查引用的 Source 是否实现了compatibleSource接口必须同时提供DgraphClient()与RunSQL(...)方法类型不匹配会在配置阶段直接报错这从机制上保证了dgraph-dql只能绑定到 Dgraph 类 Source 上。如何验证与排障配置解析验证internal/sources/dgraph/dgraph_test.go与internal/tools/dgraph/dgraph_test.go中的TestParseFromYamlDgraph覆盖了查询、变更、最小字段配置的 YAML 解析以及未知字段、缺失必填字段的报错行为可作为配置正确性的参考基线端到端验证dgraph_integration_test.go 展示了完整流程——设置DGRAPH_URL环境变量、以 API key 建立 Source、定义dgraph-dql工具isQuery: true, timeout: 20s、启动服务器并断言/api/tool/name/端点返回的工具清单。可参照该测试的结构在本地搭建 Dgraph 后复现常见排障点连接失败先确认dgraphUrl可达且/health返回healthyDgraph Cloud 共享集群不需要namespace自托管环境务必确认用户名、密码与 namespace 对应关系正确避免 token 换取失败。小结通过dgraphSource 与dgraph-dql工具的组合MCP Toolbox for Databases 将 Dgraph 的查询与写入能力封装为可供 LLM 直接调用的 MCP 工具Source 层负责 API key / 用户名密码 / JWT 的认证链路与健康检查工具层负责参数化 DQL 语句的透传与超时控制。本文涉及的完整配置示例、字段参考与源码位置source.md、dgraph-dql.md、dgraph.go、dgraph.go可直接用于搭建你自己的 Dgraph 图数据库 MCP 工具集。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考