Skip to content

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

Support npm_config_registry override in fastmcp dev apps (#5969)

Kumar Abhinandan8bd2df47951c
diff --git a/docs/apps/development.mdx b/docs/apps/development.mdx
index c81600b16..df7744032 100644
--- a/docs/apps/development.mdx
+++ b/docs/apps/development.mdx
@@ -59,6 +59,16 @@ fastmcp dev apps server.py:mcp --mcp-port 9000 --dev-port 9090 --no-reload
With `--host 0.0.0.0`, open the dev UI through `localhost` or an IP address. To reach it by hostname, pass that hostname to `--host`.
+### npm registry
+
+On first run, the dev server downloads the `@modelcontextprotocol/ext-apps` package from the public npm registry and caches it. If your network only allows an internal npm mirror, set `npm_config_registry` (or `NPM_CONFIG_REGISTRY`) to the mirror's URL, the same variable npm reads. When neither is set, or the value is empty, the dev server uses `https://registry.npmjs.org`. The mirror must serve the standard npm tarball layout.
+
+```bash
+npm_config_registry=https://npm.internal.example.com fastmcp dev apps server.py
+```
+
+This setting covers only the npm download. The dev UI also loads modules from `esm.sh`, and that host is not configurable.
+
## Multiple tools
If your server has multiple app tools, the picker shows a dropdown. Each tool gets its own form and launch button. The tool's `title` is displayed when available, falling back to the tool name.
diff --git a/fastmcp_slim/fastmcp/cli/apps_dev.py b/fastmcp_slim/fastmcp/cli/apps_dev.py
index 62e8e3f9e..8ad95463c 100644
--- a/fastmcp_slim/fastmcp/cli/apps_dev.py
+++ b/fastmcp_slim/fastmcp/cli/apps_dev.py
@@ -1146,6 +1146,22 @@ async def _read_mcp_resource(mcp_url: str, uri: str) -> str | None:
# app-bridge.js download, patch, and Zod import-map generation
# ---------------------------------------------------------------------------
+_DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org"
+
+
+def _npm_tarball_url(version: str) -> str:
+ """Return the ext-apps tarball URL, honoring ``npm_config_registry``."""
+ # npm itself sets and reads the lowercase name, so honor both spellings.
+ registry = (
+ os.environ.get("npm_config_registry") # noqa: SIM112
+ or os.environ.get("NPM_CONFIG_REGISTRY")
+ or _DEFAULT_NPM_REGISTRY
+ )
+ return (
+ f"{registry.rstrip('/')}/@modelcontextprotocol/ext-apps/-/"
+ f"ext-apps-{version}.tgz"
+ )
+
def _fetch_app_bridge_bundle_sync(
version: str,
@@ -1235,7 +1251,8 @@ def _fetch_app_bridge_bundle_sync(
app_bridge_js = app_bridge_cache.read_text(encoding="utf-8")
return app_bridge_js, import_map_json
- npm_url = f"https://registry.npmjs.org/@modelcontextprotocol/ext-apps/-/ext-apps-{version}.tgz"
+ npm_url = _npm_tarball_url(version)
+
with httpx2.Client(timeout=30.0) as client:
resp = client.get(npm_url, follow_redirects=True)
resp.raise_for_status()
diff --git a/tests/cli/test_apps_dev_server.py b/tests/cli/test_apps_dev_server.py
index 56b4bf4de..38f151b02 100644
--- a/tests/cli/test_apps_dev_server.py
+++ b/tests/cli/test_apps_dev_server.py
@@ -720,3 +720,56 @@ class TestSpawnedServer:
env = spawn.call_args.kwargs["env"]
assert env["FASTMCP_HTTP_HOST_ORIGIN_PROTECTION"] == "true"
+
+
+class TestNpmRegistry:
+ @pytest.fixture(autouse=True)
+ def _clear_registry_env(self, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.delenv("npm_config_registry", raising=False)
+ monkeypatch.delenv("NPM_CONFIG_REGISTRY", raising=False)
+
+ def test_default_registry_is_public_npm(self):
+ url = apps_dev._npm_tarball_url("1.0.0")
+
+ assert url == (
+ "https://registry.npmjs.org/@modelcontextprotocol/ext-apps/-/"
+ "ext-apps-1.0.0.tgz"
+ )
+
+ def test_registry_can_be_overridden(self, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("npm_config_registry", "https://npm.example.com")
+
+ url = apps_dev._npm_tarball_url("1.0.0")
+
+ assert url.startswith("https://npm.example.com/@modelcontextprotocol/")
+
+ def test_uppercase_registry_is_honored(self, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("NPM_CONFIG_REGISTRY", "https://npm.example.com")
+
+ url = apps_dev._npm_tarball_url("1.0.0")
+
+ assert url.startswith("https://npm.example.com/@modelcontextprotocol/")
+
+ def test_empty_registry_falls_back_to_public_npm(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ monkeypatch.setenv("npm_config_registry", "")
+
+ url = apps_dev._npm_tarball_url("1.0.0")
+
+ assert url.startswith("https://registry.npmjs.org/@modelcontextprotocol/")
+
+ @pytest.mark.parametrize(
+ "registry",
+ ["https://npm.example.com/", "https://npm.example.com//"],
+ ids=["one_slash", "two_slashes"],
+ )
+ def test_trailing_slashes_are_ignored(
+ self, monkeypatch: pytest.MonkeyPatch, registry: str
+ ):
+ monkeypatch.setenv("npm_config_registry", registry)
+
+ url = apps_dev._npm_tarball_url("1.0.0")
+
+ assert url.startswith("https://npm.example.com/@modelcontextprotocol/")
+ assert "//@modelcontextprotocol" not in url