第 2 卷
USER作用域
优先级顺序（从高到低）：
- ~/.codebuddy/.mcp.json（推荐）
- ~/.codebuddy/mcp.json（已废弃）
- ~/.codebuddy.json（旧版配置文件）
读取规则：系统会按上述顺序查找第一个存在的文件并读取其内容。
写入规则：
如果上述文件中存在任意一个，写入第一个存在的文件
如果都不存在，创建 ~/.codebuddy/.mcp.json（最高优先级）
PROJECT作用域
优先级顺序（从高到低）：
- <项目根目录>/.mcp.json（推荐）
- <项目根目录>/mcp.json（已废弃）
读取规则：系统会按上述顺序查找第一个存在的文件并读取其内容。
写入规则：
如果上述文件中存在任意一个，写入第一个存在的文件
如果都不存在，创建 <项目根目录>/.mcp.json（最高优先级）
LOCAL作用域
local作用域的配置实际上保存在 user作用域的配置文件中，通过 projects 字段来区分不同项
目的 local配置。
文件路径： ~/.codebuddy.json#/projects/<workspace_path>
#/projects/<workspace_path> 使用的是 JSON Pointer语法，用于指向 JSON 文档中的特定
位置。关于 JSON Pointer的详细说明，请参考：https://datatracker.ietf.org/doc/html/rfc6901
注意：
系统不会合并同一个作用域的多个配置文件内容，只会使用第一个存在的文件
示例见下方配置文件格式说明。
配置文件格式
MCP 配置文件支持 JSONC (JSON with Comments)格式，允许在配置中添加注释，提升可读性和可维护性。
JSONC支持的特性
单行注释：使用 // 添加行内或行尾注释
多行注释：使用 /* */ 添加块注释
尾随逗号：数组和对象的最后一个元素后可以添加逗号
基础配置格式
jsonc
{ // MCP 服务器配置 "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"
} } } } }
带注释的完整示例
jsonc
{ // MCP Server Configuration for CodeBuddy // 这个文件配置了项目使用的 MCP 服务器
"mcpServers": { /*
- Filesystem Server
*/ "filesystem": { "type": "stdio", "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace",// 工作目录路径 ], "env": { "DEBUG": "true",// 启用调试模式 }, },
// HTTP API 服务器示例 "api-server": { "type": "http", "url": "http://localhost:3000/mcp",// 本地开发服务器 "headers": { "Authorization": "Bearer your-token", }, }, },
// 已禁用的服务器列表（供参考）
"disabledMcpServers": [ "deprecated-server", ], }
注意：
标准 JSON 格式文件仍然完全兼容
解析错误时会提供清晰的错误提示
**注意**：`type` 字段是可选的。如果未指定，系统会根据配置内容自动推断：
- 包含 `command` 字段时,推断为 `stdio` 类型
- 包含 `url` 字段时,推断为 `http` 类型
建议显式指定 `type` 字段以确保配置的准确性。
### 环境变量扩展
MCP 配置支持环境变量扩展，允许您在配置中引用系统环境变量。这对于在团队间共享配置、管理敏感信息
#### 支持的语法