Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

fix(cli): prefer Claude Code project servers (#5522)

mikaae1b6bd25c23
diff --git a/fastmcp_slim/fastmcp/cli/discovery.py b/fastmcp_slim/fastmcp/cli/discovery.py
index 1a05287f9..806262fee 100644
--- a/fastmcp_slim/fastmcp/cli/discovery.py
+++ b/fastmcp_slim/fastmcp/cli/discovery.py
@@ -180,12 +180,13 @@ def _scan_claude_code(start_dir: Path) -> list[DiscoveredServer]:
if not isinstance(data, dict):
return []
- results: list[DiscoveredServer] = []
+ global_results: list[DiscoveredServer] = []
+ project_results: list[DiscoveredServer] = []
# Global servers
if global_servers := data.get("mcpServers"):
if isinstance(global_servers, dict):
- results.extend(
+ global_results.extend(
_parse_mcp_servers(
global_servers, source="claude-code", config_path=path
)
@@ -199,7 +200,7 @@ def _scan_claude_code(start_dir: Path) -> list[DiscoveredServer]:
if isinstance(project_data, dict):
if project_servers := project_data.get("mcpServers"):
if isinstance(project_servers, dict):
- results.extend(
+ project_results.extend(
_parse_mcp_servers(
project_servers,
source="claude-code",
@@ -207,7 +208,13 @@ def _scan_claude_code(start_dir: Path) -> list[DiscoveredServer]:
)
)
- return results
+ # Claude Code's project-local entries override same-name user entries.
+ # Returning both under the same qualified name makes the CLI ambiguous and
+ # would otherwise select the lower-priority user definition.
+ project_names = {server.name for server in project_results}
+ return [
+ server for server in global_results if server.name not in project_names
+ ] + project_results
def _scan_cursor_workspace(start_dir: Path) -> list[DiscoveredServer]:
diff --git a/tests/cli/test_claude_code_precedence.py b/tests/cli/test_claude_code_precedence.py
new file mode 100644
index 000000000..ac75c7061
--- /dev/null
+++ b/tests/cli/test_claude_code_precedence.py
@@ -0,0 +1,101 @@
+"""Claude Code local scope wins without losing other discovery sources."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from fastmcp.cli.discovery import _scan_claude_code, resolve_name
+from fastmcp.client.transports.stdio import StdioTransport
+
+
+def claude_project(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+ home = tmp_path / "home"
+ project = home / "project"
+ project.mkdir(parents=True)
+ monkeypatch.setattr(Path, "home", lambda: home)
+
+ def configure(user: dict[str, Any], local: dict[str, Any]) -> Path:
+ (home / ".claude.json").write_text(
+ json.dumps(
+ {
+ "mcpServers": user,
+ "projects": {str(project.resolve()): {"mcpServers": local}},
+ }
+ )
+ )
+ return project
+
+ return configure
+
+
+def test_local_wins_for_bare_and_qualified_names(claude_project) -> None:
+ project = claude_project(
+ {"weather": {"command": "user-weather", "env": {"LOWER": "user-only"}}},
+ {"weather": {"command": "local-weather"}},
+ )
+ found = _scan_claude_code(project)
+ assert len(found) == 1
+ assert found[0].qualified_name == "claude-code:weather"
+ for name in ("weather", "claude-code:weather"):
+ config = resolve_name(name, project)
+ assert isinstance(config, StdioTransport)
+ assert config.command == "local-weather"
+ assert config.env == {}
+
+
+ "user,local,expected",
+ [
+ ({"user": {"command": "u"}}, {"local": {"command": "l"}}, {"user", "local"}),
+ ({"weather": {"command": "u"}}, {}, {"weather"}),
+ ({}, {"weather": {"command": "l"}}, {"weather"}),
+ (
+ {"Weather": {"command": "u"}},
+ {"weather": {"command": "l"}},
+ {"Weather", "weather"},
+ ),
+ ],
+)
+def test_distinct_names_survive(claude_project, user, local, expected) -> None:
+ assert {
+ server.name for server in _scan_claude_code(claude_project(user, local))
+ } == expected
+
+
+def test_remote_local_overrides_stdio_user(claude_project) -> None:
+ project = claude_project(
+ {"weather": {"command": "user-weather"}},
+ {"weather": {"url": "https://example.test/mcp"}},
+ )
+ found = _scan_claude_code(project)
+ assert len(found) == 1
+ assert str(getattr(found[0].config, "url")) == "https://example.test/mcp"
+
+
+def test_other_source_remains_ambiguous(claude_project) -> None:
+ project = claude_project(
+ {"weather": {"command": "u"}}, {"weather": {"command": "l"}}
+ )
+ cursor = project / ".cursor"
+ cursor.mkdir()
+ (cursor / "mcp.json").write_text(
+ json.dumps({"mcpServers": {"weather": {"command": "cursor"}}})
+ )
+ with pytest.raises(ValueError, match="Ambiguous"):
+ resolve_name("weather", project)
+ for name, expected in (("claude-code:weather", "l"), ("cursor:weather", "cursor")):
+ config = resolve_name(name, project)
+ assert isinstance(config, StdioTransport)
+ assert config.command == expected
+
+
+def test_invalid_local_keeps_valid_user(claude_project) -> None:
+ project = claude_project(
+ {"weather": {"command": "u"}}, {"weather": {"command": ["invalid"]}}
+ )
+ config = resolve_name("weather", project)
+ assert isinstance(config, StdioTransport)
+ assert config.command == "u"