MCP (Model Context Protocol) 是一个开放标准，允许 CodeBuddy 与外部工具和数据源进行集成。通过 MCP，您可以扩展 CodeBuddy 的功能，连接到各种外部服务、数据库、API 等。

MCP 服务器是提供工具、资源和提示的独立进程,CodeBuddy 通过不同的传输协议与这些服务器通信。

MCP 服务器可以提供 Prompts(提示模板),这些 Prompts 会自动转换为 CodeBuddy 的斜杠命令。当 MCP 服务器连接后:

• 服务器提供的 Prompts 会自动注册为斜杠命令
• 命令名称格式为: /服务器名:prompt名称
• 支持动态参数,通过交互式界面收集用户输入
• 命令执行时会调用 MCP 服务器的 prompts/get 接口获取完整内容
• 支持实时监听配置变更,自动更新可用命令列表

• STDIO: 通过标准输入输出与本地进程通信
• SSE: 通过 Server-Sent Events 与远程服务通信
• HTTP: 通过 HTTP 流式传输与远程服务通信

• user: 全局用户配置，应用于所有项目
• project: 项目级配置，应用于特定项目
• local: 本地配置，仅应用于当前会话或工作区

对于同名服务（即在多个作用域有同名配置），生效的优先级为：local > project > user

项目作用域的 MCP 服务器在首次连接时需要用户审批，以确保安全性。系统会显示服务器详细信息，用户可以选择批准或拒绝连接。

在非交互模式（如使用 -p/--print 参数）下，由于无法通过 UI 进行审批，需要通过 --settings 参数预先配置允许的 MCP 服务器：

# 方式 1: 允许所有项目 MCP 服务器
codebuddy --settings '{"enableAllProjectMcpServers": true}' -p "your prompt"

# 方式 2: 允许特定的 MCP 服务器
codebuddy --settings '{"enabledMcpjsonServers": ["server-name-1", "server-name-2"]}' -p "your prompt"

MCP 工具支持完整的权限管理系统，可以精确控制哪些工具可以被使用：

权限系统支持三种规则类型（按优先级排序）：

1. 拒绝规则 (deny) - 阻止使用指定工具（最高优先级）
2. 询问规则 (ask) - 使用工具前需要用户确认（覆盖允许规则）
3. 允许规则 (allow) - 允许工具使用而无需手动批准

重要：MCP 权限不支持通配符 (*)

mcp__服务器名

• 匹配指定服务器提供的任何工具
• 服务器名是在 CodeBuddy 中配置的名称

mcp__服务器名__工具名

• 匹配指定服务器的特定工具

{
  "permissions": {
    "allow": [
      "mcp__github"
    ]
  }
}

{
  "permissions": {
    "allow": [
      "mcp__github__get_issue",
      "mcp__github__list_issues"
    ]
  }
}

{
  "permissions": {
    "deny": [
      "mcp__dangerous_server__delete_file"
    ]
  }
}

• user 作用域: ~/.codebuddy.json
• project 作用域: <项目根目录>/.mcp.json
• local 作用域: ~/.codebuddy.json#/projects/<workspace_path>

关于 local 作用域的说明：

local 作用域的配置实际上保存在 user 作用域的配置文件 ~/.codebuddy.json 中，通过 projects 字段来区分不同项目的 local 配置。#/projects/<workspace_path> 使用的是 JSON Pointer 语法，用于指向 JSON 文档中的特定位置。关于 JSON Pointer 的详细说明，请参考：https://datatracker.ietf.org/doc/html/rfc6901

示例见下方配置文件格式说明。

{
  "mcpServers": {
    "server-name": {
      "type": "stdio|sse|http",
      "command": "命令路径",
      "args": ["参数1", "参数2"],
      "env": {
        "ENV_VAR": "value"
      },
      "url": "http://example.com/mcp",
      "headers": {
        "Authorization": "Bearer token"
      },
      "description": "服务器描述"
    }
  },
  "//": "projects 字段仅在 user 作用域的文件里有效，用于识别 local 作用域的配置",
  "projects": {
    "/path/to/project": {
      "mcpServers": {
        "local-server": {
          "type": "stdio",
          "command": "./local-tool"
        }
      }
    }
  }
}

注意：type 字段是可选的。如果未指定，系统会根据配置内容自动推断：

• 包含 command 字段时，推断为 stdio 类型
• 包含 url 字段时，推断为 http 类型

建议显式指定 type 字段以确保配置的准确性。

根据不同的传输类型，MCP 服务器配置具有不同的结构：

通过标准输入输出与本地进程通信。

字段	类型	必填	说明
type	string	是	固定值 "stdio"
command	string	是	可执行文件路径或命令
args	Array<string>	否	命令行参数列表
env	Object	否	环境变量键值对

示例：

{
  "type": "stdio",
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "env": {
    "PYTHONPATH": "/path/to/tools",
    "DEBUG": "true"
  }
}

通过 Server-Sent Events 与远程服务通信。

字段	类型	必填	说明
type	string	是	固定值 "sse"
url	string	是	SSE 服务端点 URL
headers	Object	否	HTTP 请求头键值对

示例：

{
  "type": "sse",
  "url": "https://api.example.com/mcp/sse",
  "headers": {
    "Authorization": "Bearer your-api-token",
    "X-API-Version": "v1"
  }
}

通过 HTTP 流式传输与远程服务通信。

字段	类型	必填	说明
type	string	是	固定值 "http"
url	string	是	HTTP 服务端点 URL
headers	Object	否	HTTP 请求头键值对

示例：

{
  "type": "http",
  "url": "https://mcp.example.com/api/v1",
  "headers": {
    "Authorization": "Bearer secret-token",
    "Content-Type": "application/json"
  }
}

# 添加本地可执行文件
codebuddy mcp add --scope user my-tool -- /path/to/tool arg1 arg2

# 添加 Python 脚本
codebuddy mcp add --scope project python-tool -- python /path/to/script.py

# 添加 SSE 服务器
codebuddy mcp add --scope user --transport sse sse-server https://example.com/mcp/sse

# 添加 HTTP 流式服务器
codebuddy mcp add --scope project --transport http http-server https://example.com/mcp/http

# 添加 STDIO 类型服务器
codebuddy mcp add-json --scope user my-server '{"type":"stdio","command":"/usr/local/bin/tool","args":["--verbose"]}'

# 添加 HTTP 类型服务器
codebuddy mcp add-json --scope user http-server '{"type":"http","url":"https://example.com/mcp","headers":{"Authorization":"Bearer token"}}'

# 添加 SSE 类型服务器
codebuddy mcp add-json --scope project sse-server '{"type":"sse","url":"https://api.example.com/mcp/sse","headers":{"X-API-Key":"your-api-key"}}'

# 添加带环境变量的 STDIO 服务器
codebuddy mcp add-json --scope user python-tool '{"type":"stdio","command":"python","args":["-m","my_mcp_server"],"env":{"PYTHONPATH":"/path/to/tools"}}'

# 列出所有作用域的服务器
codebuddy mcp list

# 查看特定服务器信息
codebuddy mcp get my-server

# 移除特定服务器
codebuddy mcp remove my-server

# 移除特定作用域的服务器
codebuddy mcp remove my-server --scope user

• 使用 user 作用域存储个人工具和全局服务
• 使用 project 作用域存储项目特定的工具
• 使用 local 作用域存储临时或实验性工具

• 避免在配置文件中存储敏感信息
• 使用环境变量传递认证信息
• 定期审查和更新服务器配置
• 项目作用域的 MCP 服务器需要用户审批后才能连接,确保安全性
• OAuth 授权 URL 会在打开前进行安全验证,仅支持 http/https 协议

• 合理配置服务器超时时间
• 避免同时运行过多的 STDIO 服务器
• 使用缓存机制减少重复连接

• 监控服务器连接状态
• 实现重连机制
• 记录和分析错误日志

1. 检查命令路径是否正确
2. 验证参数和环境变量
3. 确认网络连接（对于远程服务器）
4. 查看服务器日志输出

1. 确认服务器已成功连接
2. 检查工具权限设置
3. 验证工具兼容性

1. 检查配置文件语法
2. 确认作用域优先级
3. 重启 CodeBuddy 应用

{
  "mcpServers": {
    "python-tools": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": {
        "PYTHONPATH": "/path/to/tools"
      },
      "description": "Python 工具集合"
    }
  }
}

{
  "mcpServers": {
    "api-server": {
      "type": "sse",
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer your-token",
        "X-API-Version": "v1"
      },
      "description": "远程 API 服务"
    }
  }
}

{
  "mcpServers": {
    "node-server": {
      "type": "stdio", 
      "command": "node",
      "args": ["./mcp-server.js"],
      "env": {
        "NODE_ENV": "production"
      },
      "description": "Node.js MCP 服务器"
    }
  }
}

1. 选择实现语言: Python、Node.js、Go 等
2. 实现 MCP 协议: 使用官方 SDK 或自行实现
3. 定义工具接口: 描述工具功能和参数
4. 处理请求: 接收和处理来自 CodeBuddy 的请求
5. 返回结果: 按 MCP 格式返回执行结果

• Python: FastMCP
• TypeScript/JavaScript: @modelcontextprotocol/sdk
• 其他语言: 参考官方文档实现

codebuddy mcp add --scope user --transport http --header "X-Tapd-Access-Token: TAPD_ACCESS_TOKEN" -- tapd_mcp_http https://mcp-oa.tapd.woa.com/mcp

codebuddy mcp add --scope user chrome-devtools -- npx -y chrome-devtools-mcp@latest

codebuddy mcp add --scope user iwiki -- npx -y mcp-remote@latest https://prod.mcp.it.woa.com/app_iwiki_mcp/mcp3

• MCP 官方文档
• MCP GitHub 仓库
• CodeBuddy 官方文档