Dubbo-MCP

Dubbo-MCP 是连接 AI 编程助手（Cursor、Claude Code、Claude Desktop、Codex CLI、Windsurf 等）与 Apache Dubbo 微服务的 Model Context Protocol (MCP) 官方协议服务端。

在日常排查业务问题、接口联调与单元测试时，让 AI 助手直接检索微服务接口定义、反查复杂 DTO 入参结构并基于原生泛化调用（Generic Invocation）发起实时 RPC 调试，无需手动编写测试用例，无需在本地工程引入任何业务 API 依赖 Jar 包。

🚀 快速安装

1. 一键脚本安装

macOS / Linux：

curl -fsSL https://raw.githubusercontent.com/b1n9bna/dubbo-mcp/main/install.sh | sh

Windows (PowerShell)：

irm https://raw.githubusercontent.com/b1n9bna/dubbo-mcp/main/install.ps1 | iex

脚本会下载可执行文件至 ~/.dubbo-mcp/dubbo-mcp.jar，并创建全局命令 dubbo-mcp。

(也可通过本地源码编译：mvn clean package -DskipTests)

2. 自动注入 AI 助手配置

安装后执行以下命令，可自动检测本机已安装的 Codex、Cursor、Claude 等工具并写入配置：

dubbo-mcp install

Related MCP server: Open Enterprise AI MCP Server

⚙️ 环境配置

配置文件路径：~/.dubbo-mcp/config.properties

# 默认激活的环境 (test / uat / prod)
active.env=test

# ==============================================================================
# 1. 开发/测试环境 (直连 ZooKeeper，泛化调用)
# ==============================================================================
env.test.type=zookeeper
env.test.registry=zookeeper://127.0.0.1:2181
env.test.timeout=5000
env.test.readonly=false

# ==============================================================================
# 2. 预发环境 (UAT)
# ==============================================================================
env.uat.type=zookeeper
env.uat.registry=zookeeper://10.20.1.15:2181
env.uat.timeout=5000
env.uat.readonly=true

# ==============================================================================
# 3. 生产环境 (对接 dubbo-admin HTTP API)
# ==============================================================================
env.prod.type=dubbo-admin
env.prod.admin_url=https://dubbo.yourcompany.com
env.prod.readonly=true
env.prod.data_masking=true

# 只读校验正则：开启 readonly=true 时，仅允许匹配该正则的方法名被执行
security.readonly.regex=^(get|query|find|select|list|count|check|is|search|fetch|read).*$

# 自定义 dubbo-admin 上下文路径（可选，如 /dubbo-admin）
# env.prod.admin_api_prefix=/dubbo-admin

🔐 生产环境登录授权 (dubbo-admin)

企业内部的 Dubbo Admin 通常接入了单点登录（SSO/OAuth）。若配置了 env.prod.type=dubbo-admin，首次使用或会话过期后，需在终端执行一次凭据保存：

1. 获取登录态：在浏览器打开并登录 Dubbo Admin 页面，按 F12 打开控制台 Console，执行：

   copy(JSON.stringify({
     cookie: document.cookie,
     authorization: localStorage.getItem('token') || localStorage.getItem('Admin-Token')
   }))

2. 终端保存凭据：在本地终端直接执行（macOS 下 --clipboard 会自动从系统剪贴板读取，避免终端长文本截断）：

   dubbo-mcp login --clipboard

凭据通过验证后将保存在 ~/.dubbo-mcp/session-prod.json（权限 0600）。MCP 进程调用时会自动读取该文件，会话过期后重新执行上述命令即可，无需重启 AI 助手。

🔌 客户端接入配置

若未使用 dubbo-mcp install 自动注入，也可手动在对应工具的配置文件中添加：

Codex

在 ~/.codex/config.toml 中添加：

[mcp_servers.dubbo]
command = "dubbo-mcp"
args = []

Cursor

在 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "dubbo": {
      "command": "dubbo-mcp",
      "args": []
    }
  }
}

Claude Code / ZCode

可通过 Git 仓库添加插件：

/plugin marketplace add https://github.com/b1n9bna/dubbo-mcp.git

或以 stdio 方式配置命令 dubbo-mcp。

💬 使用示例

配置完成后，可以在 AI 对话中直接用自然语言发起请求：

场景 1：排查业务问题

提问：“生产环境查一下订单号 2026103001 的详情，分析为什么没发货？”
AI 动作：

1. 调用 dubbo_invoke（传入 env="prod", interfaceName="com.corp.OrderQueryService", method="getOrderDetail"）；

2. Dubbo-MCP 通过 dubbo-admin 接口代理发起查询，并自动脱敏手机号、身份证等敏感字段；

3. AI 根据返回结果分析：“订单当前状态为已支付（PAID），仓库物流单号为空，停留在配货状态（STOCKING）。”

场景 2：检索服务与接口定义

提问：“测试环境有哪些与用户 (user) 相关的 Dubbo 服务？查看它们提供了哪些方法及参数结构。”
AI 动作：

1. 调用 dubbo_list_services(keyword="user") 获取匹配的接口列表；

2. 调用 dubbo_get_service_detail 反查接口下的方法签名及 DTO 入参字段；

3. 整理列出服务的方法结构供后续调用。

场景 3：多环境动态切换

提问：“把当前环境切到 UAT 环境。”
AI 动作： 调用 dubbo_switch_env(env="uat")，后续请求无缝切换至预发集群。

🛠️ MCP 工具列表

🛡️ 安全控制

为防止误操作影响线上稳定性，针对生产环境提供了两项保护机制：

1. 只读方法校验：在开启 readonly=true 的环境中，仅允许执行匹配 security.readonly.regex 正则的方法（如 get*、query*、find* 等只读前缀），写操作（如 update*、delete*）会被直接拦截；

2. 敏感数据脱敏：开启 data_masking=true 后，自动对返回值中的手机号（138****5678）和 18 位身份证（110101********2345）进行掩码脱敏，防止敏感数据进入对话上下文。

🏗️ 架构与工作原理

 ┌────────────────────────────────────────────────────────┐
 │   AI 编程助手 (Codex / Cursor / Claude Code / ZCode)    │
 └───────────────────────────┬────────────────────────────┘
                             │
               STDIO 标准输入输出 (JSON-RPC 2.0)
                             │
 ┌───────────────────────────▼────────────────────────────┐
 │  1. Transport 层: StdioJsonRpcServer (纯 Java 8 实现)   │
 │     - 日志严格重定向至 stderr，保证 stdout 纯净用于通信    │
 ├────────────────────────────────────────────────────────┤
 │  2. 安全过滤与两阶段调度层                              │
 │     - 按需探测：搜索服务 -> 获取参数元数据 -> 发起调用     │
 │     - 生产环境安全保护：只读正则校验 + 敏感信息脱敏        │
 ├────────────────────────────────────────────────────────┤
 │  3. 双通道核心驱动 (Dual-Engine Driver)                 │
 │     - 测试/开发环境：直连 ZooKeeper，原生 RPC 泛化调用     │
 │     - 生产环境：通过 dubbo-admin HTTP 接口中转调用         │
 └───────────────────────────┬────────────────────────────┘
              ┌──────────────┴──────────────┐
              ▼                             ▼
   [开发/测试环境: ZooKeeper]        [生产环境: HTTP 中转]
     Dubbo Provider 节点           企业已部署的 Dubbo Admin

📊 性能与 Token 消耗实测

实测结果：在单次微服务接口排查任务中，Dubbo-MCP 的结构化调用相比传统浏览器 Agent 方案 节省约 98% 上下文 Token，响应提速 30 倍以上，且无网页 DOM 噪音与多轮截图历史累加的包袱。

1. 大模型交互开销对比（单次服务排查）

• 分词计量基准：统一采用 OpenAI cl100k_base BPE 分词器编码，以真实生产订单详情排查为基准场景；

• Dubbo-MCP 实测：tools/list 基础 Schema（397 Token）+ 单次请求入参（51 Token）+ 接口返回真实数据（90 Token）+ AI 总结回答（34 Token）= 572 Token；

• 视觉浏览器 Agent：Anthropic 官方视觉公式（1280×800 截图每张约 1,365 Token），在 Dubbo Admin 完成“搜索 -> 点击 -> 填参 -> 提交 -> 查看弹窗”共 6 轮截图，按多轮对话上下文历史复合累加（$O(N^2)$）计算；

• DOM 浏览器 Agent：以 Dubbo Admin（Vue + Element UI）渲染后的页面可访问性树（单步约 2,500 Token），5 轮状态机历史复合累加计算。

2. 本地进程资源占用

❓ 常见问题

Dubbo-MCP 基于 Dubbo 原生泛化调用（Generic Invocation）：

• 字段结构感知：调用 dubbo_get_service_detail 时，会从 ZooKeeper 元数据中心反查入参 DTO 的属性结构（如 current, size, calculationDateList 等）；

• 类型自动匹配：AI 在 dubbo_invoke 的 args 中直接传入对应的 JSON Map 即可，底层会自动匹配目标 DTO 类型并完成序列化转换。

• 底层会自动从注册中心读取 Provider 列表，若该接口仅注册了单一版本或单一分组，会自动选用；

• 若存在多个不同版本或分组，可在 dubbo_invoke 中显式指定 version 或 group 参数进行精准路由。

若企业 SSO 会话过期，接口调用会返回 401/403。此时只需在浏览器重新打开 Dubbo Admin 执行复制脚本，在终端重新执行 dubbo-mcp login --clipboard 即可。运行中的 MCP 进程会在下一次请求时自动热加载新凭据，无需重启 AI 助手。

执行 dubbo-mcp install 后，Cursor 会在 ~/.cursor/mcp.json 中自动挂载服务。在 Cursor 对话框中直接输入自然语言，例如：

• "帮我查一下生产环境订单接口 cn.corp.trade.OrderRpcService 的入参格式"

• "用测试环境调用 UserServiceRpc.getUserById，入参 userId=10001"

Cursor 将自动调用 dubbo_get_service_detail 获取签名，并调用 dubbo_invoke 执行泛化调用返回实时 JSON，全程无需离开编辑器。

• Token 消耗直降 98.6%：单次排查实测仅需 572 Token，而视觉或 DOM 浏览器 Agent 多轮对话会复合累加产生 33,000 ~ 40,000 Token（参见上方基准图表）；

• 毫秒级直接响应：直连 RPC/API，避免了浏览器自动化中的网页加载、DOM 解析、模拟点击和截图延时（通常耗时 30~60 秒）；

• 确定性与安全性：杜绝了前端页面改版、弹窗漏点或 OCR 识别失误，且具备严格的只读正则守卫与敏感字段脱敏。

💻 本地构建与测试

# 运行单元测试
LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 mvn test

# 打包可执行 Fat-JAR
LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 mvn package -DskipTests