Skip to content

🚀 The fast, Pythonic way to build MCP servers and clients.

fix(cli): resolve config paths beside fastmcp.json (#5511)

mika3ea8d54237da
diff --git a/fastmcp_slim/fastmcp/utilities/cli.py b/fastmcp_slim/fastmcp/utilities/cli.py
index 810cf4190..1c0049078 100644
--- a/fastmcp_slim/fastmcp/utilities/cli.py
+++ b/fastmcp_slim/fastmcp/utilities/cli.py
@@ -93,6 +93,7 @@ def load_and_merge_config(
# its own name and directory.
config_path = Path(os.path.abspath(config_path))
resolved_spec = str(config_path)
+ config.anchor_paths(config_path.parent)
if config.deployment:
config.deployment.apply_runtime_settings(config_path)
diff --git a/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py
index 572472312..fed63185a 100644
--- a/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py
+++ b/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py
@@ -223,6 +223,9 @@ class MCPServerConfig(BaseModel):
def from_file(cls, file_path: Path) -> MCPServerConfig:
"""Load configuration from a JSON file.
+ Relative `source.path` and `environment.requirements` values are
+ anchored to the configuration file's directory (see `anchor_paths`).
+
Args:
file_path: Path to the configuration file
@@ -240,7 +243,34 @@ class MCPServerConfig(BaseModel):
with file_path.open("r", encoding="utf-8") as f:
data = json.load(f)
- return cls.model_validate(data)
+ config = cls.model_validate(data)
+ config.anchor_paths(file_path.parent)
+ return config
+
+ def anchor_paths(self, config_dir: Path) -> None:
+ """Make relative file paths absolute against the config file's directory.
+
+ Anchors `source.path` and `environment.requirements`, so a config
+ loaded from another working directory still finds its files. Paths are
+ made absolute without following symlinks, so a symlinked `fastmcp.json`
+ resolves paths beside the link. Other paths, such as `deployment.cwd`,
+ keep their own resolution rules.
+
+ Args:
+ config_dir: Directory containing the configuration file
+ """
+ config_dir = Path(os.path.abspath(config_dir.expanduser()))
+
+ source_path = Path(self.source.path).expanduser()
+ if not source_path.is_absolute():
+ self.source.path = os.path.abspath(config_dir / source_path)
+
+ requirements = self.environment.requirements
+ if requirements is not None:
+ requirements = requirements.expanduser()
+ if not requirements.is_absolute():
+ requirements = Path(os.path.abspath(config_dir / requirements))
+ self.environment.requirements = requirements
@classmethod
def from_cli_args(
diff --git a/tests/cli/test_config.py b/tests/cli/test_config.py
index cb4dd00a0..3e0f5e516 100644
--- a/tests/cli/test_config.py
+++ b/tests/cli/test_config.py
@@ -298,7 +298,7 @@ class TestMCPServerConfig:
# When loaded from JSON with entrypoint format, it becomes EntrypointConfig
assert isinstance(config.source, FileSystemSource)
- assert config.source.path == "src/server.py"
+ assert config.source.path == os.path.abspath(tmp_path / "src/server.py")
assert config.source.entrypoint == "app"
assert config.environment.python == "3.12"
assert config.environment.dependencies == ["requests"]
@@ -318,7 +318,7 @@ class TestMCPServerConfig:
config = MCPServerConfig.from_file(config_file)
# String entrypoint with : should be converted to EntrypointConfig
assert isinstance(config.source, FileSystemSource)
- assert config.source.path == "server.py"
+ assert config.source.path == os.path.abspath(tmp_path / "server.py")
assert config.source.entrypoint == "mcp"
def test_string_entrypoint_with_entrypoint_and_environment(self, tmp_path):
@@ -336,7 +336,7 @@ class TestMCPServerConfig:
# Should be parsed into EntrypointConfig
assert isinstance(config.source, FileSystemSource)
- assert config.source.path == "src/server.py"
+ assert config.source.path == os.path.abspath(tmp_path / "src/server.py")
assert config.source.entrypoint == "app"
# Environment config should still work
@@ -347,6 +347,57 @@ class TestMCPServerConfig:
assert config.deployment.transport == "http"
assert config.deployment.port == 8000
+ @pytest.mark.parametrize(
+ "source",
+ [
+ {"path": "../src/server.py", "entrypoint": "mcp"},
+ {"type": "filesystem", "path": "../src/server.py", "entrypoint": "mcp"},
+ ],
+ )
+ def test_from_file_resolves_paths_from_config_directory(
+ self, tmp_path, monkeypatch, source
+ ):
+ config_dir = tmp_path / "project" / "config"
+ config_dir.mkdir(parents=True)
+ caller_dir = tmp_path / "caller"
+ caller_dir.mkdir()
+ config_file = config_dir / "fastmcp.json"
+ config_file.write_text(
+ json.dumps(
+ {
+ "source": source,
+ "environment": {"requirements": "requirements.txt"},
+ "deployment": {"cwd": "runtime"},
+ }
+ )
+ )
+ monkeypatch.chdir(caller_dir)
+
+ config = MCPServerConfig.from_file(config_file)
+
+ assert config.source.path == os.path.abspath(tmp_path / "project/src/server.py")
+ assert config.source.entrypoint == "mcp"
+ assert config.environment.requirements == config_dir / "requirements.txt"
+ assert config.deployment.cwd == "runtime"
+
+ def test_from_file_preserves_absolute_paths(self, tmp_path):
+ source_path = (tmp_path / "server.py").resolve()
+ requirements = (tmp_path / "requirements.txt").resolve()
+ config_file = tmp_path / "fastmcp.json"
+ config_file.write_text(
+ json.dumps(
+ {
+ "source": {"path": str(source_path)},
+ "environment": {"requirements": str(requirements)},
+ }
+ )
+ )
+
+ config = MCPServerConfig.from_file(config_file)
+
+ assert config.source.path == str(source_path)
+ assert config.environment.requirements == requirements
+
def test_find_config_in_current_dir(self, tmp_path):
"""Test finding config in current directory."""
config_file = tmp_path / "fastmcp.json"
diff --git a/tests/cli/test_config_encoding.py b/tests/cli/test_config_encoding.py
index f3855e029..5f4b08790 100644
--- a/tests/cli/test_config_encoding.py
+++ b/tests/cli/test_config_encoding.py
@@ -3,6 +3,7 @@
import builtins
import io
import json
+import os
from pathlib import Path
from typing import Any
@@ -75,11 +76,11 @@ class TestConfigFilesReadAsUtf8:
def test_load_and_merge_fastmcp_json(self, tmp_path: Path):
path = tmp_path / "fastmcp.json"
- _write_utf8_json(path, {"source": {"path": ARABIC_PATH}})
+ _write_utf8_json(path, {"source": {"path": "فاطمة.py"}})
config, _ = load_and_merge_config(str(path))
- assert config.source.path == ARABIC_PATH
+ assert config.source.path == os.path.abspath(tmp_path / "فاطمة.py")
async def test_install_reads_fastmcp_json(self, tmp_path: Path):
path = tmp_path / "fastmcp.json"
diff --git a/tests/cli/test_run_config.py b/tests/cli/test_run_config.py
index 8c0b089f8..0156fdbf6 100644
--- a/tests/cli/test_run_config.py
+++ b/tests/cli/test_run_config.py
@@ -59,8 +59,8 @@ def test_load_mcp_server_config(sample_config, monkeypatch):
assert isinstance(config.deployment, Deployment)
assert isinstance(config.environment, UVEnvironment)
- # Check source - path is not resolved yet, only during load_server
- assert config.source.path == "server.py"
+ # Source paths are anchored when the configuration is loaded.
+ assert config.source.path == os.path.abspath(sample_config.parent / "server.py")
assert config.source.entrypoint is None
# Check environment config
@@ -98,8 +98,8 @@ def test_load_config_with_entrypoint_source(tmp_path):
config = load_mcp_server_config(config_file)
- # Check source - path is not resolved yet, only during load_server
- assert config.source.path == "src/server.py"
+ # Source paths are anchored when the configuration is loaded.
+ assert config.source.path == os.path.abspath(tmp_path / "src/server.py")
assert config.source.entrypoint == "app"
# Check deployment
@@ -183,9 +183,9 @@ def test_load_minimal_config(tmp_path):
config = load_mcp_server_config(config_file)
- # Check we got source - path is not resolved yet, only during load_server
+ # Source paths are anchored when the configuration is loaded.
assert isinstance(config.source, FileSystemSource)
- assert config.source.path == "server.py"
+ assert config.source.path == os.path.abspath(tmp_path / "server.py")
def test_load_config_with_server_args(tmp_path):
@@ -266,8 +266,8 @@ def test_config_subset_independence(tmp_path):
config = load_mcp_server_config(config_file)
# Each subset should be independently usable
- # Path is not resolved yet, only during load_server
- assert config.source.path == "server.py"
+ # The source is usable independently of the caller working directory.
+ assert config.source.path == os.path.abspath(tmp_path / "server.py")
assert config.source.entrypoint is None
assert config.environment.python == "3.12"
@@ -347,3 +347,48 @@ def test_config_symlink_keeps_its_own_name(tmp_path, monkeypatch):
_, server_spec = load_and_merge_config("fastmcp.json")
assert Path(server_spec) == link
+
+
+def test_load_and_merge_config_anchors_paths_to_config_dir(tmp_path, monkeypatch):
+ """Relative source and requirements paths resolve beside fastmcp.json, not the cwd."""
+ config_dir = tmp_path / "project" / "config"
+ config_dir.mkdir(parents=True)
+ caller_dir = tmp_path / "caller"
+ caller_dir.mkdir()
+ config_file = config_dir / "fastmcp.json"
+ config_file.write_text(
+ json.dumps(
+ {
+ "source": {"path": "../src/server.py"},
+ "environment": {"requirements": "requirements.txt"},
+ }
+ )
+ )
+ monkeypatch.chdir(caller_dir)
+
+ config, _ = load_and_merge_config(os.path.relpath(config_file, caller_dir))
+
+ assert config.source.path == os.path.abspath(tmp_path / "project/src/server.py")
+ assert config.environment.requirements == config_dir / "requirements.txt"
+
+
+def test_symlinked_config_anchors_paths_beside_the_link(tmp_path, monkeypatch):
+ """A symlinked fastmcp.json resolves relative paths beside the link, not its target."""
+ shared = tmp_path / "shared"
+ shared.mkdir()
+ target = shared / "fastmcp.json"
+ target.write_text(json.dumps({"source": {"path": "server.py"}}))
+ project = tmp_path / "project"
+ project.mkdir()
+ link = project / "fastmcp.json"
+ try:
+ link.symlink_to(target)
+ except (OSError, NotImplementedError):
+ pytest.skip("symlinks are not available")
+ monkeypatch.chdir(tmp_path)
+
+ merged, _ = load_and_merge_config("project/fastmcp.json")
+ loaded = MCPServerConfig.from_file(Path("project/fastmcp.json"))
+
+ assert merged.source.path == os.path.abspath(project / "server.py")
+ assert loaded.source.path == os.path.abspath(project / "server.py")