8000 fix(claude): write project MCP servers to the local scope in ~/.claude.json by ahmet-cetinkaya · Pull Request #23 · ahmet-cetinkaya/agent-ctrl · GitHub
[go: up one dir, main page]

Skip to content
< 8000 div class="prc-PageHeader-TitleArea-2n2J0" data-component="TitleArea" data-size-variant="medium">

fix(claude): write project MCP servers to the local scope in ~/.claude.json - #23

Merged
ahmet-cetinkaya merged 1 commit into
mainfrom
fix/claude-mcp-local-scope
Oct 31, 2026
Merged

ahmet-cetinkaya merged 1 commit into
mainfrom
fix/claude-mcp-local-scope

Conversation

@ahmet-cetinkaya
Copy link
Copy Markdown
Owner

Closes #15

Problem

profile apply claude <profile> (project scope) wrote MCP servers, with secrets already resolved, to <project>/.claude.json. Claude Code never reads that file, so the servers did not load, and the secret sat in the working tree where a commit could pick it up.

Cause: for project scope ClaudeApplyAdapter passed the project path as the Claude home, so ClaudeAdapter built its MCP path as <project>/.claude.json.

Change

  • Project scope now merges the servers into the local scope of the home config: ~/.claude.json → projects["<project path>"].mcpServers. Claude Code reads that location, and it stays out of the repository.
  • Every other key and project entry in ~/.claude.json is kept. --override replaces only this project's servers.
  • A newly created ~/.claude.json gets mode 0600. An existing file keeps its mode.
  • Safety fix in the same write path: before, any read or parse error was treated as an empty document and the file was rewritten, which could wipe a live ~/.claude.json. Now a missing file starts empty; a file that cannot be parsed, or is not a JSON object, makes the apply fail and leaves the file untouched. This also covers user scope.
  • User scope (apply claude) still writes top-level mcpServers, unchanged.
  • The reported file list shows the real MCP file path.

The second point in the issue (the ENV_FILE_MISSING warning only visible with -v) already works on current main; this PR adds a regression test for it.

Verification

  • New tests: 5 in ClaudeAdapter.test.ts, 2 in apply-profile.test.ts. 6 failed before the fix and pass after; the warning test passes before and after.
  • bun test: 1102 pass, 0 fail. scripts/lint.sh (tsc, ESLint, ShellCheck), Prettier on changed files and bun run build pass.
  • Tests point AGENT_CTRL_CLAUDE_HOME at a temp dir; I checked that the real ~/.claude.json gained no test entries.
  • Manual check in a throwaway project with a temp home: an unrelated key in ~/.claude.json survived; the server landed under projects[<path>].mcpServers; file mode was kept; no secret anywhere in the project tree; without .env and without -v the ENV_FILE_MISSING warning shows.

Not in this PR

  • An existing <project>/.claude.json written by older versions is neither deleted nor reported. Remove it by hand if it holds secrets.
  • The project key is the path the command ran in. Running from a subdirectory of a repo gives a different key than the repo root.
  • CHANGELOG entry: added at release time.

…e.json

ClaudeApplyAdapter passed the project path as the Claude home for project
scope, so ClaudeAdapter wrote mcpServers with resolved secrets to
<project>/.claude.json. Claude Code never reads that file, and the secret
landed in the repository.

For project scope the servers now go to ~/.claude.json under
projects["<project path>"].mcpServers (Claude Code's private local scope).
The file is read, merged and written back, so every other key survives and
--override replaces only that project's servers. A new file is created with
mode 0600, and an unparsable file is left untouched instead of being
replaced by an empty document. fileChanges now names the real file.

Closes #15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

profile apply claude writes MCP servers to <project>/.claude.json with resolved secrets, which Claude Code never reads

1 participant

0