initial mcp add interface (#3543)

Adds `codex mcp add`, `codex mcp list`, `codex mcp remove`. Currently writes to global config.
2025-09-14 21:30:56 -07:00
parent a797051921
commit 6a8e743d57
9 changed files with 849 additions and 5 deletions
--- a/codex-rs/cli/src/main.rs
+++ b/codex-rs/cli/src/main.rs
@@ -17,6 +17,9 @@ use codex_exec::Cli as ExecCli;
 use codex_tui::Cli as TuiCli;
 use std::path::PathBuf;

+mod mcp_cmd;
+
+use crate::mcp_cmd::McpCli;
 use crate::proto::ProtoCli;

 /// Codex CLI
@@ -56,8 +59,8 @@ enum Subcommand {
    /// Remove stored authentication credentials.
    Logout(LogoutCommand),

-    /// Experimental: run Codex as an MCP server.
-    Mcp,
+    /// [experimental] Run Codex as an MCP server and manage MCP servers.
+    Mcp(McpCli),

    /// Run the Protocol stream via stdin/stdout
    #[clap(visible_alias = "p")]
@@ -182,9 +185,10 @@ async fn cli_main(codex_linux_sandbox_exe: Option<PathBuf>) -> anyhow::Result<()
            );
            codex_exec::run_main(exec_cli, codex_linux_sandbox_exe).await?;
        }
-        Some(Subcommand::Mcp) => {
-            codex_mcp_server::run_main(codex_linux_sandbox_exe, root_config_overrides.clone())
-                .await?;
+        Some(Subcommand::Mcp(mut mcp_cli)) => {
+            // Propagate any root-level config overrides (e.g. `-c key=value`).
+            prepend_config_flags(&mut mcp_cli.config_overrides, root_config_overrides.clone());
+            mcp_cli.run(codex_linux_sandbox_exe).await?;
        }
        Some(Subcommand::Resume(ResumeCommand { session_id, last })) => {
            // Start with the parsed interactive CLI so resume shares the same
--- a/codex-rs/cli/src/mcp_cmd.rs
+++ b/codex-rs/cli/src/mcp_cmd.rs
@@ -0,0 +1,370 @@
+use std::collections::BTreeMap;
+use std::collections::HashMap;
+use std::path::PathBuf;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+use anyhow::bail;
+use codex_common::CliConfigOverrides;
+use codex_core::config::Config;
+use codex_core::config::ConfigOverrides;
+use codex_core::config::find_codex_home;
+use codex_core::config::load_global_mcp_servers;
+use codex_core::config::write_global_mcp_servers;
+use codex_core::config_types::McpServerConfig;
+
+/// [experimental] Launch Codex as an MCP server or manage configured MCP servers.
+///
+/// Subcommands:
+/// - `serve`  — run the MCP server on stdio
+/// - `list`   — list configured servers (with `--json`)
+/// - `get`    — show a single server (with `--json`)
+/// - `add`    — add a server launcher entry to `~/.codex/config.toml`
+/// - `remove` — delete a server entry
+#[derive(Debug, clap::Parser)]
+pub struct McpCli {
+    #[clap(flatten)]
+    pub config_overrides: CliConfigOverrides,
+
+    #[command(subcommand)]
+    pub cmd: Option<McpSubcommand>,
+}
+
+#[derive(Debug, clap::Subcommand)]
+pub enum McpSubcommand {
+    /// [experimental] Run the Codex MCP server (stdio transport).
+    Serve,
+
+    /// [experimental] List configured MCP servers.
+    List(ListArgs),
+
+    /// [experimental] Show details for a configured MCP server.
+    Get(GetArgs),
+
+    /// [experimental] Add a global MCP server entry.
+    Add(AddArgs),
+
+    /// [experimental] Remove a global MCP server entry.
+    Remove(RemoveArgs),
+}
+
+#[derive(Debug, clap::Parser)]
+pub struct ListArgs {
+    /// Output the configured servers as JSON.
+    #[arg(long)]
+    pub json: bool,
+}
+
+#[derive(Debug, clap::Parser)]
+pub struct GetArgs {
+    /// Name of the MCP server to display.
+    pub name: String,
+
+    /// Output the server configuration as JSON.
+    #[arg(long)]
+    pub json: bool,
+}
+
+#[derive(Debug, clap::Parser)]
+pub struct AddArgs {
+    /// Name for the MCP server configuration.
+    pub name: String,
+
+    /// Environment variables to set when launching the server.
+    #[arg(long, value_parser = parse_env_pair, value_name = "KEY=VALUE")]
+    pub env: Vec<(String, String)>,
+
+    /// Command to launch the MCP server.
+    #[arg(trailing_var_arg = true, num_args = 1..)]
+    pub command: Vec<String>,
+}
+
+#[derive(Debug, clap::Parser)]
+pub struct RemoveArgs {
+    /// Name of the MCP server configuration to remove.
+    pub name: String,
+}
+
+impl McpCli {
+    pub async fn run(self, codex_linux_sandbox_exe: Option<PathBuf>) -> Result<()> {
+        let McpCli {
+            config_overrides,
+            cmd,
+        } = self;
+        let subcommand = cmd.unwrap_or(McpSubcommand::Serve);
+
+        match subcommand {
+            McpSubcommand::Serve => {
+                codex_mcp_server::run_main(codex_linux_sandbox_exe, config_overrides).await?;
+            }
+            McpSubcommand::List(args) => {
+                run_list(&config_overrides, args)?;
+            }
+            McpSubcommand::Get(args) => {
+                run_get(&config_overrides, args)?;
+            }
+            McpSubcommand::Add(args) => {
+                run_add(&config_overrides, args)?;
+            }
+            McpSubcommand::Remove(args) => {
+                run_remove(&config_overrides, args)?;
+            }
+        }
+
+        Ok(())
+    }
+}
+
+fn run_add(config_overrides: &CliConfigOverrides, add_args: AddArgs) -> Result<()> {
+    // Validate any provided overrides even though they are not currently applied.
+    config_overrides.parse_overrides().map_err(|e| anyhow!(e))?;
+
+    let AddArgs { name, env, command } = add_args;
+
+    validate_server_name(&name)?;
+
+    let mut command_parts = command.into_iter();
+    let command_bin = command_parts
+        .next()
+        .ok_or_else(|| anyhow!("command is required"))?;
+    let command_args: Vec<String> = command_parts.collect();
+
+    let env_map = if env.is_empty() {
+        None
+    } else {
+        let mut map = HashMap::new();
+        for (key, value) in env {
+            map.insert(key, value);
+        }
+        Some(map)
+    };
+
+    let codex_home = find_codex_home().context("failed to resolve CODEX_HOME")?;
+    let mut servers = load_global_mcp_servers(&codex_home)
+        .with_context(|| format!("failed to load MCP servers from {}", codex_home.display()))?;
+
+    let new_entry = McpServerConfig {
+        command: command_bin,
+        args: command_args,
+        env: env_map,
+        startup_timeout_ms: None,
+    };
+
+    servers.insert(name.clone(), new_entry);
+
+    write_global_mcp_servers(&codex_home, &servers)
+        .with_context(|| format!("failed to write MCP servers to {}", codex_home.display()))?;
+
+    println!("Added global MCP server '{name}'.");
+
+    Ok(())
+}
+
+fn run_remove(config_overrides: &CliConfigOverrides, remove_args: RemoveArgs) -> Result<()> {
+    config_overrides.parse_overrides().map_err(|e| anyhow!(e))?;
+
+    let RemoveArgs { name } = remove_args;
+
+    validate_server_name(&name)?;
+
+    let codex_home = find_codex_home().context("failed to resolve CODEX_HOME")?;
+    let mut servers = load_global_mcp_servers(&codex_home)
+        .with_context(|| format!("failed to load MCP servers from {}", codex_home.display()))?;
+
+    let removed = servers.remove(&name).is_some();
+
+    if removed {
+        write_global_mcp_servers(&codex_home, &servers)
+            .with_context(|| format!("failed to write MCP servers to {}", codex_home.display()))?;
+    }
+
+    if removed {
+        println!("Removed global MCP server '{name}'.");
+    } else {
+        println!("No MCP server named '{name}' found.");
+    }
+
+    Ok(())
+}
+
+fn run_list(config_overrides: &CliConfigOverrides, list_args: ListArgs) -> Result<()> {
+    let overrides = config_overrides.parse_overrides().map_err(|e| anyhow!(e))?;
+    let config = Config::load_with_cli_overrides(overrides, ConfigOverrides::default())
+        .context("failed to load configuration")?;
+
+    let mut entries: Vec<_> = config.mcp_servers.iter().collect();
+    entries.sort_by(|(a, _), (b, _)| a.cmp(b));
+
+    if list_args.json {
+        let json_entries: Vec<_> = entries
+            .into_iter()
+            .map(|(name, cfg)| {
+                let env = cfg.env.as_ref().map(|env| {
+                    env.iter()
+                        .map(|(k, v)| (k.clone(), v.clone()))
+                        .collect::<BTreeMap<_, _>>()
+                });
+                serde_json::json!({
+                    "name": name,
+                    "command": cfg.command,
+                    "args": cfg.args,
+                    "env": env,
+                    "startup_timeout_ms": cfg.startup_timeout_ms,
+                })
+            })
+            .collect();
+        let output = serde_json::to_string_pretty(&json_entries)?;
+        println!("{output}");
+        return Ok(());
+    }
+
+    if entries.is_empty() {
+        println!("No MCP servers configured yet. Try `codex mcp add my-tool -- my-command`.");
+        return Ok(());
+    }
+
+    let mut rows: Vec<[String; 4]> = Vec::new();
+    for (name, cfg) in entries {
+        let args = if cfg.args.is_empty() {
+            "-".to_string()
+        } else {
+            cfg.args.join(" ")
+        };
+
+        let env = match cfg.env.as_ref() {
+            None => "-".to_string(),
+            Some(map) if map.is_empty() => "-".to_string(),
+            Some(map) => {
+                let mut pairs: Vec<_> = map.iter().collect();
+                pairs.sort_by(|(a, _), (b, _)| a.cmp(b));
+                pairs
+                    .into_iter()
+                    .map(|(k, v)| format!("{k}={v}"))
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            }
+        };
+
+        rows.push([name.clone(), cfg.command.clone(), args, env]);
+    }
+
+    let mut widths = ["Name".len(), "Command".len(), "Args".len(), "Env".len()];
+    for row in &rows {
+        for (i, cell) in row.iter().enumerate() {
+            widths[i] = widths[i].max(cell.len());
+        }
+    }
+
+    println!(
+        "{:<name_w$}  {:<cmd_w$}  {:<args_w$}  {:<env_w$}",
+        "Name",
+        "Command",
+        "Args",
+        "Env",
+        name_w = widths[0],
+        cmd_w = widths[1],
+        args_w = widths[2],
+        env_w = widths[3],
+    );
+
+    for row in rows {
+        println!(
+            "{:<name_w$}  {:<cmd_w$}  {:<args_w$}  {:<env_w$}",
+            row[0],
+            row[1],
+            row[2],
+            row[3],
+            name_w = widths[0],
+            cmd_w = widths[1],
+            args_w = widths[2],
+            env_w = widths[3],
+        );
+    }
+
+    Ok(())
+}
+
+fn run_get(config_overrides: &CliConfigOverrides, get_args: GetArgs) -> Result<()> {
+    let overrides = config_overrides.parse_overrides().map_err(|e| anyhow!(e))?;
+    let config = Config::load_with_cli_overrides(overrides, ConfigOverrides::default())
+        .context("failed to load configuration")?;
+
+    let Some(server) = config.mcp_servers.get(&get_args.name) else {
+        bail!("No MCP server named '{name}' found.", name = get_args.name);
+    };
+
+    if get_args.json {
+        let env = server.env.as_ref().map(|env| {
+            env.iter()
+                .map(|(k, v)| (k.clone(), v.clone()))
+                .collect::<BTreeMap<_, _>>()
+        });
+        let output = serde_json::to_string_pretty(&serde_json::json!({
+            "name": get_args.name,
+            "command": server.command,
+            "args": server.args,
+            "env": env,
+            "startup_timeout_ms": server.startup_timeout_ms,
+        }))?;
+        println!("{output}");
+        return Ok(());
+    }
+
+    println!("{}", get_args.name);
+    println!("  command: {}", server.command);
+    let args = if server.args.is_empty() {
+        "-".to_string()
+    } else {
+        server.args.join(" ")
+    };
+    println!("  args: {args}");
+    let env_display = match server.env.as_ref() {
+        None => "-".to_string(),
+        Some(map) if map.is_empty() => "-".to_string(),
+        Some(map) => {
+            let mut pairs: Vec<_> = map.iter().collect();
+            pairs.sort_by(|(a, _), (b, _)| a.cmp(b));
+            pairs
+                .into_iter()
+                .map(|(k, v)| format!("{k}={v}"))
+                .collect::<Vec<_>>()
+                .join(", ")
+        }
+    };
+    println!("  env: {env_display}");
+    if let Some(timeout) = server.startup_timeout_ms {
+        println!("  startup_timeout_ms: {timeout}");
+    }
+    println!("  remove: codex mcp remove {}", get_args.name);
+
+    Ok(())
+}
+
+fn parse_env_pair(raw: &str) -> Result<(String, String), String> {
+    let mut parts = raw.splitn(2, '=');
+    let key = parts
+        .next()
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .ok_or_else(|| "environment entries must be in KEY=VALUE form".to_string())?;
+    let value = parts
+        .next()
+        .map(str::to_string)
+        .ok_or_else(|| "environment entries must be in KEY=VALUE form".to_string())?;
+
+    Ok((key.to_string(), value))
+}
+
+fn validate_server_name(name: &str) -> Result<()> {
+    let is_valid = !name.is_empty()
+        && name
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_');
+
+    if is_valid {
+        Ok(())
+    } else {
+        bail!("invalid server name '{name}' (use letters, numbers, '-', '_')");
+    }
+}