Repository navigation
codebuddy: project-scope MCP written to .codebuddy/mcp.json instead of .mcp.json (mcpProject unused) #1185
Description
teamai CLI 反馈：codebuddy 项目级 MCP 落盘到错误路径
环境
- teamai-cli 0.28.0-beta.4（
npm i -g teamai-cli） - CodeBuddy Code（@tencent-ai/codebuddy-code）
- 复现目录：一个 teamai workspace-scope 初始化的项目
问题（TL;DR）
teamai 的 codebuddy 分支未使用 mcpProject 字段，把 project-scope MCP 写到了
<项目根>/.codebuddy/mcp.json，而 CodeBuddy 只读 <项目根>/.mcp.json。
这是 teamai 的 bug（非 CodeBuddy）。结果：所有项目级 MCP server
（context7 / graphify / postgresql-service 等）都不会被加载——/mcp 只显示 user 级
server，项目级一个都不出现，且无任何报错，极难排查。
复现步骤
teamai init <team-repo> --agent codebuddy（workspace/project scope 均可）- 团队成员确认 MCP 已声明（
teamai mcp list显示installed: codebuddy） - 文件确实写到了
<项目根>/.codebuddy/mcp.json（内容正确） - 但 CodeBuddy
/mcp里 看不到 这些 server - 执行
ln -sf .codebuddy/mcp.json .mcp.json后，重启 CodeBuddy →
/mcp立即列出全部三个 project server
证据
CodeBuddy 官方文档 cn/cli/mcp.md「PROJECT 作用域」明确：
优先级顺序（从高到低）：
1. <项目根目录>/.mcp.json （推荐）
2. <项目根目录>/mcp.json （已废弃）
而 teamai dist/cli.js 中 codebuddy 的 toolPaths 其实已经定义了正确字段：
codebuddy: {
skills: ".codebuddy/skills",
rules: ".codebuddy/rules",
settings: ".codebuddy/settings.json",
claudemd: ".codebuddy/CODEBUDDY.md",
agents: ".codebuddy/agents",
mcp: ".codebuddy/mcp.json", // ← 实际写入用的是这个（user-scope 语义）
mcpProject: ".mcp.json" // ← project-scope 应使用这个，但未被选用
}对比 claude / cursor 也都同时定义了 mcp 与 mcpProject 两个字段，
说明 mcpProject 是设计内的 project-scope 路径。
责任归属：这是 teamai 的 bug，不是 CodeBuddy 的
请明确：不要在 CodeBuddy 侧修复，也不应请求 CodeBuddy 去读 .codebuddy/mcp.json。
- CodeBuddy 只读
<项目根>/.mcp.json是其公开文档契约，且.mcp.json是主流
AI 编码工具（Claude Code 等）通用的项目级 MCP 文件名。CodeBuddy 行为正确、无 bug。 - teamai 的 toolPaths 里已经存在正确的 project-scope 字段
mcpProject: ".mcp.json"
（与 claude / cursor 完全并列定义），但 codebuddy 分支在写入 project-scope MCP 时
没有选用它，而是误用了 user-scope 的mcp字段，导致文件落到 CodeBuddy 不读的
.codebuddy/mcp.json。
一句话：teamai 的 codebuddy 分支未使用 mcpProject 字段 —— 这是根因。
期望修复
teamai 写入 project-scope MCP 时（scope 为 project / workspace），
codebuddy 分支应选用 mcpProject（即 <项目根>/.mcp.json），而非 mcp。
- 修复点集中在「按 scope 选择 MCP 配置文件路径」的那段逻辑；
由于mcpProject字段已在 toolPaths 中就绪，改动量应很小。 - 建议同时补一个回归测试：对 codebuddy，project/workspace scope 下 MCP 必须落到
.mcp.json（可参考 claude 的同类测试）。 - 我未能精确定位到做出该选择的代码行（发布包
dist/cli.js为压缩产物），
以上为可复现的行为证据 + 字段已存在的代码证据；据此应能快速定位。
临时绕过
受影响成员可自行：ln -sf .codebuddy/mcp.json .mcp.json
（.mcp.json 通常在 .gitignore 中，且软链能跟随后续 teamai pull 的更新）
附：同类问题（顺带反馈，可另开 issue）
teamai 分发的 MCP server 在 uvx 下易因依赖漂移而启动即崩（已在本团队 PR 修复，
但建议 teamai 侧在文档/模板中提示）：
- 用
mcp.server.fastmcp的 Python MCP 包（postgres-mcp、mcp-server-mysql 等）
在mcpSDK v2 下会ModuleNotFoundError: No module named 'mcp.server.fastmcp'
（v2 把FastMCP改名MCPServer）→ 需--with mcp<2 graphifyy基础包不含mcp模块 → 需--from graphifyy[mcp]mcp-server-mysql只读环境变量MYSQL_*，不认--host/--port/...命令行参数
Activity
SaulMoro commentedon Oct 17, 2026
Thanks for the detailed report. I could not reproduce it with the default paths, and I think the cause is a different one.
On 0.28.0-beta.4, with an isolated HOME, a local team repo and one CodeBuddy MCP server,
teamai mcp injectwrites:teamai.yamltoolPaths<root>/.mcp.jsontoolPaths<root>/.mcp.jsontoolPaths.codebuddy.mcpProject: .codebuddy/mcp.json<root>/.codebuddy/mcp.jsonmcpProjectis used in project and workspace scope (src/mcp-reconcile.ts:565,const rel = projectScope ? paths.mcpProject : paths.mcp). CodeBuddy's default has been.mcp.jsonsince v0.24.0 (57636a2). CodeBuddy 2.168.0'scodebuddy mcp listshows<root>/.mcp.jsonand does not show.codebuddy/mcp.json, so the CodeBuddy side of your report is right.So
.codebuddy/mcp.jsonmost likely comes from atoolPathsentry in your team'steamai.yaml.initdoes not write one. Could you paste that section?If that is it, the bug is still in teamai, one level up.
toolPathsisz.record(...).default({...})(src/types.ts:461), so anytoolPathskey inteamai.yamlreplaces the whole default table instead of merging with it:.codebuddy/mcp.jsonand never gets the fix.codebuddyundertoolPaths,teamai mcp listno longer detects Claude Code, although.claudeexists.That is the trap from #1115. The fix is to merge the team's
toolPathsover the defaults, tool by tool, so an override changes only the tool it names.Workaround until then: if the team's
toolPathsonly repeats the defaults, delete the block. Otherwise setcodebuddy.mcpProject: .mcp.json. Then runteamai pull.Two CodeBuddy behaviors can also hide project servers once the file is in the right place:
<root>/.mcp.jsonservers pending until they are approved (enableAllProjectMcpServersorenabledMcpjsonServers).codebuddy mcp listshows them as "Needs approval"..mcp.jsonnor the local-scope servers.legend91019 commentedon Oct 18, 2026
I'll take this issue. I'll work on tool-by-tool merging of custom toolPaths over default tool paths and add test coverage.
test(e2e): cover sparse toolPaths merge against built CLI (Tencent#1185)
test(source): keep Codex-only fixtures explicit (Tencent#1185)
test(source): isolate retarget ownership fixtures (Tencent#1185)
fix(config): merge custom toolPaths tool by tool over defaults (Tence…
test(e2e): cover sparse toolPaths merge against built CLI (Tencent#1185)
test(source): keep Codex-only fixtures explicit (Tencent#1185)
test(source): isolate retarget ownership fixtures (Tencent#1185)
fix(config): merge custom toolPaths tool by tool over defaults (#1185) (