Support project-level `.codewhale/mcp.json` auto-merge

[yekern]

Environment

• OS: Ubuntu 24.04.4 LTS, Linux 6.8.0-111-generic, x86_64
• Rust: rustc 1.75.0 (82e1608df 2023-12-21)
• codewhale: 0.8.53 (8dff2f7)

---

Summary

The install page states that .codewhale/ can carry project-level MCP servers, but codewhale 0.8.53 only loads from ~/.codewhale/mcp.json and ignores the workspace-level .codewhale/mcp.json entirely.

Steps to Reproduce

1. Create .codewhale/mcp.json in any workspace root:

{
  "servers": {
    "laravel-boost": {
      "command": "php",
      "args": ["artisan", "boost:mcp"]
    }
  }
}

2. Run codewhale mcp list — only global servers appear.
3. Run codewhale doctor — output shows "MCP config found at ~/.codewhale/mcp.json" with no mention of the project-level file.

Expected Behavior

On startup, codewhale should detect .codewhale/mcp.json in the workspace root and merge its servers with the global config:

• Global servers + project servers → final available server list
• Same-name server: project-level overrides global
• Project-level MCP cwd defaults to workspace root
• Same format as global mcp.json (key: "servers")

This mirrors the existing project-level skills discovery — codewhale doctor already correctly recognizes .agents/skills and .claude/skills.

Actual Behavior

.codewhale/mcp.json is silently ignored. Only ~/.codewhale/mcp.json is read. The workaround of adding project-specific servers to the global config pollutes other workspaces and causes startup errors when those servers' commands are unavailable.

Use Case

A Laravel project ships with a laravel-boost MCP server (php artisan boost:mcp) providing database schema queries, log reading, and documentation search. This is project-specific and cannot live in the global config.

References

• Install page §06 "Where config lives" — explicitly states project-level MCP is supported
• codewhale doctor already supports project-level skills discovery, can serve as a reference implementation

---

---

环境

• OS: Ubuntu 24.04.4 LTS, Linux 6.8.0-111-generic, x86_64
• Rust: rustc 1.75.0 (82e1608df 2023-12-21)
• codewhale: 0.8.53 (8dff2f7)

概述

安装文档明确说 .codewhale/ 可以承载项目级 MCP servers，但 codewhale 0.8.53 只从 ~/.codewhale/mcp.json 加载，完全忽略工作区下的 .codewhale/mcp.json。

复现步骤

1. 在任意工作区根目录创建 .codewhale/mcp.json：

{
  "servers": {
    "laravel-boost": {
      "command": "php",
      "args": ["artisan", "boost:mcp"]
    }
  }
}

2. 运行 codewhale mcp list — 只显示全局 server。
3. 运行 codewhale doctor — 输出显示 "MCP config found at ~/.codewhale/mcp.json"，未提及项目级文件。

期望行为

启动时检测工作区根目录下的 .codewhale/mcp.json，将其 servers 与全局配置合并：

• 全局 server + 项目级 server → 最终可用列表
• 同名 server：项目级覆盖全局
• 项目级 MCP 的 cwd 默认为项目根目录
• 格式与全局 mcp.json 保持一致（键名 "servers"）

类似 skills 的项目级发现机制——doctor 已能正确识别 .agents/skills 和 .claude/skills。

实际行为

.codewhale/mcp.json 被静默忽略，只读取 ~/.codewhale/mcp.json。将项目专属 server 写入全局配置会污染其他工作区，并在对应命令不存在时报错。

使用场景

Laravel 项目自带 laravel-boost MCP server（php artisan boost:mcp），提供数据库 schema 查询、日志读取、文档搜索等工具。这是项目专属的，不能放在全局配置中。

相关

• 安装文档第 06 节 "Where config lives" — 明确说明支持项目级 MCP
• codewhale doctor 已支持项目级 skills 发现，可作为参考实现

[github-actions]

Thanks @yekern for the report.

This repository is currently observing a maintainer-managed contribution gate in dry-run mode, so this issue is staying open. When enforcement is enabled, issues from contributors who are not listed in .github/APPROVED_CONTRIBUTORS will be closed automatically.

Please read CONTRIBUTING.md for the expected issue shape. A maintainer can grant issue access by commenting /lgtmi on an issue.

[yekern]

/lgtmi

[Hmbown]

Fixed by #2770 (95e24194e) on the v0.9 integration branch.

CodeWhale now honors a workspace .codewhale/mcp.json after the workspace has been trusted in user-owned config, merges it with the global MCP config, lets project servers override same-name global servers, defaults project stdio server cwd to the workspace, and uses the merged MCP view in the TUI engine, runtime API, doctor, and codewhale mcp read/connect/validate flows. The landed harvest also rejects project cwd escapes and ignores checked-in legacy trust markers for MCP subprocess startup.

Verification run locally on the harvest branch:

• cargo test -p codewhale-tui workspace_mcp --all-features --locked -- --nocapture (11 passed)
• cargo test -p codewhale-tui reload_if_config_changed --all-features --locked -- --nocapture (3 passed)
• cargo test -p codewhale-tui doctor_mcp --all-features --locked -- --nocapture (6 passed)
• cargo test -p codewhale-tui mcp_pool_call_tool --all-features --locked -- --nocapture (3 passed)
• cargo fmt --all -- --check
• git diff --check
• ./scripts/release/check-versions.sh
• cargo check -p codewhale-tui --all-features --locked
• cargo clippy -p codewhale-tui --all-features --locked -- -D warnings
• contributor-credit audit passed for origin/main..HEAD after the merge

Thanks @yekern for the clear Laravel MCP reproduction and acceptance criteria, and thanks @cyq1017 for PR #2751, which supplied the core project MCP merge implementation. Please retest on the next v0.9 build and open a follow-up if a trusted workspace still misses its project MCP server.