Skip to content

Build and run agents you can see, understand and trust.

fix(hub): preserve GitHub MCP environment inputs (#2230)

Ziyang Guo41db2106533f
diff --git a/examples/web_ui/frontend/src/components/dialog/InstallMCPDialog.tsx b/examples/web_ui/frontend/src/components/dialog/InstallMCPDialog.tsx
index 2ff882133..3bba34059 100644
--- a/examples/web_ui/frontend/src/components/dialog/InstallMCPDialog.tsx
+++ b/examples/web_ui/frontend/src/components/dialog/InstallMCPDialog.tsx
@@ -52,7 +52,9 @@ export function InstallMCPDialog({ card, editing, onOpenChange, onInstalled }: P
useEffect(() => {
if (!card) return;
setName(editing?.name ?? card.name);
- setValues(defaultValuesFromSchema(card.inputs_schema as JSONSchema, new Set()));
+ setValues(
+ editing ? {} : defaultValuesFromSchema(card.inputs_schema as JSONSchema, new Set()),
+ );
setError(null);
}, [card, editing]);
diff --git a/src/agentscope/app/_service/_mcp_render.py b/src/agentscope/app/_service/_mcp_render.py
index 088476d87..18b033b3b 100644
--- a/src/agentscope/app/_service/_mcp_render.py
+++ b/src/agentscope/app/_service/_mcp_render.py
@@ -18,6 +18,42 @@ class MCPRenderError(ValueError):
"""
+def _effective_values(schema: dict, values: dict) -> dict:
+ """Overlay submitted values on defaults declared by the input schema."""
+ effective = {
+ name: prop["default"]
+ for name, prop in schema.get("properties", {}).items()
+ if isinstance(prop, dict) and "default" in prop
+ }
+ effective.update(values)
+ return effective
+
+
+def _omit_unfilled_optional_env(
+ config: dict,
+ values: dict,
+ declared: set[str],
+ required: set[str],
+) -> None:
+ """Drop env entries whose optional inputs were not supplied.
+
+ Optional placeholders elsewhere remain errors: omitting a URL or an
+ argument can change the meaning of a config. Environment entries are
+ independent, so leaving one unset means not exporting that variable.
+ """
+ env = config.get("env")
+ if not isinstance(env, dict):
+ return
+
+ optional = declared - required
+ for key, value in list(env.items()):
+ if not isinstance(value, str):
+ continue
+ identifiers = set(Template(value).get_identifiers())
+ if (identifiers & optional) - values.keys():
+ del env[key]
+
+
def _substitute(
node: Any,
values: dict,
@@ -89,6 +125,7 @@ def render_mcp(
declared placeholder unfilled, or produce a config the
client rejects.
"""
+ values = _effective_values(card.inputs_schema, values)
try:
jsonschema.validate(values, card.inputs_schema)
except jsonschema.ValidationError as e:
@@ -97,9 +134,17 @@ def render_mcp(
) from e
declared = set(card.inputs_schema.get("properties", {}))
+ required = set(card.inputs_schema.get("required", []))
missing: set[str] = set()
+ config_template = card.config_template.model_dump(mode="json")
+ _omit_unfilled_optional_env(
+ config_template,
+ values,
+ declared,
+ required,
+ )
config = _substitute(
- card.config_template.model_dump(mode="json"),
+ config_template,
values,
declared,
missing,
diff --git a/src/agentscope/app/hub/_mcp/_github_hub.py b/src/agentscope/app/hub/_mcp/_github_hub.py
index 9edff93b3..1ea1cb76b 100644
--- a/src/agentscope/app/hub/_mcp/_github_hub.py
+++ b/src/agentscope/app/hub/_mcp/_github_hub.py
@@ -62,6 +62,42 @@ def _substitute(value: Any) -> Any:
return value
+def _input_property(name: str, spec: dict) -> dict:
+ """Convert one registry variable definition to JSON Schema."""
+ prop: dict = {
+ "type": "string",
+ "title": name,
+ "description": spec.get("description") or "",
+ }
+ if spec.get("is_secret"):
+ prop["writeOnly"] = True
+ prop["format"] = "password"
+ if spec.get("choices"):
+ prop["enum"] = [str(choice) for choice in spec["choices"]]
+ if spec.get("default") is not None:
+ prop["default"] = str(spec["default"])
+ return prop
+
+
+def _inputs_schema(inputs: dict[str, dict]) -> dict:
+ """Build the install form schema for registry variables."""
+ if not inputs:
+ return {}
+
+ schema: dict = {
+ "type": "object",
+ "properties": {
+ name: _input_property(name, spec) for name, spec in inputs.items()
+ },
+ }
+ required = sorted(
+ name for name, spec in inputs.items() if spec.get("is_required")
+ )
+ if required:
+ schema["required"] = required
+ return schema
+
+
class GitHubMCPHub(MCPHubBase):
"""An MCP hub backed by GitHub's MCP registry.
@@ -180,10 +216,10 @@ class GitHubMCPHub(MCPHubBase):
Returns:
`tuple[dict, dict]`:
- The config template and the ``{name: description}`` of
- the secrets it references.
+ The config template and registry definitions of the
+ install inputs it references.
"""
- secrets: dict[str, str] = {}
+ inputs: dict[str, dict] = {}
headers = {}
for header in remote.get("headers") or []:
value = header.get("value") or ""
@@ -192,12 +228,16 @@ class GitHubMCPHub(MCPHubBase):
key = header.get("name") or "Authorization"
headers[key] = _substitute(value)
for match in _PLACEHOLDER.finditer(value):
- secrets[match.group(1)] = header.get("description") or ""
+ inputs[match.group(1)] = {
+ "description": header.get("description") or "",
+ "is_required": True,
+ "is_secret": header.get("is_secret", True),
+ }
config: dict = {"type": "http_mcp", "url": remote["url"]}
if headers:
config["headers"] = headers
- return config, secrets
+ return config, inputs
@staticmethod
def _from_package(package: dict) -> tuple[dict, dict] | None:
@@ -209,8 +249,9 @@ class GitHubMCPHub(MCPHubBase):
Returns:
`tuple[dict, dict] | None`:
- The config template and its secrets, or ``None`` when the
- registry does not say how to run the package.
+ The config template and registry definitions of its
+ install inputs, or ``None`` when the registry does not
+ say how to run the package.
"""
runtime = package.get("runtime_hint")
if runtime not in _RUNTIMES:
@@ -223,14 +264,28 @@ class GitHubMCPHub(MCPHubBase):
spec = f"{name}@{version}" if version and runtime == "npx" else name
env = {}
- secrets: dict[str, str] = {}
+ inputs: dict[str, dict] = {}
for variable in package.get("environment_variables") or []:
key = variable.get("name")
if not key:
continue
- env[key] = f"${{{key}}}"
- if variable.get("is_secret"):
- secrets[key] = variable.get("description") or ""
+
+ nested = variable.get("variables")
+ value = variable.get("value")
+ if isinstance(nested, dict):
+ env[key] = str(_substitute(value or ""))
+ inputs.update(
+ {
+ input_name: input_spec
+ for input_name, input_spec in nested.items()
+ if isinstance(input_spec, dict)
+ },
+ )
+ elif value is not None:
+ env[key] = str(value)
+ else:
+ env[key] = f"${{{key}}}"
+ inputs[key] = variable
config: dict = {
"type": "stdio_mcp",
@@ -239,7 +294,7 @@ class GitHubMCPHub(MCPHubBase):
}
if env:
config["env"] = env
- return config, secrets
+ return config, inputs
def _to_card(self, entry: dict, readme: bool = False) -> MCPCard | None:
"""Build a card from one registry entry.
@@ -273,23 +328,8 @@ class GitHubMCPHub(MCPHubBase):
if built is None:
return None
- config, secrets = built
- inputs_schema: dict = {}
- if secrets:
- inputs_schema = {
- "type": "object",
- "properties": {
- key: {
- "type": "string",
- "title": key,
- "description": description,
- "writeOnly": True,
- "format": "password",
- }
- for key, description in secrets.items()
- },
- "required": sorted(secrets),
- }
+ config, inputs = built
+ inputs_schema = _inputs_schema(inputs)
name = server.get("name") or ""
owner = name.rsplit("/", 1)[0] if "/" in name else None
@@ -333,7 +373,7 @@ class GitHubMCPHub(MCPHubBase):
else None,
# STDIO servers must be stateful — the process is the session.
is_stateful=config["type"] == "stdio_mcp",
- auth="inputs" if secrets else "none",
+ auth="inputs" if inputs else "none",
inputs_schema=inputs_schema,
config_template=config, # type: ignore[arg-type]
)
diff --git a/tests/hub_github_test.py b/tests/hub_github_test.py
index 5962baca0..94bfcbb81 100644
--- a/tests/hub_github_test.py
+++ b/tests/hub_github_test.py
@@ -89,7 +89,11 @@ class GitHubCardTest(TestCase):
"name": "pkg",
"runtime_hint": "uvx",
"environment_variables": [
- {"name": "API_KEY", "is_secret": True},
+ {
+ "name": "API_KEY",
+ "is_required": True,
+ "is_secret": True,
+ },
],
},
],
@@ -99,6 +103,123 @@ class GitHubCardTest(TestCase):
self.assertIn("API_KEY", card.inputs_schema["properties"])
self.assertEqual(card.config_template.env["API_KEY"], "${API_KEY}")
+ def test_required_non_secret_env_var_becomes_an_input(self) -> None:
+ """Required configuration is collected even when it is not secret."""
+ card = self._card(
+ {
+ "packages": [
+ {
+ "name": "pkg",
+ "runtime_hint": "uvx",
+ "environment_variables": [
+ {
+ "name": "DT_ENVIRONMENT",
+ "description": "Dynatrace URL",
+ "is_required": True,
+ },
+ ],
+ },
+ ],
+ },
+ )
+
+ prop = card.inputs_schema["properties"]["DT_ENVIRONMENT"]
+ self.assertFalse(prop.get("writeOnly", False))
+ self.assertIn("DT_ENVIRONMENT", card.inputs_schema["required"])
+ client = render_mcp(card, {"DT_ENVIRONMENT": "https://example.com"})
+ self.assertEqual(
+ client.mcp_config.env["DT_ENVIRONMENT"],
+ "https://example.com",
+ )
+
+ def test_default_env_input_is_rendered_when_omitted(self) -> None:
+ """Registry defaults become effective values for API callers."""
+ card = self._card(
+ {
+ "packages": [
+ {
+ "name": "pkg",
+ "runtime_hint": "uvx",
+ "environment_variables": [
+ {
+ "name": "MODE",
+ "default": "safe",
+ },
+ ],
+ },
+ ],
+ },
+ )
+
+ prop = card.inputs_schema["properties"]["MODE"]
+ self.assertEqual(prop["default"], "safe")
+ client = render_mcp(card, {})
+ self.assertEqual(client.mcp_config.env["MODE"], "safe")
+
+ def test_nested_env_template_uses_declared_input(self) -> None:
+ """Registry ``value`` templates name inputs independently of env."""
+ card = self._card(
+ {
+ "packages": [
+ {
+ "name": "firecrawl-mcp",
+ "runtime_hint": "npx",
+ "environment_variables": [
+ {
+ "name": "FIRECRAWL_API_KEY",
+ "value": "{api_key}",
+ "variables": {
+ "api_key": {
+ "description": "your API key",
+ "is_required": True,
+ "is_secret": True,
+ },
+ },
+ },
+ ],
+ },
+ ],
+ },
+ )
+
+ self.assertEqual(
+ card.config_template.env["FIRECRAWL_API_KEY"],
+ "${api_key}",
+ )
+ self.assertTrue(
+ card.inputs_schema["properties"]["api_key"]["writeOnly"],
+ )
+ client = render_mcp(card, {"api_key": "fc-secret"})
+ self.assertEqual(
+ client.mcp_config.env["FIRECRAWL_API_KEY"],
+ "fc-secret",
+ )
+
+ def test_literal_env_value_is_preserved(self) -> None:
+ """A registry-provided value is a literal, not an install input."""
+ card = self._card(
+ {
+ "packages": [
+ {
+ "name": "sendmux-mcp",
+ "runtime_hint": "uvx",
+ "environment_variables": [
+ {
+ "name": "SENDMUX_MCP_SURFACES",
+ "value": "mailbox,management,sending",
+ "is_required": True,
+ },
+ ],
+ },
+ ],
+ },
+ )
+
+ self.assertEqual(
+ card.config_template.env["SENDMUX_MCP_SURFACES"],
+ "mailbox,management,sending",
+ )
+
def test_unrunnable_package_is_skipped(self) -> None:
"""Around a third of the catalog names a package without saying
how to run it; listing it would offer an install that cannot
diff --git a/tests/hub_router_test.py b/tests/hub_router_test.py
index 2d1fe5e29..d04f4db4c 100644
--- a/tests/hub_router_test.py
+++ b/tests/hub_router_test.py
@@ -94,6 +94,36 @@ class FakeMCPHub(MCPHubBase):
"headers": {"Authorization": "Bearer ${api_key}"},
},
),
+ "gitlab": MCPCard(
+ hub_id="fake",
+ name="gitlab",
+ auth="inputs",
+ is_stateful=True,
+ inputs_schema={
+ "type": "object",
+ "properties": {
+ "api_key": {
+ "type": "string",
+ "writeOnly": True,
+ "format": "password",
+ },
+ "base_url": {
+ "type": "string",
+ "default": "https://gitlab.com/api/v4",
+ },
+ },
+ "required": ["api_key"],
+ },
+ config_template={
+ "type": "stdio_mcp",
+ "command": "uvx",
+ "args": ["gitlab-mcp"],
+ "env": {
+ "GITLAB_TOKEN": "${api_key}",
+ "GITLAB_API_URL": "${base_url}",
+ },
+ },
+ ),
}
async def list_mcps(
@@ -243,7 +273,7 @@ class HubRouterTest(IsolatedAsyncioTestCase):
).json()
names = [c["name"] for c in body["cards"]]
- self.assertEqual(sorted(names), ["echo", "notion", "tagged"])
+ self.assertEqual(sorted(names), ["echo", "gitlab", "notion", "tagged"])
notion = next(c for c in body["cards"] if c["name"] == "notion")
prop = notion["inputs_schema"]["properties"]["api_key"]
self.assertTrue(prop["writeOnly"])
@@ -438,6 +468,38 @@ class HubRouterTest(IsolatedAsyncioTestCase):
self.assertEqual(record.values, {"api_key": "old"})
self.assertEqual(record.client.name, "notion-2")
+ async def test_rekey_preserves_custom_non_secret_value(self) -> None:
+ """Editing one input must not replace another with its schema
+ default."""
+ mcp_id = self._install_mcp(
+ "gitlab",
+ values={
+ "api_key": "old",
+ "base_url": "https://gitlab.internal/api/v4",
+ },
+ ).json()["id"]
+
+ response = self._client.patch(
+ f"/mcp/{mcp_id}",
+ json={"values": {"api_key": "new"}},
+ headers=HEADERS,
+ )
+
+ self.assertEqual(response.status_code, 200)
+ storage = self._client.app.state.storage
+ record = await storage.get_mcp("alice", mcp_id)
+ self.assertEqual(
+ record.values,
+ {
+ "api_key": "new",
+ "base_url": "https://gitlab.internal/api/v4",
+ },
+ )
+ self.assertEqual(
+ record.client.mcp_config.env["GITLAB_API_URL"],
+ "https://gitlab.internal/api/v4",
+ )
+
def test_rename_keeps_the_config(self) -> None:
"""Renaming touches the name, not the rendered config."""
mcp_id = self._install_mcp("echo").json()["id"]
diff --git a/tests/service_mcp_render_test.py b/tests/service_mcp_render_test.py
index 4b6b4b2e2..50736e8f2 100644
--- a/tests/service_mcp_render_test.py
+++ b/tests/service_mcp_render_test.py
@@ -165,6 +165,55 @@ class MCPRenderTest(TestCase):
self.assertIn("region", str(ctx.exception))
+ def test_missing_optional_env_is_omitted(self) -> None:
+ """An unfilled optional env input is not launched as a placeholder."""
+ card = MCPCard(
+ hub_id="testhub",
+ name="local",
+ inputs_schema={
+ "type": "object",
+ "properties": {"region": {"type": "string"}},
+ },
+ config_template={
+ "type": "stdio_mcp",
+ "command": "uvx",
+ "args": ["server"],
+ "env": {"REGION": "${region}"},
+ },
+ )
+
+ client = render_mcp(card, {})
+
+ self.assertEqual(client.mcp_config.env, {})
+
+ def test_schema_default_fills_omitted_env_input(self) -> None:
+ """API callers inherit schema defaults without submitting them."""
+ card = MCPCard(
+ hub_id="testhub",
+ name="local",
+ inputs_schema={
+ "type": "object",
+ "properties": {
+ "mode": {
+ "type": "string",
+ "default": "safe",
+ },
+ },
+ },
+ config_template={
+ "type": "stdio_mcp",
+ "command": "uvx",
+ "args": ["server"],
+ "env": {"MODE": "${mode}"},
+ },
+ )
+ submitted: dict = {}
+
+ client = render_mcp(card, submitted)
+
+ self.assertEqual(client.mcp_config.env, {"MODE": "safe"})
+ self.assertEqual(submitted, {})
+
def test_no_inputs_card(self) -> None:
"""A card with no inputs renders as-is."""
card = MCPCard(