fix(mcp): align Claude Code user/project MCP command strings#204
Merged
Conversation
The user-scope ~/.claude.json gortex stanza was written with an absolute os.Executable() path while the project .mcp.json template uses the bare "gortex" command. Claude Code stores OAuth tokens per endpoint (command + args), so the two differing strings trip its "conflicting scopes" diagnostic. - Add agents.ResolveGortexCommand: prefer bare "gortex" when it resolves on PATH to the same running binary, falling back to the absolute path only when gortex is not on PATH. The global install now matches the portable project template. - Heal stale stanzas: upsertGlobalMCPConfig uses UpsertMCPServerWithMigration, and IsGortexAuthoredMCPEntry now recognizes the legacy absolute-path form so an older entry is rewritten in place instead of left behind. - Project-mode init warns and skips writing .mcp.json when gortex is already registered at user scope (override with --force), and warns about the duplication when a .mcp.json already exists.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #201.
What the issue was
The "MCP config diagnostics ⚠ / Conflicting scopes" message is emitted by Claude Code, not Gortex — no crash, no failed tool call. Claude Code stores OAuth tokens per endpoint (command + args), and the reporter had
gortexregistered in two scopes with two different command strings:C:\Users\daoti\AppData\Local\Programs\gortex\gortex.exe mcpgortex mcpRoot cause
The two registration paths wrote the command differently. The project
.mcp.jsontemplate (ProjectMCPJSON) hardcodes the portable bare"gortex", while the global install path (upsertGlobalMCPConfig) hand-rolled an absoluteos.Executable()path. On a machine with both scopes populated, the strings disagree and Claude Code flags it.Fix
Make the strings agree (the source of the conflict):
agents.ResolveGortexCommand()— prefers bare"gortex"when it resolves on PATH to the same running binary, falling back to the absolute path only when gortex is genuinely not on PATH (e.g. a Windows install dir not on PATH). The global entry now matches the portable project template.upsertGlobalMCPConfignow usesUpsertMCPServerWithMigrationinstead ofUpsertMCPServer, andIsGortexAuthoredMCPEntryrecognizes the legacy absolute-path form — so an older…\gortex.exestanza is rewritten in place on the nextgortex installrather than left behind (otherwise the warning would persist after upgrade).Catch the cases that can't be unified:
initwarns and skips writing.mcp.jsonwhen gortex is already registered at user scope (override with--force, e.g. to commit a.mcp.jsonfor teammates without a global install). When a.mcp.jsonalready exists alongside a user-scope entry, it warns and points atclaude mcp remove.Net effect for the reporter
After upgrading and re-running
gortex install, the migration rewrites theirC:\…\gortex.exeuser-scope stanza to baregortex(their working bare-command project entry implies gortex is on PATH), matching.mcp.json— and the warning clears on its own.Tests
All pass under
-race:TestResolveGortexCommandFrom— 5 cases incl. not-on-PATH Windows path and same-vs-different-binary.TestIsGortexAuthoredMCPEntryAbsolutePath— incl. the literal issue-Conflicting scopes #201 Windows path; user wrapper scripts still preserved.TestProjectModeSkipsMCPWhenUserScopeRegistered/TestProjectModeWritesMCPWhenNoUserScope— skip+warn without--force, write with--force, unchanged common path.go build ./...,go vet, andgolangci-lintare clean on the touched packages.