Add Agent Plugins MCP config parsing (#36796)

## What changed

- Add `parse_agent_plugin_mcp_config` to translate Agent Plugins v1 `mcp.json` files into Codex MCP server configuration.
- Normalize `stdio` and streamable HTTP transports, including `PLUGIN_ROOT` and `PLUGIN_DATA` expansion, contained plugin paths, secure endpoint validation, and filtering of client-owned HTTP headers.
- Keep valid sibling servers when another server is invalid, while returning per-server parse errors.
- Preserve UTF-8 HTTP header values when forwarding streamable HTTP protocol headers.

## Testing

- Cover transport mapping, placeholder expansion, path containment, schema and field validation, per-server errors, platform-specific environment handling, and UTF-8 headers.

GitOrigin-RevId: ed4ab0fcf495afbb381ce48beb93989629444c56
This commit is contained in:
jacobzhou-oai authored and copyberry committed 2026-08-03 20:36:59 +00:00
1 parent 3149fa4b99
commit bd12b3a9ec
6 files changed
+1052 -1

No files matched your search

@@ -1,5 +1,6 @@
use super::PluginMcpConfigParseOutcome;
use super::PluginMcpServerParseError;
use super::parse_agent_plugin_mcp_config;
use super::parse_executor_plugin_mcp_config;
use super::parse_plugin_mcp_config;
use codex_config::DEFAULT_MCP_SERVER_ENVIRONMENT_ID;
@@ -25,6 +26,497 @@ fn plugin_root_uri(plugin_root: &Path) -> PathUri {
PathUri::from_host_native_path(plugin_root).expect("plugin root URI")
}
#[test]
fn agent_plugin_placeholder_expansion_is_single_pass() {
let plugin_root = plugin_root().join("${PLUGIN_DATA}");
let plugin_data_root = plugin_root
.parent()
.expect("plugin root parent")
.join("plugin-data");
let outcome = parse_agent_plugin_mcp_config(
&plugin_root,
&plugin_data_root,
r#"{
"$schema":"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers":{"demo":{
"type":"stdio",
"command":"python",
"args":["${PLUGIN_ROOT}:${PLUGIN_DATA}"]
}}
}"#,
)
.expect("parse Agent Plugins MCP config");
let McpServerTransportConfig::Stdio { args, .. } = &outcome.servers["demo"].transport else {
panic!("expected stdio transport");
};
assert_eq!(
args,
&vec![format!(
"{}:{}",
plugin_root.display(),
plugin_data_root.display()
)]
);
}
#[test]
fn agent_plugin_mcp_expands_reserved_paths_and_maps_transports() {
let plugin_root = plugin_root();
let plugin_data_root = plugin_root.parent().expect("parent").join("plugin-data");
let outcome = parse_agent_plugin_mcp_config(
&plugin_root,
&plugin_data_root,
r#"{
"$schema":"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"local": {
"type":"stdio",
"command":"python",
"args":["${PLUGIN_ROOT}/server.py", "${PLUGIN_DATA}/state.json"],
"env":{"CACHE":"${PLUGIN_DATA}/cache"},
"cwd":"${PLUGIN_ROOT}/scripts"
},
"remote": {
"type":"streamable-http",
"url":"https://example.com/mcp",
"headers":{"X-Plugin":"demo"}
}
}
}"#,
)
.expect("parse Agent Plugins MCP config");
assert!(outcome.errors.is_empty());
let local = outcome.servers.get("local").expect("local server");
let McpServerTransportConfig::Stdio { args, env, cwd, .. } = &local.transport else {
panic!("expected stdio transport");
};
assert_eq!(
args,
&vec![
format!("{}/server.py", plugin_root.display()),
format!("{}/state.json", plugin_data_root.display()),
]
);
assert_eq!(
env.as_ref().expect("environment").get("PLUGIN_ROOT"),
Some(&plugin_root.display().to_string())
);
assert_eq!(
env.as_ref().expect("environment").get("PLUGIN_DATA"),
Some(&plugin_data_root.display().to_string())
);
assert_eq!(
cwd.as_ref(),
Some(&LegacyAppPathString::from_path(
&plugin_root.join("scripts")
))
);
let remote = outcome.servers.get("remote").expect("remote server");
let McpServerTransportConfig::StreamableHttp { http_headers, .. } = &remote.transport else {
panic!("expected HTTP transport");
};
assert_eq!(
http_headers
.as_ref()
.and_then(|headers| headers.get("X-Plugin")),
Some(&"demo".to_string())
);
}
#[test]
fn agent_plugin_mcp_handles_portable_path_and_http_edge_cases() {
let plugin_root = plugin_root();
let plugin_data_root = plugin_root.parent().expect("parent").join("plugin-data");
let outcome = parse_agent_plugin_mcp_config(
&plugin_root,
&plugin_data_root,
r#"{
"$schema":"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"contained":{"type":"stdio","command":"./bin/../server","cwd":"${PLUGIN_ROOT}/work/../data"},
"redundant-separator":{"type":"stdio","command":".//bin/server"},
"root-slash":{"type":"stdio","command":"python","cwd":"${PLUGIN_ROOT}/"},
"data-slash":{"type":"stdio","command":"python","cwd":"${PLUGIN_DATA}/"},
"headers":{"type":"streamable-http","url":"https://example.com/mcp","headers":{"aUtHoRiZaTiOn":"public-package-value","Content-Length":"0","HOST":"other.example.com","Proxy-Authorization":"public-package-value","Transfer-Encoding":"chunked","uSeR-aGeNt":"plugin-agent/1.0","X-Plugin":"demo","X-Plugin-Name":"café"}},
"loopback":{"type":"streamable-http","url":"http://[::1]/mcp"}
}
}"#,
)
.expect("parse Agent Plugins MCP config");
assert!(outcome.errors.is_empty());
assert_eq!(
outcome.servers.keys().collect::<Vec<_>>(),
vec![
"contained",
"data-slash",
"headers",
"loopback",
"redundant-separator",
"root-slash"
]
);
let McpServerTransportConfig::Stdio { command, cwd, .. } =
&outcome.servers["contained"].transport
else {
panic!("expected stdio transport");
};
assert_eq!(command, &plugin_root.join("server").display().to_string());
assert_eq!(
cwd.as_ref(),
Some(&LegacyAppPathString::from_path(&plugin_root.join("data")))
);
let McpServerTransportConfig::Stdio { command, .. } =
&outcome.servers["redundant-separator"].transport
else {
panic!("expected stdio transport");
};
assert_eq!(
command,
&plugin_root.join("bin").join("server").display().to_string()
);
for (server_name, expected_cwd) in [
("root-slash", plugin_root.as_path()),
("data-slash", plugin_data_root.as_path()),
] {
let McpServerTransportConfig::Stdio { cwd, .. } = &outcome.servers[server_name].transport
else {
panic!("expected stdio transport");
};
assert_eq!(
cwd.as_ref(),
Some(&LegacyAppPathString::from_path(expected_cwd))
);
}
let McpServerTransportConfig::StreamableHttp { http_headers, .. } =
&outcome.servers["headers"].transport
else {
panic!("expected HTTP transport");
};
assert_eq!(
http_headers,
&Some(HashMap::from([
("X-Plugin".to_string(), "demo".to_string()),
("X-Plugin-Name".to_string(), "café".to_string()),
]))
);
}
#[test]
fn agent_plugin_mcp_skips_invalid_server_without_disabling_siblings() {
let plugin_root = plugin_root();
let outcome = parse_agent_plugin_mcp_config(
&plugin_root,
&plugin_root.join("data"),
r#"{
"$schema":"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"valid":{"type":"stdio","command":"python"},
"reserved":{"type":"stdio","command":"python","env":{"PLUGIN_ROOT":"bad"}}
}
}"#,
)
.expect("parse Agent Plugins MCP config");
assert_eq!(outcome.servers.keys().collect::<Vec<_>>(), vec!["valid"]);
assert_eq!(outcome.errors.len(), 1);
assert_eq!(outcome.errors[0].name, "reserved");
assert!(
outcome.errors[0]
.message
.contains("reserved variable `PLUGIN_ROOT`")
);
}
#[test]
fn agent_plugin_mcp_preserves_server_named_mcp_servers() {
let plugin_root = plugin_root();
let outcome = parse_agent_plugin_mcp_config(
&plugin_root,
&plugin_root.join("data"),
r#"{
"$schema":"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"mcpServers":{"type":"stdio","command":"first"},
"sibling":{"type":"stdio","command":"second"}
}
}"#,
)
.expect("parse Agent Plugins MCP config");
assert!(outcome.errors.is_empty());
assert_eq!(
outcome.servers.keys().collect::<Vec<_>>(),
vec!["mcpServers", "sibling"]
);
}
#[test]
fn agent_plugin_mcp_preserves_arbitrary_server_names() {
let plugin_root = plugin_root();
let outcome = parse_agent_plugin_mcp_config(
&plugin_root,
&plugin_root.join("data"),
r#"{
"$schema":"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers":{"agent.smoke / local":{"type":"stdio","command":"python"}}
}"#,
)
.expect("parse Agent Plugins MCP config");
assert!(outcome.errors.is_empty());
assert!(outcome.servers.contains_key("agent.smoke / local"));
}
#[test]
fn agent_plugin_mcp_rejects_explicit_null_optional_fields() {
let plugin_root = plugin_root();
let outcome = parse_agent_plugin_mcp_config(
&plugin_root,
&plugin_root.join("data"),
r#"{
"$schema":"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers":{
"cwd":{"type":"stdio","command":"python","cwd":null},
"headers":{"type":"streamable-http","url":"https://example.com/mcp","headers":null}
}
}"#,
)
.expect("parse Agent Plugins MCP config");
assert!(outcome.servers.is_empty());
assert_eq!(outcome.errors.len(), 2);
assert!(
outcome
.errors
.iter()
.any(|error| error.message.contains("`cwd`"))
);
assert!(
outcome
.errors
.iter()
.any(|error| error.message.contains("`headers`"))
);
}
#[cfg(windows)]
#[test]
fn agent_plugin_mcp_rejects_reserved_environment_aliases_case_insensitively() {
let plugin_root = plugin_root();
let outcome = parse_agent_plugin_mcp_config(
&plugin_root,
&plugin_root.join("data"),
r#"{
"$schema":"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers":{"reserved":{"type":"stdio","command":"python","env":{"plugin_root":"bad"}}}
}"#,
)
.expect("parse Agent Plugins MCP config");
assert!(outcome.servers.is_empty());
assert_eq!(outcome.errors.len(), 1);
}
#[cfg(windows)]
#[test]
fn agent_plugin_mcp_overlays_windows_environment_case_insensitively() {
let plugin_root = plugin_root();
let outcome = parse_agent_plugin_mcp_config(
&plugin_root,
&plugin_root.join("data"),
r#"{
"$schema":"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers":{
"configured":{"type":"stdio","command":"python","env":{"Path":"configured"}},
"duplicate":{"type":"stdio","command":"python","env":{"PATH":"one","Path":"two"}}
}
}"#,
)
.expect("parse Agent Plugins MCP config");
assert_eq!(
outcome.servers.keys().collect::<Vec<_>>(),
vec!["configured"]
);
assert_eq!(outcome.errors.len(), 1);
let McpServerTransportConfig::Stdio { env, .. } = &outcome.servers["configured"].transport
else {
panic!("expected stdio transport");
};
assert_eq!(
env.as_ref().and_then(|env| env.get("PATH")),
Some(&"configured".to_string())
);
}
#[cfg(unix)]
#[test]
fn agent_plugin_mcp_resolves_root_before_collapsing_parent_components() {
use std::os::unix::fs::symlink;
let temp = tempfile::tempdir().expect("temporary directory");
let base = temp.path().join("base");
let outside = temp.path().join("outside");
let outside_directory = outside.join("directory");
let resolved_plugin_root = outside.join("plugin");
let plugin_data_root = temp.path().join("plugin-data");
std::fs::create_dir_all(&base).expect("create base directory");
std::fs::create_dir_all(&outside_directory).expect("create symlink target");
std::fs::create_dir_all(&resolved_plugin_root).expect("create resolved plugin root");
std::fs::create_dir_all(&plugin_data_root).expect("create plugin data root");
let canonical_plugin_root = resolved_plugin_root
.canonicalize()
.expect("canonical plugin root");
symlink(&outside_directory, base.join("link")).expect("create root symlink");
let plugin_root = base.join("link/../plugin");
let outcome = parse_agent_plugin_mcp_config(
&plugin_root,
&plugin_data_root,
r#"{
"$schema":"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers":{"demo":{"type":"stdio","command":"python"}}
}"#,
)
.expect("parse Agent Plugins MCP config");
assert!(outcome.errors.is_empty());
let McpServerTransportConfig::Stdio { env, cwd, .. } = &outcome.servers["demo"].transport
else {
panic!("expected stdio transport");
};
assert_eq!(
env.as_ref().and_then(|env| env.get("PLUGIN_ROOT")),
Some(&canonical_plugin_root.display().to_string())
);
assert_eq!(
cwd.as_ref(),
Some(&LegacyAppPathString::from_path(&canonical_plugin_root))
);
}
#[cfg(unix)]
#[test]
fn agent_plugin_mcp_rejects_missing_descendant_below_escaping_symlink() {
use std::os::unix::fs::symlink;
let temp = tempfile::tempdir().expect("temporary directory");
let plugin_root = temp.path().join("plugin");
let plugin_data_root = temp.path().join("plugin-data");
let outside = temp.path().join("outside");
std::fs::create_dir_all(&plugin_root).expect("create plugin root");
std::fs::create_dir_all(&plugin_data_root).expect("create plugin data root");
std::fs::create_dir_all(&outside).expect("create outside directory");
symlink(&outside, plugin_root.join("link")).expect("create escaping symlink");
let outcome = parse_agent_plugin_mcp_config(
&plugin_root,
&plugin_data_root,
r#"{
"$schema":"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers":{"escape":{"type":"stdio","command":"./link/missing"}}
}"#,
)
.expect("parse Agent Plugins MCP config");
assert!(outcome.servers.is_empty());
assert_eq!(outcome.errors.len(), 1);
assert!(outcome.errors[0].message.contains("must remain within"));
}
#[test]
fn agent_plugin_mcp_enforces_closed_transport_and_path_semantics() {
let plugin_root = plugin_root();
let outcome = parse_agent_plugin_mcp_config(
&plugin_root,
&plugin_root.join("data"),
r#"{
"$schema":"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"valid":{"type":"stdio","command":"python"},
"command":{"type":"stdio","command":"../server"},
"escape":{"type":"stdio","command":"./../server"},
"cwd":{"type":"stdio","command":"python","cwd":"${PLUGIN_ROOT}/../outside"},
"backslash":{"type":"stdio","command":"./scripts\\..\\outside"},
"remote":{"type":"streamable-http","url":"http://example.com/mcp"},
"header":{"type":"streamable-http","url":"https://example.com/mcp","headers":{"X-Demo":"one","x-demo":"two"}},
"sse":{"type":"sse","url":"https://example.com/sse"},
"unknown":{"type":"stdio","command":"python","future":true}
}
}"#,
)
.expect("parse Agent Plugins MCP config");
assert_eq!(outcome.servers.keys().collect::<Vec<_>>(), vec!["valid"]);
assert_eq!(outcome.errors.len(), 8);
}
#[cfg(windows)]
#[test]
fn agent_plugin_mcp_rejects_drive_relative_windows_command() {
let plugin_root = plugin_root();
let outcome = parse_agent_plugin_mcp_config(
&plugin_root,
&plugin_root.join("data"),
r#"{"$schema":"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json","mcpServers":{"drive-relative":{"type":"stdio","command":"C:server.exe"}}}"#,
)
.expect("parse Agent Plugins MCP config");
assert!(outcome.servers.is_empty());
assert_eq!(outcome.errors.len(), 1);
}
#[test]
fn agent_plugin_mcp_treats_args_and_env_as_opaque_after_expansion() {
let plugin_root = plugin_root();
let data_root = plugin_root.join("data");
let outcome = parse_agent_plugin_mcp_config(
&plugin_root,
&data_root,
r#"{
"$schema":"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers":{"demo":{
"type":"stdio",
"command":"python",
"args":["${PLUGIN_ROOT}/../opaque"],
"env":{"OPAQUE":"${PLUGIN_DATA}/../opaque"}
}}
}"#,
)
.expect("parse Agent Plugins MCP config");
assert!(outcome.errors.is_empty());
let McpServerTransportConfig::Stdio { args, env, .. } = &outcome.servers["demo"].transport
else {
panic!("expected stdio transport");
};
assert_eq!(args, &vec![format!("{}/../opaque", plugin_root.display())]);
assert_eq!(
env.as_ref().and_then(|env| env.get("OPAQUE")),
Some(&format!("{}/../opaque", data_root.display()))
);
}
#[test]
fn agent_plugin_mcp_rejects_unsupported_schema() {
let plugin_root = plugin_root();
let error = parse_agent_plugin_mcp_config(
&plugin_root,
&plugin_root.join("data"),
r#"{"$schema":"https://agent-plugins.org/schemas/2.0.0/mcp.schema.json","mcpServers":{}}"#,
)
.expect_err("unsupported schema");
assert!(
error
.to_string()
.contains("unsupported Agent Plugins MCP schema")
);
}
fn stdio_server(
command: &str,
environment_id: &str,