企业官网建设流程全解析

• 数据库
• 图数据库
• 分布式数据库
• 后端

Dgraph MCP（Master Control Protocol）服务器是 Dgraph 官方内置的一项能力，它把 Dgraph 的 Schema 管理、DQL 查询与变更能力封装为标准 MCP 工具，让 Claude Desktop、Cursor 等支持 MCP 协议的 AI 客户端可以直接用自然语言对话操作图数据库。本文基于 dgraph/cmd/mcp 模块的官方文档，结合 mcp_server.go、run.go 与 alpha 的 HTTP 接入代码，完整讲解两种接入方式、全部工具与资源清单、配置步骤与排错思路。读完本文，你将能独立把本地或远程 Dgraph 实例接入任意 MCP 客户端，并理解其读写权限控制与底层实现原理。

Dgraph MCP 是什么

Dgraph MCP 是一个基于 Dgraph 的 Master Control Protocol（MCP）实现，为 AI 智能体提供高级图数据库管理与查询能力。它不是一个独立的数据库服务，而是一层"翻译层"：把 MCP 客户端（如 Claude）发来的工具调用请求，翻译成对 Dgraph Alpha 的 DQL 操作。

从代码结构看，整个模块由三部分构成：

• run.go：定义dgraph mcp子命令，负责解析参数并启动 STDIO 模式的 MCP 服务器；
• mcp_server.go：核心实现，注册全部 MCP 工具、资源和 Prompt；
• mcp_server_sse_test.go：SSE 模式的端到端集成测试，验证工具、资源、Prompt 的可用性。

两种访问方式

官方文档明确指出，你可以通过两种方式访问 MCP 服务器：

1. 通过 dgraph alpha 的 HTTP 端点：启动 alpha 时开启 MCP 功能，Alpha 会在 HTTP 端口暴露/mcp/sse与/mcp-ro/sse两个 SSE（Server-Sent Events）端点；
2. 通过 Go 代码 / 命令行：直接运行dgraph mcp子命令，以 STDIO 模式与客户端通信。

这两种方式底层复用同一个NewMCPServer构造函数（定义于 mcp_server.go），区别仅在于传输层：alpha 走 HTTP SSE，独立子命令走标准输入输出流。

方式一：通过 Dgraph Alpha 的 HTTP 端点接入

开启 Alpha 的 MCP 功能

Alpha 默认不开启 MCP 端点，需要显式传入--mcp标志。在 alpha/run.go 中该标志定义如下：

flag.Bool("mcp", false, "run MCP server along with alpha.")

启动命令示例：

dgraph alpha --mcp

当该标志为真时，setupServer 会同时注册两个端点：

• /mcp（读写模式，readOnly=false）
• /mcp-ro（只读模式，readOnly=true）

两个端点都通过setupMcp注册到 alpha 的 HTTP 路由上：

if enableMcp { if err := setupMcp(baseMux, buildConnectionString(laddr, grpcPort()), "/mcp", false); err != nil { log.Fatal(err) } if err := setupMcp(baseMux, buildConnectionString(laddr, grpcPort()), "/mcp-ro", true); err != nil { log.Fatal(err) } }

setupMcp（alpha/run.go#L433-L456）内部做了三件事：调用mcp.NewMCPServer构造服务器、用server.NewSSEServer包装成 SSE 服务、再包一层 CORS 处理函数后挂载到路由。这意味着浏览器类 MCP 客户端（如 Claude Desktop）可以直接跨域访问该端点。

MCP 客户端配置

在支持 MCP 的客户端（Claude Desktop、Cursor 等）配置文件中添加以下 JSON 即可：

只读配置：

{ "dgraph-mcp-ro": { "serverUrl": "http://localhost:8080/mcp-ro/sse" } }

读写配置：

{ "dgraph-mcp": { "serverUrl": "http://localhost:8080/mcp/sse" } }

其中8080是 alpha 默认的 HTTP 端口（可通过--http_port调整），路径必须带/sse后缀，这是 MCP SSE 传输的端点约定。集成测试 mcp_server_sse_test.go 也验证了这一路径格式：

port, err := c.GetAlphaHttpPublicPort(0) serverURL := fmt.Sprintf("http://localhost:%s/mcp/sse", port) mcpClient, err := client.NewSSEMCPClient(serverURL)

安全提示：/mcp端点包含alter_schema与run_mutation两个破坏性工具，若你的 alpha 暴露在公网，务必通过--mcp配合 ACL 与 TLS 配置使用；只读场景优先选择/mcp-ro端点。

方式二：通过 Go 代码 / 命令行以 STDIO 模式接入

安装与运行

这种方式要求本机已安装 dgraph 二进制文件。mcp子命令在 run.go 中定义，归属于tool命令组：

Mcp.Cmd = &cobra.Command{ Use: "mcp", Short: "Run Dgraph MCP server", Long: ` A Dgraph MCP server is a long running process that provides an STDIO interface for running mcp server. `, ... Annotations: map[string]string{"group": "tool"}, }

该子命令支持两个参数：

连接字符串的端口是gRPC 端口（默认 9080），而非 HTTP 端口。alpha 内部在构建自连接字符串时也遵循这一约定（alpha/run.go#L458-L460）：

func buildConnectionString(addr string, port int) string { return fmt.Sprintf("dgraph://%s:%d", addr, port) }

MCP 客户端配置

在 MCP 客户端配置文件中添加：

{ "mcpServers": { "dgraph": { "command": "dgraph_binary", "args": ["mcp", "-c", "dgraph://localhost:9080"] } } }

• command：dgraph 二进制的实际路径（Windows 上可写dgraph.exe）；
• args中的mcp指定子命令，-c指定连接字符串；
• 如需只读模式，追加--read-only参数。

客户端会以子进程方式启动该命令，通过 STDIO 与 MCP 服务器通信。服务器在 run() 中通过server.ServeStdio(s)启动。

连接重试机制

值得一提的细节：getConn（mcp_server.go#L29-L52）在首次打开连接失败时会自动重试最多 3 次，间隔随次数递增（0s、1s、2s）：

conn, err := dgo.Open(connectionString) if err != nil { for i := range 3 { time.Sleep(time.Second * time.Duration(i)) conn, err = dgo.Open(connectionString) if err == nil { break } } ... }

连接对象以包级变量dgraphConnection缓存并用互斥锁保护，后续工具调用复用同一连接，避免重复建连开销。

Claude Desktop 本地接入步骤

官方文档给出了 macOS 上配置 Claude Desktop 的完整流程：

1. 从 Claude 官网下载并安装 Claude.app；
2. 在 macOS 上，配置文件位于~/Library/Application Support/Claude，创建claude_desktop_config.json，内容填入上文任一 MCP 配置（本地体验推荐 STDIO 模式，无需serverUrl的 SSE 配置则使用command方式）；
3. 完全关闭 Claude 应用后重新打开；
4. 点击工具（tools）图标，检查 MCP 工具列表是否已加载；
5. 现在你就可以直接用自然语言与 Claude 对话，让它操作你的 Dgraph 实例了。

注：Linux/Windows 下 Claude Desktop 的配置目录不同，请以官方客户端说明为准；其他支持 MCP 的客户端（如 Cursor、VS Code 扩展）配置格式类似，区别仅在于配置文件位置。

MCP 工具与资源全解析

NewMCPServer（mcp_server.go#L58-L445）注册了 6 个工具、2 个资源与 1 个 Prompt。集成测试 mcp_server_sse_test.go 对工具清单做了断言，与下述列表完全一致。

工具清单

只读与读写分离的实现：readOnly参数控制着工具注册。当readOnly=true时，mcp_server.go#L149 的if !readOnly分支被跳过，alter_schema与run_mutation根本不会被注册。这就是/mcp-ro端点"只读"的底层保障——不是运行时拦截，而是注册阶段就不暴露。

工具注解（ToolAnnotation）：每个工具都声明了 MCP 规范建议的四项注解，供客户端进行安全提示：

• alter_schema：ReadOnlyHint=false、DestructiveHint=true、IdempotentHint=false；
• run_mutation：ReadOnlyHint=false、DestructiveHint=true、IdempotentHint=false；
• 查询类工具（get_schema、run_query、validate_query_syntax、get_common_queries）：全部标记为只读、幂等、非破坏。

各工具的工作原理

get_schema：通过只读事务执行 DQL 内建查询schema {}并返回 JSON 结果：

txn := conn.NewReadOnlyTxn() ... resp, err := txn.Query(ctx, "schema {}") return mcp.NewToolResultText(string(resp.GetJson()))

validate_query_syntax：调用 Dgraph 官方解析器dql.Parse做语法与语义校验。它需要构造dql.Request结构体，variables参数按map[string]string解析后一并传给解析器。集成测试覆盖了多种合法与非法场景（mcp_server_sse_test.go#L223-L280）：不存在的函数名（foo is not valid）、未声明的变量（Type of variable $notname not specified）、变量误用（Variables are not used properly）都会被正确报错。

run_query：在只读事务中执行带变量的查询。variables参数是一个 JSON 字符串，支持 string、number、boolean 三类值，例如：

{"$param1": "value1", "$param2": 123, "$param3": true}

实现上先把 JSON 反序列化为map[string]any，再按类型转换为map[string]string传给QueryWithVars：浮点数用strconv.FormatFloat（保留完整精度）、布尔用FormatBool、null转成字符串"null"。若变量值是嵌套对象等复杂结构，会返回could not convert complex variable错误（测试用例见 mcp_server_sse_test.go#L339-L348）。

alter_schema：调用 dgo 客户端的conn.SetSchema(ctx, schema)执行 DDL，成功返回Schema updated successfully。

run_mutation：接收 JSON 格式的变更载荷，示例：

{"set": [{ "uid": "_:1", "n": "Foo", "m": 20, "p": 3.14 }]}

表示用空白标识符_:1创建一个节点，属性 n="Foo"、m=20、p=3.14；删除节点则用：

{ "delete": [{ "uid": "0xfa12" }]}

实现中通过txn.Mutate(ctx, &api.Mutation{SetJson: ..., CommitNow: true})执行并即时提交，成功后返回创建 UID 的数量（mcp_server.go#L235-L242）。集成测试断言插入 1 个节点会返回Mutation completed, 1 UIDs created。

资源（Resources）

MCP 服务器还注册了 2 个文本资源，客户端可以直接读取：

其中dgraph://common_queries提供的最短路径查询模板（mcp_server.go#L361-L381）很有实战价值：

{ q(func: eq(guid, "first guid") { // 先取出第一个 uid a as uid } q1(func: eq(guid, "second guid")) { // 再取出第二个 uid b as uid } path as shortest(from: uid(a), to: uid(b), numpaths: 5, maxheapsize: 10000) { connected_to @facets(weight) // 有边权重时保留 @facets(weight)，权重相同时去掉 } path(func: uid(path)) { uid } }

Prompt：quick_start_prompt

服务器内置了一个quick_start_prompt，其内容通过//go:embed prompt.txt直接编译进二进制（mcp_server.go#L23-L24）。该 Prompt 从 prompt.txt 读取，为 LLM 定义了完整的交互行为规范，包括：

• 连接校验：先用get_schema验证连接可用性；
• Schema 探索：解析出全部谓词与类型，以可读结构呈现；
• 查询执行：先validate_query_syntax校验、再run_query执行、最后解释结果；
• 变更安全：执行删除等破坏性操作前必须向用户确认，并警告"删除不可逆、需先备份"；
• 向量搜索支持：识别相似度/最近邻意图，识别float32vector类型字段，使用similar_to函数；
• 最佳实践：内存缓存 Schema、维护查询历史、善用代码块与项目符号格式化输出。

Prompt 中给出的向量搜索示例：

query vectorSearch($vec: [float]) { vecSearch(func: similar_to(embedding, $vec, 5)) { uid name embedding } }

DQL 要点速查（来自内置 Prompt）

Prompt 内嵌了一套 DQL 速查，可视为 AI 助手操作 Dgraph 的行为基线：

• 常用语句：query { ... }查询节点与边；query me($foo: string, $bar: int) { ... }带变量查询；mutation { set { ... } }插入/更新；mutation { delete { ... } }删除；schema {}查看当前 Schema；
• 数据类型：string（UTF-8）、int（32/64 位）、float、bool、datetime（RFC3339）、geo（地理点/形状）、uid（节点间连接）、float32vector（向量相似度搜索）；
• 语法要点：谓词用尖括号<name>；数据用三元组<subject> <predicate> <object> .；uid()按唯一标识取节点；过滤函数eq、allofterms、anyofterms、has、le、ge、regexp、match等；变量用var(func: ...)定义可复用块；指令@filter、@cascade、@normalize控制输出。

端到端验证：集成测试做了什么

TestMCPSSE 是理解整个系统行为的最佳入口。它构建一个包含 1 个 Alpha + 1 个 Zero 的本地集群，连上/mcp/sse端点后依次验证：

1. 服务器元数据：初始化结果中 ServerInfo.Name 必须为Dgraph MCP Server，版本号非空；
2. 工具清单：6 个工具全部存在且数量一致；
3. 资源清单：dgraph://schema与dgraph://common_queries均可读取且内容非空；
4. Prompt 清单：quick_start_prompt存在且消息非空；
5. 功能链路：先alter_schema建立索引（n: string @index(term) .、m: int @index(int) .、p: float @index(float) .），再run_mutation写入节点，然后validate_query_syntax、run_query验证查询返回的 UID 符合0x...十六进制格式，最后get_common_queries返回示例。

这条链路完整覆盖了"建 Schema → 写数据 → 校验查询 → 读数据"的典型工作流，也是你在自己环境中手工验证 MCP 服务器是否正常的最快路径。

常见问题排查

官方文档给出了三条基础排查方向，结合源码可以进一步细化：

1. 检查 Dgraph 连接设置：
   • STDIO 模式下确认-c指向的是gRPC 端口（默认dgraph://localhost:9080），不是 HTTP 端口；
   • SSE 模式下确认 alpha 已带--mcp标志启动，且 HTTP 端口与路径（/mcp/sse或/mcp-ro/sse）拼写正确；
   • 若配置了 TLS 或 ACL，确认客户端连接字符串包含相应认证信息。
2. 验证 Go 模块依赖：go.mod中依赖github.com/mark3labs/mcp-go（MCP 协议实现）与github.com/dgraph-io/dgo/v250（Dgraph 客户端）；依赖缺失或版本不匹配会导致二进制无法编译或运行。构建可参考仓库根目录 Makefile 中的相关目标。
3. 仔细查看错误日志：dgraph 使用 glog 输出日志。连接失败时 run.go 会打印Failed to initialize MCPServer: ...；工具调用失败时各工具通过NewToolResultErrorFromErr返回具体原因，例如Error opening connection with Dgraph Alpha、Error parsing query、Schema alteration failed、Error running mutation等，客户端界面上会直接显示这些错误文本，据此定位是网络问题、语法问题还是权限问题。

一个值得注意的边界情况：validate_query_syntax只做解析校验，不校验谓词是否存在于 Schema 中（谓词存在性由get_schema交叉核对），所以 AI 助手的工作流是先get_schema摸清结构，再校验语法、再执行查询。

小结

Dgraph MCP 为 AI 原生的图数据库操作提供了一条标准、安全的通道：

• 两种接入方式：alpha 内置 SSE 端点（/mcp读写、/mcp-ro只读）适合 Claude Desktop 等 GUI 客户端；dgraph mcp子命令的 STDIO 模式适合本地进程内嵌场景；
• 能力边界清晰：只读模式在注册阶段就剔除alter_schema与run_mutation，配合工具注解让客户端能做出安全提示；
• 开箱即用：6 个工具 + 2 个资源 + 1 个内嵌 Prompt，覆盖"Schema 管理 → 语法校验 → 查询 → 变更 → 常用查询参考"的完整闭环，并内置向量相似度搜索支持。

对照 mcp_server_sse_test.go 的测试链路，你可以在自己的环境里完整复现这套工作流，快速验证接入是否成功。

• 数据库
• 图数据库
• 分布式数据库
• 后端