Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
269 KB
Raw Blame
//! `ai-memory install-mcp` — print the MCP server registration
//! snippet for any supported client.
//!
//! The snippet format and the config-file location differ across
//! clients. We render the *content* the user needs to paste; we
//! deliberately do not auto-edit their config (formats are evolving
//! upstream and a bad merge is very user-visible).
//!
//! For clients that don't support remote MCP servers in their JSON
//! config (Claude Desktop today), the rendered snippet uses the
//! community-standard `npx mcp-remote` stdio shim so the same HTTP
//! endpoint still works.
//!
//! OMP uses a native `mcp.json` in its agent dir (`~/.omp/agent`, a named
//! profile's `~/.omp/profiles/<name>/agent`, or `$PI_CODING_AGENT_DIR`) with
//! the same `mcpServers` root as several other clients.

use std::fs;
use std::path::{Path, PathBuf};

use anyhow::{Context, Result, bail};
use jsonc_parser::ParseOptions;
use jsonc_parser::cst::{CstInputValue, CstRootNode};
use serde_json::json;

use crate::cli::{InstallMcpArgs, McpClient, SchemaFlavor};
use crate::commands::apply_shared::{ApplyOutcome, apply_atomic, mutate_json, mutate_toml};
use crate::commands::path_util::{claude_config_dir, home_dir};
use crate::commands::render_shared::{
    bearer_header_value, hook_embedded_exe_path, shell_quote, yaml_single_quote,
};
use crate::config::{Config, DEFAULT_MCP_URL};
use crate::local_auth::HookCredential;

const GEMINI_MCP_TIMEOUT_MS: u64 = 5000;

/// The variable a Prime Agent entry names in `bearerTokenEnvVar`: the same one
/// ai-memory's own hooks and CLI read the server token from.
const PRIME_AGENT_TOKEN_ENV: &str = "AI_MEMORY_AUTH_TOKEN";

#[derive(Clone, Copy)]
enum JsonMcpLocation {
    RootMcpServers,
    RootMcp,
    NestedMcpServers,
    /// Top-level `servers` key — what VS Code's MCP framework expects
    /// in `.vscode/mcp.json` (workspace) or the user-level mcp.json.
    /// Distinct from `RootMcpServers` despite the similar shape: VS
    /// Code documents `servers`, not `mcpServers`, and writing the
    /// wrong key produces a silent no-op rather than an error.
    RootServers,
    /// Top-level `context_servers` key used by Zed's settings.json.
    RootContextServers,
    /// Muse Code's settings.json: the top-level `mcpServers` map, or the
    /// legacy snake_case `mcp_servers` when the file already uses it. Muse
    /// drops the whole MCP block when both are present, so exactly one is
    /// ever written (see [`muse_servers_key`]).
    MuseServers,
}

/// Run the `install-mcp` subcommand.
///
/// # Errors
/// Returns an error if JSON serialisation fails (should never happen
/// for our handcrafted values).
pub fn run(config: &Config, args: InstallMcpArgs) -> Result<()> {
    run_with_opencode_dialect(config, args, None)
}

pub(crate) fn run_with_opencode_dialect(
    config: &Config,
    mut args: InstallMcpArgs,
    dialect: Option<ai_memory_workstream::OpenCodeDialect>,
) -> Result<()> {
    let child_env = super::run::EffectiveChildEnv::from_runtime(&config.runtime_env);
    args.client = match (args.client, dialect) {
        (McpClient::OpenCode, Some(ai_memory_workstream::OpenCodeDialect::V1)) => {
            McpClient::OpenCode
        }
        (McpClient::OpenCode, Some(ai_memory_workstream::OpenCodeDialect::V2)) => {
            McpClient::OpenCode2
        }
        (client, None) => super::opencode_dialect::resolve_client(client, &child_env)?,
        (client, Some(_)) => client,
    };
    let needs_inferred_url = args.server_url.is_none() && !config.server_url_configured();
    let needs_inferred_token = args.auth_token.is_none() && config.auth.bearer_token.is_none();
    let inferred = if args.name == "ai-memory"
        && matches!(args.client, McpClient::OpenCode | McpClient::OpenCode2)
        && (needs_inferred_url || needs_inferred_token)
    {
        let path = resolve_config_file(&args)?;
        fs::read_to_string(path)
            .ok()
            .map(|content| infer_owned_opencode_mcp_config(&content, args.client))
            .transpose()?
            .flatten()
    } else {
        None
    };
    let server_url = if config.server_url_configured() || args.server_url.is_some() {
        effective_mcp_server_url(config, &args)
    } else {
        inferred.as_ref().map_or_else(
            || effective_mcp_server_url(config, &args),
            |entry| entry.mcp_url.clone(),
        )
    };
    // A token read from `[auth].bearer_token_file` is never copied into a
    // harness config: that file exists to keep it out of them (#552). An
    // inferred literal from an old entry is ignored then too, since it would
    // re-embed a stale credential.
    let token_file = config.auth.token_file_path();
    let token_given = args.auth_token.is_some();
    let auth_token = args
        .auth_token
        .or_else(|| config.auth.renderable_bearer_token().map(str::to_owned))
        .or_else(|| {
            inferred
                .filter(|_| token_file.is_none())
                .and_then(|entry| entry.auth_token)
        });
    let mut args = InstallMcpArgs {
        server_url: Some(server_url),
        auth_token,
        ..args
    };
    if args.auth_token.is_none()
        && let Some(token_file) = token_file
    {
        route_file_token(&mut args, token_file)?;
    }
    // The bridge loads its config and token from a data dir the way any CLI
    // call does. Muse starts stdio servers with a cleared environment (`HOME`,
    // `PATH` and its own `MUSE_SESSION_ID`), so its bridge finds this install
    // only through an explicit `--data-dir`, as the Muse hooks do. Hermes
    // keeps only a short allowlist (`PATH`, `HOME`, `XDG_*`, ...;
    // `_build_safe_env` in `tools/mcp_tool_config.py`), which drops
    // `AI_MEMORY_DATA_DIR` the same way. Any other
    // bridge needs it when this install was given a data dir: the hooks name
    // that dir, and a bridge without it would read the default one, with its
    // own config and bearer. Not from inside the Docker helper, whose data dir
    // is a container path the host-side bridge cannot open.
    let runs_bridge = (args.client == McpClient::ClaudeCode && args.session_aware)
        || args.stdio_bridge
        || args.client == McpClient::Qoder;
    if config.runtime_env.host_cwd().is_none()
        && (matches!(
            args.client,
            McpClient::Muse | McpClient::Freebuff | McpClient::Hermes
        ) || (runs_bridge && config.data_dir_explicit))
    {
        args.bridge_data_dir = Some(config.data_dir.clone());
    }
    // An explicit `--auth-token` for an entry that runs `mcp-bridge` goes where
    // the hooks keep theirs, `<data_dir>/auth-token`, and the bridge reads it
    // from there when nothing else is configured. Inline in the harness config
    // it would sit outside the data dir's protection and outlive a rotation,
    // the reasons #552 moved the hooks' copy. The entry then names that data
    // dir, so the bridge reads the file the key went into. Only `--apply`
    // stores, as with `install-hooks`: a printed snippet is the operator's to
    // place. The key stays inline, as before, whenever the bridge would not
    // reach it: a bearer this config is configured with would win over it, a
    // different key already stored belongs to the hooks, the store failed, or
    // this is the Docker helper, whose data dir the host-side bridge cannot
    // open.
    // FreeBuff belongs here for the same reason Muse does: its entry is always
    // the session-less bridge (`build_json_mcp_entry` routes the client to
    // `stdio_bridge_entry` unconditionally), and it already gets the
    // `--data-dir` above, so the bridge reads the file the key goes into.
    let bridge_carries_token = matches!(
        args.client,
        McpClient::Muse | McpClient::Freebuff | McpClient::Qoder
    ) || (args.client == McpClient::ClaudeCode && args.session_aware);
    let may_store_bridge_key = args.apply
        && token_given
        && bridge_carries_token
        && config.auth.configured_bearer_token().is_none()
        && config.runtime_env.host_cwd().is_none()
        && same_mcp_endpoint(
            &config.server_url,
            args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL),
        );
    validate_args(&args)?;
    if args.apply {
        if may_store_bridge_key
            && let Some(token) = args.auth_token.clone()
            && let Some(stored) = store_bridge_key(&config.data_dir, &token)
        {
            args.auth_token = None;
            args.bridge_data_dir = Some(config.data_dir.clone());
            if let Err(error) = apply_to_config_file(&args) {
                if stored == HookCredential::Seeded
                    && crate::config::read_hook_auth_token(&config.data_dir).as_deref()
                        == Some(token.as_str())
                {
                    crate::config::clear_hook_auth_token(&config.data_dir).with_context(
                        || "rolling back the bridge credential after MCP config update failed",
                    )?;
                }
                return Err(error);
            }
            return Ok(());
        }
        return apply_to_config_file(&args);
    }
    let snippet = match args.client {
        McpClient::ClaudeCode => render_claude_code(&args, &resolve_config_file(&args)?)?,
        McpClient::Codex => render_codex(&args)?,
        McpClient::Grok => render_grok(&args)?,
        McpClient::OpenCode => render_opencode(&args)?,
        McpClient::OpenCode2 => render_opencode2(&args)?,
        McpClient::Cursor => render_cursor(&args)?,
        McpClient::ClaudeDesktop => render_claude_desktop(&args)?,
        McpClient::GeminiCli => render_gemini_cli(&args)?,
        McpClient::QwenCode => render_qwen_code(&args)?,
        McpClient::Qoder => render_json_mcp_fragment(&args)?,
        McpClient::Openclaw => render_openclaw(&args)?,
        McpClient::Pi => render_pi(&args)?,
        McpClient::Omp => render_omp(&args)?,
        McpClient::AntigravityCli => render_antigravity_cli(&args)?,
        McpClient::Zero => render_zero(&args)?,
        McpClient::Zcode => render_zcode(&args)?,
        McpClient::Devin => render_devin(&args)?,
        McpClient::KimiCode => render_kimi_code(&args)?,
        McpClient::KiroCli => render_kiro_cli(&args)?,
        McpClient::CommandCode => render_command_code(&args)?,
        McpClient::IbmBob => render_ibm_bob(&args)?,
        McpClient::CopilotCli => render_copilot_cli(&args)?,
        McpClient::Droid => render_droid(&args)?,
        McpClient::Swival => render_swival(&args)?,
        McpClient::VsCodeCopilot => render_vscode_copilot(&args)?,
        McpClient::Zed => render_zed(&args)?,
        McpClient::Muse => render_muse(&args)?,
        McpClient::Dsh => render_dsh(&args)?,
        McpClient::Hermes => render_hermes(&args),
        McpClient::PrimeAgent => render_prime_agent(&args)?,
        McpClient::Cline => render_json_mcp_fragment(&args)?,
        McpClient::Freebuff => render_json_mcp_fragment(&args)?,
    };
    println!("{snippet}");
    Ok(())
}

/// Wire a client to a server whose bearer lives in `[auth].bearer_token_file`
/// without writing the token into the client's config.
///
/// - Claude Code gets the session-aware `ai-memory mcp-bridge` entry, and
///   Muse Code already has one (its entry is always the bridge).
/// - Codex, Prime Agent and Droid reference `AI_MEMORY_AUTH_TOKEN` by name,
///   the form their writers already use and each client documents.
/// - Pi is unchanged: its generated extension reads the hook credential file.
/// - Every other client that runs local commands gets a stdio entry for the
///   session-less bridge (`mcp-bridge --no-session-id`), in that client's own
///   documented stdio shape. The bridge is our own process, loads config like
///   any subcommand, and so reads the token from the file at launch.
/// - ZCode is refused: its entry schema keeps only `type`/`url`/`headers`/
///   `enabled`/`timeoutMs` and silently drops `command`/`args` (#511), so it
///   can only take a literal header.
fn route_file_token(args: &mut InstallMcpArgs, token_file: &Path) -> Result<()> {
    match args.client {
        McpClient::ClaudeCode => args.session_aware = true,
        McpClient::Codex | McpClient::PrimeAgent | McpClient::Droid => args.token_env_var = true,
        McpClient::Pi | McpClient::Muse => {}
        McpClient::Zcode => bail!(
            "this server's bearer token lives in {path} and ai-memory does not copy it into \
             another program's config. ZCode keeps only HTTP entries (`type`/`url`/`headers`), \
             so it can only take the token as a literal header and is not registered \
             automatically. Add the entry by hand with the header read from that file, or pass \
             the token explicitly with `{env}=... ai-memory install-mcp --client zcode ...` if \
             you accept it being stored in ZCode's config.",
            path = token_file.display(),
            env = PRIME_AGENT_TOKEN_ENV,
        ),
        _ => args.stdio_bridge = true,
    }
    Ok(())
}

/// Store `token` in `<data_dir>/auth-token` for the bridge, the file and
/// format `install-hooks --apply` uses. Returns whether this call created the
/// files or found the same key; `None` means the caller must keep the key in
/// the entry.
fn store_bridge_key(data_dir: &Path, token: &str) -> Option<HookCredential> {
    // The hooks present an OIDC `auth.json` only while no key is stored, so
    // storing one here would quietly switch them to this key.
    if crate::config::read_hook_auth_token(data_dir).is_none()
        && ai_memory_llm::OidcToken::load(&data_dir.join("auth.json"))
            .ok()
            .flatten()
            .is_some()
    {
        eprintln!(
            "[ai-memory] this install's hooks sign in with OIDC; keeping the --auth-token key \
             in the MCP entry, as before, so they keep doing so"
        );
        return None;
    }
    match crate::local_auth::seed_hook_credential(data_dir, token) {
        Ok(outcome @ (HookCredential::Seeded | HookCredential::Current)) => {
            eprintln!(
                "[ai-memory] stored the bridge's key in {}; the MCP entry carries no token",
                crate::config::hook_auth_token_path_in(data_dir).display()
            );
            Some(outcome)
        }
        Ok(HookCredential::KeptOther) => {
            eprintln!(
                "[ai-memory] warning: {} already holds a different key for this install's \
                 hooks; keeping the --auth-token key in the MCP entry, as before",
                crate::config::hook_auth_token_path_in(data_dir).display()
            );
            None
        }
        Err(e) => {
            eprintln!(
                "[ai-memory] warning: could not store the key under {} ({e:#}); keeping it in \
                 the MCP entry, as before",
                data_dir.display()
            );
            None
        }
    }
}

/// The bare command name, resolved through `PATH`. Inside a container the
/// Docker wrapper on the host intercepts `mcp-bridge`, so the entry must name
/// the wrapper rather than the container's own binary.
const BRIDGE_COMMAND: &str = "ai-memory";

/// The command a stdio bridge entry runs: this binary's absolute path, the
/// same one hook commands embed, because clients often start MCP servers
/// without the login shell's `PATH` and a bare `ai-memory` then fails to
/// spawn. Inside a container, or when the path cannot be trusted to survive
/// (see [`hook_embedded_exe_path`]), the bare [`BRIDGE_COMMAND`].
fn bridge_command() -> String {
    bridge_command_for(
        ai_memory_wiki::backup::running_in_container(),
        hook_embedded_exe_path(),
    )
}

fn bridge_command_for(in_container: bool, exe: PathBuf) -> String {
    if in_container {
        BRIDGE_COMMAND.to_owned()
    } else {
        exe.to_string_lossy().into_owned()
    }
}

/// Whether `command` runs ai-memory: the bare name, what [`bridge_command`]
/// writes from this binary, or an absolute path to a binary named `ai-memory`
/// that an earlier install wrote.
fn is_bridge_command(command: &str) -> bool {
    if command == BRIDGE_COMMAND || command == bridge_command() {
        return true;
    }
    let path = Path::new(command);
    path.is_absolute() && path.file_stem().and_then(|stem| stem.to_str()) == Some(BRIDGE_COMMAND)
}

/// Arguments of the session-less bridge for `args`: the URL carries the
/// client's schema-flavor marker, because the bridge forwards `tools/list`
/// to it verbatim and the client is the one that needs the dialect.
fn session_less_bridge_args(args: &InstallMcpArgs) -> Vec<String> {
    let base_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);
    let mut argv = vec![
        "mcp-bridge".to_owned(),
        "--no-session-id".to_owned(),
        "--server-url".to_owned(),
        flavored_url_for(args, base_url),
    ];
    argv.extend(bridge_data_dir_args(args));
    argv
}

/// `--data-dir <dir>` for a bridge entry when [`InstallMcpArgs::bridge_data_dir`]
/// is set, else nothing.
fn bridge_data_dir_args(args: &InstallMcpArgs) -> Vec<String> {
    args.bridge_data_dir
        .as_ref()
        .map_or_else(Vec::new, |data_dir| {
            vec![
                "--data-dir".to_owned(),
                data_dir.to_string_lossy().into_owned(),
            ]
        })
}

/// The upstream URL of an ai-memory bridge entry: an ai-memory `command` with
/// `args`, or OpenCode's single `command` array, running `mcp-bridge` with a
/// `--server-url`. `None` for any other entry.
pub(crate) fn bridge_entry_url(entry: &serde_json::Value) -> Option<&str> {
    let entry = entry
        .get("transport")
        .filter(|transport| transport.is_object())
        .unwrap_or(entry);
    let argv: Vec<&str> = match entry.get("command")? {
        serde_json::Value::String(command) if is_bridge_command(command) => entry
            .get("args")?
            .as_array()?
            .iter()
            .filter_map(serde_json::Value::as_str)
            .collect(),
        serde_json::Value::Array(command) => {
            let mut words = command.iter().filter_map(serde_json::Value::as_str);
            if !words.next().is_some_and(is_bridge_command) {
                return None;
            }
            words.collect()
        }
        _ => return None,
    };
    if argv.first() != Some(&"mcp-bridge") {
        return None;
    }
    argv.iter()
        .position(|arg| *arg == "--server-url")
        .and_then(|i| argv.get(i + 1))
        .copied()
}

/// What the entry `name` in `client`'s config file at `path` targets: an
/// HTTP entry's URL (`url`, `httpUrl`, `serverUrl`), a bridge entry's
/// upstream, or the URL a Claude Desktop `mcp-remote` shim forwards to.
/// `Ok(None)` when the file or the entry is absent, or the entry targets no
/// URL this installer could have written.
///
/// # Errors
/// The file exists but cannot be read or parsed.
pub(crate) fn existing_entry_endpoint(
    client: McpClient,
    path: &Path,
    name: &str,
) -> Result<Option<String>> {
    let text = match fs::read_to_string(path) {
        Ok(text) => text,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(e) => return Err(e).with_context(|| format!("reading {}", path.display())),
    };
    if matches!(client, McpClient::Codex | McpClient::Grok) {
        let doc: toml_edit::DocumentMut = text
            .parse()
            .with_context(|| format!("parsing {}", path.display()))?;
        let Some(table) = doc
            .get("mcp_servers")
            .and_then(|servers| servers.get(name))
            .and_then(toml_edit::Item::as_table_like)
        else {
            return Ok(None);
        };
        let as_json = json!({
            "url": table.get("url").and_then(toml_edit::Item::as_str),
            "command": table.get("command").and_then(toml_edit::Item::as_str),
            "args": table.get("args").and_then(toml_edit::Item::as_array).map(|args| {
                args.iter().filter_map(toml_edit::Value::as_str).collect::<Vec<_>>()
            }),
        });
        return Ok(entry_endpoint(&as_json).map(str::to_owned));
    }
    let Some(location) = json_mcp_location(client) else {
        return Ok(None);
    };
    let root: serde_json::Value = jsonc_parser::parse_to_ast(
        &text,
        &jsonc_parser::CollectOptions::default(),
        &ParseOptions::default(),
    )
    .map_err(|e| anyhow::anyhow!("parsing {}: {e}", path.display()))?
    .value
    .map_or(serde_json::Value::Null, Into::into);
    let pointers: &[&str] = match location {
        JsonMcpLocation::RootMcpServers => &["/mcpServers"],
        JsonMcpLocation::RootMcp => &["/mcp"],
        JsonMcpLocation::NestedMcpServers => &["/mcp/servers"],
        JsonMcpLocation::RootServers => &["/servers"],
        JsonMcpLocation::RootContextServers => &["/context_servers"],
        JsonMcpLocation::MuseServers => &["/mcpServers", "/mcp_servers"],
    };
    let Some(entry) = pointers
        .iter()
        .find_map(|pointer| root.pointer(pointer).and_then(|servers| servers.get(name)))
    else {
        return Ok(None);
    };
    if let Some(url) = ["url", "httpUrl", "serverUrl"]
        .iter()
        .find_map(|key| entry.get(*key).and_then(serde_json::Value::as_str))
        .or_else(|| {
            entry
                .pointer("/transport/url")
                .and_then(serde_json::Value::as_str)
        })
        .or_else(|| bridge_entry_url(entry))
    {
        return Ok(Some(url.to_owned()));
    }
    let args: Vec<&str> = entry
        .get("args")
        .and_then(serde_json::Value::as_array)
        .map(|args| args.iter().filter_map(serde_json::Value::as_str).collect())
        .unwrap_or_default();
    Ok(args
        .iter()
        .position(|arg| *arg == "mcp-remote")
        .and_then(|i| args.get(i + 1))
        .map(|url| (*url).to_owned()))
}

/// The stdio entry, in the client's documented shape, that runs the
/// session-less bridge. `None` for clients whose entry is not JSON or that
/// take no stdio entry here.
fn stdio_bridge_entry(args: &InstallMcpArgs) -> Option<serde_json::Value> {
    let bridge = session_less_bridge_args(args);
    let command = bridge_command();
    let plain = || json!({"command": command, "args": bridge.clone()});
    let typed = |kind: &str| json!({"type": kind, "command": command, "args": bridge.clone()});
    let mut opencode_argv = vec![command.clone()];
    opencode_argv.extend(bridge.iter().cloned());
    Some(match args.client {
        McpClient::ClaudeDesktop
        | McpClient::Zed
        | McpClient::Devin
        | McpClient::KimiCode
        | McpClient::KiroCli
        | McpClient::Openclaw
        | McpClient::IbmBob
        | McpClient::Cline => plain(),
        McpClient::Qoder => {
            let env = args
                .auth_token
                .as_ref()
                .map_or_else(|| json!({}), |token| json!({"AI_MEMORY_AUTH_TOKEN": token}));
            json!({"command": command, "args": bridge, "env": env})
        }
        McpClient::GeminiCli | McpClient::AntigravityCli | McpClient::QwenCode => json!({
            "command": command,
            "args": bridge,
            "timeout": GEMINI_MCP_TIMEOUT_MS,
        }),
        McpClient::Cursor | McpClient::VsCodeCopilot | McpClient::Swival | McpClient::Zero => {
            typed("stdio")
        }
        McpClient::Freebuff => {
            let env = args
                .auth_token
                .as_ref()
                .map_or_else(|| json!({}), |token| json!({"AI_MEMORY_AUTH_TOKEN": token}));
            json!({
                "command": BRIDGE_COMMAND,
                "args": bridge,
                "env": env,
            })
        }
        McpClient::Omp => json!({
            "type": "stdio",
            "command": command,
            "args": bridge,
            "enabled": true,
        }),
        McpClient::CopilotCli => json!({
            "type": "local",
            "command": command,
            "args": bridge,
            "tools": ["*"],
        }),
        McpClient::CommandCode => json!({
            "transport": "stdio",
            "enabled": true,
            "command": command,
            "args": bridge,
        }),
        McpClient::OpenCode => json!({"type": "local", "command": opencode_argv, "enabled": true}),
        McpClient::OpenCode2 => json!({"type": "local", "command": opencode_argv}),
        _ => return None,
    })
}

fn effective_mcp_server_url(config: &Config, args: &InstallMcpArgs) -> String {
    if let Some(url) = &args.server_url {
        // Normalize an explicit --server-url exactly like the config/env
        // branch below: users habitually pass the BASE url (the same value
        // `install-hooks --server-url` takes), and returning it verbatim
        // rendered a config pointing at the server root, which 404s (#185).
        // `mcp_server_url_from_base` is idempotent for full `/mcp` endpoints,
        // so callers who already pass the endpoint are unchanged.
        return mcp_server_url_from_base(url);
    }
    // A URL derived from `bind` counts here too: with nothing configured and no
    // existing entry to infer from, the client should reach the server this
    // config starts (#1269).
    if config.server_url_configured() || config.server_url_derived_from_bind {
        return mcp_server_url_from_base(&config.server_url);
    }
    DEFAULT_MCP_URL.to_string()
}

pub(crate) fn mcp_server_url_from_base(server_url: &str) -> String {
    let trimmed = server_url.trim();
    // A query (a schema `?flavor=` marker on a bridge's upstream URL) stays
    // after the path, which is what gains the `/mcp` suffix.
    let (path, query) = trimmed
        .split_once('?')
        .map_or((trimmed, None), |(path, query)| (path, Some(query)));
    let path = path.trim_end_matches('/');
    let path = if path.ends_with("/mcp") {
        path.to_string()
    } else {
        format!("{path}/mcp")
    };
    match query {
        Some(query) => format!("{path}?{query}"),
        None => path,
    }
}

fn same_mcp_endpoint(left: &str, right: &str) -> bool {
    fn normalized(url: &str) -> String {
        mcp_server_url_from_base(url).split_once('?').map_or_else(
            || mcp_server_url_from_base(url),
            |(base, _)| base.to_owned(),
        )
    }
    normalized(left) == normalized(right)
}

fn validate_args(args: &InstallMcpArgs) -> Result<()> {
    if args.session_aware && !matches!(args.client, McpClient::ClaudeCode) {
        bail!("--session-aware is supported only for --client claude-code");
    }
    if matches!(args.client, McpClient::KiroCli) {
        validate_kiro_remote_url(args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL))?;
    }
    if matches!(args.client, McpClient::Dsh) {
        validate_dsh_server_name(&args.name)?;
    }
    if matches!(args.client, McpClient::PrimeAgent) {
        validate_prime_agent_server_name(&args.name)?;
    }
    Ok(())
}

/// DSH's `serverName` must match `[A-Za-z0-9_-]{1,32}`, and the
/// rendered entry reuses the entry name for it, so reject an unusable
/// `--name` before printing a snippet DSH would refuse.
fn validate_dsh_server_name(name: &str) -> Result<()> {
    let valid = !name.is_empty()
        && name.len() <= 32
        && name
            .bytes()
            .all(|b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-');
    if !valid {
        bail!("DSH serverName must be 1-32 characters of [A-Za-z0-9_-]; got {name:?}");
    }
    Ok(())
}

/// Prime Agent resolves a user MCP server only when its name is 1-64
/// characters of `[A-Za-z0-9_-]` starting with a letter or digit; any other
/// name is never connected, so refuse it before writing the entry.
fn validate_prime_agent_server_name(name: &str) -> Result<()> {
    let valid = name.len() <= 64
        && name
            .bytes()
            .next()
            .is_some_and(|b| b.is_ascii_alphanumeric())
        && name
            .bytes()
            .all(|b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-');
    if !valid {
        bail!(
            "Prime Agent MCP server names must be 1-64 characters of [A-Za-z0-9_-] starting with a letter or digit; got {name:?}"
        );
    }
    Ok(())
}

/// Kiro accepts HTTPS remote MCP endpoints and plain HTTP only on loopback.
/// Reject an unusable registration before `--apply` mutates user config.
fn validate_kiro_remote_url(server_url: &str) -> Result<()> {
    let parsed = reqwest::Url::parse(server_url).context("Kiro MCP URL is not a valid URL")?;
    if parsed.scheme() == "https" {
        return Ok(());
    }
    let loopback = parsed.host_str().is_some_and(|host| {
        let normalized = host
            .strip_prefix('[')
            .and_then(|host| host.strip_suffix(']'))
            .unwrap_or(host);
        normalized.eq_ignore_ascii_case("localhost")
            || normalized
                .parse::<std::net::IpAddr>()
                .is_ok_and(|address| address.is_loopback())
    });
    if parsed.scheme() == "http" && loopback {
        return Ok(());
    }
    bail!(
        "Kiro CLI requires HTTPS for remote MCP servers (plain HTTP is accepted only on localhost); configure an HTTPS reverse proxy or pass a loopback URL"
    )
}

/// Default MCP config-file path for a client (ignores any
/// `--config-file` override). Shared by install and uninstall.
///
/// # Errors
/// Returns an error for `Pi` (no MCP config), for Claude Desktop on
/// unsupported OSes, or when `$HOME` can't be resolved.
pub(crate) fn mcp_config_path(client: crate::cli::McpClient) -> Result<PathBuf> {
    mcp_config_path_with(client, &|name| std::env::var_os(name))
}

/// [`mcp_config_path`] with the relocation variables (`CLAUDE_CONFIG_DIR`,
/// `CODEX_HOME`, `COPILOT_HOME`, `GROK_HOME`, `KIMI_CODE_HOME`, `KIRO_HOME`,
/// `PRIME_AGENT_CODING_AGENT_DIR`, `CLINE_MCP_SETTINGS_PATH`, and OMP's
/// `OMP_PROFILE`, `PI_PROFILE`, `PI_CODING_AGENT_DIR` and `PI_CONFIG_DIR`) read
/// through `env`,
/// so `ai-memory run --env` can point auto-wire at the same config home
/// it launches the harness with.
pub(crate) fn mcp_config_path_with(
    client: crate::cli::McpClient,
    env: &dyn Fn(&str) -> Option<std::ffi::OsString>,
) -> Result<PathBuf> {
    use crate::cli::McpClient;
    let home = || {
        env("HOME")
            .filter(|value| !value.is_empty())
            .map(PathBuf::from)
            .or_else(home_dir)
            .context("could not locate $HOME for config-file auto-detect")
    };
    Ok(match client {
        McpClient::ClaudeCode => claude_code_config_path_in(env("CLAUDE_CONFIG_DIR"))?,
        McpClient::Codex => codex_config_path_in(env("CODEX_HOME"))?,
        // Project scope is `.grok/config.toml` under cwd/repo; pass
        // --config-file for that case rather than inventing a second default.
        McpClient::Grok => grok_home_in(env("GROK_HOME"))?.join("config.toml"),
        McpClient::OpenCode => home()?
            .join(".config")
            .join("opencode")
            .join("opencode.json"),
        // V2 reads the same global config file (`opencode.json(c)`) but uses
        // `mcp.servers`. Users who keep comments in `opencode.jsonc` should
        // pass it via `--config-file` (`mutate_json` refuses to rewrite
        // non-strict JSON).
        McpClient::OpenCode2 => home()?
            .join(".config")
            .join("opencode")
            .join("opencode.json"),
        McpClient::Cursor => home()?.join(".cursor").join("mcp.json"),
        McpClient::ClaudeDesktop => {
            #[cfg(target_os = "macos")]
            {
                home()?
                    .join("Library")
                    .join("Application Support")
                    .join("Claude")
                    .join("claude_desktop_config.json")
            }
            #[cfg(target_os = "windows")]
            {
                // The variables come first, through `env`, so a relocated
                // profile (`run --env`, a hermetic test) is honoured; the
                // Known Folder API ignores them.
                let known_dir = |name: &str, fallback: fn() -> Option<PathBuf>| {
                    env(name)
                        .filter(|value| !value.is_empty())
                        .map(PathBuf::from)
                        .or_else(fallback)
                };
                let local_data_dir = known_dir("LOCALAPPDATA", dirs::data_local_dir)
                    .context("could not locate %LOCALAPPDATA% for Claude Desktop config")?;
                let roaming_config_dir = known_dir("APPDATA", dirs::config_dir)
                    .context("could not locate %APPDATA% for Claude Desktop config")?;
                claude_desktop_config_path_in(&local_data_dir, &roaming_config_dir)?
            }
            #[cfg(not(any(target_os = "macos", target_os = "windows")))]
            {
                // Anthropic's Linux beta keeps Electron's profile, and the
                // config, under $XDG_CONFIG_HOME/Claude.
                claude_desktop_config_path_linux(
                    &dirs::config_dir()
                        .context("could not locate the user config directory for Claude Desktop")?,
                )
            }
        }
        McpClient::GeminiCli => home()?.join(".gemini").join("settings.json"),
        McpClient::QwenCode => home()?.join(".qwen").join("settings.json"),
        McpClient::Qoder => home()?.join(".qoder").join("settings.json"),
        McpClient::Openclaw => home()?.join(".openclaw").join("config.json"),
        McpClient::Pi => bail!(
            "Pi has no native mcp.json; use `ai-memory install-hooks --agent pi --apply` to install the generated MCP bridge extension."
        ),
        McpClient::Dsh => bail!(
            "DeepSeek Harness has no fixed MCP config file; merge the printed snippet into $DSH_HOME/profiles/<profile>/cordis.patch.yml."
        ),
        McpClient::Hermes => bail!(HERMES_MCP_APPLY_GUIDANCE),
        // OMP reads mcp.json from its agent dir, the one its extensions live
        // in, so a profile, PI_CODING_AGENT_DIR or PI_CONFIG_DIR moves it too.
        McpClient::Omp => {
            ai_memory_workstream::omp_agent_dir(&home()?, None, env)?.join("mcp.json")
        }
        McpClient::AntigravityCli => home()?
            .join(".gemini")
            .join("config")
            .join("mcp_config.json"),
        // Zero resolves its user config under $XDG_CONFIG_HOME falling back
        // to ~/.config; we target the default and --config-file covers
        // non-default XDG setups (same policy as OpenCode above).
        McpClient::Zero => home()?.join(".config").join("zero").join("config.json"),
        // ZCode keeps its user-scope config at ~/.zcode/cli/config.json
        // (workspace scopes like .zcode/config.json exist, but user scope
        // is the install default for every other client too).
        McpClient::Zcode => home()?.join(".zcode").join("cli").join("config.json"),
        McpClient::Devin => home()?.join(".devin").join("config.json"),
        // Kimi Code keeps its data dir at $KIMI_CODE_HOME when set,
        // falling back to ~/.kimi-code; MCP servers live in mcp.json at
        // that root.
        McpClient::KimiCode => kimi_code_home(env("KIMI_CODE_HOME"))?.join("mcp.json"),
        McpClient::KiroCli => kiro_home(env("KIRO_HOME"))?
            .join("settings")
            .join("mcp.json"),
        McpClient::CommandCode => home()?.join(".commandcode").join("mcp.json"),
        McpClient::IbmBob => home()?.join(".bob").join("settings").join("mcp.json"),
        // Copilot CLI keeps its whole config dir at $COPILOT_HOME when set,
        // falling back to ~/.copilot; user-level MCP servers live in
        // mcp-config.json there (project `.mcp.json` / `.github/mcp.json`
        // files are left to `--config-file`).
        McpClient::CopilotCli => copilot_home_in(env("COPILOT_HOME"))?.join("mcp-config.json"),
        // Droid's user-level MCP servers live in ~/.factory/mcp.json; a
        // project's `.factory/mcp.json` is left to --config-file.
        McpClient::Droid => factory_home(&home()?).join("mcp.json"),
        McpClient::Swival => {
            let cwd = std::env::current_dir()
                .context("could not resolve current dir for .swival/mcp.json default")?;
            swival_project_root(&cwd).join(".swival").join("mcp.json")
        }
        // VS Code MCP is workspace-scoped by default: `.vscode/mcp.json`
        // at the current workspace root. The user-profile alternative
        // lives under VS Code's profile-specific data dir; use VS
        // Code's `MCP: Open User Configuration` command to open it,
        // then pass that concrete path via `--config-file`.
        McpClient::VsCodeCopilot => std::env::current_dir()
            .context("could not resolve current dir for .vscode/mcp.json default")?
            .join(".vscode")
            .join("mcp.json"),
        McpClient::Zed => {
            let config_dir = if cfg!(target_os = "macos") {
                home()?.join(".config")
            } else {
                dirs::config_dir().context("could not locate user config directory for Zed")?
            };
            zed_config_path_in(&config_dir, std::env::consts::OS)
        }
        // Muse Code keeps its user settings at
        // ${XDG_CONFIG_HOME:-~/.config}/muse/settings.json.
        McpClient::Muse => muse_settings_path_in(env("XDG_CONFIG_HOME"), home_dir())?,
        // Prime Agent's agent dir is $PRIME_AGENT_CODING_AGENT_DIR when set,
        // else ~/.prime/agent; user MCP servers live in its settings.json
        // (a project's `.prime/agent/settings.json` overrides it: pass that
        // path via --config-file).
        McpClient::PrimeAgent => {
            prime_agent_dir_in(env("PRIME_AGENT_CODING_AGENT_DIR"))?.join("settings.json")
        }
        McpClient::Cline => env("CLINE_MCP_SETTINGS_PATH")
            .filter(|path| !path.is_empty())
            .map(PathBuf::from)
            .unwrap_or(home()?.join(".cline/data/settings/cline_mcp_settings.json")),
        McpClient::Freebuff => home()?.join(".agents").join("mcp.json"),
    })
}

/// Match Swival's own base-dir discovery: the nearest ancestor containing
/// `.git` or `swival.toml`, falling back to the invocation directory.
fn swival_project_root(start: &Path) -> PathBuf {
    let resolved = std::fs::canonicalize(start).unwrap_or_else(|_| start.to_path_buf());
    let mut current = resolved.as_path();
    loop {
        if current.join(".git").exists() || current.join("swival.toml").exists() {
            return current.to_path_buf();
        }
        let Some(parent) = current.parent() else {
            return resolved;
        };
        current = parent;
    }
}

/// Resolve Zed's user settings from the platform config root. The root is
/// injected so path behavior can be tested without consulting the real home.
fn zed_config_path_in(config_dir: &Path, target_os: &str) -> PathBuf {
    let app_dir = if target_os == "windows" { "Zed" } else { "zed" };
    config_dir.join(app_dir).join("settings.json")
}

/// Claude Desktop's config file under the Linux user config directory.
#[cfg_attr(any(target_os = "macos", target_os = "windows"), allow(dead_code))]
fn claude_desktop_config_path_linux(config_dir: &Path) -> PathBuf {
    config_dir.join("Claude").join("claude_desktop_config.json")
}

#[cfg(any(target_os = "windows", test))]
fn claude_desktop_config_path_in(
    local_data_dir: &Path,
    roaming_config_dir: &Path,
) -> Result<PathBuf> {
    let local_packages_dir = local_data_dir.join("Packages");
    Ok(
        packaged_claude_desktop_config_path(&local_packages_dir)?.unwrap_or_else(|| {
            roaming_config_dir
                .join("Claude")
                .join("claude_desktop_config.json")
        }),
    )
}

/// Detect an MSIX/AppX-packaged Claude Desktop under
/// `%LOCALAPPDATA%\Packages`. Prefer the package that already contains a
/// config file; otherwise a single package directory is enough because the
/// atomic apply path creates its lazy `LocalCache` descendants.
#[cfg(any(target_os = "windows", test))]
fn packaged_claude_desktop_config_path(local_packages_dir: &Path) -> Result<Option<PathBuf>> {
    let entries = match std::fs::read_dir(local_packages_dir) {
        Ok(entries) => entries,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(error) => {
            return Err(error).with_context(|| {
                format!(
                    "could not inspect Claude Desktop packages under {}",
                    local_packages_dir.display()
                )
            });
        }
    };
    let mut candidates: Vec<PathBuf> = entries
        .filter_map(|entry| entry.ok())
        .map(|entry| entry.path())
        .filter(|path| {
            path.is_dir()
                && path
                    .file_name()
                    .and_then(|name| name.to_str())
                    .and_then(|name| name.get(.."Claude_".len()))
                    .is_some_and(|prefix| prefix.eq_ignore_ascii_case("Claude_"))
        })
        .collect();
    candidates.sort();

    let config_path = |package_dir: &Path| {
        package_dir
            .join("LocalCache")
            .join("Roaming")
            .join("Claude")
            .join("claude_desktop_config.json")
    };
    let existing: Vec<PathBuf> = candidates
        .iter()
        .map(|package_dir| config_path(package_dir))
        .filter(|path| path.is_file())
        .collect();

    match (existing.as_slice(), candidates.as_slice()) {
        ([path], _) => Ok(Some(path.clone())),
        ([], []) => Ok(None),
        ([], [package_dir]) => Ok(Some(config_path(package_dir))),
        _ => {
            let package_names = candidates
                .iter()
                .filter_map(|path| path.file_name())
                .map(|name| name.to_string_lossy())
                .collect::<Vec<_>>()
                .join(", ");
            bail!(
                "multiple Claude Desktop packages were found under {} ({package_names}); \
                 pass --config-file with the active package's \
                 LocalCache\\Roaming\\Claude\\claude_desktop_config.json path",
                local_packages_dir.display()
            )
        }
    }
}

/// Claude Code reads MCP-server registrations from `.claude.json`
/// (the same file `claude mcp add`/`claude mcp list` operate on) —
/// `$CLAUDE_CONFIG_DIR/.claude.json` when the var is set, else
/// `~/.claude.json`. `settings.json` is a separate file for hooks /
/// permissions / etc. — putting `mcpServers` there does NOT make
/// Claude Code load the server. (Confirmed against CC 1.x by
/// observing that `mcpServers` in settings.json is silently ignored
/// while the same entry under `~/.claude.json` shows up in
/// `claude mcp list`.) The env value comes in as a parameter so tests
/// can exercise both branches without mutating process env.
fn claude_code_config_path_in(env_override: Option<std::ffi::OsString>) -> Result<PathBuf> {
    if let Some(dir) = claude_config_dir(env_override) {
        return Ok(dir.join(".claude.json"));
    }
    Ok(home_dir()
        .context("could not locate $HOME for ~/.claude.json")?
        .join(".claude.json"))
}

/// Codex's user config, where its MCP servers live: `$CODEX_HOME/config.toml`
/// when the var is set, else `~/.codex/config.toml`. Codex keeps its whole
/// config home under `CODEX_HOME`, which `install-hooks` already honors for
/// `hooks.json`; writing the MCP entry to the default path left a relocated
/// Codex with hooks but no ai-memory server. Blank counts as unset, as it does
/// for the hooks path. The env value comes in as a parameter so tests can
/// exercise both branches without mutating process env.
fn codex_config_path_in(env_override: Option<std::ffi::OsString>) -> Result<PathBuf> {
    if let Some(dir) = crate::commands::path_util::agent_config_home(env_override) {
        return Ok(dir.join("config.toml"));
    }
    Ok(home_dir()
        .context("could not locate $HOME for ~/.codex/config.toml")?
        .join(".codex")
        .join("config.toml"))
}

/// Kimi Code's data dir: `$KIMI_CODE_HOME` when set and not blank, else
/// `~/.kimi-code`. The env value comes in as a parameter so tests can
/// exercise both branches without mutating process env.
fn kimi_code_home(env_override: Option<std::ffi::OsString>) -> Result<PathBuf> {
    if let Some(dir) = crate::commands::path_util::agent_config_home(env_override) {
        return Ok(dir);
    }
    Ok(home_dir()
        .context("could not locate $HOME for config-file auto-detect")?
        .join(".kimi-code"))
}

/// Kiro CLI's global configuration root: `$KIRO_HOME` when set and not
/// blank, otherwise `~/.kiro`. The override is injected to keep path tests
/// process-local.
fn kiro_home(env_override: Option<std::ffi::OsString>) -> Result<PathBuf> {
    if let Some(dir) = crate::commands::path_util::agent_config_home(env_override) {
        return Ok(dir);
    }
    Ok(home_dir()
        .context("could not locate $HOME for Kiro configuration")?
        .join(".kiro"))
}

/// GitHub Copilot CLI's configuration directory: `$COPILOT_HOME` when set and
/// not blank, otherwise `~/.copilot`. It holds both `mcp-config.json` and the
/// user-level `hooks/` directory, so `install-hooks --agent copilot-cli`
/// resolves through here too. The override is injected to keep tests
/// process-local.
pub(crate) fn copilot_home_in(env_override: Option<std::ffi::OsString>) -> Result<PathBuf> {
    if let Some(dir) = crate::commands::path_util::agent_config_home(env_override) {
        return Ok(dir);
    }
    Ok(home_dir()
        .context("could not locate $HOME for Copilot CLI configuration")?
        .join(".copilot"))
}

/// Meta Muse Code's user settings file,
/// `${XDG_CONFIG_HOME:-~/.config}/muse/settings.json`: the one file both its
/// hooks and its MCP servers live in. `XDG_CONFIG_HOME` counts only when set
/// to an absolute path, as the XDG base-directory spec requires; a blank or
/// relative value falls back to `<home>/.config`. Lexical only: the path is
/// never canonicalized.
///
/// # Errors
/// No usable `XDG_CONFIG_HOME` and no home directory.
pub(crate) fn muse_settings_path_in(
    xdg_config_home: Option<std::ffi::OsString>,
    home: Option<PathBuf>,
) -> Result<PathBuf> {
    let config_root = match crate::commands::path_util::agent_config_home(xdg_config_home)
        .filter(|dir| dir.is_absolute())
    {
        Some(dir) => dir,
        None => home
            .context("could not locate $HOME for ~/.config/muse/settings.json")?
            .join(".config"),
    };
    Ok(config_root.join("muse").join("settings.json"))
}

/// Factory Droid's user configuration root, `~/.factory`, under an injected
/// home so path tests never consult the real one. Droid documents no
/// variable that relocates it.
pub(crate) fn factory_home(home: &Path) -> PathBuf {
    home.join(".factory")
}

/// Prime Agent's agent directory: `$PRIME_AGENT_CODING_AGENT_DIR` when set and
/// not blank, otherwise `~/.prime/agent`. The override is injected to keep
/// path tests process-local.
fn prime_agent_dir_in(env_override: Option<std::ffi::OsString>) -> Result<PathBuf> {
    if let Some(dir) = crate::commands::path_util::agent_config_home(env_override) {
        return Ok(dir);
    }
    Ok(home_dir()
        .context("could not locate $HOME for Prime Agent configuration")?
        .join(".prime")
        .join("agent"))
}

/// Resolve Grok Build CLI's user configuration root. Grok honours
/// `GROK_HOME`; otherwise it uses `~/.grok`.
pub(crate) fn grok_home() -> Result<PathBuf> {
    grok_home_in(std::env::var_os("GROK_HOME"))
}

/// [`grok_home`] with the `GROK_HOME` value passed in, so auto-wire can resolve
/// it from `ai-memory run --env` and tests stay process-local.
pub(crate) fn grok_home_in(env_override: Option<std::ffi::OsString>) -> Result<PathBuf> {
    if let Some(dir) = crate::commands::path_util::agent_config_home(env_override) {
        return Ok(dir);
    }
    Ok(home_dir()
        .context("could not locate $HOME for Grok configuration")?
        .join(".grok"))
}

/// Resolve the user-config file for this client. Honours
/// `--config-file` when provided, else uses the canonical default
/// per client.
fn resolve_config_file(args: &InstallMcpArgs) -> Result<PathBuf> {
    if let Some(p) = &args.config_file {
        return Ok(p.clone());
    }
    mcp_config_path(args.client)
}

/// True when the client's MCP config already holds a session-aware ai-memory
/// bridge under `name` — a Claude Code stdio entry whose args run `mcp-bridge`.
///
/// Auto-wire consults this before its version-keyed re-wire so it never
/// downgrades a deliberately-installed bridge to the static HTTP registration,
/// which would silently disable `[auto_scope] per_session` for MCP calls. Only
/// Claude Code has a session-aware variant, so every other client answers
/// `false`. A missing file or any parse error also answers `false`: the caller
/// then falls back to its normal install, which is the safe default.
pub(crate) fn existing_entry_is_session_aware(
    client: McpClient,
    config_file: Option<&Path>,
    name: &str,
) -> bool {
    if !matches!(client, McpClient::ClaudeCode) {
        return false;
    }
    let path = match config_file {
        Some(path) => path.to_path_buf(),
        None => match mcp_config_path(client) {
            Ok(path) => path,
            Err(_) => return false,
        },
    };
    let Ok(text) = std::fs::read_to_string(&path) else {
        return false;
    };
    let Ok(root) = serde_json::from_str::<serde_json::Value>(&text) else {
        return false;
    };
    let Some(entry) = root.get("mcpServers").and_then(|servers| servers.get(name)) else {
        return false;
    };
    let is_stdio = entry.get("type").and_then(serde_json::Value::as_str) == Some("stdio");
    let runs_bridge = entry
        .get("args")
        .and_then(serde_json::Value::as_array)
        .is_some_and(|args| args.iter().any(|arg| arg.as_str() == Some("mcp-bridge")));
    is_stdio && runs_bridge
}

/// True when Claude Code or Muse still holds an ai-memory bridge entry under
/// `name` in its default config file. `install-mcp --apply --auth-token`
/// writes those two without the key, which the bridge then reads from
/// `<data_dir>/auth-token`, so an uninstall that keeps such an entry must keep
/// that file. Unreadable files answer `false`, as for the session-aware check.
pub(crate) fn bridge_entry_remains(name: &str) -> bool {
    existing_entry_is_session_aware(McpClient::ClaudeCode, None, name)
        || mcp_config_path(McpClient::Muse)
            .ok()
            .and_then(|path| existing_entry_endpoint(McpClient::Muse, &path, name).ok())
            .flatten()
            .is_some()
}

/// Mutate the resolved client config file in place. Idempotent —
/// re-runs that produce the same content are reported as no-op.
fn apply_to_config_file(args: &InstallMcpArgs) -> Result<()> {
    if matches!(args.client, McpClient::Pi) {
        bail!(pi_mcp_apply_guidance(args));
    }
    if matches!(args.client, McpClient::Dsh) {
        bail!(dsh_mcp_apply_guidance(args));
    }
    if matches!(args.client, McpClient::Hermes) {
        bail!(HERMES_MCP_APPLY_GUIDANCE);
    }
    let path = resolve_config_file(args)?;
    let outcome = match args.client {
        McpClient::Codex => apply_atomic(&path, |existing| {
            mutate_toml(existing, |doc| codex_upsert_mcp_server(doc, args))
        })?,
        McpClient::Grok => apply_atomic(&path, |existing| {
            mutate_toml(existing, |doc| grok_upsert_mcp_server(doc, args))
        })?,
        McpClient::Zed => apply_atomic(&path, |existing| zed_upsert_mcp_server(existing, args))?,
        _ => apply_atomic(&path, |existing| {
            mutate_json(existing, |root| upsert_json_mcp_entry(root, args))
        })?,
    };
    println!(
        "✓ {} {} ({})",
        outcome.verb(),
        path.display(),
        match outcome {
            ApplyOutcome::Created => "new file",
            ApplyOutcome::Updated => "backup written next to it",
            ApplyOutcome::NoOp => "already up to date",
        }
    );
    if matches!(args.client, McpClient::PrimeAgent)
        && (args.auth_token.is_some() || args.token_env_var)
    {
        println!(
            "  Prime Agent reads the token from ${PRIME_AGENT_TOKEN_ENV}; export it where you launch prime-agent."
        );
    }
    if matches!(args.client, McpClient::Droid) && (args.auth_token.is_some() || args.token_env_var)
    {
        println!(
            "  Droid expands ${{{PRIME_AGENT_TOKEN_ENV}}} in the Authorization header; export it where you launch droid, or the server fails to connect."
        );
    }
    if matches!(args.client, McpClient::Codex) && args.token_env_var {
        println!(
            "  Codex reads the token from ${PRIME_AGENT_TOKEN_ENV}; export it where you launch codex."
        );
    }
    Ok(())
}

/// Merge ai-memory into Zed's JSONC settings without discarding comments,
/// trailing commas, or unrelated formatting.
fn zed_upsert_mcp_server(existing: &str, args: &InstallMcpArgs) -> Result<String> {
    let root = CstRootNode::parse(existing, &ParseOptions::default())
        .context("parsing Zed settings.json as JSONC")?;
    let settings = root
        .object_value_or_create()
        .context("Zed settings.json root is present but not an object")?;
    let servers = settings
        .object_value_or_create("context_servers")
        .context("`context_servers` is present but not an object")?;
    let entry = serde_json_to_cst(build_json_mcp_entry(args)?);
    if let Some(existing_entry) = servers.get(&args.name) {
        existing_entry.set_value(entry);
    } else {
        servers.append(&args.name, entry);
    }
    Ok(root.to_string())
}

fn serde_json_to_cst(value: serde_json::Value) -> CstInputValue {
    match value {
        serde_json::Value::Null => CstInputValue::Null,
        serde_json::Value::Bool(value) => CstInputValue::Bool(value),
        serde_json::Value::Number(value) => CstInputValue::Number(value.to_string()),
        serde_json::Value::String(value) => CstInputValue::String(value),
        serde_json::Value::Array(values) => {
            CstInputValue::Array(values.into_iter().map(serde_json_to_cst).collect())
        }
        serde_json::Value::Object(values) => CstInputValue::Object(
            values
                .into_iter()
                .map(|(key, value)| (key, serde_json_to_cst(value)))
                .collect(),
        ),
    }
}

fn json_mcp_location(client: McpClient) -> Option<JsonMcpLocation> {
    match client {
        McpClient::ClaudeCode
        | McpClient::ClaudeDesktop
        | McpClient::Cursor
        | McpClient::GeminiCli
        | McpClient::QwenCode
        | McpClient::Qoder
        | McpClient::Omp
        | McpClient::AntigravityCli
        | McpClient::Devin
        | McpClient::KimiCode
        | McpClient::KiroCli
        | McpClient::CommandCode
        | McpClient::IbmBob
        | McpClient::CopilotCli
        | McpClient::Droid
        | McpClient::Swival
        | McpClient::PrimeAgent => Some(JsonMcpLocation::RootMcpServers),
        McpClient::Cline | McpClient::Freebuff => Some(JsonMcpLocation::RootMcpServers),
        McpClient::OpenCode => Some(JsonMcpLocation::RootMcp),
        // V2 nests servers under `mcp.servers` — the same shape OpenClaw,
        // Zero, and ZCode use.
        McpClient::OpenCode2 => Some(JsonMcpLocation::NestedMcpServers),
        // Zero's config.json nests servers under `mcp.servers`, the same
        // shape OpenClaw uses. ZCode nests its servers the same way.
        McpClient::Openclaw | McpClient::Zero | McpClient::Zcode => {
            Some(JsonMcpLocation::NestedMcpServers)
        }
        McpClient::VsCodeCopilot => Some(JsonMcpLocation::RootServers),
        McpClient::Zed => Some(JsonMcpLocation::RootContextServers),
        McpClient::Muse => Some(JsonMcpLocation::MuseServers),
        McpClient::Codex | McpClient::Grok | McpClient::Pi | McpClient::Dsh | McpClient::Hermes => {
            None
        }
    }
}

fn build_json_mcp_entry(args: &InstallMcpArgs) -> Result<serde_json::Value> {
    validate_args(args)?;
    // FreeBuff supports local stdio MCP servers, not remote HTTP entries.
    // Always bridge to the configured ai-memory HTTP server; starting another
    // `serve` process would contend for the data-dir lock. Keep this at the
    // typed builder boundary so auth-enable and other internal callers cannot
    // accidentally request an unsupported direct entry.
    if (args.stdio_bridge || matches!(args.client, McpClient::Freebuff | McpClient::Qoder))
        && let Some(entry) = stdio_bridge_entry(args)
    {
        return Ok(entry);
    }
    match args.client {
        McpClient::OpenCode => build_mcp_entry_opencode(args),
        McpClient::OpenCode2 => build_mcp_entry_opencode2(args),
        McpClient::Openclaw => build_mcp_entry_openclaw(args),
        McpClient::Zero => build_mcp_entry_zero(args),
        McpClient::Zcode => build_mcp_entry_zcode(args),
        McpClient::Muse => build_mcp_entry_muse(args),
        McpClient::Cline => build_mcp_entry_cline(args),
        McpClient::Codex | McpClient::Grok => {
            bail!("internal: Codex/Grok MCP config is TOML, not JSON")
        }
        McpClient::Dsh => {
            bail!("internal: DeepSeek Harness MCP config is a Cordis YAML patch, not JSON")
        }
        McpClient::Hermes => {
            bail!("internal: Hermes Agent MCP config is ~/.hermes/config.yaml, not JSON")
        }
        _ => build_mcp_entry(args),
    }
}

fn migrate_opencode_mcp_entry(
    root: &mut serde_json::Map<String, serde_json::Value>,
    args: &InstallMcpArgs,
) -> Result<()> {
    if matches!(args.client, McpClient::OpenCode | McpClient::OpenCode2)
        && opencode_selected_entry(root, args.client, &args.name)
            .is_some_and(|entry| !opencode_mcp_entry_has_generated_shape(entry, args.client))
    {
        bail!(
            "refusing to replace user-owned OpenCode MCP entry '{}' in the selected major-version location",
            args.name
        );
    }
    let alternate = match args.client {
        McpClient::OpenCode => root
            .get("mcp")
            .and_then(serde_json::Value::as_object)
            .and_then(|mcp| mcp.get("servers"))
            .and_then(serde_json::Value::as_object)
            .and_then(|servers| servers.get(&args.name))
            .cloned(),
        McpClient::OpenCode2 => root
            .get("mcp")
            .and_then(serde_json::Value::as_object)
            .and_then(|mcp| mcp.get(&args.name))
            .cloned(),
        _ => None,
    };
    let Some(alternate) = alternate else {
        return Ok(());
    };
    if opencode_mcp_entry_has_generated_shape(
        &alternate,
        match args.client {
            McpClient::OpenCode => McpClient::OpenCode2,
            McpClient::OpenCode2 => McpClient::OpenCode,
            other => other,
        },
    ) && opencode_selected_entry(root, args.client, &args.name)
        .is_some_and(|entry| !opencode_mcp_entry_has_generated_shape(entry, args.client))
    {
        bail!(
            "refusing to replace a user-owned OpenCode MCP entry '{}' in the selected major-version location while migrating the generated alternate entry",
            args.name
        );
    }
    if !opencode_mcp_entry_is_owned(&alternate, args) {
        eprintln!(
            "[ai-memory] warning: preserving ambiguous OpenCode MCP entry '{}' in the alternate major-version location",
            args.name
        );
        return Ok(());
    }
    let mcp = root
        .get_mut("mcp")
        .and_then(serde_json::Value::as_object_mut)
        .context("`mcp` is present but not an object")?;
    match args.client {
        McpClient::OpenCode => {
            if let Some(servers) = mcp
                .get_mut("servers")
                .and_then(serde_json::Value::as_object_mut)
            {
                servers.remove(&args.name);
                if servers.is_empty() {
                    mcp.remove("servers");
                }
            }
        }
        McpClient::OpenCode2 => {
            mcp.remove(&args.name);
        }
        _ => {}
    }
    Ok(())
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct InferredOpenCodeMcpConfig {
    pub(crate) mcp_url: String,
    pub(crate) auth_token: Option<String>,
}

pub(crate) fn infer_owned_opencode_mcp_config(
    content: &str,
    selected: McpClient,
) -> Result<Option<InferredOpenCodeMcpConfig>> {
    let root: serde_json::Value = match serde_json::from_str(content) {
        Ok(root) => root,
        Err(_) => return Ok(None),
    };
    let v1_entry = root.pointer("/mcp/ai-memory");
    let v2_entry = root.pointer("/mcp/servers/ai-memory");
    let v1 = v1_entry.and_then(|entry| inferred_owned_opencode_entry(entry, McpClient::OpenCode));
    let v2 = v2_entry.and_then(|entry| inferred_owned_opencode_entry(entry, McpClient::OpenCode2));
    let selected_is_user_owned = match selected {
        McpClient::OpenCode => v1_entry.is_some() && v1.is_none(),
        McpClient::OpenCode2 => v2_entry.is_some() && v2.is_none(),
        _ => false,
    };
    let alternate_is_generated = match selected {
        McpClient::OpenCode => v2.is_some(),
        McpClient::OpenCode2 => v1.is_some(),
        _ => false,
    };
    if selected_is_user_owned && alternate_is_generated {
        bail!(
            "a user-owned OpenCode MCP entry occupies the selected major-version location while a generated entry remains in the alternate location; preserved both, pass explicit --server-url and --auth-token after resolving the conflict"
        );
    }
    match (v1, v2) {
        (Some(v1), Some(v2)) if v1 != v2 => bail!(
            "conflicting generated OpenCode MCP entries exist in the V1 and V2 locations; pass explicit --server-url and --auth-token before installing"
        ),
        (Some(v1), Some(_)) | (Some(v1), None) => Ok(Some(v1)),
        (None, Some(v2)) => Ok(Some(v2)),
        (None, None) => {
            let selected_entry = match selected {
                McpClient::OpenCode => root.pointer("/mcp/ai-memory"),
                McpClient::OpenCode2 => root.pointer("/mcp/servers/ai-memory"),
                _ => None,
            };
            if selected_entry.is_some() {
                eprintln!(
                    "[ai-memory] warning: preserving user-owned OpenCode MCP entry in the selected major-version location; pass explicit --server-url and --auth-token rather than inferring from it"
                );
            }
            Ok(None)
        }
    }
}

fn inferred_owned_opencode_entry(
    entry: &serde_json::Value,
    location: McpClient,
) -> Option<InferredOpenCodeMcpConfig> {
    if !opencode_mcp_entry_has_generated_shape(entry, location) {
        return None;
    }
    let object = entry.as_object()?;
    Some(InferredOpenCodeMcpConfig {
        mcp_url: entry_endpoint(entry)?.to_string(),
        auth_token: object
            .get("headers")
            .and_then(|headers| headers.get("Authorization"))
            .and_then(serde_json::Value::as_str)
            .and_then(|value| value.trim().strip_prefix("Bearer "))
            .map(str::trim)
            .filter(|value| !value.is_empty())
            .map(ToOwned::to_owned),
    })
}

fn opencode_selected_entry<'a>(
    root: &'a serde_json::Map<String, serde_json::Value>,
    client: McpClient,
    name: &str,
) -> Option<&'a serde_json::Value> {
    let mcp = root.get("mcp")?.as_object()?;
    match client {
        McpClient::OpenCode => mcp.get(name),
        McpClient::OpenCode2 => mcp.get("servers")?.as_object()?.get(name),
        _ => None,
    }
}

fn opencode_generated_headers(headers: Option<&serde_json::Value>) -> bool {
    let Some(headers) = headers else {
        return true;
    };
    let Some(headers) = headers.as_object() else {
        return false;
    };
    headers.len() == 1
        && headers
            .get("Authorization")
            .and_then(serde_json::Value::as_str)
            .is_some_and(|value| value.starts_with("Bearer ") && value.len() > "Bearer ".len())
}

fn opencode_mcp_entry_has_generated_shape(entry: &serde_json::Value, location: McpClient) -> bool {
    if bridge_entry_url(entry).is_some() {
        return opencode_bridge_entry_has_generated_shape(entry, location);
    }
    let Some(entry) = entry.as_object() else {
        return false;
    };
    if entry.get("type").and_then(serde_json::Value::as_str) != Some("remote")
        || entry
            .get("url")
            .and_then(serde_json::Value::as_str)
            .is_none()
    {
        return false;
    }
    let allowed = ["type", "url", "enabled", "oauth", "headers"];
    if entry.keys().any(|key| !allowed.contains(&key.as_str()))
        || !opencode_generated_headers(entry.get("headers"))
    {
        return false;
    }
    match location {
        McpClient::OpenCode => {
            entry.get("enabled").and_then(serde_json::Value::as_bool) == Some(true)
                && !entry.contains_key("oauth")
        }
        McpClient::OpenCode2 => {
            entry.get("oauth").and_then(serde_json::Value::as_bool) == Some(false)
                && !entry.contains_key("enabled")
        }
        _ => false,
    }
}

/// The stdio bridge entry `install-mcp` writes for OpenCode on a token-file
/// install: `type: "local"` and the `command` array, plus `enabled: true` in
/// the V1 location only.
fn opencode_bridge_entry_has_generated_shape(
    entry: &serde_json::Value,
    location: McpClient,
) -> bool {
    let Some(object) = entry.as_object() else {
        return false;
    };
    let allowed = ["type", "command", "enabled"];
    if object.get("type").and_then(serde_json::Value::as_str) != Some("local")
        || !object
            .get("command")
            .is_some_and(serde_json::Value::is_array)
        || object.keys().any(|key| !allowed.contains(&key.as_str()))
    {
        return false;
    }
    match location {
        McpClient::OpenCode => {
            object.get("enabled").and_then(serde_json::Value::as_bool) == Some(true)
        }
        McpClient::OpenCode2 => !object.contains_key("enabled"),
        _ => false,
    }
}

/// The endpoint an entry targets: its `url`, or a bridge entry's upstream.
fn entry_endpoint(entry: &serde_json::Value) -> Option<&str> {
    entry
        .get("url")
        .and_then(serde_json::Value::as_str)
        .or_else(|| {
            entry
                .pointer("/transport/url")
                .and_then(serde_json::Value::as_str)
        })
        .or_else(|| bridge_entry_url(entry))
}

fn opencode_mcp_entry_is_owned(entry: &serde_json::Value, args: &InstallMcpArgs) -> bool {
    let expected_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);
    entry_endpoint(entry) == Some(expected_url)
        && opencode_mcp_entry_has_generated_shape(
            entry,
            match args.client {
                McpClient::OpenCode => McpClient::OpenCode2,
                McpClient::OpenCode2 => McpClient::OpenCode,
                other => other,
            },
        )
}

fn upsert_json_mcp_entry(
    root: &mut serde_json::Map<String, serde_json::Value>,
    args: &InstallMcpArgs,
) -> Result<()> {
    let entry = build_json_mcp_entry(args)?;
    migrate_opencode_mcp_entry(root, args)?;
    match json_mcp_location(args.client).context("internal: unsupported JSON MCP client")? {
        JsonMcpLocation::RootMcpServers => {
            let servers = root
                .entry("mcpServers")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`mcpServers` is present but not an object")?;
            servers.insert(args.name.clone(), entry);
        }
        JsonMcpLocation::RootMcp => {
            let mcp = root
                .entry("mcp")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`mcp` is present but not an object")?;
            mcp.insert(args.name.clone(), entry);
        }
        JsonMcpLocation::NestedMcpServers => {
            let mcp = root
                .entry("mcp")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`mcp` is present but not an object")?;
            let servers = mcp
                .entry("servers")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`mcp.servers` is present but not an object")?;
            servers.insert(args.name.clone(), entry);
        }
        JsonMcpLocation::RootServers => {
            let servers = root
                .entry("servers")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`servers` is present but not an object")?;
            servers.insert(args.name.clone(), entry);
        }
        JsonMcpLocation::RootContextServers => {
            let servers = root
                .entry("context_servers")
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .context("`context_servers` is present but not an object")?;
            servers.insert(args.name.clone(), entry);
        }
        JsonMcpLocation::MuseServers => {
            let key = muse_servers_key(root)?;
            let entry = muse_entry_for_key(entry, key);
            let servers = root
                .entry(key)
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
                .as_object_mut()
                .with_context(|| format!("`{key}` is present but not an object"))?;
            servers.insert(args.name.clone(), entry);
        }
    }
    // Muse Code fails *every* command at startup when settings.json omits
    // `schema_version`, so creating the file without it would break the
    // user's agent rather than just their memory server. Only fill it in
    // when absent: an unrecognized value is Muse's own error to report,
    // and a future schema 2 must not be silently downgraded here.
    if matches!(args.client, McpClient::Muse) {
        root.entry("schema_version")
            .or_insert_with(|| serde_json::Value::from(1));
    }
    Ok(())
}

fn render_json_mcp_fragment(args: &InstallMcpArgs) -> Result<String> {
    let entry = build_json_mcp_entry(args)?;
    let fragment =
        match json_mcp_location(args.client).context("internal: unsupported JSON MCP client")? {
            JsonMcpLocation::RootMcpServers => json!({
                "mcpServers": { args.name.as_str(): entry }
            }),
            JsonMcpLocation::RootMcp => json!({
                "mcp": { args.name.as_str(): entry }
            }),
            JsonMcpLocation::NestedMcpServers => json!({
                "mcp": { "servers": { args.name.as_str(): entry } }
            }),
            JsonMcpLocation::RootServers => json!({
                "servers": { args.name.as_str(): entry }
            }),
            JsonMcpLocation::RootContextServers => json!({
                "context_servers": { args.name.as_str(): entry }
            }),
            // `schema_version` rides along: a hand-merged Muse settings.json
            // without it fails every command at startup, so the printed
            // snippet has to carry the key the same way --apply does.
            JsonMcpLocation::MuseServers => json!({
                "schema_version": 1,
                "mcpServers": { args.name.as_str(): entry }
            }),
        };
    Ok(serde_json::to_string_pretty(&fragment)?)
}

/// Append the `flavor=moonshot` marker to the MCP URL written into Kimi
/// Code's mcp.json: Moonshot's API 400s root-level `anyOf`/`oneOf`/`allOf`
/// in tool parameter schemas (issue #155's `anyOf` on `memory_read_page`),
/// and the server answers flavored requests with flat schemas. Idempotent
/// so re-runs never stack duplicate query pairs.
fn flavored_mcp_url(server_url: &str, flavor: &str) -> String {
    let marker = format!("flavor={flavor}");
    let url = server_url.trim();
    let already_marked = url
        .split_once('?')
        .is_some_and(|(_, query)| query.split('&').any(|pair| pair == marker));
    if already_marked {
        return url.to_string();
    }
    let separator = if url.contains('?') { '&' } else { '?' };
    format!("{url}{separator}{marker}")
}

/// Every marker `install-mcp` can write. `uninstall` walks this so an entry
/// installed with `--flavor` is still matched by URL; adding a flavor without
/// adding it here would leave those entries behind.
pub(crate) const FLAVOR_MARKERS: [&str; 3] = ["moonshot", "bedrock", "gemini"];

/// [`flavored_mcp_url`] for a marker already in hand — what `uninstall` needs
/// to rebuild each candidate URL form without knowing the flavor type.
pub(crate) fn flavored_mcp_url_for_marker(server_url: &str, marker: &str) -> String {
    flavored_mcp_url(server_url, marker)
}

/// The dialect a client always needs, from its name alone. Only clients with a
/// single fixed upstream appear here — Kimi Code is Moonshot, Kiro is Bedrock.
/// A client that fronts several models has no answer here and needs `--flavor`.
fn client_default_flavor(client: McpClient) -> Option<&'static str> {
    match client {
        McpClient::KimiCode => Some("moonshot"),
        McpClient::KiroCli => Some("bedrock"),
        _ => None,
    }
}

/// The URL to write into the client config: the endpoint plus whichever
/// `?flavor=` marker applies. An explicit `--flavor` wins over the client's
/// built-in default, which is safe in one direction only by construction —
/// every flavor is at least as permissive as any default, so an override can
/// relax the advertised schema but never tighten it past what the client needs.
pub(crate) fn flavored_url_for(args: &InstallMcpArgs, server_url: &str) -> String {
    match args
        .flavor
        .map(SchemaFlavor::marker)
        .or_else(|| client_default_flavor(args.client))
    {
        Some(marker) => flavored_mcp_url(server_url, marker),
        None => server_url.to_string(),
    }
}

/// JSON entry shape used by Claude Code, Claude Desktop, Cursor, and
/// Gemini CLI — they all accept `mcpServers.<name>` with `url` or
/// `httpUrl` plus optional `headers`. Returns the per-client variant.
fn build_mcp_entry(args: &InstallMcpArgs) -> Result<serde_json::Value> {
    let bearer = bearer_header_value(args.auth_token.as_deref());
    // `run()` resolves the URL before dispatch; the fallback only fires for
    // direct callers (tests, uninstall re-render) that skip that step.
    let base_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);
    // The flavor marker is a `tools/list` concern, so it belongs on the URL a
    // client fetches schemas from. `mcp-bridge` is not that: it is our own
    // process, and it re-derives its endpoint, so it keeps the bare URL.
    let flavored = flavored_url_for(args, base_url);
    let server_url = flavored.as_str();
    let mut entry = serde_json::Map::new();
    match args.client {
        McpClient::ClaudeCode => {
            if args.session_aware {
                entry.insert("type".into(), json!("stdio"));
                entry.insert("command".into(), json!(bridge_command()));
                let mut argv = vec![
                    "mcp-bridge".to_owned(),
                    "--server-url".to_owned(),
                    base_url.to_owned(),
                ];
                argv.extend(bridge_data_dir_args(args));
                entry.insert("args".into(), json!(argv));
                if let Some(token) = &args.auth_token {
                    entry.insert("env".into(), json!({"AI_MEMORY_AUTH_TOKEN": token}));
                }
            } else {
                entry.insert("type".into(), json!("http"));
                entry.insert("url".into(), json!(server_url));
                if let Some(b) = &bearer {
                    entry.insert("headers".into(), json!({"Authorization": b}));
                }
            }
        }
        McpClient::ClaudeDesktop => {
            // Stdio shim via mcp-remote — Claude Desktop's JSON
            // doesn't accept HTTP transport directly.
            let mut cmd_args = vec![json!("-y"), json!("mcp-remote"), json!(server_url)];
            if let Some(b) = &bearer {
                cmd_args.push(json!("--header"));
                cmd_args.push(json!("Authorization:${AI_MEMORY_AUTH_HEADER}"));
                entry.insert("env".into(), json!({"AI_MEMORY_AUTH_HEADER": b}));
            }
            entry.insert("command".into(), json!("npx"));
            entry.insert("args".into(), serde_json::Value::Array(cmd_args));
        }
        McpClient::Cursor | McpClient::Zed => {
            entry.insert("url".into(), json!(server_url));
            if let Some(b) = &bearer {
                entry.insert("headers".into(), json!({"Authorization": b}));
            }
        }
        McpClient::GeminiCli | McpClient::QwenCode => {
            // Qwen Code uses the same `httpUrl` field as Gemini CLI for
            // streamable HTTP; the plain `url` key is legacy SSE
            // (<https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/>).
            entry.insert("httpUrl".into(), json!(server_url));
            entry.insert("timeout".into(), json!(GEMINI_MCP_TIMEOUT_MS));
            if let Some(b) = &bearer {
                entry.insert("headers".into(), json!({"Authorization": b}));
            }
        }
        McpClient::Omp => {
            entry.insert("type".into(), json!("http"));
            entry.insert("url".into(), json!(server_url));
            entry.insert("enabled".into(), json!(true));
            if let Some(b) = &bearer {
                entry.insert("headers".into(), json!({"Authorization": b}));
            }
        }
        McpClient::AntigravityCli => {
            entry.insert("serverUrl".into(), json!(server_url));
            entry.insert("timeout".into(), json!(GEMINI_MCP_TIMEOUT_MS));
            if let Some(b) = &bearer {
                entry.insert("headers".into(), json!({"Authorization": b}));
            }
        }
        McpClient::Devin => {
            entry.insert("url".into(), json!(server_url));
            entry.insert("transport".into(), json!("http"));
            if let Some(b) = &bearer {
                entry.insert("headers".into(), json!({"Authorization": b}));
            }
        }
        McpClient::KimiCode => {
            // Kimi Code treats an entry with `url` and no `transport`
            // field as streamable-HTTP; `transport` is only for legacy
            // SSE endpoints.
            entry.insert("url".into(), json!(server_url));
            if let Some(b) = &bearer {
                entry.insert("headers".into(), json!({"Authorization": b}));
            }
        }
        McpClient::KiroCli => {
            entry.insert("url".into(), json!(server_url));
            if let Some(b) = &bearer {
                entry.insert("headers".into(), json!({"Authorization": b}));
            }
        }
        McpClient::CommandCode => {
            entry.insert("transport".into(), json!("http"));
            entry.insert("enabled".into(), json!(true));
            entry.insert("url".into(), json!(server_url));
            if let Some(b) = &bearer {
                entry.insert("headers".into(), json!({"Authorization": b}));
            }
        }
        McpClient::IbmBob => {
            // Bob's HTTP client sends a non-standard `server/discover` probe
            // in automatic mode. ai-memory implements the MCP initialize
            // handshake, so pin Bob to its documented legacy negotiation path.
            entry.insert("type".into(), json!("streamable-http"));
            entry.insert("url".into(), json!(server_url));
            entry.insert("protocolNegotiation".into(), json!("legacy"));
            if let Some(b) = &bearer {
                entry.insert("headers".into(), json!({"Authorization": b}));
            }
        }
        McpClient::Swival => {
            // Swival .swival/mcp.json entry: `type: "http"` + `url` +
            // optional headers (documented format).
            entry.insert("type".into(), json!("http"));
            entry.insert("url".into(), json!(server_url));
            if let Some(b) = &bearer {
                entry.insert("headers".into(), json!({"Authorization": b}));
            }
        }
        McpClient::VsCodeCopilot => {
            // VS Code MCP framework schema: `type: "http"` + `url`,
            // headers map for auth. Verified against
            // https://code.visualstudio.com/docs/agents/reference/mcp-configuration.
            // The `mcpServers` key (used by Claude Code/Cursor/Gemini)
            // is silently ignored here — VS Code reads `servers`.
            entry.insert("type".into(), json!("http"));
            entry.insert("url".into(), json!(server_url));
            if let Some(b) = &bearer {
                entry.insert("headers".into(), json!({"Authorization": b}));
            }
        }
        McpClient::CopilotCli => {
            // Copilot CLI's `mcp-config.json` remote entry: `type: "http"` +
            // `url`, optional `headers`, and `tools`, written as `["*"]` (all
            // tools — Copilot's documented default and its own example).
            // Verified against
            // https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.
            entry.insert("type".into(), json!("http"));
            entry.insert("url".into(), json!(server_url));
            if let Some(b) = &bearer {
                entry.insert("headers".into(), json!({"Authorization": b}));
            }
            entry.insert("tools".into(), json!(["*"]));
        }
        McpClient::Droid => {
            // Droid's `mcp.json` HTTP entry: `type: "http"` + `url`, optional
            // `headers`. Droid expands a bare `${NAME}` only inside
            // `headers` (and stdio env / OAuth fields), never in `url`, so
            // the URL stays literal and the bearer is referenced by name,
            // which also keeps the token out of the file (#1240).
            entry.insert("type".into(), json!("http"));
            entry.insert("url".into(), json!(server_url));
            if args.auth_token.is_some() || args.token_env_var {
                entry.insert(
                    "headers".into(),
                    json!({"Authorization": format!("Bearer ${{{PRIME_AGENT_TOKEN_ENV}}}")}),
                );
            }
        }
        McpClient::PrimeAgent => {
            // Prime Agent 0.10 counts a user HTTP server as connected, and
            // names it to the model, only with an OAuth grant or a
            // `bearerTokenEnvVar` whose variable is set; a literal
            // `headers.Authorization` still dispatches but stays unlisted.
            // So the token is referenced by variable, which also keeps it
            // out of settings.json. The camelCase key is the one Prime
            // Agent's loader reads (its own `mcp add` writes snake_case,
            // which is ignored).
            entry.insert("type".into(), json!("http"));
            entry.insert("url".into(), json!(server_url));
            if args.auth_token.is_some() || args.token_env_var {
                entry.insert("bearerTokenEnvVar".into(), json!(PRIME_AGENT_TOKEN_ENV));
            }
        }
        McpClient::Cline | McpClient::Freebuff => {
            bail!("internal: client has a dedicated MCP entry builder")
        }
        _ => bail!("internal: build_mcp_entry called for unsupported client"),
    }
    Ok(serde_json::Value::Object(entry))
}

fn build_mcp_entry_opencode(args: &InstallMcpArgs) -> Result<serde_json::Value> {
    let bearer = bearer_header_value(args.auth_token.as_deref());
    let base_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);
    // `--flavor` is a `tools/list` concern, so it rides on the URL OpenCode
    // fetches schemas from — the same place `build_mcp_entry` puts it. The
    // flag's own documentation names an OpenCode install routed to Vertex.
    let server_url = flavored_url_for(args, base_url);
    let mut entry = serde_json::Map::new();
    entry.insert("type".into(), json!("remote"));
    entry.insert("url".into(), json!(server_url));
    entry.insert("enabled".into(), json!(true));
    if let Some(b) = bearer {
        entry.insert("headers".into(), json!({"Authorization": b}));
    }
    Ok(serde_json::Value::Object(entry))
}

/// Cline's MCP entry uses top-level transport fields. Keeping the explicit
/// `streamableHttp` discriminator is load-bearing: a bare `url` is parsed as
/// legacy SSE and sends GET requests to ai-memory's POST-only MCP endpoint.
fn build_mcp_entry_cline(args: &InstallMcpArgs) -> Result<serde_json::Value> {
    let base_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);
    let mut entry = serde_json::Map::new();
    entry.insert("type".into(), json!("streamableHttp"));
    entry.insert("url".into(), json!(flavored_url_for(args, base_url)));
    if let Some(bearer) = bearer_header_value(args.auth_token.as_deref()) {
        entry.insert("headers".into(), json!({"Authorization": bearer}));
    }
    entry.insert("disabled".into(), json!(false));
    entry.insert("autoApprove".into(), json!([]));
    Ok(serde_json::Value::Object(entry))
}

/// OpenCode V2 MCP entry: `type: "remote"` + `url` + optional
/// `headers` under `mcp.servers`. V2 has no `enabled` field (servers
/// connect unless `disabled: true`), and header-credentialed servers
/// must set `oauth: false` so V2 does not attempt OAuth discovery
/// against ai-memory's local endpoint
/// (https://opencode.ai/v2/docs/mcp-servers).
fn build_mcp_entry_opencode2(args: &InstallMcpArgs) -> Result<serde_json::Value> {
    let bearer = bearer_header_value(args.auth_token.as_deref());
    let base_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);
    let server_url = flavored_url_for(args, base_url);
    let mut entry = serde_json::Map::new();
    entry.insert("type".into(), json!("remote"));
    entry.insert("url".into(), json!(server_url));
    // `false`, not absence: without it the beta probes the endpoint for
    // OAuth metadata on every connect.
    entry.insert("oauth".into(), json!(false));
    if let Some(b) = bearer {
        entry.insert("headers".into(), json!({"Authorization": b}));
    }
    Ok(serde_json::Value::Object(entry))
}

fn build_mcp_entry_openclaw(args: &InstallMcpArgs) -> Result<serde_json::Value> {
    let bearer = bearer_header_value(args.auth_token.as_deref());
    let server_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);
    let mut entry = serde_json::Map::new();
    entry.insert("url".into(), json!(server_url));
    entry.insert("transport".into(), json!("streamable-http"));
    if let Some(b) = bearer {
        entry.insert("headers".into(), json!({"Authorization": b}));
    }
    Ok(serde_json::Value::Object(entry))
}

/// Zero (Gitlawb/zero) MCP entry: native HTTP transport with optional
/// bearer headers — `internal/config/types.go`'s `MCPServerConfig` accepts
/// `type: "http"` + `url` + a `headers` map (issue #156).
fn build_mcp_entry_zero(args: &InstallMcpArgs) -> Result<serde_json::Value> {
    let bearer = bearer_header_value(args.auth_token.as_deref());
    let server_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);
    let mut entry = serde_json::Map::new();
    entry.insert("type".into(), json!("http"));
    entry.insert("url".into(), json!(server_url));
    if let Some(b) = bearer {
        entry.insert("headers".into(), json!({"Authorization": b}));
    }
    Ok(serde_json::Value::Object(entry))
}

/// ZCode MCP entry: `type: "http"` + `url` + optional `headers` under
/// `~/.zcode/cli/config.json`'s `mcp.servers` map. ZCode's entry schema
/// is strict — an entry carrying any key outside `type`/`url`/`headers`/
/// `enabled`/`timeoutMs` is dropped silently — so this deliberately
/// emits nothing else (issue #511).
fn build_mcp_entry_zcode(args: &InstallMcpArgs) -> Result<serde_json::Value> {
    let bearer = bearer_header_value(args.auth_token.as_deref());
    let server_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);
    let mut entry = serde_json::Map::new();
    entry.insert("type".into(), json!("http"));
    entry.insert("url".into(), json!(server_url));
    if let Some(b) = bearer {
        entry.insert("headers".into(), json!({"Authorization": b}));
    }
    Ok(serde_json::Value::Object(entry))
}

/// Muse Code MCP entry, in the `mcpServers` shape: a stdio
/// `ai-memory mcp-bridge --agent muse` that forwards the `MUSE_SESSION_ID`
/// Muse gives its stdio servers as the actor session id, so unscoped calls
/// follow the session's own project. A streamable-HTTP entry would carry no
/// session id at all. [`muse_entry_for_key`] renames `type` to `transport`
/// for a file that keeps the legacy `mcp_servers` map.
///
/// Muse starts stdio servers with a cleared environment, so the entry names
/// the install's data dir (`--data-dir`, when [`InstallMcpArgs::bridge_data_dir`]
/// is set) and the bridge reads its bearer from that install's config
/// (`[auth].bearer_token_file`) at launch; a token given explicitly is
/// passed in `env` the way Claude Code's session-aware entry carries it,
/// unless `--apply` stored it in that data dir for the bridge. `mode` is written
/// explicitly because Muse defaults it to `required`, which aborts the whole
/// run when the server cannot start; ai-memory augments a session and must
/// never gate it.
fn build_mcp_entry_muse(args: &InstallMcpArgs) -> Result<serde_json::Value> {
    let base_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);
    let mut entry = serde_json::Map::new();
    entry.insert("type".into(), json!("stdio"));
    entry.insert("command".into(), json!(bridge_command()));
    let mut argv = vec![
        json!("mcp-bridge"),
        json!("--agent"),
        json!("muse"),
        json!("--server-url"),
        json!(base_url),
    ];
    argv.extend(bridge_data_dir_args(args).into_iter().map(|arg| json!(arg)));
    entry.insert("args".into(), serde_json::Value::Array(argv));
    if let Some(token) = &args.auth_token {
        entry.insert("env".into(), json!({"AI_MEMORY_AUTH_TOKEN": token}));
    }
    entry.insert("mode".into(), json!("optional"));
    Ok(serde_json::Value::Object(entry))
}

/// The server map a Muse settings file takes ai-memory's entry under: the
/// legacy `mcp_servers` when the file already has it, else `mcpServers`.
/// Muse drops its whole MCP block when both keys are present, so adding the
/// second would disconnect every server the user has; a file that already
/// holds both is refused.
///
/// # Errors
/// Both keys are present.
fn muse_servers_key(root: &serde_json::Map<String, serde_json::Value>) -> Result<&'static str> {
    match (
        root.contains_key("mcpServers"),
        root.contains_key("mcp_servers"),
    ) {
        (true, true) => bail!(
            "this Muse settings file has both `mcpServers` and `mcp_servers`, and Muse ignores \
             every MCP server when both are present. Move the servers into one of the two maps \
             and re-run this command."
        ),
        (false, true) => Ok("mcp_servers"),
        _ => Ok("mcpServers"),
    }
}

/// [`build_mcp_entry_muse`]'s entry for the map it goes under: the legacy
/// `mcp_servers` names the transport `transport`, `mcpServers` names it
/// `type`.
fn muse_entry_for_key(entry: serde_json::Value, key: &str) -> serde_json::Value {
    let serde_json::Value::Object(mut entry) = entry else {
        return entry;
    };
    if key == "mcp_servers"
        && let Some(kind) = entry.remove("type")
    {
        entry.insert("transport".into(), kind);
    }
    serde_json::Value::Object(entry)
}

/// Insert / replace `[mcp_servers.<name>]` in a Codex `config.toml`.
///
/// Codex parses both forms (block-style `[mcp_servers.foo]` and the
/// dotted-inline `mcp_servers = { foo = { ... } }`), but its docs show
/// the block form and that's the only one humans want to read. This
/// helper canonicalises to the block form even when the file currently
/// stores `mcp_servers` as an inline table — siblings are preserved.
fn codex_upsert_mcp_server(
    doc: &mut toml_edit::DocumentMut,
    args: &InstallMcpArgs,
) -> anyhow::Result<()> {
    use toml_edit::{Item, Table, value};

    // Build our `[mcp_servers.<name>]` as a block-style table.
    //
    // IMPORTANT: Codex's MCP schema (verified against
    // `openai/codex/codex-rs/config/src/mcp_types.rs`) draws a hard
    // line between transports. For STREAMABLE_HTTP (which ai-memory
    // uses — `url = "...mcp"` triggers this transport), the
    // allowed auth-related keys are:
    //
    //   bearer_token_env_var  string  env-var NAME holding the token
    //   http_headers          table   static headers map
    //   env_http_headers      table   header_name → env_var_name
    //
    // `bearer_token` (literal) is rejected with
    //   "bearer_token is not supported for streamable_http"
    // — it's a stdio-transport-only key. Confusingly the field
    // sits in the same struct, but throw_if_set guards it for
    // streamable_http.
    //
    // We use [mcp_servers.<name>.http_headers] with a literal
    // Authorization header. Static, no env-var dance required.
    //
    // History note (so the next maintainer doesn't repeat this):
    //   - v1: emitted `[mcp_servers.X.headers]` — wrong key name
    //     entirely, Codex silently ignored it and fell back to
    //     OAuth ("Run `codex mcp login <name>`").
    //   - v2: switched to top-level `bearer_token = "..."` — also
    //     wrong; Codex rejects this for streamable_http with the
    //     "bearer_token is not supported" error.
    //   - v3 (this): `[mcp_servers.X.http_headers]` with
    //     `Authorization = "Bearer ..."`. Codex schema-validates
    //     and uses it as a static auth header.
    // Read before the server table is replaced: per-tool approval
    // overrides the user already chose survive a re-install.
    let tools = codex_tool_approvals(
        doc.get("mcp_servers")
            .and_then(|servers| servers.get(&args.name))
            .and_then(|server| server.get("tools")),
    );
    let mut server = Table::new();
    server["url"] = value(args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL));
    // Auto-approve ai-memory's tool calls. Without this, Codex
    // prompts on EVERY tool invocation ("approve memory_query?"
    // "approve memory_briefing?" …) which makes the MCP unusable
    // for an auto-capture workflow. The valid values per Codex's
    // config reference are "auto" / "prompt" / "writes" /
    // "approve" — `approve` means "no prompt, just run it". The
    // tools annotated destructive get a per-tool
    // `[mcp_servers.X.tools.<tool>] approval_mode = "prompt"`
    // override below (`codex_tool_approvals`).
    // https://developers.openai.com/codex/config-reference
    // (`mcp_servers.<id>.default_tools_approval_mode`,
    // `mcp_servers.<id>.tools.<tool>.approval_mode`).
    server["default_tools_approval_mode"] = value("approve");
    if args.token_env_var {
        server["bearer_token_env_var"] = value(PRIME_AGENT_TOKEN_ENV);
    } else if let Some(b) = bearer_header_value(args.auth_token.as_deref()) {
        let mut headers = Table::new();
        headers["Authorization"] = value(b);
        server["http_headers"] = Item::Table(headers);
    }
    server.insert("tools", Item::Table(tools));

    upsert_toml_mcp_server(doc, &args.name, server);
    Ok(())
}

/// Codex `[mcp_servers.<name>.tools]`: the user's existing per-tool entries,
/// copied as plain keys, plus `approval_mode = "prompt"` for every tool
/// annotated destructive that has no approval mode yet. The server-wide
/// default stays `approve`, so the read tools never prompt, while every tool
/// annotated destructive asks first.
fn codex_tool_approvals(existing: Option<&toml_edit::Item>) -> toml_edit::Table {
    use toml_edit::{Item, Table, value};

    let mut tools = Table::new();
    tools.set_implicit(true);
    if let Some(existing) = existing.and_then(Item::as_table_like) {
        for (tool, entry) in existing.iter() {
            let Some(entry) = entry.as_table_like() else {
                continue;
            };
            let mut copy = Table::new();
            for (key, item) in entry.iter() {
                if let Some(value) = item.as_value() {
                    copy.insert(key, Item::Value(value.clone()));
                }
            }
            tools.insert(tool, Item::Table(copy));
        }
    }
    for tool in ai_memory_mcp::AiMemoryServer::destructive_tool_names() {
        if !tools.contains_key(&tool) {
            tools.insert(&tool, Item::Table(Table::new()));
        }
        if let Some(entry) = tools.get_mut(&tool).and_then(Item::as_table_mut)
            && !entry.contains_key("approval_mode")
        {
            entry.insert("approval_mode", value("prompt"));
        }
    }
    tools
}

/// Insert / replace `[mcp_servers.<name>]` in a Grok `config.toml`.
///
/// Grok's schema (user-guide § MCP Servers) uses:
/// - `url` for native HTTP/SSE
/// - optional `enabled = true`
/// - `[mcp_servers.<name>.headers]` for static headers (NOT Codex's
///   `http_headers` key — wrong key is silently ignored by Grok)
///
/// Sibling servers are preserved; storage is canonicalised to block form
/// even when the file currently holds an inline `mcp_servers` table.
fn grok_upsert_mcp_server(
    doc: &mut toml_edit::DocumentMut,
    args: &InstallMcpArgs,
) -> anyhow::Result<()> {
    use toml_edit::{Item, Table, value};

    let mut server = Table::new();
    if args.stdio_bridge {
        // Grok picks stdio from `command` (and HTTP from `url`).
        server["command"] = value(bridge_command());
        server["args"] = value(
            session_less_bridge_args(args)
                .iter()
                .map(String::as_str)
                .collect::<toml_edit::Array>(),
        );
        server["enabled"] = value(true);
        upsert_toml_mcp_server(doc, &args.name, server);
        return Ok(());
    }
    server["url"] = value(args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL));
    server["enabled"] = value(true);
    if let Some(b) = bearer_header_value(args.auth_token.as_deref()) {
        let mut headers = Table::new();
        headers["Authorization"] = value(b);
        server["headers"] = Item::Table(headers);
    }

    upsert_toml_mcp_server(doc, &args.name, server);
    Ok(())
}

/// Replace one server while preserving siblings and canonicalising an inline
/// `mcp_servers` map to block-form TOML tables.
fn upsert_toml_mcp_server(doc: &mut toml_edit::DocumentMut, name: &str, server: toml_edit::Table) {
    use toml_edit::{Item, Table, Value};

    let preserved: Vec<(String, Item)> = match doc.get("mcp_servers") {
        Some(Item::Table(table)) => table
            .iter()
            .filter(|(key, _)| *key != name)
            .map(|(key, value)| (key.to_string(), value.clone()))
            .collect(),
        Some(Item::Value(Value::InlineTable(table))) => table
            .iter()
            .filter(|(key, _)| *key != name)
            .map(|(key, value)| (key.to_string(), Item::Value(value.clone())))
            .collect(),
        _ => Vec::new(),
    };

    let mut parent = Table::new();
    parent.set_implicit(true);
    for (k, v) in preserved {
        parent.insert(&k, v);
    }
    parent.insert(name, Item::Table(server));

    doc.insert("mcp_servers", Item::Table(parent));
}

fn render_claude_code(args: &InstallMcpArgs, config_path: &Path) -> Result<String> {
    let bearer = bearer_header_value(args.auth_token.as_deref());
    let cli_line = if args.session_aware {
        let env = args
            .auth_token
            .as_deref()
            .map(|token| format!(" --env \"AI_MEMORY_AUTH_TOKEN={token}\""))
            .unwrap_or_default();
        let data_dir = args
            .bridge_data_dir
            .as_ref()
            .map_or_else(String::new, |path| {
                format!(" --data-dir {}", shell_quote(&path.to_string_lossy()))
            });
        format!(
            "claude mcp add --transport stdio{env} {name} -- \\\n    {command} mcp-bridge --server-url {url}{data_dir}",
            name = args.name,
            command = shell_quote(&bridge_command()),
            url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL),
            data_dir = data_dir,
        )
    } else if let Some(b) = &bearer {
        format!(
            "claude mcp add --transport http {name} {url} \\\n    --header \"Authorization: {b}\"",
            name = args.name,
            url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL),
            b = b,
        )
    } else {
        format!(
            "claude mcp add --transport http {name} {url}",
            name = args.name,
            url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL),
        )
    };
    let snippet = render_json_mcp_fragment(args)?;
    Ok(format!(
        "# Claude Code — register the MCP server\n\
         #\n\
         # Recommended (one-shot CLI):\n\
         {cli_line}\n\
         #\n\
         # Equivalent JSON if you'd rather edit {config_path} directly:\n\
         {snippet}\n",
        config_path = config_path.display(),
    ))
}

fn render_codex(args: &InstallMcpArgs) -> Result<String> {
    // Codex uses TOML, not JSON. Build the printed table with the very
    // writer `--apply` uses (`codex_upsert_mcp_server`) so the snippet and
    // the file can never disagree. Hand-interpolating `[mcp_servers.{name}]`
    // made them disagree for any name TOML has to quote: `--name ai.memory`
    // printed a header that reads as `mcp_servers` -> `ai` -> `memory`, and
    // `--name "my memory"` printed an unparseable header that breaks the
    // whole `config.toml` it is pasted into -- while `--apply` wrote
    // `[mcp_servers."ai.memory"]` correctly all along. `render_grok` was
    // moved onto its writer for exactly this reason; Codex is the other
    // TOML client and was missed.
    //
    // The explanatory comments ride along as `toml_edit` decor, so the
    // snippet for an ordinary name is byte-for-byte what it always was.
    //
    // Schema: Codex's MCP `streamable_http` transport accepts
    //   - `bearer_token_env_var = "NAME"` (env-var indirection)
    //   - `[mcp_servers.<name>.http_headers]` (static headers)
    //   - `[mcp_servers.<name>.env_http_headers]` (env-var-sourced headers)
    // — NOT a literal `bearer_token = "..."` (that's stdio-only)
    // and NOT a `[mcp_servers.<name>.headers]` sub-table (the key
    // is `http_headers`, with the `http_` prefix).
    let mut doc = toml_edit::DocumentMut::new();
    codex_upsert_mcp_server(&mut doc, args)?;
    let server = doc
        .get_mut("mcp_servers")
        .and_then(toml_edit::Item::as_table_mut)
        .and_then(|servers| servers.get_mut(&args.name))
        .and_then(toml_edit::Item::as_table_mut)
        .context("internal: generated Codex TOML table missing")?;
    if let Some(mut key) = server.key_mut("default_tools_approval_mode") {
        key.leaf_decor_mut().set_prefix(
            "# Skip per-call approval prompts on ai-memory's read tools;\n\
             # the destructive ones below still ask first.\n",
        );
    }
    if let Some(headers) = server
        .get_mut("http_headers")
        .and_then(toml_edit::Item::as_table_mut)
    {
        headers.decor_mut().set_prefix("\n");
    }
    let mut out = String::from(
        "# Codex CLI — append to $CODEX_HOME/config.toml (default ~/.codex/config.toml)\n#\n",
    );
    out.push_str(&doc.to_string());
    // Trailing prose: `toml_edit` 0.22 has no document-trailer setter, and a
    // comment after the last key carries no TOML structure either way.
    if args.token_env_var {
        out.push_str(&format!(
            "# The token is read from ${PRIME_AGENT_TOKEN_ENV}; export it where you launch codex.\n"
        ));
    } else if bearer_header_value(args.auth_token.as_deref()).is_some() {
        out.push_str(
            "# Alternative (avoids embedding the literal token):\n\
             # bearer_token_env_var = \"AI_MEMORY_AUTH_TOKEN\"\n\
             # — and export AI_MEMORY_AUTH_TOKEN in your shell init.\n",
        );
    }
    Ok(out)
}

fn render_grok(args: &InstallMcpArgs) -> Result<String> {
    // Grok Build CLI uses TOML under ~/.grok/config.toml. Schema differs
    // from Codex: static auth lives under `.headers` (not `http_headers`),
    // and `enabled = true` is the documented toggle.
    let mut doc = toml_edit::DocumentMut::new();
    grok_upsert_mcp_server(&mut doc, args)?;
    let config_path = grok_home()?.join("config.toml");
    let mut out = format!(
        "# Grok Build CLI — append to {config_path}\n\
         #\n\
         # Native HTTP transport. Pair with:\n\
         #   ai-memory install-hooks --agent grok --apply\n\
         # for lifecycle capture. Grok ignores SessionStart stdout; the\n\
         # first PostToolUse injects the handoff, and --apply also writes\n\
         # the first-turn memory_handoff_list rule under $GROK_HOME/rules.\n\
         #\n\
         # CLI alternative:\n\
         #   grok mcp add --transport http {name} {url}\n\
         #\n\
         [mcp_servers.{name}]\n\
         url = \"{url}\"\n\
         enabled = true\n",
        name = args.name,
        url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL),
        config_path = config_path.display(),
    );
    let config_start = out
        .find("[mcp_servers.")
        .context("internal: generated Grok TOML table missing")?;
    out.truncate(config_start);
    out.push_str(&doc.to_string());
    Ok(out)
}

fn render_opencode(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# OpenCode — add to ~/.config/opencode/opencode.json under \"mcp\":\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_opencode2(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# OpenCode V2 (`opencode2` compatibility alias) — merge into\n\
         # ~/.config/opencode/opencode.json(c) under \"mcp\" → \"servers\":\n\
         #\n\
         # V2 nests servers under `mcp.servers` (V1 used direct `mcp`)\n\
         # and has no `enabled` field. Apply mode migrates an alternate V1\n\
         # entry only when its endpoint and generated shape prove ownership.\n\
         # If your config is `opencode.jsonc` with comments, re-run with\n\
         # `--config-file ~/.config/opencode/opencode.jsonc`.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_cursor(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# Cursor — write to one of:\n\
         #   - ~/.cursor/mcp.json   (global, all projects)\n\
         #   - .cursor/mcp.json     (per-project, in the workspace root)\n\
         #\n\
         # Cursor supports HTTP MCP servers via the `url` field. Restart\n\
         # Cursor (or toggle the server off+on in Settings → MCP) after\n\
         # adding a new entry; live reload landed in recent builds but\n\
         # is still flaky.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_claude_desktop(args: &InstallMcpArgs) -> Result<String> {
    // mcp-remote's --header flag is how we plumb the Authorization
    // through Claude Desktop's stdio-only config. Put the Bearer value
    // in env so Windows subprocess parsing never has to split a value
    // containing a space.
    Ok(format!(
        "# Claude Desktop — write to claude_desktop_config.json:\n\
         #   - macOS:    ~/Library/Application Support/Claude/claude_desktop_config.json\n\
         #   - Windows (unpackaged): %APPDATA%\\Claude\\claude_desktop_config.json\n\
         #   - Windows (MSIX):       %LOCALAPPDATA%\\Packages\\Claude_<id>\\LocalCache\\Roaming\\Claude\\claude_desktop_config.json\n\
         #     --apply detects the installed form; if multiple MSIX packages\n\
         #     are present, select the active one with --config-file.\n\
         #   - Linux (beta, Debian/Ubuntu): $XDG_CONFIG_HOME/Claude/claude_desktop_config.json\n\
         #               (default ~/.config/Claude/claude_desktop_config.json)\n\
         #\n\
         # Claude Desktop's JSON config does not support HTTP MCP servers\n\
         # directly. We bridge through the community `mcp-remote` stdio shim\n\
         # (https://www.npmjs.com/package/mcp-remote). Requires Node.js.\n\
         # After editing, fully quit + relaunch Claude Desktop; \"Check for\n\
         # Updates\" is not enough.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_gemini_cli(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# Gemini CLI — merge into ~/.gemini/settings.json:\n\
         #\n\
         # Gemini CLI uses `httpUrl` (not `url`) for streamable-HTTP\n\
         # endpoints. The `timeout` is in milliseconds.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_qwen_code(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# Qwen Code — merge into ~/.qwen/settings.json:\n\
         #\n\
         # Qwen Code uses `httpUrl` (not `url`) for streamable-HTTP\n\
         # endpoints; `url` is the legacy SSE transport. The `timeout` is\n\
         # in milliseconds. Pair with `ai-memory install-hooks --agent\n\
         # qwen-code --apply` for lifecycle capture.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_openclaw(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# OpenClaw — merge into ~/.openclaw/config.json:\n\
         #\n\
         # OpenClaw distinguishes transports explicitly. Use\n\
         # \"transport\": \"streamable-http\" for ai-memory's HTTP endpoint.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_zero(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# Zero (Gitlawb/zero) — merge into ~/.config/zero/config.json\n\
         # ($XDG_CONFIG_HOME/zero/config.json on non-default XDG setups),\n\
         # or run `zero mcp add` / re-run this command with --apply.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_zcode(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# ZCode (z.ai) — merge into ~/.zcode/cli/config.json\n\
         # (or re-run this command with --apply), then restart ZCode.\n\
         #\n\
         # The entry schema is strict: keys outside type/url/headers/\n\
         # enabled/timeoutMs make ZCode drop the server silently.\n\
         # ai-memory's default stateless /mcp endpoint needs no flavor\n\
         # marker; auth goes in the headers map.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_muse(args: &InstallMcpArgs) -> Result<String> {
    let token_note = if args.auth_token.is_some() {
        "# The entry carries the token in `env`; treat settings.json as\n\
         # sensitive (chmod 600).\n"
    } else {
        ""
    };
    Ok(format!(
        "# Meta Muse Code — merge into ${{XDG_CONFIG_HOME:-~/.config}}/muse/settings.json\n\
         # (or re-run this command with --apply), then start a new session.\n\
         #\n\
         # Keep \"schema_version\": 1 — without it every muse command fails\n\
         # at startup with `malformed settings file`.\n\
         #\n\
         # If the file already keeps its servers under the legacy `mcp_servers`\n\
         # map, put the entry there instead, with `\"transport\": \"stdio\"` in\n\
         # place of `\"type\": \"stdio\"`: Muse ignores every MCP server when both\n\
         # maps are present.\n\
         #\n\
         # The bridge forwards MUSE_SESSION_ID, so unscoped memory calls follow\n\
         # the session's project. mode is \"optional\" on purpose: Muse defaults\n\
         # it to \"required\", which aborts the whole run when the server cannot\n\
         # start. Pair with `ai-memory install-hooks --agent muse` for capture.\n\
         {token_note}\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_prime_agent(args: &InstallMcpArgs) -> Result<String> {
    let auth = if args.auth_token.is_some() || args.token_env_var {
        format!(
            "# The token is not written: the entry names ${PRIME_AGENT_TOKEN_ENV}\n\
             # (bearerTokenEnvVar), so export it where you launch prime-agent.\n\
             # Without it the server is disconnected and calls fail.\n"
        )
    } else {
        format!(
            "# Without a token Prime Agent 0.10 lists the server as not connected\n\
             # and leaves it out of the model's MCP prompt, though\n\
             # mcp.call_tool(\"{name}\", ...) still reaches it. Run the server\n\
             # with {PRIME_AGENT_TOKEN_ENV} and pass --auth-token to list it.\n",
            name = args.name,
        )
    };
    Ok(format!(
        "# Prime Agent - merge into $PRIME_AGENT_CODING_AGENT_DIR/settings.json\n\
         # (default ~/.prime/agent/settings.json), or re-run with --apply to\n\
         # merge it in place preserving other settings. A project's\n\
         # .prime/agent/settings.json also works: pass it via --config-file.\n\
         #\n\
         {auth}\
         #\n\
         # The model calls tools from its Python REPL:\n\
         #   await mcp.call_tool(\"{name}\", \"memory_query\", {{...}})\n\
         # MCP-only: Prime Agent has no lifecycle hooks to capture sessions.\n\
         {snippet}\n",
        name = args.name,
        snippet = render_json_mcp_fragment(args)?,
    ))
}

/// DeepSeek Harness (DSH) has no fixed JSON/TOML MCP config: the client is a
/// Cordis plugin entry inside a profile's cordis.patch.yml. Render the
/// patch-list fragment the operator merges by hand; --apply is refused.
fn render_dsh(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# DeepSeek Harness (DSH) - merge the entry below into the DSH\n\
         # profile patch at $DSH_HOME/profiles/<profile>/cordis.patch.yml,\n\
         # then reload the profile (the web profile reloads live).\n\
         #\n\
         # DSH has no fixed MCP config file: the client is a Cordis plugin\n\
         # entry, so this integration is print-only. A new top-level\n\
         # - insert: item is fine - patch row order carries no load\n\
         # semantics. This wires MCP only; no lifecycle capture.\n\
         {snippet}\n",
        snippet = render_dsh_snippet(args),
    ))
}

fn render_dsh_snippet(args: &InstallMcpArgs) -> String {
    // Single-quote every interpolated scalar: a plain YAML scalar would turn
    // a valid `--name 123` into an integer `serverName`, and a URL or token
    // carrying `"`, `\` or ` #` would no longer parse as one string.
    let name = yaml_single_quote(&args.name);
    let url = yaml_single_quote(args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL));
    let mut out = String::new();
    out.push_str("- insert:\n");
    out.push_str(&format!("    - id: {name}\n"));
    out.push_str("      name: '@deepseek-ai/dsh-mcp-client'\n");
    out.push_str("      config:\n");
    out.push_str(&format!("        serverName: {name}\n"));
    if args.stdio_bridge {
        out.push_str("        transport: stdio\n");
        out.push_str(&format!(
            "        command: {}\n",
            yaml_single_quote(&bridge_command())
        ));
        out.push_str("        args:\n");
        for arg in session_less_bridge_args(args) {
            out.push_str(&format!("          - {}\n", yaml_single_quote(&arg)));
        }
        out.push_str("        toolCallTimeoutMs: 120000");
        return out;
    }
    out.push_str("        transport: streamable-http\n");
    out.push_str(&format!("        url: {url}\n"));
    if let Some(value) = bearer_header_value(args.auth_token.as_deref()) {
        out.push_str("        headers:\n");
        out.push_str(&format!(
            "          Authorization: {}\n",
            yaml_single_quote(&value)
        ));
    }
    // Fixed at the value validated against DSH. Pending: candidate for a CLI
    // parameter (e.g. --tool-call-timeout-ms) if demand appears.
    out.push_str("        toolCallTimeoutMs: 120000");
    out
}

fn dsh_mcp_apply_guidance(args: &InstallMcpArgs) -> String {
    format!(
        "DeepSeek Harness has no fixed MCP config file; refusing to write MCP config. Re-run without --apply to print the Cordis patch fragment, then merge it into $DSH_HOME/profiles/<profile>/cordis.patch.yml{}",
        if args.auth_token.is_some() {
            " (the printed entry carries the auth header)."
        } else {
            "."
        }
    )
}

/// Hermes Agent reads MCP servers from the `mcp_servers:` map of
/// `~/.hermes/config.yaml` (`$HERMES_HOME/config.yaml`), keyed by server name
/// with `command`/`args` for a stdio server
/// (<https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp>,
/// v0.22.2). Print the entry to merge by hand; --apply is refused.
///
/// The entry is always the session-less stdio bridge. Hermes passes an MCP
/// server a filtered environment with no session id in it, so the client is
/// static, and a bridge keeps the bearer out of the file: it authenticates
/// with this install's own token.
fn render_hermes(args: &InstallMcpArgs) -> String {
    let token_note = if args.auth_token.is_some() {
        "#\n\
         # The token is not written here. The bridge sends this install's\n\
         # [auth].bearer_token or [auth].bearer_token_file; Hermes does not\n\
         # pass AI_MEMORY_AUTH_TOKEN from its own environment to MCP servers.\n"
    } else {
        ""
    };
    format!(
        "# Hermes Agent - merge the entry below into the `mcp_servers:` map of\n\
         # ~/.hermes/config.yaml ($HERMES_HOME/config.yaml), then restart\n\
         # Hermes; a running gateway reloads MCP servers within about a minute.\n\
         #\n\
         # Hermes does not read an MCP server's instructions, so the routing\n\
         # rules reach the model through the ai-memory skills\n\
         # (`ai-memory install-skills --scope global --agent hermes`, into\n\
         # ~/.hermes/skills) and the handoff `install-hooks --agent hermes`\n\
         # brings into the next primary-session turn.\n\
         {token_note}\
         {snippet}\n",
        snippet = render_hermes_snippet(args),
    )
}

fn render_hermes_snippet(args: &InstallMcpArgs) -> String {
    // Single-quote every scalar, as for DSH: a plain `--name 123` would key
    // the map with an integer, and a path with ` #` would be cut at the
    // comment.
    let mut out = String::from("mcp_servers:\n");
    out.push_str(&format!("  {}:\n", yaml_single_quote(&args.name)));
    out.push_str(&format!(
        "    command: {}\n",
        yaml_single_quote(&bridge_command())
    ));
    out.push_str("    args:");
    for arg in session_less_bridge_args(args) {
        out.push_str(&format!("\n      - {}", yaml_single_quote(&arg)));
    }
    out
}

/// Why `install-mcp --client hermes --apply` writes nothing, and what to do.
const HERMES_MCP_APPLY_GUIDANCE: &str = "Hermes Agent keeps MCP servers in ~/.hermes/config.yaml, a YAML file ai-memory does not edit; refusing to write MCP config. Re-run without --apply to print the mcp_servers entry, then merge it into ~/.hermes/config.yaml ($HERMES_HOME/config.yaml).";

fn render_pi(args: &InstallMcpArgs) -> Result<String> {
    Ok(pi_mcp_render_guidance(args))
}

fn pi_mcp_render_guidance(args: &InstallMcpArgs) -> String {
    format!(
        "# Pi has no native mcp.json. Do not write ~/.pi/agent/mcp.json.\n\
         # Install ai-memory's generated Pi extension instead; it includes\n\
         # lifecycle capture and an HTTP MCP bridge that registers tools in Pi.\n\
         ai-memory install-hooks --agent pi --apply --server-url {}{}\n\
         # The extension is installed at ~/.pi/agent/extensions/ai-memory-pi.ts by default.\n\
         # If PI_CODING_AGENT_DIR is set, it is at $PI_CODING_AGENT_DIR/extensions/ai-memory-pi.ts instead.\n\
         # Restart Pi after installing the extension.\n",
        hook_server_url_from_mcp_url(args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL)),
        if args.auth_token.is_some() {
            " --auth-token <token>"
        } else {
            ""
        }
    )
}

fn pi_mcp_apply_guidance(args: &InstallMcpArgs) -> String {
    format!(
        "Pi has no native mcp.json; refusing to write MCP config. Install the generated bridge instead: ai-memory install-hooks --agent pi --apply --server-url {}{}",
        hook_server_url_from_mcp_url(args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL)),
        if args.auth_token.is_some() {
            " --auth-token <token>"
        } else {
            ""
        }
    )
}

fn hook_server_url_from_mcp_url(url: &str) -> String {
    let trimmed = url.trim().trim_end_matches('/');
    trimmed.strip_suffix("/mcp").unwrap_or(trimmed).to_string()
}

fn render_omp(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# Oh My Pi / OMP — merge into mcp.json in OMP's agent dir:\n\
         # ~/.omp/agent/mcp.json by default, ~/.omp/profiles/<name>/agent/mcp.json\n\
         # under a named profile (OMP_PROFILE), or $PI_CODING_AGENT_DIR/mcp.json\n\
         # when that variable relocates the default profile.\n\
         #\n\
         # The current Oh My Pi package exposes the `omp` binary and native\n\
         # `.omp` config directories. Restart `omp` after changing MCP config.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_antigravity_cli(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# Antigravity CLI (`agy`) — merge into ~/.gemini/config/mcp_config.json:\n\
         #\n\
         # Antigravity CLI uses `serverUrl` (not `url` or `httpUrl`) for\n\
         # streamable-HTTP endpoints. The `timeout` is in milliseconds.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_devin(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# Devin CLI — merge into ~/.devin/config.json:\n\
         #\n\
         # Devin uses `mcpServers` with HTTP transport and optional Bearer auth.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_kimi_code(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# Kimi Code — merge into ~/.kimi-code/mcp.json\n\
         # ($KIMI_CODE_HOME/mcp.json when KIMI_CODE_HOME is set):\n\
         #\n\
         # An entry with `url` and no `transport` field is a streamable-HTTP\n\
         # server; `transport` is only needed for legacy SSE endpoints.\n\
         # `?flavor=moonshot`: Moonshot's API rejects root-level schema\n\
         # combinators; ai-memory serves flat schemas to flavored requests.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_kiro_cli(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# Kiro CLI - merge into $KIRO_HOME/settings/mcp.json\n\
         # (defaults to ~/.kiro/settings/mcp.json):\n\
         #\n\
         # Kiro accepts HTTPS remote endpoints and plain HTTP only on\n\
         # localhost. `?flavor=bedrock` removes unsupported root-level\n\
         # schema combinators while handler validation remains unchanged.\n\
         # Lifecycle capture is installed separately: use\n\
         # `install-hooks --agent kiro-cli` for v2 or the explicit\n\
         # `install-hooks --agent kiro-cli-v3` target for v3.\n\
         # Managed workstreams are not installed by this command.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_command_code(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# Command Code — merge into ~/.commandcode/mcp.json:\n\
         #\n\
         # The equivalent CLI registration is:\n\
         #   cmd mcp add --transport http --scope user {name} {url}\n\
         # (`cmdc` is the native Windows executable name.)\n\
         {snippet}\n",
        name = args.name,
        url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL),
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_ibm_bob(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# IBM Bob IDE — merge into ~/.bob/settings/mcp.json, or re-run with\n\
         # --apply to merge it in place preserving other servers. Bob also\n\
         # supports project-level .bob/mcp.json via --config-file.\n\
         # protocolNegotiation is set to legacy because Bob's automatic mode\n\
         # probes server/discover before the standard MCP initialize handshake.\n\
         # Pair with `ai-memory install-hooks --agent ibm-bob --apply` for\n\
         # lifecycle capture and automatic handoff delivery.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_copilot_cli(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# GitHub Copilot CLI — merge into $COPILOT_HOME/mcp-config.json\n\
         # (default ~/.copilot/mcp-config.json), or re-run with --apply to merge\n\
         # it in place preserving other servers. Project-level `.mcp.json` and\n\
         # `.github/mcp.json` also work: pass that path via --config-file.\n\
         #\n\
         # The equivalent CLI registration is:\n\
         #   copilot mcp add --transport http {name} {url}\n\
         # Pair with `ai-memory install-hooks --agent copilot-cli` for capture.\n\
         {snippet}\n",
        name = args.name,
        url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL),
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_droid(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# Factory Droid CLI — merge into ~/.factory/mcp.json, or re-run with\n\
         # --apply to merge it in place preserving other servers. A project's\n\
         # `.factory/mcp.json` also works: pass that path via --config-file.\n\
         #\n\
         # The equivalent CLI registration is:\n\
         #   droid mcp add {name} {url} --type http\n\
         # Droid expands ${{VAR}} only in headers, so the URL is literal and a\n\
         # bearer is read from ${env} where droid runs.\n\
         # Pair with `ai-memory install-hooks --agent droid` for capture.\n\
         {snippet}\n",
        name = args.name,
        url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL),
        env = PRIME_AGENT_TOKEN_ENV,
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_swival(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# Swival CLI — merge into .swival/mcp.json in the project root
         # (Swival's documented default lookup; project-scoped by design), or
         # re-run with --apply to merge it in place preserving other servers.
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_vscode_copilot(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# VS Code GitHub Copilot (agent mode) — write to one of:\n\
         #   - .vscode/mcp.json   (workspace, recommended — matches\n\
         #                         ai-memory's per-cwd auto-scoping)\n\
         #   - the user-profile mcp.json opened by VS Code's\n\
         #     `MCP: Open User Configuration` command\n\
         #\n\
         # VS Code's MCP framework uses `servers` (NOT `mcpServers`) as the\n\
         # top-level key, `type: \"http\"` for streamable-HTTP endpoints, and\n\
         # an inline `headers` map for Authorization. Copilot's agent mode\n\
         # reads this config along with any other MCP-capable VS Code\n\
         # extension. Toggle the server from the MCP view in the\n\
         # Extensions sidebar after editing.\n\
         #\n\
         # NOTE: VS Code Copilot does not yet expose lifecycle hooks\n\
         # (PreToolUse / PostToolUse / SessionStart), so ai-memory's\n\
         # automatic capture is NOT active here — call `memory_query`,\n\
         # `memory_write_page`, etc. from chat when you need them.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

fn render_zed(args: &InstallMcpArgs) -> Result<String> {
    Ok(format!(
        "# Zed - merge into settings.json:\n\
         #   - macOS:   ~/.config/zed/settings.json\n\
         #   - Linux:   $XDG_CONFIG_HOME/zed/settings.json\n\
         #              (defaults to ~/.config/zed/settings.json)\n\
         #   - Windows: %APPDATA%\\Zed\\settings.json\n\
         #\n\
         # Zed reads remote MCP servers from the top-level\n\
         # `context_servers` map. This is MCP-only: Zed does not expose\n\
         # ai-memory-compatible lifecycle hooks, so automatic capture and\n\
         # managed-workstream continuity are not active.\n\
         {snippet}\n",
        snippet = render_json_mcp_fragment(args)?,
    ))
}

#[cfg(test)]
mod tests {
    use super::*;
    use clap::Parser;
    use std::fs;
    use tempfile;

    fn args_for(client: McpClient) -> InstallMcpArgs {
        InstallMcpArgs {
            client,
            server_url: None,
            name: "ai-memory".into(),
            auth_token: None,
            apply: false,
            config_file: None,
            session_aware: false,
            flavor: None,
            token_env_var: false,
            stdio_bridge: false,
            bridge_data_dir: None,
        }
    }

    fn args_with_token(client: McpClient) -> InstallMcpArgs {
        InstallMcpArgs {
            client,
            server_url: None,
            name: "ai-memory".into(),
            auth_token: Some("test-token-deadbeef".into()),
            apply: false,
            config_file: None,
            session_aware: false,
            flavor: None,
            token_env_var: false,
            stdio_bridge: false,
            bridge_data_dir: None,
        }
    }

    #[test]
    fn cline_entry_explicitly_selects_streamable_http() {
        let entry = build_json_mcp_entry(&args_with_token(McpClient::Cline)).unwrap();
        assert_eq!(entry["type"], "streamableHttp");
        assert_eq!(entry["url"], "http://127.0.0.1:49374/mcp");
        assert_eq!(
            entry["headers"]["Authorization"],
            "Bearer test-token-deadbeef"
        );
        assert!(entry.get("transport").is_none(), "{entry:#}");
        assert_eq!(entry["disabled"], false);
        assert_eq!(entry["autoApprove"], json!([]));
    }

    #[test]
    fn cline_apply_replaces_the_old_nested_entry_and_preserves_siblings() {
        let tmp = tempfile::tempdir().unwrap();
        let file = tmp.path().join("cline_mcp_settings.json");
        fs::write(
            &file,
            json!({
                "mcpServers": {
                    "ai-memory": {
                        "transport": {
                            "type": "streamableHttp",
                            "url": "https://old.example/mcp"
                        },
                        "disabled": false,
                        "autoApprove": []
                    },
                    "other": {"command": "other"}
                },
                "keep": true
            })
            .to_string(),
        )
        .unwrap();
        let mut args = args_for(McpClient::Cline);
        args.apply = true;
        args.config_file = Some(file.clone());
        args.server_url = Some("https://memory.example/mcp".into());

        apply_to_config_file(&args).unwrap();
        let first = fs::read_to_string(&file).unwrap();
        apply_to_config_file(&args).unwrap();
        assert_eq!(first, fs::read_to_string(&file).unwrap());

        let root: serde_json::Value = serde_json::from_str(&first).unwrap();
        assert_eq!(root["keep"], true);
        assert_eq!(root["mcpServers"]["other"]["command"], "other");
        assert_eq!(
            root["mcpServers"]["ai-memory"],
            json!({
                "type": "streamableHttp",
                "url": "https://memory.example/mcp",
                "disabled": false,
                "autoApprove": []
            })
        );
    }

    #[test]
    fn freebuff_entry_uses_sessionless_bridge_not_a_second_server() {
        let mut args = args_for(McpClient::Freebuff);
        args.server_url = Some("https://memory.example/mcp".into());
        let entry = build_json_mcp_entry(&args).unwrap();
        assert_eq!(entry["command"], "ai-memory");
        assert_eq!(
            entry["args"],
            json!([
                "mcp-bridge",
                "--no-session-id",
                "--server-url",
                "https://memory.example/mcp"
            ])
        );
        assert_eq!(entry["env"], json!({}));
        assert!(
            !entry["args"]
                .as_array()
                .unwrap()
                .iter()
                .any(|arg| arg.as_str() == Some("serve"))
        );

        let mut authenticated = args_for(McpClient::Freebuff);
        authenticated.server_url = Some("https://memory.example/mcp".into());
        authenticated.auth_token = Some("explicit-token".into());
        authenticated.bridge_data_dir = Some(PathBuf::from("/srv/ai-memory"));
        let entry = build_json_mcp_entry(&authenticated).unwrap();
        assert_eq!(entry["env"]["AI_MEMORY_AUTH_TOKEN"], "explicit-token");
        assert_eq!(
            entry["args"],
            json!([
                "mcp-bridge",
                "--no-session-id",
                "--server-url",
                "https://memory.example/mcp",
                "--data-dir",
                "/srv/ai-memory"
            ])
        );
    }

    /// Droid's `mcp.json` HTTP entry (#1240): the URL is literal (Droid
    /// never expands variables there), and a configured bearer becomes the
    /// `${AI_MEMORY_AUTH_TOKEN}` reference Droid expands in headers, never
    /// the token itself. No bearer, no header.
    #[test]
    fn droid_entry_keeps_url_literal_and_references_the_token_variable() {
        let entry = build_json_mcp_entry(&args_with_token(McpClient::Droid)).unwrap();
        assert_eq!(
            entry,
            json!({
                "type": "http",
                "url": "http://127.0.0.1:49374/mcp",
                "headers": {"Authorization": "Bearer ${AI_MEMORY_AUTH_TOKEN}"},
            })
        );
        assert!(!entry.to_string().contains("test-token-deadbeef"));
        let plain = build_json_mcp_entry(&args_for(McpClient::Droid)).unwrap();
        assert_eq!(
            plain,
            json!({"type": "http", "url": "http://127.0.0.1:49374/mcp"})
        );
        let rendered = render_droid(&args_with_token(McpClient::Droid)).unwrap();
        assert!(rendered.contains("\"mcpServers\""), "{rendered}");
        assert!(rendered.contains("~/.factory/mcp.json"), "{rendered}");
        assert!(!rendered.contains("test-token-deadbeef"), "{rendered}");
    }

    /// `--apply` merges into `~/.factory/mcp.json`'s `mcpServers`, keeping
    /// other servers and top-level keys, and a re-run is a no-op.
    #[test]
    fn droid_apply_merges_into_mcp_servers_and_is_idempotent() {
        let tmp = tempfile::tempdir().unwrap();
        let file = tmp.path().join("mcp.json");
        std::fs::write(
            &file,
            json!({"mcpServers": {"other": {"type": "stdio", "command": "x"}}, "keep": 1})
                .to_string(),
        )
        .unwrap();
        let mut args = args_for(McpClient::Droid);
        args.apply = true;
        args.config_file = Some(file.clone());
        args.server_url = Some("http://memory:49374/mcp".into());
        apply_to_config_file(&args).unwrap();
        let first = std::fs::read_to_string(&file).unwrap();
        apply_to_config_file(&args).unwrap();
        assert_eq!(first, std::fs::read_to_string(&file).unwrap());
        let root: serde_json::Value = serde_json::from_str(&first).unwrap();
        assert_eq!(root["keep"], 1);
        assert_eq!(root["mcpServers"]["other"]["command"], "x");
        assert_eq!(
            root["mcpServers"]["ai-memory"],
            json!({"type": "http", "url": "http://memory:49374/mcp"})
        );
        assert_eq!(
            existing_entry_endpoint(McpClient::Droid, &file, "ai-memory").unwrap(),
            Some("http://memory:49374/mcp".into())
        );
    }

    #[test]
    fn droid_mcp_config_lives_under_dot_factory() {
        assert_eq!(
            factory_home(Path::new("/home/me")).join("mcp.json"),
            Path::new("/home/me/.factory/mcp.json")
        );
        if let Ok(path) = mcp_config_path(McpClient::Droid) {
            assert!(
                path.ends_with(Path::new(".factory").join("mcp.json")),
                "{}",
                path.display()
            );
        }
    }

    #[test]
    fn qwen_code_entry_uses_documented_http_url_shape() {
        assert_eq!(
            build_json_mcp_entry(&args_with_token(McpClient::QwenCode)).unwrap(),
            json!({
                "httpUrl": "http://127.0.0.1:49374/mcp",
                "timeout": 5000,
                "headers": {"Authorization": "Bearer test-token-deadbeef"},
            })
        );
        assert_eq!(
            build_json_mcp_entry(&args_for(McpClient::QwenCode)).unwrap(),
            json!({
                "httpUrl": "http://127.0.0.1:49374/mcp",
                "timeout": 5000,
            })
        );
        let path = mcp_config_path_with(McpClient::QwenCode, &|_| None).unwrap();
        assert!(
            path.ends_with(Path::new(".qwen/settings.json")),
            "{}",
            path.display()
        );
    }

    #[test]
    fn qwen_code_apply_preserves_siblings_and_is_idempotent() {
        let tmp = tempfile::tempdir().unwrap();
        let file = tmp.path().join("settings.json");
        fs::write(
            &file,
            json!({
                "mcpServers": {"other": {"command": "other"}},
                "hooks": {"PreToolUse": []},
                "keep": true
            })
            .to_string(),
        )
        .unwrap();
        let mut args = args_for(McpClient::QwenCode);
        args.config_file = Some(file.clone());
        args.server_url = Some("https://memory.example/mcp".into());
        apply_to_config_file(&args).unwrap();
        let first = fs::read_to_string(&file).unwrap();
        apply_to_config_file(&args).unwrap();
        assert_eq!(first, fs::read_to_string(&file).unwrap());
        let root: serde_json::Value = serde_json::from_str(&first).unwrap();
        assert_eq!(root["keep"], true);
        assert_eq!(root["hooks"]["PreToolUse"], json!([]));
        assert_eq!(root["mcpServers"]["other"]["command"], "other");
        assert_eq!(
            root["mcpServers"]["ai-memory"],
            json!({
                "httpUrl": "https://memory.example/mcp",
                "timeout": 5000,
            })
        );
        assert_eq!(
            existing_entry_endpoint(McpClient::QwenCode, &file, "ai-memory").unwrap(),
            Some("https://memory.example/mcp".into())
        );
    }

    #[test]
    fn ibm_bob_entry_uses_documented_legacy_streamable_http_shape() {
        assert_eq!(
            build_json_mcp_entry(&args_with_token(McpClient::IbmBob)).unwrap(),
            json!({
                "type": "streamable-http",
                "url": "http://127.0.0.1:49374/mcp",
                "protocolNegotiation": "legacy",
                "headers": {"Authorization": "Bearer test-token-deadbeef"},
            })
        );
        assert_eq!(
            build_json_mcp_entry(&args_for(McpClient::IbmBob)).unwrap(),
            json!({
                "type": "streamable-http",
                "url": "http://127.0.0.1:49374/mcp",
                "protocolNegotiation": "legacy",
            })
        );
        let path = mcp_config_path_with(McpClient::IbmBob, &|_| None).unwrap();
        assert!(
            path.ends_with(Path::new(".bob/settings/mcp.json")),
            "{}",
            path.display()
        );
    }

    #[test]
    fn ibm_bob_apply_preserves_siblings_and_is_idempotent() {
        let tmp = tempfile::tempdir().unwrap();
        let file = tmp.path().join("mcp.json");
        fs::write(
            &file,
            json!({
                "mcpServers": {"other": {"type": "stdio", "command": "other"}},
                "keep": true
            })
            .to_string(),
        )
        .unwrap();
        let mut args = args_for(McpClient::IbmBob);
        args.config_file = Some(file.clone());
        args.server_url = Some("https://memory.example/mcp".into());
        apply_to_config_file(&args).unwrap();
        let first = fs::read_to_string(&file).unwrap();
        apply_to_config_file(&args).unwrap();
        assert_eq!(first, fs::read_to_string(&file).unwrap());
        let root: serde_json::Value = serde_json::from_str(&first).unwrap();
        assert_eq!(root["keep"], true);
        assert_eq!(root["mcpServers"]["other"]["command"], "other");
        assert_eq!(
            root["mcpServers"]["ai-memory"],
            json!({
                "type": "streamable-http",
                "url": "https://memory.example/mcp",
                "protocolNegotiation": "legacy",
            })
        );
        assert_eq!(
            existing_entry_endpoint(McpClient::IbmBob, &file, "ai-memory").unwrap(),
            Some("https://memory.example/mcp".into())
        );
    }

    /// Muse's entry is the session-aware stdio bridge for `--agent muse`, so
    /// Muse forwards `MUSE_SESSION_ID`; a streamable-HTTP entry would carry no
    /// session id. `mode` is `optional` because Muse's default `required`
    /// aborts the whole run when the server cannot start. An explicit token
    /// rides `env`, never the command line.
    #[test]
    fn muse_entry_is_the_session_aware_bridge() {
        let entry = build_json_mcp_entry(&args_for(McpClient::Muse)).unwrap();
        assert_eq!(
            entry,
            json!({
                "type": "stdio",
                "command": bridge_command(),
                "args": ["mcp-bridge", "--agent", "muse", "--server-url", "http://127.0.0.1:49374/mcp"],
                "mode": "optional",
            })
        );
        let with_token = build_json_mcp_entry(&args_with_token(McpClient::Muse)).unwrap();
        assert_eq!(
            with_token["env"]["AI_MEMORY_AUTH_TOKEN"],
            "test-token-deadbeef"
        );
        assert!(
            !with_token["args"].to_string().contains("test-token"),
            "{with_token:#}"
        );
        assert!(bridge_entry_url(&entry).is_some());

        // Muse clears the environment of its stdio servers, so the install's
        // data dir rides the entry.
        let mut args = args_for(McpClient::Muse);
        args.bridge_data_dir = Some(PathBuf::from("/srv/ai-memory"));
        let baked = build_json_mcp_entry(&args).unwrap();
        assert_eq!(baked["args"][5], "--data-dir");
        assert_eq!(baked["args"][6], "/srv/ai-memory");
        assert_eq!(bridge_entry_url(&baked), Some("http://127.0.0.1:49374/mcp"));
    }

    #[test]
    fn muse_upsert_adds_schema_version_and_preserves_siblings() {
        let mut root = serde_json::Map::new();
        root.insert("telemetry".into(), json!({"enabled": false}));
        root.insert(
            "hooks".into(),
            json!({"Stop": [{"hooks": [{"type": "command", "command": "notify"}]}]}),
        );

        upsert_json_mcp_entry(&mut root, &args_for(McpClient::Muse)).unwrap();

        // Without this key every muse command fails at startup.
        assert_eq!(root["schema_version"], 1);
        assert_eq!(root["telemetry"]["enabled"], false);
        assert_eq!(root["hooks"]["Stop"][0]["hooks"][0]["command"], "notify");
        assert_eq!(root["mcpServers"]["ai-memory"]["type"], "stdio");
        assert!(!root.contains_key("mcp_servers"), "{root:#?}");
    }

    /// Adversarial: Muse drops every MCP server when `mcpServers` and the
    /// legacy `mcp_servers` are both present. A file that keeps the legacy
    /// map gets the entry there (in its `transport` spelling) and never a
    /// second map; a file that already has both is refused and left as it
    /// was. Control: a file with neither gets `mcpServers`.
    #[test]
    fn muse_upsert_writes_exactly_one_server_map() {
        let mut legacy = serde_json::Map::new();
        legacy.insert("schema_version".into(), json!(1));
        legacy.insert(
            "mcp_servers".into(),
            json!({"my-tools": {"transport": "stdio", "command": "my-mcp-server"}}),
        );
        upsert_json_mcp_entry(&mut legacy, &args_for(McpClient::Muse)).unwrap();
        assert!(!legacy.contains_key("mcpServers"), "{legacy:#?}");
        let ours = &legacy["mcp_servers"]["ai-memory"];
        assert_eq!(ours["transport"], "stdio");
        assert!(ours.get("type").is_none(), "{ours:#}");
        assert_eq!(ours["mode"], "optional");
        assert_eq!(
            legacy["mcp_servers"]["my-tools"]["command"],
            "my-mcp-server"
        );

        let mut both = serde_json::Map::new();
        both.insert("mcpServers".into(), json!({"a": {"type": "stdio"}}));
        both.insert("mcp_servers".into(), json!({"b": {"transport": "stdio"}}));
        let before = both.clone();
        let error = upsert_json_mcp_entry(&mut both, &args_for(McpClient::Muse)).unwrap_err();
        assert!(error.to_string().contains("both"), "{error:#}");
        assert_eq!(both, before, "a refused file is not touched");

        let mut empty = serde_json::Map::new();
        upsert_json_mcp_entry(&mut empty, &args_for(McpClient::Muse)).unwrap();
        assert!(empty.contains_key("mcpServers"));
        assert!(!empty.contains_key("mcp_servers"));
    }

    /// `--apply` against a real file: idempotent, keeps unknown keys and the
    /// user's own hooks, writes the bridge, and refuses (leaving the file
    /// byte-identical) when both server maps are present. The endpoint is read
    /// back from either map.
    #[test]
    fn muse_apply_is_idempotent_and_refuses_both_server_maps() {
        let tmp = tempfile::tempdir().unwrap();
        let file = tmp.path().join("settings.json");
        std::fs::write(
            &file,
            r#"{"schema_version":1,"theme":"dark","mcp_servers":{"x":{"transport":"stdio","command":"x"}}}"#,
        )
        .unwrap();
        let mut args = args_for(McpClient::Muse);
        args.apply = true;
        args.config_file = Some(file.clone());
        args.server_url = Some(DEFAULT_MCP_URL.into());
        apply_to_config_file(&args).unwrap();
        let first = std::fs::read_to_string(&file).unwrap();
        apply_to_config_file(&args).unwrap();
        assert_eq!(std::fs::read_to_string(&file).unwrap(), first);
        let root: serde_json::Value = serde_json::from_str(&first).unwrap();
        assert_eq!(root["theme"], "dark");
        assert_eq!(root["mcp_servers"]["ai-memory"]["args"][2], "muse");
        assert!(root.get("mcpServers").is_none());
        assert_eq!(
            existing_entry_endpoint(McpClient::Muse, &file, "ai-memory")
                .unwrap()
                .as_deref(),
            Some(DEFAULT_MCP_URL)
        );

        let both = tmp.path().join("both.json");
        let text = r#"{"schema_version":1,"mcpServers":{},"mcp_servers":{}}"#;
        std::fs::write(&both, text).unwrap();
        args.config_file = Some(both.clone());
        assert!(apply_to_config_file(&args).is_err());
        assert_eq!(std::fs::read_to_string(&both).unwrap(), text);
    }

    /// Muse resolves its settings under `XDG_CONFIG_HOME` when that is an
    /// absolute path, else under `~/.config`; a blank or relative value is
    /// ignored.
    #[test]
    fn muse_settings_path_follows_xdg_config_home() {
        let home = Some(PathBuf::from("/home/u"));
        assert_eq!(
            muse_settings_path_in(None, home.clone()).unwrap(),
            Path::new("/home/u/.config/muse/settings.json")
        );
        // Absolute on the host platform: a Unix-style root is relative on
        // Windows, where it would rightly be ignored.
        let xdg = if cfg!(windows) { r"C:\xdg" } else { "/xdg" };
        assert_eq!(
            muse_settings_path_in(Some(xdg.into()), home.clone()).unwrap(),
            Path::new(xdg).join("muse").join("settings.json")
        );
        for ignored in ["", "  ", "relative/dir"] {
            assert_eq!(
                muse_settings_path_in(Some(ignored.into()), home.clone()).unwrap(),
                Path::new("/home/u/.config/muse/settings.json"),
                "{ignored:?}"
            );
        }
        assert!(muse_settings_path_in(None, None).is_err());
        let xdg2 = if cfg!(windows) { r"C:\xdg2" } else { "/xdg2" };
        let env = move |name: &str| (name == "XDG_CONFIG_HOME").then(|| xdg2.into());
        assert_eq!(
            mcp_config_path_with(McpClient::Muse, &env).unwrap(),
            Path::new(xdg2).join("muse").join("settings.json")
        );
    }

    #[test]
    fn muse_upsert_never_rewrites_an_existing_schema_version() {
        let mut root = serde_json::Map::new();
        root.insert("schema_version".into(), json!(2));

        upsert_json_mcp_entry(&mut root, &args_for(McpClient::Muse)).unwrap();

        // Downgrading a future schema would break the user's settings file;
        // an unrecognized value is Muse's own error to report.
        assert_eq!(root["schema_version"], 2);
    }

    #[test]
    fn muse_render_carries_schema_version_for_hand_merging() {
        let rendered = render_muse(&args_for(McpClient::Muse)).unwrap();

        assert!(rendered.contains("\"schema_version\": 1"), "{rendered}");
        assert!(rendered.contains("\"mcpServers\""), "{rendered}");
        assert!(rendered.contains("\"--agent\""), "{rendered}");
        assert!(rendered.contains("\"optional\""), "{rendered}");
    }

    #[test]
    fn opencode_mcp_migration_moves_only_owned_alternate_shape() {
        let args = args_with_token(McpClient::OpenCode2);
        let mut root = json!({
            "mcp": {
                "ai-memory": {
                    "type": "remote",
                    "url": "http://127.0.0.1:49374/mcp",
                    "enabled": true,
                    "headers": {"Authorization": "Bearer old"}
                },
                "other": {"type": "remote", "url": "https://example.invalid/mcp"}
            }
        })
        .as_object()
        .unwrap()
        .clone();

        upsert_json_mcp_entry(&mut root, &args).unwrap();
        assert!(root["mcp"].get("ai-memory").is_none());
        assert_eq!(root["mcp"]["other"]["url"], "https://example.invalid/mcp");
        assert_eq!(root["mcp"]["servers"]["ai-memory"]["oauth"], json!(false));
        let once = serde_json::to_string_pretty(&root).unwrap();
        upsert_json_mcp_entry(&mut root, &args).unwrap();
        assert_eq!(serde_json::to_string_pretty(&root).unwrap(), once);
    }

    #[test]
    fn opencode_mcp_migration_works_in_both_major_directions() {
        let mut root = json!({
            "mcp": {
                "servers": {
                    "ai-memory": {
                        "type": "remote",
                        "url": "http://127.0.0.1:49374/mcp",
                        "oauth": false
                    }
                }
            }
        })
        .as_object()
        .unwrap()
        .clone();

        upsert_json_mcp_entry(&mut root, &args_for(McpClient::OpenCode)).unwrap();
        assert!(root["mcp"].get("servers").is_none());
        assert_eq!(root["mcp"]["ai-memory"]["enabled"], json!(true));
    }

    #[test]
    fn opencode_mcp_migration_preserves_custom_headers() {
        let args = args_for(McpClient::OpenCode2);
        let user_entry = json!({
            "type": "remote",
            "url": "http://127.0.0.1:49374/mcp",
            "enabled": true,
            "headers": {
                "Authorization": "Bearer user-token",
                "X-User-Route": "custom"
            }
        });
        let mut root = json!({"mcp": {"ai-memory": user_entry.clone()}})
            .as_object()
            .unwrap()
            .clone();

        upsert_json_mcp_entry(&mut root, &args).unwrap();
        assert_eq!(root["mcp"]["ai-memory"], user_entry);
        assert!(root["mcp"]["servers"]["ai-memory"].is_object());
    }

    #[test]
    fn opencode_mcp_migration_accepts_only_historical_generated_headers() {
        for headers in [
            None,
            Some(json!({"Authorization": "Bearer historical-token"})),
        ] {
            let mut entry = serde_json::Map::from_iter([
                ("type".to_string(), json!("remote")),
                ("url".to_string(), json!("http://127.0.0.1:49374/mcp")),
                ("enabled".to_string(), json!(true)),
            ]);
            if let Some(headers) = headers {
                entry.insert("headers".to_string(), headers);
            }
            assert!(opencode_mcp_entry_is_owned(
                &serde_json::Value::Object(entry),
                &args_for(McpClient::OpenCode2),
            ));
        }
    }

    #[test]
    fn opencode_install_reuses_owned_endpoint_and_token_across_major_transitions() {
        for (client, initial, selected_path, removed_path, expected_url) in [
            (
                McpClient::OpenCode2,
                json!({"mcp":{"ai-memory":{"type":"remote","url":"http://v1-host:49374/mcp","enabled":true,"headers":{"Authorization":"Bearer v1-token"}}}}),
                "/mcp/servers/ai-memory",
                "/mcp/ai-memory",
                "http://v1-host:49374/mcp",
            ),
            (
                McpClient::OpenCode,
                json!({"mcp":{"servers":{"ai-memory":{"type":"remote","url":"http://v2-host:49374/mcp","oauth":false,"headers":{"Authorization":"Bearer v2-token"}}}}}),
                "/mcp/ai-memory",
                "/mcp/servers/ai-memory",
                "http://v2-host:49374/mcp",
            ),
        ] {
            let tmp = tempfile::tempdir().unwrap();
            let config_path = tmp.path().join("opencode.json");
            fs::write(
                &config_path,
                serde_json::to_string_pretty(&initial).unwrap(),
            )
            .unwrap();
            let config = Config::default();
            let mut args = args_for(client);
            args.server_url = None;
            args.config_file = Some(config_path.clone());
            args.apply = true;

            run_with_opencode_dialect(
                &config,
                args,
                Some(match client {
                    McpClient::OpenCode => ai_memory_workstream::OpenCodeDialect::V1,
                    McpClient::OpenCode2 => ai_memory_workstream::OpenCodeDialect::V2,
                    _ => unreachable!(),
                }),
            )
            .unwrap();

            let root: serde_json::Value =
                serde_json::from_str(&fs::read_to_string(config_path).unwrap()).unwrap();
            let entry = root.pointer(selected_path).unwrap();
            assert_eq!(entry["url"], expected_url);
            let expected_token = if client == McpClient::OpenCode2 {
                "Bearer v1-token"
            } else {
                "Bearer v2-token"
            };
            assert_eq!(entry["headers"]["Authorization"], expected_token);
            assert!(root.pointer(removed_path).is_none());
        }
    }

    #[test]
    fn opencode_install_refuses_conflicting_owned_transition_entries() {
        let tmp = tempfile::tempdir().unwrap();
        let config_path = tmp.path().join("opencode.json");
        let initial = json!({"mcp":{
            "ai-memory":{"type":"remote","url":"http://v1-host:49374/mcp","enabled":true},
            "servers":{"ai-memory":{"type":"remote","url":"http://v2-host:49374/mcp","oauth":false}}
        }});
        fs::write(
            &config_path,
            serde_json::to_string_pretty(&initial).unwrap(),
        )
        .unwrap();
        let mut args = args_for(McpClient::OpenCode2);
        args.server_url = None;
        args.config_file = Some(config_path.clone());
        args.apply = true;

        let error = run_with_opencode_dialect(
            &Config::default(),
            args,
            Some(ai_memory_workstream::OpenCodeDialect::V2),
        )
        .unwrap_err();
        assert!(
            error
                .to_string()
                .contains("conflicting generated OpenCode MCP entries")
        );
        assert_eq!(
            serde_json::from_str::<serde_json::Value>(&fs::read_to_string(config_path).unwrap())
                .unwrap(),
            initial
        );
    }

    #[test]
    fn opencode_install_refuses_generated_transition_over_a_user_owned_selected_entry() {
        let tmp = tempfile::tempdir().unwrap();
        let config_path = tmp.path().join("opencode.json");
        let initial = json!({"mcp":{
            "ai-memory":{"type":"remote","url":"http://user-host:49374/mcp","enabled":true,"command":"user-owned"},
            "servers":{"ai-memory":{"type":"remote","url":"http://generated-host:49374/mcp","oauth":false}}
        }});
        fs::write(
            &config_path,
            serde_json::to_string_pretty(&initial).unwrap(),
        )
        .unwrap();
        let mut args = args_for(McpClient::OpenCode);
        args.server_url = None;
        args.config_file = Some(config_path.clone());
        args.apply = true;

        let error = run_with_opencode_dialect(
            &Config::default(),
            args,
            Some(ai_memory_workstream::OpenCodeDialect::V1),
        )
        .unwrap_err();
        assert!(error.to_string().contains("user-owned OpenCode MCP entry"));
        assert_eq!(
            serde_json::from_str::<serde_json::Value>(&fs::read_to_string(config_path).unwrap())
                .unwrap(),
            initial
        );
    }

    #[test]
    fn opencode_install_does_not_infer_from_a_user_owned_transition_entry() {
        let tmp = tempfile::tempdir().unwrap();
        let config_path = tmp.path().join("opencode.json");
        let user = json!({
            "type":"remote",
            "url":"http://user-host:49374/mcp",
            "enabled":true,
            "headers":{"Authorization":"Bearer user-token","X-User":"route"}
        });
        fs::write(
            &config_path,
            serde_json::to_string_pretty(&json!({"mcp":{"ai-memory":user.clone()}})).unwrap(),
        )
        .unwrap();
        let mut args = args_for(McpClient::OpenCode2);
        args.server_url = None;
        args.config_file = Some(config_path.clone());
        args.apply = true;

        run_with_opencode_dialect(
            &Config::default(),
            args,
            Some(ai_memory_workstream::OpenCodeDialect::V2),
        )
        .unwrap();

        let root: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(config_path).unwrap()).unwrap();
        assert_eq!(root["mcp"]["ai-memory"], user);
        assert_eq!(root["mcp"]["servers"]["ai-memory"]["url"], DEFAULT_MCP_URL);
    }

    #[test]
    fn opencode_mcp_apply_is_byte_idempotent_after_migration() {
        let tmp = tempfile::tempdir().unwrap();
        let config = tmp.path().join("opencode.json");
        fs::write(
            &config,
            serde_json::to_string_pretty(&json!({
                "mcp": {
                    "ai-memory": {
                        "type": "remote",
                        "url": "http://127.0.0.1:49374/mcp",
                        "enabled": true
                    }
                }
            }))
            .unwrap(),
        )
        .unwrap();
        let mut args = args_for(McpClient::OpenCode2);
        args.config_file = Some(config.clone());
        args.apply = true;

        apply_to_config_file(&args).unwrap();
        let first = fs::read(&config).unwrap();
        apply_to_config_file(&args).unwrap();
        assert_eq!(fs::read(&config).unwrap(), first);
    }

    #[test]
    fn opencode_mcp_migration_preserves_ambiguous_user_entry() {
        let args = args_for(McpClient::OpenCode2);
        let user_entry = json!({
            "type": "remote",
            "url": "http://127.0.0.1:49374/mcp",
            "enabled": true,
            "command": "user-owned"
        });
        let mut root = json!({"mcp": {"ai-memory": user_entry.clone()}})
            .as_object()
            .unwrap()
            .clone();

        upsert_json_mcp_entry(&mut root, &args).unwrap();
        assert_eq!(root["mcp"]["ai-memory"], user_entry);
        assert!(root["mcp"]["servers"]["ai-memory"].is_object());
    }

    #[test]
    fn opencode2_entry_uses_v2_servers_shape() {
        // V2 nests under `mcp.servers`, drops v1's `enabled`, and disables
        // OAuth discovery: ai-memory authenticates with a static header.
        let entry = build_json_mcp_entry(&args_with_token(McpClient::OpenCode2)).unwrap();
        assert_eq!(entry["type"], json!("remote"));
        assert_eq!(entry["url"], json!("http://127.0.0.1:49374/mcp"));
        assert_eq!(entry["oauth"], json!(false));
        assert!(entry.get("enabled").is_none());
        assert_eq!(
            entry["headers"]["Authorization"],
            json!("Bearer test-token-deadbeef")
        );

        let mut root = serde_json::Map::new();
        upsert_json_mcp_entry(&mut root, &args_with_token(McpClient::OpenCode2)).unwrap();
        assert!(root["mcp"]["servers"]["ai-memory"].is_object());
        assert!(root.get("mcpServers").is_none());

        // v1 still lands under top-level `mcp`, so both stay wired.
        let mut v1 = serde_json::Map::new();
        upsert_json_mcp_entry(&mut v1, &args_with_token(McpClient::OpenCode)).unwrap();
        assert!(v1["mcp"]["ai-memory"].is_object());
        assert!(v1["mcp"].get("servers").is_none());
    }

    #[test]
    fn opencode2_render_points_at_v2_key() {
        let out = render_opencode2(&args_for(McpClient::OpenCode2)).unwrap();
        assert!(out.contains("opencode2"));
        assert!(out.contains("mcp"));
        assert!(out.contains("servers"));
        assert!(out.contains("http://127.0.0.1:49374/mcp"));
    }

    #[test]
    fn dsh_render_uses_cordis_patch_insert_shape() {
        let rendered = render_dsh(&args_for(McpClient::Dsh)).expect("render");
        assert!(rendered.contains("- insert:"));
        assert!(rendered.contains("name: '@deepseek-ai/dsh-mcp-client'"));
        assert!(rendered.contains("transport: streamable-http"));
        assert!(rendered.contains("url: 'http://127.0.0.1:49374/mcp'"));
        assert!(rendered.contains("toolCallTimeoutMs: 120000"));
    }

    #[test]
    fn dsh_render_carries_the_bearer_header_when_a_token_is_present() {
        let rendered = render_dsh(&args_with_token(McpClient::Dsh)).expect("render");
        assert!(rendered.contains("Authorization: 'Bearer test-token-deadbeef'"));
    }

    #[test]
    fn dsh_render_quotes_every_interpolated_scalar_as_a_yaml_string() {
        // `123` passes the serverName check but is a YAML integer unquoted;
        // the URL and token carry characters that end a plain scalar.
        let mut args = args_with_token(McpClient::Dsh);
        args.name = "123".into();
        args.server_url = Some("http://h:1/mcp?a=\"b\" #c".into());
        args.auth_token = Some("it's #x".into());
        let rendered = render_dsh(&args).expect("render");
        assert!(rendered.contains("    - id: '123'\n"), "{rendered}");
        assert!(
            rendered.contains("        serverName: '123'\n"),
            "{rendered}"
        );
        assert!(
            rendered.contains("        url: 'http://h:1/mcp?a=\"b\" #c'\n"),
            "{rendered}"
        );
        assert!(
            rendered.contains("          Authorization: 'Bearer it''s #x'\n"),
            "{rendered}"
        );
    }

    #[test]
    fn dsh_rejects_an_unusable_server_name() {
        let mut args = args_for(McpClient::Dsh);
        args.name = "not a name".into();
        let error = validate_args(&args).expect_err("name must be rejected");
        assert!(format!("{error}").contains("serverName"));
    }

    #[test]
    fn dsh_accepts_a_valid_server_name() {
        let mut args = args_for(McpClient::Dsh);
        args.name = "ai-memory_2".into();
        validate_args(&args).expect("valid name");
    }

    /// Hermes' entry is the session-less stdio bridge under `mcp_servers:`,
    /// every scalar a single-quoted YAML string.
    #[test]
    fn hermes_render_is_a_quoted_stdio_bridge_entry() {
        let mut args = args_for(McpClient::Hermes);
        args.name = "123".into();
        args.server_url = Some("http://h:1/mcp?a=\"b\" #c".into());
        args.bridge_data_dir = Some(PathBuf::from("/data dir/it's"));
        let rendered = render_hermes(&args);
        let command = yaml_single_quote(&bridge_command());
        let expected = format!(
            "mcp_servers:\n  '123':\n    command: {command}\n    args:\n      \
             - 'mcp-bridge'\n      - '--no-session-id'\n      - '--server-url'\n      \
             - 'http://h:1/mcp?a=\"b\" #c'\n      - '--data-dir'\n      - '/data dir/it''s'\n"
        );
        assert!(rendered.ends_with(&expected), "{rendered}");
        // The model never sees ai-memory's MCP instructions in Hermes, so the
        // header points at what carries them instead.
        assert!(rendered.contains("does not read an MCP server's instructions"));
        assert!(rendered.contains("~/.hermes/skills"));
        assert!(rendered.contains("next primary-session turn"));
    }

    /// No bearer reaches Hermes' config: the bridge authenticates with the
    /// install's own token.
    #[test]
    fn hermes_render_never_embeds_the_token() {
        let rendered = render_hermes(&args_with_token(McpClient::Hermes));
        assert!(!rendered.contains("test-token-deadbeef"), "{rendered}");
        assert!(!rendered.contains("Bearer"), "{rendered}");
        assert!(!rendered.contains("headers"), "{rendered}");
        assert!(rendered.contains("The token is not written here"));
        assert!(!render_hermes(&args_for(McpClient::Hermes)).contains("The token is not"));
    }

    #[test]
    fn hermes_apply_and_config_path_are_refused_with_guidance() {
        let mut args = args_with_token(McpClient::Hermes);
        args.apply = true;
        let error = apply_to_config_file(&args).expect_err("apply must be refused");
        let message = format!("{error}");
        assert!(message.contains("~/.hermes/config.yaml"), "{message}");
        assert!(message.contains("without --apply"), "{message}");
        assert!(!message.contains("test-token-deadbeef"), "{message}");
        let error = mcp_config_path(McpClient::Hermes).expect_err("no writable config");
        assert!(format!("{error}").contains("~/.hermes/config.yaml"));
        assert!(json_mcp_location(McpClient::Hermes).is_none());
        assert!(build_json_mcp_entry(&args_for(McpClient::Hermes)).is_err());
    }

    #[test]
    fn dsh_apply_is_refused_with_the_patch_pointer() {
        let mut args = args_for(McpClient::Dsh);
        args.apply = true;
        let error = apply_to_config_file(&args).expect_err("apply must be refused");
        assert!(format!("{error}").contains("cordis.patch.yml"));
    }

    #[test]
    fn claude_desktop_render_lists_packaged_and_unpacked_windows_paths() {
        let rendered = render_claude_desktop(&args_for(McpClient::ClaudeDesktop)).unwrap();
        assert!(rendered.contains(r"%APPDATA%\Claude\claude_desktop_config.json"));
        assert!(rendered.contains(
            r"%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.json"
        ));
        assert!(rendered.contains("--apply detects the installed form"));
        assert!(rendered.contains("--config-file"));
    }

    #[test]
    fn claude_code_config_path_honours_claude_config_dir() {
        let custom = if cfg!(windows) {
            r"C:\custom\claude"
        } else {
            "/custom/claude"
        };
        let path = claude_code_config_path_in(Some(std::ffi::OsString::from(custom))).unwrap();
        assert_eq!(path, std::path::Path::new(custom).join(".claude.json"));

        // Empty override and unset var both fall back to ~/.claude.json.
        for env in [None, Some(std::ffi::OsString::new())] {
            let path = claude_code_config_path_in(env).unwrap();
            assert!(
                path.ends_with(".claude.json") && !path.starts_with(custom),
                "default must be ~/.claude.json, got {}",
                path.display()
            );
        }
    }

    #[test]
    fn codex_config_path_honours_codex_home() {
        let custom = if cfg!(windows) {
            r"C:\custom\codex"
        } else {
            "/custom/codex"
        };
        let path = codex_config_path_in(Some(std::ffi::OsString::from(custom))).unwrap();
        assert_eq!(path, std::path::Path::new(custom).join("config.toml"));

        // Unset, empty and blank all fall back to ~/.codex/config.toml, the
        // same reading `install-hooks` gives CODEX_HOME for hooks.json.
        for env in [
            None,
            Some(std::ffi::OsString::new()),
            Some(std::ffi::OsString::from("  ")),
        ] {
            let path = codex_config_path_in(env).unwrap();
            assert!(
                path.ends_with(std::path::Path::new(".codex").join("config.toml")),
                "default must be ~/.codex/config.toml, got {}",
                path.display()
            );
        }
    }

    /// Auto-wire resolves MCP targets through `run --env`; every relocatable
    /// client must read its variable from the supplied lookup, not the process.
    #[test]
    fn mcp_config_path_with_reads_relocation_from_the_supplied_env() {
        let root = if cfg!(windows) {
            std::path::Path::new(r"C:\relocated")
        } else {
            std::path::Path::new("/relocated")
        };
        for (client, var, relative) in [
            (McpClient::ClaudeCode, "CLAUDE_CONFIG_DIR", ".claude.json"),
            (McpClient::Codex, "CODEX_HOME", "config.toml"),
            (McpClient::CopilotCli, "COPILOT_HOME", "mcp-config.json"),
            (McpClient::Grok, "GROK_HOME", "config.toml"),
            (McpClient::KimiCode, "KIMI_CODE_HOME", "mcp.json"),
            (McpClient::KiroCli, "KIRO_HOME", "settings/mcp.json"),
            (McpClient::Omp, "PI_CODING_AGENT_DIR", "mcp.json"),
            (
                McpClient::PrimeAgent,
                "PRIME_AGENT_CODING_AGENT_DIR",
                "settings.json",
            ),
        ] {
            let env = |name: &str| (name == var).then(|| root.as_os_str().to_owned());
            assert_eq!(
                mcp_config_path_with(client, &env).unwrap(),
                root.join(relative),
                "{client:?} must follow {var}"
            );
        }

        let cline_file = root.join("cline-mcp.json");
        let env = |name: &str| {
            (name == "CLINE_MCP_SETTINGS_PATH").then(|| cline_file.clone().into_os_string())
        };
        assert_eq!(
            mcp_config_path_with(McpClient::Cline, &env).unwrap(),
            cline_file
        );

        let env = |name: &str| (name == "HOME").then(|| root.as_os_str().to_owned());
        assert_eq!(
            mcp_config_path_with(McpClient::Cline, &env).unwrap(),
            root.join(".cline/data/settings/cline_mcp_settings.json")
        );
        assert_eq!(
            mcp_config_path_with(McpClient::Freebuff, &env).unwrap(),
            root.join(".agents/mcp.json")
        );
    }

    #[test]
    fn claude_desktop_config_sits_under_the_linux_config_dir() {
        let config = Path::new("/home/me/.config");
        assert_eq!(
            claude_desktop_config_path_linux(config),
            Path::new("/home/me/.config/Claude/claude_desktop_config.json")
        );
        let rendered = render_claude_desktop(&args_for(McpClient::ClaudeDesktop)).unwrap();
        assert!(rendered.contains("$XDG_CONFIG_HOME/Claude/claude_desktop_config.json"));
        assert!(!rendered.contains("not officially distributed"));
    }

    /// A relocated Windows profile (`run --env`, a hermetic backup test)
    /// moves Claude Desktop's config with it; the Known Folder API alone
    /// would keep pointing at the real profile.
    #[cfg(windows)]
    #[test]
    fn claude_desktop_config_follows_the_supplied_appdata() {
        let root = tempfile::tempdir().unwrap();
        let local = root.path().join("Local");
        let roaming = root.path().join("Roaming");
        let env = |name: &str| match name {
            "LOCALAPPDATA" => Some(local.clone().into_os_string()),
            "APPDATA" => Some(roaming.clone().into_os_string()),
            _ => None,
        };
        assert_eq!(
            mcp_config_path_with(McpClient::ClaudeDesktop, &env).unwrap(),
            roaming.join("Claude").join("claude_desktop_config.json")
        );
    }

    /// OMP's MCP file lives in the same agent dir as its extensions: a named
    /// profile owns it and ignores `PI_CODING_AGENT_DIR`, as OMP does.
    #[test]
    fn omp_mcp_config_follows_the_profile_agent_dir() {
        let home = home_dir().unwrap();
        let profile = home
            .join(".omp")
            .join("profiles")
            .join("work")
            .join("agent")
            .join("mcp.json");
        for pairs in [
            &[("OMP_PROFILE", "work")][..],
            &[("OMP_PROFILE", "work"), ("PI_CODING_AGENT_DIR", "/custom")][..],
            &[("PI_PROFILE", "work")][..],
        ] {
            let env = |name: &str| {
                pairs
                    .iter()
                    .find(|(key, _)| *key == name)
                    .map(|(_, value)| std::ffi::OsString::from(value))
            };
            assert_eq!(
                mcp_config_path_with(McpClient::Omp, &env).unwrap(),
                profile,
                "{pairs:?}"
            );
        }
        let invalid = |name: &str| (name == "OMP_PROFILE").then(|| "Work".into());
        assert!(mcp_config_path_with(McpClient::Omp, &invalid).is_err());
        let renamed = |name: &str| (name == "PI_CONFIG_DIR").then(|| ".omp-alt".into());
        assert_eq!(
            mcp_config_path_with(McpClient::Omp, &renamed).unwrap(),
            home.join(".omp-alt").join("agent").join("mcp.json"),
            "PI_CONFIG_DIR renames OMP's root"
        );
    }

    /// A blank relocation variable is unset, the rule every installer and
    /// native session import share; otherwise the MCP entry, bearer token
    /// included, landed in a whitespace-named directory under the cwd.
    #[test]
    fn mcp_config_path_with_treats_blank_relocation_as_unset() {
        let home = home_dir().unwrap();
        for (client, var, relative) in [
            (McpClient::ClaudeCode, "CLAUDE_CONFIG_DIR", ".claude.json"),
            (McpClient::Codex, "CODEX_HOME", ".codex/config.toml"),
            (McpClient::Grok, "GROK_HOME", ".grok/config.toml"),
            (McpClient::KimiCode, "KIMI_CODE_HOME", ".kimi-code/mcp.json"),
            (McpClient::KiroCli, "KIRO_HOME", ".kiro/settings/mcp.json"),
            (McpClient::Omp, "PI_CODING_AGENT_DIR", ".omp/agent/mcp.json"),
            (McpClient::Omp, "OMP_PROFILE", ".omp/agent/mcp.json"),
            (McpClient::Omp, "PI_CONFIG_DIR", ".omp/agent/mcp.json"),
        ] {
            for blank in ["", "   ", "\t", " \n"] {
                let env = |name: &str| (name == var).then(|| std::ffi::OsString::from(blank));
                assert_eq!(
                    mcp_config_path_with(client, &env).unwrap(),
                    home.join(relative),
                    "{client:?} with {var}={blank:?}"
                );
            }
        }
    }

    /// The snippet names CODEX_HOME rather than a resolved path: it is often
    /// rendered inside the Docker image, whose paths mean nothing on the host.
    #[test]
    fn codex_render_names_codex_home() {
        let out = render_codex(&args_for(McpClient::Codex)).unwrap();
        assert!(
            out.contains("$CODEX_HOME/config.toml"),
            "render must point a relocated Codex at its config home:\n{out}"
        );
    }

    #[test]
    fn zed_config_path_uses_platform_conventions() {
        for (target_os, root, expected) in [
            (
                "linux",
                "/home/alice/.config",
                "/home/alice/.config/zed/settings.json",
            ),
            (
                "macos",
                "/Users/alice/.config",
                "/Users/alice/.config/zed/settings.json",
            ),
            (
                "windows",
                "C:/Users/alice/AppData/Roaming",
                "C:/Users/alice/AppData/Roaming/Zed/settings.json",
            ),
        ] {
            assert_eq!(
                zed_config_path_in(Path::new(root), target_os),
                PathBuf::from(expected),
                "target OS: {target_os}"
            );
        }
    }

    #[test]
    fn zed_renderer_uses_context_servers_and_native_remote_http() {
        let fragment = render_json_mcp_fragment(&args_with_token(McpClient::Zed)).unwrap();
        let value: serde_json::Value = serde_json::from_str(&fragment).unwrap();

        assert_eq!(
            value,
            json!({
                "context_servers": {
                    "ai-memory": {
                        "url": "http://127.0.0.1:49374/mcp",
                        "headers": {
                            "Authorization": "Bearer test-token-deadbeef"
                        }
                    }
                }
            })
        );
        assert!(
            render_zed(&args_for(McpClient::Zed))
                .unwrap()
                .contains("MCP-only")
        );
    }

    #[test]
    fn command_code_renderer_uses_documented_user_scope_http_schema() {
        let fragment = render_json_mcp_fragment(&args_with_token(McpClient::CommandCode)).unwrap();
        let value: serde_json::Value = serde_json::from_str(&fragment).unwrap();

        assert_eq!(
            value,
            json!({
                "mcpServers": {
                    "ai-memory": {
                        "transport": "http",
                        "enabled": true,
                        "url": "http://127.0.0.1:49374/mcp",
                        "headers": {
                            "Authorization": "Bearer test-token-deadbeef"
                        }
                    }
                }
            })
        );
        let rendered = render_command_code(&args_for(McpClient::CommandCode)).unwrap();
        assert!(rendered.contains("~/.commandcode/mcp.json"));
        assert!(rendered.contains("cmd mcp add --transport http --scope user"));
        assert!(rendered.contains("`cmdc` is the native Windows executable"));
    }

    /// Copilot CLI's documented remote entry (#1040): root `mcpServers`,
    /// `type: "http"` + `url` + `headers`, and `tools: ["*"]`.
    #[test]
    fn copilot_cli_renderer_uses_documented_http_schema() {
        let fragment = render_json_mcp_fragment(&args_with_token(McpClient::CopilotCli)).unwrap();
        let value: serde_json::Value = serde_json::from_str(&fragment).unwrap();

        assert_eq!(
            value,
            json!({
                "mcpServers": {
                    "ai-memory": {
                        "type": "http",
                        "url": "http://127.0.0.1:49374/mcp",
                        "headers": {
                            "Authorization": "Bearer test-token-deadbeef"
                        },
                        "tools": ["*"]
                    }
                }
            })
        );
        let rendered = render_copilot_cli(&args_for(McpClient::CopilotCli)).unwrap();
        assert!(rendered.contains("mcp-config.json"));
        assert!(rendered.contains("copilot mcp add --transport http ai-memory"));
        assert!(rendered.contains("install-hooks --agent copilot-cli"));
    }

    #[test]
    fn copilot_home_honours_env_override() {
        assert_eq!(
            copilot_home_in(Some("/tmp/custom-copilot-home".into())).unwrap(),
            PathBuf::from("/tmp/custom-copilot-home")
        );
        let default = home_dir().unwrap().join(".copilot");
        assert_eq!(copilot_home_in(Some("".into())).unwrap(), default);
        assert_eq!(copilot_home_in(None).unwrap(), default);
    }

    #[test]
    fn zed_apply_preserves_settings_and_siblings_and_is_idempotent() {
        let tmp = tempfile::TempDir::new().unwrap();
        let config_path = tmp.path().join("settings.json");
        fs::write(
            &config_path,
            r#"{
  // Keep this user comment.
  "theme": "One Dark",
  "context_servers": {
    // Keep this sibling comment.
    "other": { "url": "https://other.example/mcp" },
  },
}
"#,
        )
        .unwrap();
        let mut args = args_with_token(McpClient::Zed);
        args.config_file = Some(config_path.clone());

        apply_to_config_file(&args).unwrap();
        let first = fs::read_to_string(&config_path).unwrap();
        apply_to_config_file(&args).unwrap();
        let second = fs::read_to_string(&config_path).unwrap();

        assert_eq!(first, second);
        assert!(second.contains("// Keep this user comment."));
        assert!(second.contains("// Keep this sibling comment."));
        let root = CstRootNode::parse(&second, &ParseOptions::default()).unwrap();
        let value = root.to_serde_value().unwrap();
        assert_eq!(value["theme"], "One Dark");
        assert_eq!(
            value["context_servers"]["other"]["url"],
            "https://other.example/mcp"
        );
        assert_eq!(
            value["context_servers"]["ai-memory"]["headers"]["Authorization"],
            "Bearer test-token-deadbeef"
        );
    }

    #[test]
    fn zed_apply_rejects_non_object_context_servers_without_writing() {
        let tmp = tempfile::TempDir::new().unwrap();
        let config_path = tmp.path().join("settings.json");
        let original = "{\n  // User-owned invalid shape.\n  \"context_servers\": false,\n}\n";
        fs::write(&config_path, original).unwrap();
        let mut args = args_for(McpClient::Zed);
        args.config_file = Some(config_path.clone());

        let error = apply_to_config_file(&args).unwrap_err();

        assert!(error.to_string().contains("not an object"));
        assert_eq!(fs::read_to_string(config_path).unwrap(), original);
    }

    #[test]
    fn packaged_claude_desktop_path_prefers_localcache_when_package_dir_exists() {
        let packages = tempfile::TempDir::new().unwrap();
        fs::create_dir_all(packages.path().join("Claude_pzs8sxrjxfjjc")).unwrap();

        let found = packaged_claude_desktop_config_path(packages.path())
            .unwrap()
            .unwrap();
        assert_eq!(
            found,
            packages
                .path()
                .join("Claude_pzs8sxrjxfjjc")
                .join("LocalCache")
                .join("Roaming")
                .join("Claude")
                .join("claude_desktop_config.json")
        );
    }

    #[test]
    fn packaged_claude_desktop_path_ignores_unrelated_and_non_dir_entries() {
        let packages = tempfile::TempDir::new().unwrap();
        fs::create_dir_all(packages.path().join("Microsoft.WindowsTerminal_abc123")).unwrap();
        fs::write(packages.path().join("Claude_notadir"), b"").unwrap();

        assert!(
            packaged_claude_desktop_config_path(packages.path())
                .unwrap()
                .is_none()
        );
    }

    #[test]
    fn packaged_claude_desktop_path_none_when_packages_dir_absent_or_empty() {
        let missing = tempfile::TempDir::new().unwrap();
        assert!(
            packaged_claude_desktop_config_path(&missing.path().join("does-not-exist"))
                .unwrap()
                .is_none()
        );

        let empty = tempfile::TempDir::new().unwrap();
        assert!(
            packaged_claude_desktop_config_path(empty.path())
                .unwrap()
                .is_none()
        );
    }

    #[test]
    fn claude_desktop_path_uses_resolved_app_data_roots() {
        let root = tempfile::TempDir::new().unwrap();
        let local = root.path().join("redirected-local");
        let roaming = root.path().join("redirected-roaming");

        assert_eq!(
            claude_desktop_config_path_in(&local, &roaming).unwrap(),
            roaming.join("Claude").join("claude_desktop_config.json")
        );
    }

    #[test]
    fn packaged_claude_desktop_path_prefers_existing_config_among_packages() {
        let packages = tempfile::TempDir::new().unwrap();
        fs::create_dir_all(packages.path().join("Claude_old")).unwrap();
        let active_config = packages
            .path()
            .join("Claude_current")
            .join("LocalCache")
            .join("Roaming")
            .join("Claude")
            .join("claude_desktop_config.json");
        fs::create_dir_all(active_config.parent().unwrap()).unwrap();
        fs::write(&active_config, b"{}").unwrap();

        assert_eq!(
            packaged_claude_desktop_config_path(packages.path())
                .unwrap()
                .unwrap(),
            active_config
        );
    }

    #[test]
    fn packaged_claude_desktop_path_rejects_ambiguous_packages() {
        let packages = tempfile::TempDir::new().unwrap();
        fs::create_dir_all(packages.path().join("Claude_first")).unwrap();
        fs::create_dir_all(packages.path().join("Claude_second")).unwrap();

        let error = packaged_claude_desktop_config_path(packages.path()).unwrap_err();
        assert!(error.to_string().contains("--config-file"));
    }

    #[test]
    fn claude_code_render_shows_resolved_config_path() {
        let args = args_for(McpClient::ClaudeCode);
        let config_path = std::path::Path::new("/stores/claude/.claude.json");
        let out = render_claude_code(&args, config_path).unwrap();
        assert!(
            out.contains("/stores/claude/.claude.json"),
            "render must mention the resolved config path:\n{out}"
        );
        assert!(
            !out.contains("~/.claude.json"),
            "render must not hardcode ~/.claude.json when the resolved path differs:\n{out}"
        );
    }

    #[test]
    fn bridge_command_names_the_binary_by_absolute_path_outside_a_container() {
        let exe = PathBuf::from("/opt/ai-memory/ai-memory");
        assert_eq!(
            bridge_command_for(false, exe.clone()),
            "/opt/ai-memory/ai-memory"
        );
        assert_eq!(bridge_command_for(true, exe), BRIDGE_COMMAND);
    }

    #[test]
    fn bridge_entries_are_recognized_by_bare_name_or_absolute_path() {
        #[cfg(windows)]
        let absolute_command = r"C:\opt\ai-memory.exe";
        #[cfg(not(windows))]
        let absolute_command = "/opt/ai-memory/ai-memory";

        for command in ["ai-memory", absolute_command] {
            let entry =
                json!({"command": command, "args": ["mcp-bridge", "--server-url", "http://h/mcp"]});
            assert_eq!(bridge_entry_url(&entry), Some("http://h/mcp"), "{command}");
            let opencode =
                json!({"command": [command, "mcp-bridge", "--server-url", "http://h/mcp"]});
            assert_eq!(
                bridge_entry_url(&opencode),
                Some("http://h/mcp"),
                "{command}"
            );
        }
        for command in ["other", "/usr/bin/other", "bin/ai-memory"] {
            let entry =
                json!({"command": command, "args": ["mcp-bridge", "--server-url", "http://h/mcp"]});
            assert_eq!(bridge_entry_url(&entry), None, "{command}");
        }
    }

    #[test]
    fn claude_code_session_aware_entry_uses_owned_stdio_bridge() {
        let mut args = args_with_token(McpClient::ClaudeCode);
        args.server_url = Some("https://memory.example/mcp".into());
        args.session_aware = true;
        args.bridge_data_dir = Some(PathBuf::from("/srv/AI Memory/data"));

        let entry = build_mcp_entry(&args).unwrap();

        assert_eq!(entry["type"], "stdio");
        assert_eq!(entry["command"], bridge_command());
        assert_eq!(
            entry["args"],
            json!([
                "mcp-bridge",
                "--server-url",
                "https://memory.example/mcp",
                "--data-dir",
                "/srv/AI Memory/data"
            ])
        );
        assert_eq!(entry["env"]["AI_MEMORY_AUTH_TOKEN"], "test-token-deadbeef");
        assert!(entry.get("url").is_none());
        assert!(entry.get("headers").is_none());

        let rendered = render_claude_code(&args, Path::new("/home/alice/.claude.json")).unwrap();
        assert!(rendered.contains("claude mcp add --transport stdio"));
        assert!(rendered.contains(&format!(
            "{} mcp-bridge --server-url",
            shell_quote(&bridge_command())
        )));
        assert!(rendered.contains("--data-dir '/srv/AI Memory/data'"));
    }

    #[test]
    fn claude_code_session_aware_apply_is_idempotent() {
        let tmp = tempfile::TempDir::new().unwrap();
        let config_file = tmp.path().join(".claude.json");
        let mut args = args_with_token(McpClient::ClaudeCode);
        args.server_url = Some("http://192.168.0.90:49374/mcp".into());
        args.config_file = Some(config_file.clone());
        args.session_aware = true;
        args.apply = true;

        apply_to_config_file(&args).unwrap();
        let first = fs::read_to_string(&config_file).unwrap();
        apply_to_config_file(&args).unwrap();
        let second = fs::read_to_string(&config_file).unwrap();

        assert_eq!(first, second);
        let value: serde_json::Value = serde_json::from_str(&second).unwrap();
        assert_eq!(
            value["mcpServers"]["ai-memory"]["args"],
            json!([
                "mcp-bridge",
                "--server-url",
                "http://192.168.0.90:49374/mcp"
            ])
        );
    }

    #[test]
    fn session_aware_rejects_non_claude_clients() {
        let mut args = args_for(McpClient::Codex);
        args.session_aware = true;

        let error = build_json_mcp_entry(&args).unwrap_err();

        assert!(
            error
                .to_string()
                .contains("supported only for --client claude-code"),
            "{error:#}"
        );
    }

    fn render_with_token(client: McpClient) -> String {
        let args = args_with_token(client);
        match args.client {
            McpClient::ClaudeCode => {
                render_claude_code(&args, Path::new("/home/alice/.claude.json")).unwrap()
            }
            McpClient::Codex => render_codex(&args).unwrap(),
            McpClient::Grok => render_grok(&args).unwrap(),
            McpClient::OpenCode => render_opencode(&args).unwrap(),
            McpClient::OpenCode2 => render_opencode2(&args).unwrap(),
            McpClient::Cursor => render_cursor(&args).unwrap(),
            McpClient::ClaudeDesktop => render_claude_desktop(&args).unwrap(),
            McpClient::GeminiCli => render_gemini_cli(&args).unwrap(),
            McpClient::QwenCode => render_qwen_code(&args).unwrap(),
            McpClient::Qoder => render_json_mcp_fragment(&args).unwrap(),
            McpClient::Openclaw => render_openclaw(&args).unwrap(),
            McpClient::Pi => render_pi(&args).unwrap(),
            McpClient::Omp => render_omp(&args).unwrap(),
            McpClient::AntigravityCli => render_antigravity_cli(&args).unwrap(),
            McpClient::Zero => render_zero(&args).unwrap(),
            McpClient::Zcode => render_zcode(&args).unwrap(),
            McpClient::Devin => render_devin(&args).unwrap(),
            McpClient::KimiCode => render_kimi_code(&args).unwrap(),
            McpClient::KiroCli => render_kiro_cli(&args).unwrap(),
            McpClient::CommandCode => render_command_code(&args).unwrap(),
            McpClient::IbmBob => render_ibm_bob(&args).unwrap(),
            McpClient::CopilotCli => render_copilot_cli(&args).unwrap(),
            McpClient::Droid => render_droid(&args).unwrap(),
            McpClient::Swival => render_swival(&args).unwrap(),
            McpClient::VsCodeCopilot => render_vscode_copilot(&args).unwrap(),
            McpClient::Zed => render_zed(&args).unwrap(),
            McpClient::Muse => render_muse(&args).unwrap(),
            McpClient::Dsh => render_dsh(&args).unwrap(),
            McpClient::Hermes => render_hermes(&args),
            McpClient::PrimeAgent => render_prime_agent(&args).unwrap(),
            McpClient::Cline => render_json_mcp_fragment(&args).unwrap(),
            McpClient::Freebuff => {
                let mut args = args;
                args.stdio_bridge = true;
                render_json_mcp_fragment(&args).unwrap()
            }
        }
    }

    /// With `--auth-token` set, every renderer must embed the Bearer
    /// header in its output.
    #[test]
    fn auth_token_threaded_into_every_client() {
        for client in [
            McpClient::ClaudeCode,
            McpClient::Codex,
            McpClient::Grok,
            McpClient::OpenCode,
            McpClient::OpenCode2,
            McpClient::Cursor,
            McpClient::ClaudeDesktop,
            McpClient::GeminiCli,
            McpClient::QwenCode,
            McpClient::Qoder,
            McpClient::Openclaw,
            McpClient::Omp,
            McpClient::AntigravityCli,
            McpClient::Zero,
            McpClient::Zcode,
            McpClient::Devin,
            McpClient::KimiCode,
            McpClient::KiroCli,
            McpClient::CommandCode,
            McpClient::IbmBob,
            McpClient::CopilotCli,
            McpClient::Swival,
            McpClient::VsCodeCopilot,
            McpClient::Zed,
            McpClient::Dsh,
            McpClient::Cline,
        ] {
            let out = render_with_token(client);
            // Every client embeds the token as `Authorization:
            // Bearer <token>` in some flavour of headers map — the
            // exact key path differs (Codex uses `http_headers`,
            // OpenCode uses `headers`, Cursor / Gemini / Claude
            // Desktop / Claude Code use `headers` inside their
            // server entry, etc.), but the literal `Bearer
            // <token>` substring shows up in all of them. Keep
            // the assertion uniform.
            let carries_token = out.contains("Bearer test-token-deadbeef")
                || (client == McpClient::Qoder && out.contains("test-token-deadbeef"));
            assert!(
                carries_token,
                "client {client:?} did not embed the bearer token:\n{out}"
            );
        }
    }

    /// Sanity: every supported client renders without error and the
    /// output mentions the configured server URL.
    #[test]
    fn every_client_renders() {
        for client in [
            McpClient::ClaudeCode,
            McpClient::Codex,
            McpClient::Grok,
            McpClient::OpenCode,
            McpClient::OpenCode2,
            McpClient::Cursor,
            McpClient::ClaudeDesktop,
            McpClient::GeminiCli,
            McpClient::QwenCode,
            McpClient::Qoder,
            McpClient::Openclaw,
            McpClient::Omp,
            McpClient::AntigravityCli,
            McpClient::Zero,
            McpClient::Zcode,
            McpClient::Devin,
            McpClient::KimiCode,
            McpClient::IbmBob,
            McpClient::KiroCli,
            McpClient::CommandCode,
            McpClient::CopilotCli,
            McpClient::Droid,
            McpClient::Swival,
            McpClient::VsCodeCopilot,
            McpClient::Zed,
            McpClient::Muse,
            McpClient::Dsh,
            McpClient::Hermes,
            McpClient::PrimeAgent,
            McpClient::Cline,
            McpClient::Freebuff,
        ] {
            let out = render_for_test(client);
            assert!(
                out.contains("http://127.0.0.1:49374/mcp"),
                "client {client:?} did not include the server URL in output:\n{out}"
            );
        }
    }

    #[test]
    fn qoder_always_uses_the_sessionless_bridge_in_its_native_stdio_shape() {
        let mut args = args_for(McpClient::Qoder);
        args.auth_token = Some("qoder-token".into());
        let entry = build_json_mcp_entry(&args).unwrap();
        // The command is this binary (or the bare name inside a container), so
        // compare against what the builder is contracted to produce rather than
        // a substring of the test binary's path: under `cargo test` that path is
        // `ai_memory_cli-<hash>`, which only happens to contain `ai-memory` when
        // the checkout does, and an out-of-tree `CARGO_TARGET_DIR` then fails
        // the suite for the fixture's spelling (#1691).
        let command = entry["command"].as_str().unwrap();
        assert!(
            is_bridge_command(command),
            "the Qoder entry must run this binary: {command}"
        );
        let bridge_args = entry["args"].as_array().unwrap();
        assert!(bridge_args.iter().any(|arg| arg == "mcp-bridge"));
        assert!(bridge_args.iter().any(|arg| arg == "--no-session-id"));
        assert_eq!(entry["env"]["AI_MEMORY_AUTH_TOKEN"], "qoder-token");
        assert!(entry.get("url").is_none());
    }

    fn render_for_test(client: McpClient) -> String {
        let args = args_for(client);
        match args.client {
            McpClient::ClaudeCode => {
                render_claude_code(&args, Path::new("/home/alice/.claude.json")).unwrap()
            }
            McpClient::Codex => render_codex(&args).unwrap(),
            McpClient::Grok => render_grok(&args).unwrap(),
            McpClient::OpenCode => render_opencode(&args).unwrap(),
            McpClient::OpenCode2 => render_opencode2(&args).unwrap(),
            McpClient::Cursor => render_cursor(&args).unwrap(),
            McpClient::ClaudeDesktop => render_claude_desktop(&args).unwrap(),
            McpClient::GeminiCli => render_gemini_cli(&args).unwrap(),
            McpClient::QwenCode => render_qwen_code(&args).unwrap(),
            McpClient::Qoder => render_json_mcp_fragment(&args).unwrap(),
            McpClient::Openclaw => render_openclaw(&args).unwrap(),
            McpClient::Pi => render_pi(&args).unwrap(),
            McpClient::Omp => render_omp(&args).unwrap(),
            McpClient::AntigravityCli => render_antigravity_cli(&args).unwrap(),
            McpClient::Zero => render_zero(&args).unwrap(),
            McpClient::Zcode => render_zcode(&args).unwrap(),
            McpClient::Devin => render_devin(&args).unwrap(),
            McpClient::KimiCode => render_kimi_code(&args).unwrap(),
            McpClient::KiroCli => render_kiro_cli(&args).unwrap(),
            McpClient::CommandCode => render_command_code(&args).unwrap(),
            McpClient::IbmBob => render_ibm_bob(&args).unwrap(),
            McpClient::CopilotCli => render_copilot_cli(&args).unwrap(),
            McpClient::Droid => render_droid(&args).unwrap(),
            McpClient::Swival => render_swival(&args).unwrap(),
            McpClient::VsCodeCopilot => render_vscode_copilot(&args).unwrap(),
            McpClient::Zed => render_zed(&args).unwrap(),
            McpClient::Muse => render_muse(&args).unwrap(),
            McpClient::Dsh => render_dsh(&args).unwrap(),
            McpClient::Hermes => render_hermes(&args),
            McpClient::PrimeAgent => render_prime_agent(&args).unwrap(),
            McpClient::Cline => render_json_mcp_fragment(&args).unwrap(),
            McpClient::Freebuff => {
                let mut args = args;
                args.stdio_bridge = true;
                render_json_mcp_fragment(&args).unwrap()
            }
        }
    }

    const FILE_TOKEN: &str = "file-token-0123456789abcdef";

    /// A config whose bearer came from `[auth].bearer_token_file`, as
    /// `Config::load` leaves it on a new install.
    fn file_token_config(dir: &Path) -> Config {
        let mut config = Config::default();
        config
            .auth
            .adopt_token_file(dir.join("auth-tokens").join("default"), FILE_TOKEN.into());
        config
    }

    fn apply_with(config: &Config, client: McpClient, file: &Path) -> Result<()> {
        let mut args = args_for(client);
        args.apply = true;
        args.config_file = Some(file.to_path_buf());
        let dialect = match client {
            McpClient::OpenCode => Some(ai_memory_workstream::OpenCodeDialect::V1),
            McpClient::OpenCode2 => Some(ai_memory_workstream::OpenCodeDialect::V2),
            _ => None,
        };
        run_with_opencode_dialect(config, args, dialect)
    }

    /// New-install default: a token read from the token file is never written
    /// into a harness config, and every client `install-mcp --apply` writes
    /// still gets an entry that reaches the server: Claude Code the
    /// session-aware bridge, Codex and Prime Agent a reference to
    /// `$AI_MEMORY_AUTH_TOKEN`, every other client the session-less bridge in
    /// its own stdio shape. ZCode, which keeps only HTTP entries, is the one
    /// refusal, and writes nothing.
    #[test]
    fn a_file_sourced_token_wires_every_client_without_entering_its_config() {
        let tmp = tempfile::tempdir().unwrap();
        let config = file_token_config(tmp.path());
        let url = DEFAULT_MCP_URL;
        for &client in <McpClient as clap::ValueEnum>::value_variants() {
            if matches!(client, McpClient::Pi | McpClient::Dsh | McpClient::Hermes) {
                continue; // no config file: an extension, and print-only
            }
            let ext = if matches!(client, McpClient::Codex | McpClient::Grok) {
                "toml"
            } else {
                "json"
            };
            let file = tmp.path().join(format!("{client:?}.{ext}"));
            let result = apply_with(&config, client, &file);
            if client == McpClient::Zcode {
                let err = result.unwrap_err();
                assert!(format!("{err:#}").contains("ZCode"), "{err:#}");
                assert!(!file.exists(), "ZCode must not be written");
                continue;
            }
            result.unwrap_or_else(|e| panic!("{client:?}: {e:#}"));
            let text = std::fs::read_to_string(&file).unwrap();
            assert!(
                !text.contains(FILE_TOKEN),
                "token leaked into {client:?}: {text}"
            );
            assert_eq!(
                text.contains("Authorization"),
                client == McpClient::Droid,
                "only Droid takes a header, and only a variable reference: {text}"
            );
            match client {
                McpClient::Codex => assert!(
                    text.contains("bearer_token_env_var = \"AI_MEMORY_AUTH_TOKEN\""),
                    "{text}"
                ),
                McpClient::PrimeAgent => {
                    assert!(text.contains("\"bearerTokenEnvVar\""), "{text}");
                }
                McpClient::Droid => {
                    assert!(
                        text.contains("\"Bearer ${AI_MEMORY_AUTH_TOKEN}\""),
                        "{text}"
                    );
                    assert!(!text.contains("mcp-bridge"), "{text}");
                }
                _ => {
                    let endpoint = existing_entry_endpoint(client, &file, "ai-memory")
                        .unwrap()
                        .unwrap_or_else(|| panic!("{client:?} entry has no endpoint: {text}"));
                    assert_eq!(endpoint.split('?').next(), Some(url), "{client:?}: {text}");
                    assert!(text.contains("mcp-bridge"), "{client:?}: {text}");
                    assert_eq!(
                        text.contains("--no-session-id"),
                        !matches!(client, McpClient::ClaudeCode | McpClient::Muse),
                        "only Claude Code and Muse forward a session id: {text}"
                    );
                }
            }
        }
    }

    /// The documented stdio shape of a few clients whose keys differ.
    #[test]
    fn stdio_bridge_entries_follow_each_clients_documented_shape() {
        let entry = |client| {
            let mut args = args_for(client);
            args.stdio_bridge = true;
            build_json_mcp_entry(&args).unwrap()
        };
        let opencode = entry(McpClient::OpenCode);
        assert_eq!(opencode["type"], "local");
        assert_eq!(opencode["command"][0], bridge_command());
        assert_eq!(opencode["command"][1], "mcp-bridge");
        assert_eq!(opencode["enabled"], true);
        assert!(entry(McpClient::OpenCode2).get("enabled").is_none());
        assert_eq!(entry(McpClient::CopilotCli)["type"], "local");
        assert_eq!(entry(McpClient::CopilotCli)["tools"][0], "*");
        assert_eq!(entry(McpClient::CommandCode)["transport"], "stdio");
        assert_eq!(entry(McpClient::VsCodeCopilot)["type"], "stdio");
        assert!(entry(McpClient::Zed).get("type").is_none());
        let cline = entry(McpClient::Cline);
        assert_eq!(cline["command"], bridge_command());
        assert_eq!(cline["args"][0], "mcp-bridge");
        assert!(cline.get("transport").is_none(), "{cline:#}");
        // Kimi Code's schema dialect rides the bridge's upstream URL.
        assert_eq!(
            entry(McpClient::KimiCode)["args"][3],
            "http://127.0.0.1:49374/mcp?flavor=moonshot"
        );

        let mut grok = args_for(McpClient::Grok);
        grok.stdio_bridge = true;
        let mut doc = toml_edit::DocumentMut::new();
        grok_upsert_mcp_server(&mut doc, &grok).unwrap();
        let text = doc.to_string();
        let expected_command = bridge_command();
        assert_eq!(
            doc["mcp_servers"]["ai-memory"]["command"].as_str(),
            Some(expected_command.as_str()),
            "{text}"
        );
        assert!(!text.contains("url ="), "{text}");

        let mut dsh = args_for(McpClient::Dsh);
        dsh.stdio_bridge = true;
        let yaml = render_dsh_snippet(&dsh);
        assert!(yaml.contains("transport: stdio"), "{yaml}");
        assert!(yaml.contains("- '--no-session-id'"), "{yaml}");
    }

    /// A flavored upstream URL keeps its query when the bridge normalises it.
    #[test]
    fn mcp_server_url_from_base_keeps_a_query_after_the_path() {
        assert_eq!(
            mcp_server_url_from_base("http://h:1/mcp?flavor=moonshot"),
            "http://h:1/mcp?flavor=moonshot"
        );
        assert_eq!(
            mcp_server_url_from_base("http://h:1/?flavor=gemini"),
            "http://h:1/mcp?flavor=gemini"
        );
        assert_eq!(mcp_server_url_from_base("http://h:1/"), "http://h:1/mcp");
    }

    /// Controls: an inline token (pre-default install, `AI_MEMORY_AUTH_TOKEN`) and
    /// an explicit `--auth-token` keep embedding exactly as before.
    #[test]
    fn inline_and_explicit_tokens_still_embed_as_before() {
        let tmp = tempfile::tempdir().unwrap();
        let mut inline = Config::default();
        inline.auth.bearer_token = Some("inline-token".into());
        let cursor = tmp.path().join("cursor.json");
        apply_with(&inline, McpClient::Cursor, &cursor).unwrap();
        assert!(
            std::fs::read_to_string(&cursor)
                .unwrap()
                .contains("Bearer inline-token")
        );

        let config = file_token_config(tmp.path());
        let explicit = tmp.path().join("explicit.json");
        let mut args = args_for(McpClient::Cursor);
        args.apply = true;
        args.config_file = Some(explicit.clone());
        args.auth_token = Some("explicit-token".into());
        run_with_opencode_dialect(&config, args, None).unwrap();
        let text = std::fs::read_to_string(&explicit).unwrap();
        assert!(text.contains("Bearer explicit-token"), "{text}");
        assert!(!text.contains(FILE_TOKEN), "{text}");
    }

    /// Every bridge entry names a data dir the install was given, as the
    /// install's hooks do, so the bridge reads that install's config and
    /// bearer rather than the default data dir's. Controls: a default install
    /// keeps its entries unchanged (only Muse, which clears the environment,
    /// names the dir regardless), and the Docker helper, whose data dir is a
    /// container path, names it for no client.
    /// Whether a written entry names `path`. JSON (and TOML basic strings)
    /// escape a Windows path's backslashes, so look for that form too.
    fn names_path(text: &str, path: &Path) -> bool {
        let raw = path.to_string_lossy();
        let escaped = serde_json::to_string(raw.as_ref()).unwrap();
        text.contains(raw.as_ref()) || text.contains(escaped.trim_matches('"'))
    }

    #[test]
    fn bridge_entries_name_a_data_dir_the_install_was_given() {
        let tmp = tempfile::tempdir().unwrap();
        let data_dir = tmp.path().join("client-data");
        let installed = |config: &Config, label: &str| {
            let mut bridges = 0;
            for &client in <McpClient as clap::ValueEnum>::value_variants() {
                if matches!(
                    client,
                    McpClient::Pi | McpClient::Dsh | McpClient::Zcode | McpClient::Hermes
                ) {
                    continue; // no config file, print-only, HTTP-only, and YAML print-only
                }
                let ext = if matches!(client, McpClient::Codex | McpClient::Grok) {
                    "toml"
                } else {
                    "json"
                };
                let file = tmp.path().join(format!("{label}-{client:?}.{ext}"));
                apply_with(config, client, &file).unwrap_or_else(|e| panic!("{client:?}: {e:#}"));
                let text = std::fs::read_to_string(&file).unwrap();
                if text.contains("mcp-bridge") {
                    bridges += 1;
                }
                let names_dir = text.contains("--data-dir") && names_path(&text, &data_dir);
                let expected = match label {
                    "explicit" => text.contains("mcp-bridge"),
                    "default" => matches!(client, McpClient::Muse | McpClient::Freebuff),
                    _ => false,
                };
                assert_eq!(names_dir, expected, "{label} {client:?}: {text}");
            }
            assert!(
                bridges > 2,
                "{label}: too few bridge entries to prove anything"
            );
        };

        let mut explicit = file_token_config(&data_dir);
        explicit.data_dir = data_dir.clone();
        explicit.data_dir_explicit = true;
        installed(&explicit, "explicit");

        let mut default = explicit.clone();
        default.data_dir_explicit = false;
        installed(&default, "default");

        let mut docker = explicit.clone();
        docker.runtime_env = crate::config::RuntimeEnv::with_host_cwd_for_tests("/host/repo");
        installed(&docker, "docker");
    }

    /// An explicit `--auth-token` for an entry that runs the bridge is stored
    /// in `<data_dir>/auth-token`, where the bridge reads it, and the entry
    /// names that data dir instead of carrying the key. Controls, each of
    /// which keeps the key inline as before and stores nothing new: the print
    /// path, a bearer the config already resolves (it would win over the
    /// stored key), a different key already stored for the hooks, hooks that
    /// sign in with OIDC, the Docker helper, and an HTTP entry, whose literal
    /// header is documented.
    #[test]
    fn an_explicit_key_for_a_bridge_is_stored_instead_of_written_inline() {
        const KEY: &str = "aim_explicit_key";
        let tmp = tempfile::tempdir().unwrap();
        let config_in = |name: &str| Config {
            data_dir: tmp.path().join(name),
            ..Config::default()
        };
        let install = |config: &Config, client: McpClient, apply: bool| -> String {
            let file = config.data_dir.with_extension(format!("{client:?}.json"));
            let mut args = args_for(client);
            args.apply = apply;
            args.config_file = Some(file.clone());
            args.session_aware = client == McpClient::ClaudeCode;
            args.auth_token = Some(KEY.into());
            run_with_opencode_dialect(config, args, None).unwrap();
            std::fs::read_to_string(&file).unwrap_or_default()
        };
        let stored = |config: &Config| crate::config::read_hook_auth_token(&config.data_dir);

        for client in [McpClient::ClaudeCode, McpClient::Muse] {
            let config = config_in(&format!("stored-{client:?}"));
            let text = install(&config, client, true);
            assert!(
                !text.contains(KEY),
                "{client:?} entry still carries the key: {text}"
            );
            assert!(!text.contains("AI_MEMORY_AUTH_TOKEN"), "{client:?}: {text}");
            assert!(text.contains("--data-dir"), "{client:?}: {text}");
            assert!(
                names_path(&text, &config.data_dir),
                "{client:?} entry must name the dir the key went into: {text}"
            );
            assert_eq!(stored(&config).as_deref(), Some(KEY), "{client:?}");
            // The shell hooks read the header file of the same pair.
            assert_eq!(
                std::fs::read_to_string(crate::config::hook_auth_header_path_in(&config.data_dir))
                    .unwrap(),
                format!("Authorization: Bearer {KEY}\n")
            );
        }

        let printed = config_in("printed");
        install(&printed, McpClient::ClaudeCode, false);
        assert_eq!(
            stored(&printed),
            None,
            "a printed snippet must store nothing"
        );

        let mut configured = config_in("configured");
        configured.auth.bearer_token = Some("configured-bearer".into());
        assert!(install(&configured, McpClient::ClaudeCode, true).contains(KEY));
        assert_eq!(stored(&configured), None);

        let remote = config_in("different-endpoint");
        let remote_file = remote.data_dir.with_extension("remote.json");
        let mut remote_args = args_for(McpClient::ClaudeCode);
        remote_args.apply = true;
        remote_args.session_aware = true;
        remote_args.config_file = Some(remote_file.clone());
        remote_args.server_url = Some("https://other.example/mcp".into());
        remote_args.auth_token = Some(KEY.into());
        run_with_opencode_dialect(&remote, remote_args, None).unwrap();
        let remote_text = std::fs::read_to_string(remote_file).unwrap();
        assert!(remote_text.contains(KEY));
        assert_eq!(
            stored(&remote),
            None,
            "a key for another server is not hook auth"
        );

        let other = config_in("other");
        crate::config::store_hook_auth_token(&other.data_dir, "aim_hooks_key").unwrap();
        assert!(install(&other, McpClient::ClaudeCode, true).contains(KEY));
        assert_eq!(stored(&other).as_deref(), Some("aim_hooks_key"));

        let oidc = config_in("oidc");
        let response = ai_memory_llm::OidcTokenResponse {
            access_token: "oidc-access".into(),
            refresh_token: Some("oidc-refresh".into()),
            expires_in: None,
        };
        std::fs::create_dir_all(&oidc.data_dir).unwrap();
        ai_memory_llm::OidcToken::from_token_response(&response, "iss", "cid", "ep", None)
            .unwrap()
            .save(&oidc.data_dir.join("auth.json"))
            .unwrap();
        assert!(install(&oidc, McpClient::ClaudeCode, true).contains(KEY));
        assert_eq!(
            stored(&oidc),
            None,
            "OIDC hooks must not be switched to the key"
        );

        let mut docker = config_in("docker");
        docker.runtime_env = crate::config::RuntimeEnv::with_host_cwd_for_tests("/host/repo");
        assert!(install(&docker, McpClient::ClaudeCode, true).contains(KEY));
        assert_eq!(stored(&docker), None);

        let http = config_in("http");
        assert!(install(&http, McpClient::Cursor, true).contains(&format!("Bearer {KEY}")));
        assert_eq!(stored(&http), None);
    }

    #[test]
    fn failed_bridge_apply_rolls_back_a_newly_stored_key() {
        let tmp = tempfile::tempdir().unwrap();
        let config = Config {
            data_dir: tmp.path().join("data"),
            ..Config::default()
        };
        let config_file = tmp.path().join("broken.json");
        std::fs::write(&config_file, "[]").unwrap();
        let mut args = args_for(McpClient::ClaudeCode);
        args.apply = true;
        args.session_aware = true;
        args.config_file = Some(config_file);
        args.auth_token = Some("aim_must_rollback".into());

        let error = run_with_opencode_dialect(&config, args, None).unwrap_err();
        assert!(error.to_string().contains("object"), "{error:#}");
        assert_eq!(crate::config::read_hook_auth_token(&config.data_dir), None);
        assert!(!crate::config::hook_auth_header_path_in(&config.data_dir).exists());
    }

    #[test]
    fn mcp_server_url_defaults_to_configured_server_url() {
        let config = Config {
            server_url: "http://192.168.0.90:49374/".into(),
            ..Config::default()
        };
        let args = args_for(McpClient::OpenCode);

        assert_eq!(
            effective_mcp_server_url(&config, &args),
            "http://192.168.0.90:49374/mcp"
        );
    }

    #[test]
    fn mcp_server_url_does_not_duplicate_mcp_suffix() {
        let config = Config {
            server_url: "http://192.168.0.90:49374/mcp".into(),
            ..Config::default()
        };
        let args = args_for(McpClient::OpenCode);

        assert_eq!(
            effective_mcp_server_url(&config, &args),
            "http://192.168.0.90:49374/mcp"
        );
    }

    /// Regression for #185: an explicit `--server-url` passed as a BASE url
    /// (the same value `install-hooks --server-url` takes) must gain the
    /// `/mcp` suffix, or every client renderer emits a config pointing at
    /// the server root, which 404s. Trailing slashes are trimmed first.
    #[test]
    fn mcp_server_url_explicit_base_url_gains_mcp_suffix() {
        let config = Config::default();
        let mut args = args_for(McpClient::ClaudeCode);
        args.server_url = Some("https://memory.example.com".into());
        assert_eq!(
            effective_mcp_server_url(&config, &args),
            "https://memory.example.com/mcp"
        );

        args.server_url = Some("https://memory.example.com/".into());
        assert_eq!(
            effective_mcp_server_url(&config, &args),
            "https://memory.example.com/mcp"
        );

        // A reverse-proxy base path keeps its prefix.
        args.server_url = Some("https://host/prefix".into());
        assert_eq!(
            effective_mcp_server_url(&config, &args),
            "https://host/prefix/mcp"
        );
    }

    #[test]
    fn mcp_server_url_explicit_flag_wins_over_config() {
        let config = Config {
            server_url: "http://homelab:49374".into(),
            ..Config::default()
        };
        let mut args = args_for(McpClient::OpenCode);
        args.server_url = Some("http://explicit:49374/mcp".into());

        assert_eq!(
            effective_mcp_server_url(&config, &args),
            "http://explicit:49374/mcp"
        );
    }

    /// Regression (found 2026-07-12 during Devin real-acceptance A/B
    /// testing): an explicit `--server-url` that happens to equal the
    /// compiled-in `DEFAULT_MCP_URL` must still win over a configured
    /// (env/config.toml) server_url pointing somewhere else. Mirrors
    /// `hook_server_url_explicit_flag_matching_compiled_default_still_wins`
    /// in install_hooks.rs -- same bug class, same fix, both commands.
    #[test]
    fn mcp_server_url_explicit_flag_matching_compiled_default_still_wins() {
        let config = Config {
            server_url: "http://127.0.0.1:49375".into(),
            ..Config::default()
        };
        let mut args = args_for(McpClient::OpenCode);
        args.server_url = Some(DEFAULT_MCP_URL.to_string());

        assert_eq!(
            effective_mcp_server_url(&config, &args),
            DEFAULT_MCP_URL,
            "an explicit --server-url matching the compiled default must not be \
             silently overridden by a differently-configured server_url"
        );
    }

    /// #1269: with only a custom `bind`, the MCP entry points at the server
    /// that bind starts rather than the compiled default; a plain default
    /// config is unchanged.
    #[test]
    fn mcp_server_url_uses_a_bind_derived_url() {
        let config = Config {
            server_url: "http://127.0.0.1:49921".into(),
            server_url_derived_from_bind: true,
            ..Config::default()
        };
        let args = args_for(McpClient::OpenCode);
        assert_eq!(
            effective_mcp_server_url(&config, &args),
            "http://127.0.0.1:49921/mcp"
        );
        assert_eq!(
            effective_mcp_server_url(&Config::default(), &args),
            DEFAULT_MCP_URL
        );
    }

    /// Specific shape checks — each client has a distinguishing key
    /// in its JSON snippet. This catches accidental cross-pollination
    /// between renderers (e.g. Gemini's `httpUrl` showing up under
    /// Cursor's `mcpServers`).
    #[test]
    fn client_specific_shape_keys() {
        assert!(render_for_test(McpClient::Cursor).contains("\"url\""));
        assert!(render_for_test(McpClient::GeminiCli).contains("\"httpUrl\""));
        assert!(render_for_test(McpClient::QwenCode).contains("\"httpUrl\""));
        assert!(render_for_test(McpClient::ClaudeDesktop).contains("mcp-remote"));
        assert!(render_for_test(McpClient::Openclaw).contains("\"streamable-http\""));
        assert!(render_for_test(McpClient::Codex).contains("[mcp_servers.ai-memory]"));
        let grok = render_for_test(McpClient::Grok);
        assert!(grok.contains("[mcp_servers.ai-memory]"));
        assert!(grok.contains("enabled = true"));
        assert!(
            grok.contains(
                &grok_home()
                    .unwrap()
                    .join("config.toml")
                    .display()
                    .to_string()
            )
        );
        // Grok uses `headers`, never Codex's `http_headers`.
        let grok_token = render_with_token(McpClient::Grok);
        assert!(grok_token.contains("[mcp_servers.ai-memory.headers]"));
        assert!(!grok_token.contains("http_headers"));
        let omp = render_for_test(McpClient::Omp);
        for location in [
            "~/.omp/agent/mcp.json",
            "~/.omp/profiles/<name>/agent/mcp.json",
            "$PI_CODING_AGENT_DIR/mcp.json",
        ] {
            assert!(omp.contains(location), "{location} missing from:\n{omp}");
        }
        let pi = render_pi(&args_for(McpClient::Pi)).unwrap();
        assert!(pi.contains("Pi has no native mcp.json"));
        assert!(pi.contains("install-hooks --agent pi --apply"));
        assert!(pi.contains("~/.pi/agent/extensions/ai-memory-pi.ts"));
        assert!(pi.contains("$PI_CODING_AGENT_DIR/extensions/ai-memory-pi.ts"));
        assert!(!pi.contains("~/.pi/agent/extensions/ai-memory.ts"));
        assert!(!pi.contains("~/.omp"));
        assert!(render_for_test(McpClient::AntigravityCli).contains("\"serverUrl\""));
        // The snippet must point at the documented global config, not the
        // internal ~/.gemini/antigravity-cli/ data dir (#510).
        assert!(
            render_for_test(McpClient::AntigravityCli).contains("~/.gemini/config/mcp_config.json")
        );
        assert!(!render_for_test(McpClient::AntigravityCli).contains("~/.gemini/antigravity-cli/"));
        let devin = render_for_test(McpClient::Devin);
        assert!(devin.contains("\"mcpServers\""));
        assert!(devin.contains("\"url\""));
        assert!(devin.contains("\"transport\": \"http\""));
        assert!(!devin.contains("\"httpUrl\""));
        let devin_with_token = render_with_token(McpClient::Devin);
        assert!(devin_with_token.contains("\"headers\""));
        assert!(devin_with_token.contains("\"Authorization\": \"Bearer test-token-deadbeef\""));
        // Kimi Code: `url` with NO `transport` field means streamable-HTTP
        // (`transport` is legacy-SSE-only there), and the URL key is plain
        // `url` — not Gemini's `httpUrl` or Antigravity's `serverUrl`.
        let kimi = render_for_test(McpClient::KimiCode);
        assert!(kimi.contains("\"mcpServers\""));
        assert!(kimi.contains("\"url\""));
        assert!(kimi.contains("http://127.0.0.1:49374/mcp?flavor=moonshot"));
        assert!(!kimi.contains("\"transport\""));
        assert!(!kimi.contains("\"httpUrl\""));
        assert!(!kimi.contains("\"serverUrl\""));
        let kimi_with_token = render_with_token(McpClient::KimiCode);
        assert!(kimi_with_token.contains("\"headers\""));
        assert!(kimi_with_token.contains("\"Authorization\": \"Bearer test-token-deadbeef\""));
        let kiro = render_for_test(McpClient::KiroCli);
        assert!(kiro.contains("\"mcpServers\""));
        assert!(kiro.contains("http://127.0.0.1:49374/mcp?flavor=bedrock"));
        assert!(!kiro.contains("\"transport\""));
        assert!(kiro.contains("install-hooks --agent kiro-cli"));
        assert!(kiro.contains("install-hooks --agent kiro-cli-v3"));
        let kiro_with_token = render_with_token(McpClient::KiroCli);
        assert!(kiro_with_token.contains("\"Authorization\": \"Bearer test-token-deadbeef\""));
        // VS Code Copilot must use the `servers` top-level key — the
        // `mcpServers` form is silently ignored by VS Code's MCP
        // framework. Regression guard against a future copy-paste
        // from the Cursor / Claude Code renderer.
        let vsc = render_for_test(McpClient::VsCodeCopilot);
        assert!(vsc.contains("\"servers\""));
        assert!(!vsc.contains("\"mcpServers\""));
        assert!(vsc.contains("\"type\": \"http\""));
        let zed = render_for_test(McpClient::Zed);
        assert!(zed.contains("\"context_servers\""));
        assert!(!zed.contains("\"mcpServers\""));
        assert!(!zed.contains("\"type\": \"http\""));
    }

    /// Kimi Code resolves its mcp.json under $KIMI_CODE_HOME when the env
    /// var is set (non-empty), else under ~/.kimi-code. Tested through the
    /// helper's parameter so no process-env mutation (unsafe in edition
    /// 2024, and racy under parallel tests) is needed.
    #[test]
    fn kimi_code_home_honours_env_override() {
        assert_eq!(
            kimi_code_home(Some("/tmp/custom-kimi-home".into())).unwrap(),
            PathBuf::from("/tmp/custom-kimi-home")
        );
        let default = home_dir().unwrap().join(".kimi-code");
        // An empty override falls back to the default home-based dir.
        assert_eq!(kimi_code_home(Some("".into())).unwrap(), default);
        assert_eq!(kimi_code_home(None).unwrap(), default);
    }

    #[test]
    fn kiro_home_honours_env_override() {
        assert_eq!(
            kiro_home(Some("/tmp/custom-kiro-home".into())).unwrap(),
            PathBuf::from("/tmp/custom-kiro-home")
        );
        let default = home_dir().unwrap().join(".kiro");
        assert_eq!(kiro_home(Some("".into())).unwrap(), default);
        assert_eq!(kiro_home(None).unwrap(), default);
    }

    /// Pin the Antigravity CLI config destination to the documented global
    /// config at ~/.gemini/config/mcp_config.json. ~/.gemini/antigravity-cli/
    /// is Antigravity's internal data dir and only holds a copy Antigravity
    /// itself writes, so a registration there works by coincidence on an
    /// established install and is silently ignored on a fresh one (#510).
    #[test]
    fn antigravity_cli_mcp_config_path_pins_documented_location() {
        assert_eq!(
            mcp_config_path(McpClient::AntigravityCli).unwrap(),
            home_dir()
                .unwrap()
                .join(".gemini")
                .join("config")
                .join("mcp_config.json")
        );
    }

    /// Pin ZCode's user-scope config destination: ~/.zcode/cli/config.json.
    /// Workspace scopes (.zcode/config.json, zcode.json, .agents/mcp.json)
    /// exist, but user scope is the install default every other client
    /// uses too (#511).
    #[test]
    fn zcode_mcp_config_path_pins_user_scope_location() {
        assert_eq!(
            mcp_config_path(McpClient::Zcode).unwrap(),
            home_dir()
                .unwrap()
                .join(".zcode")
                .join("cli")
                .join("config.json")
        );
    }

    /// ZCode's entry schema is strict — any key outside
    /// type/url/headers/enabled/timeoutMs makes it drop the server
    /// silently — so the fragment must carry exactly the documented
    /// keys, nested under `mcp.servers` (#511).
    #[test]
    fn zcode_renderer_nests_strict_http_entry_under_mcp_servers() {
        let fragment = render_json_mcp_fragment(&args_with_token(McpClient::Zcode)).unwrap();
        let value: serde_json::Value = serde_json::from_str(&fragment).unwrap();

        assert_eq!(
            value,
            json!({
                "mcp": {
                    "servers": {
                        "ai-memory": {
                            "type": "http",
                            "url": "http://127.0.0.1:49374/mcp",
                            "headers": {
                                "Authorization": "Bearer test-token-deadbeef"
                            }
                        }
                    }
                }
            })
        );
        let rendered = render_zcode(&args_for(McpClient::Zcode)).unwrap();
        assert!(rendered.contains("~/.zcode/cli/config.json"));
        assert!(rendered.contains("strict"));
    }

    /// `--apply` merges under `mcp.servers` keeping the rest of the
    /// config and sibling servers intact, and re-runs are a no-op.
    #[test]
    fn zcode_apply_preserves_siblings_and_is_idempotent() {
        let tmp = tempfile::TempDir::new().unwrap();
        let config_path = tmp.path().join("config.json");
        fs::write(
            &config_path,
            r#"{
  "theme": "dark",
  "mcp": {
    "servers": {
      "other": {"type": "http", "url": "https://other.example/mcp"}
    }
  }
}"#,
        )
        .unwrap();
        let mut args = args_with_token(McpClient::Zcode);
        args.config_file = Some(config_path.clone());

        apply_to_config_file(&args).unwrap();
        let first = fs::read_to_string(&config_path).unwrap();
        apply_to_config_file(&args).unwrap();
        let second = fs::read_to_string(&config_path).unwrap();

        assert_eq!(first, second);
        let value: serde_json::Value = serde_json::from_str(&second).unwrap();
        assert_eq!(value["theme"], "dark");
        assert_eq!(
            value["mcp"]["servers"]["other"]["url"], "https://other.example/mcp",
            "install must preserve sibling servers"
        );
        assert_eq!(value["mcp"]["servers"]["ai-memory"]["type"], "http");
        assert_eq!(
            value["mcp"]["servers"]["ai-memory"]["headers"]["Authorization"],
            "Bearer test-token-deadbeef"
        );
    }

    /// Pin the append rules: `?` on a bare endpoint, `&` with an existing
    /// query, never duplicate an existing marker.
    #[test]
    fn an_explicit_flavor_pins_a_client_the_installer_cannot_infer() {
        // The issue-735 shape: Command Code fronts several models, so its name
        // says nothing about the upstream. Routed to Vertex it needs the Gemini
        // dialect, and before --flavor there was no installer path to it.
        let mut args = args_for(McpClient::CommandCode);
        args.server_url = Some("https://memory.example/mcp".into());
        args.flavor = Some(SchemaFlavor::Gemini);

        let entry = build_mcp_entry(&args).unwrap();

        assert_eq!(
            entry["url"].as_str().unwrap(),
            "https://memory.example/mcp?flavor=gemini"
        );
    }

    /// OpenCode is the other client `--flavor`'s documentation names, and it
    /// has its own entry builders. They read `server_url` directly, so the
    /// flag was silently dropped and Vertex 400'd every `tools/list`.
    #[test]
    fn an_explicit_flavor_reaches_the_opencode_entry_builders() {
        for client in [McpClient::OpenCode, McpClient::OpenCode2] {
            let mut args = args_for(client);
            args.server_url = Some("https://memory.example/mcp".into());
            args.flavor = Some(SchemaFlavor::Gemini);

            let entry = match client {
                McpClient::OpenCode => build_mcp_entry_opencode(&args).unwrap(),
                _ => build_mcp_entry_opencode2(&args).unwrap(),
            };

            assert_eq!(
                entry["url"].as_str().unwrap(),
                "https://memory.example/mcp?flavor=gemini",
                "{client:?}"
            );
        }
    }

    /// Control: OpenCode has no built-in dialect, so an install that did not
    /// ask for one must still get the bare endpoint.
    #[test]
    fn opencode_stays_unflavored_without_the_flag() {
        for client in [McpClient::OpenCode, McpClient::OpenCode2] {
            let mut args = args_for(client);
            args.server_url = Some("https://memory.example/mcp".into());

            let entry = match client {
                McpClient::OpenCode => build_mcp_entry_opencode(&args).unwrap(),
                _ => build_mcp_entry_opencode2(&args).unwrap(),
            };

            assert_eq!(
                entry["url"].as_str().unwrap(),
                "https://memory.example/mcp",
                "{client:?}"
            );
        }
    }

    #[test]
    fn a_client_without_a_fixed_upstream_stays_unflavored_by_default() {
        let mut args = args_for(McpClient::CommandCode);
        args.server_url = Some("https://memory.example/mcp".into());

        let entry = build_mcp_entry(&args).unwrap();

        assert_eq!(entry["url"].as_str().unwrap(), "https://memory.example/mcp");
    }

    #[test]
    fn an_explicit_flavor_replaces_the_clients_built_in_default() {
        // Kimi Code defaults to moonshot. Asking for gemini must not stack a
        // second marker: the server maxes over every pair, so both would work,
        // but the installed URL would carry a dialect the operator did not pick.
        let mut args = args_for(McpClient::KimiCode);
        args.server_url = Some("https://memory.example/mcp".into());
        args.flavor = Some(SchemaFlavor::Gemini);

        let entry = build_mcp_entry(&args).unwrap();

        assert_eq!(
            entry["url"].as_str().unwrap(),
            "https://memory.example/mcp?flavor=gemini"
        );
    }

    #[test]
    fn the_session_aware_bridge_keeps_the_unflavored_url() {
        // `mcp-bridge` is our own process, not a schema consumer. Handing it a
        // flavored URL would push the marker through to the server on every
        // bridged request, narrowing schemas for a client that never asked.
        let mut args = args_for(McpClient::ClaudeCode);
        args.server_url = Some("https://memory.example/mcp".into());
        args.session_aware = true;
        args.flavor = Some(SchemaFlavor::Gemini);

        let entry = build_mcp_entry(&args).unwrap();

        let bridge_args: Vec<&str> = entry["args"]
            .as_array()
            .unwrap()
            .iter()
            .map(|a| a.as_str().unwrap())
            .collect();
        assert_eq!(
            bridge_args,
            vec!["mcp-bridge", "--server-url", "https://memory.example/mcp"]
        );
    }

    #[test]
    fn every_flavor_marker_is_one_the_server_recognizes() {
        // The server matches `flavor=` values exactly. A marker the CLI can
        // write but the server does not match would install a URL that silently
        // serves upstream schemas — the exact failure --flavor exists to avoid.
        for flavor in [
            SchemaFlavor::Moonshot,
            SchemaFlavor::Bedrock,
            SchemaFlavor::Gemini,
        ] {
            assert!(
                FLAVOR_MARKERS.contains(&flavor.marker()),
                "{:?} writes marker {:?}, which uninstall does not know",
                flavor,
                flavor.marker()
            );
        }
    }

    #[test]
    fn moonshot_flavored_mcp_url_appends_marker_idempotently() {
        for (input, expected) in [
            (
                "http://127.0.0.1:49374/mcp",
                "http://127.0.0.1:49374/mcp?flavor=moonshot",
            ),
            (
                "http://homelab:49374/mcp?token=abc",
                "http://homelab:49374/mcp?token=abc&flavor=moonshot",
            ),
            (
                "http://127.0.0.1:49374/mcp?flavor=moonshot",
                "http://127.0.0.1:49374/mcp?flavor=moonshot",
            ),
            (
                "http://homelab:49374/mcp?token=abc&flavor=moonshot",
                "http://homelab:49374/mcp?token=abc&flavor=moonshot",
            ),
            // Whole-pair match: a marker inside another pair's VALUE doesn't count.
            (
                "http://homelab:49374/mcp?note=flavor=moonshot",
                "http://homelab:49374/mcp?note=flavor=moonshot&flavor=moonshot",
            ),
        ] {
            assert_eq!(
                flavored_mcp_url_for_marker(input, "moonshot"),
                expected,
                "input: {input}"
            );
        }
    }

    #[test]
    fn bedrock_flavored_mcp_url_appends_marker_idempotently() {
        assert_eq!(
            flavored_mcp_url_for_marker("https://memory.example/mcp", "bedrock"),
            "https://memory.example/mcp?flavor=bedrock"
        );
        assert_eq!(
            flavored_mcp_url_for_marker("https://memory.example/mcp?token=x", "bedrock"),
            "https://memory.example/mcp?token=x&flavor=bedrock"
        );
        assert_eq!(
            flavored_mcp_url_for_marker("https://memory.example/mcp?flavor=bedrock", "bedrock"),
            "https://memory.example/mcp?flavor=bedrock"
        );
    }

    #[test]
    fn kiro_rejects_plain_http_for_non_loopback_servers() {
        for allowed in [
            "http://localhost:49374/mcp",
            "http://127.0.0.1:49374/mcp",
            "http://[::1]:49374/mcp",
            "https://memory.example/mcp",
        ] {
            let mut args = args_for(McpClient::KiroCli);
            args.server_url = Some(allowed.into());
            validate_args(&args).unwrap_or_else(|error| panic!("{allowed}: {error:#}"));
        }

        let mut args = args_for(McpClient::KiroCli);
        args.server_url = Some("http://192.168.0.90:49374/mcp".into());
        let error = validate_args(&args).unwrap_err();
        assert!(error.to_string().contains("requires HTTPS"), "{error:#}");
    }

    #[test]
    fn copilot_cli_apply_preserves_siblings_and_is_idempotent() {
        let tmp = tempfile::TempDir::new().unwrap();
        let config_path = tmp.path().join("mcp-config.json");
        fs::write(
            &config_path,
            r#"{"mcpServers":{"github":{"type":"http","url":"https://api.githubcopilot.com/mcp/"}}}"#,
        )
        .unwrap();
        let mut args = args_with_token(McpClient::CopilotCli);
        args.server_url = Some("https://memory.example/mcp".into());
        args.config_file = Some(config_path.clone());

        apply_to_config_file(&args).unwrap();
        let first = fs::read_to_string(&config_path).unwrap();
        apply_to_config_file(&args).unwrap();
        let second = fs::read_to_string(&config_path).unwrap();

        assert_eq!(first, second);
        let value: serde_json::Value = serde_json::from_str(&second).unwrap();
        assert_eq!(
            value["mcpServers"]["github"]["url"],
            "https://api.githubcopilot.com/mcp/"
        );
        let ours = &value["mcpServers"]["ai-memory"];
        assert_eq!(ours["type"], "http");
        // No default flavor: Copilot CLI fronts several model vendors.
        assert_eq!(ours["url"], "https://memory.example/mcp");
        assert_eq!(
            ours["headers"]["Authorization"],
            "Bearer test-token-deadbeef"
        );
        assert_eq!(ours["tools"], json!(["*"]));
    }

    /// Prime Agent 0.10 lists a user HTTP server to the model only when its
    /// `bearerTokenEnvVar` is set, so a token is referenced by variable and
    /// never written into settings.json.
    #[test]
    fn prime_agent_entry_names_the_token_variable_never_the_token() {
        let fragment = render_json_mcp_fragment(&args_with_token(McpClient::PrimeAgent)).unwrap();
        let value: serde_json::Value = serde_json::from_str(&fragment).unwrap();
        assert_eq!(
            value,
            json!({
                "mcpServers": {
                    "ai-memory": {
                        "type": "http",
                        "url": "http://127.0.0.1:49374/mcp",
                        "bearerTokenEnvVar": "AI_MEMORY_AUTH_TOKEN"
                    }
                }
            })
        );

        let rendered = render_prime_agent(&args_with_token(McpClient::PrimeAgent)).unwrap();
        assert!(!rendered.contains("test-token-deadbeef"), "{rendered}");
        assert!(rendered.contains("export it where you launch prime-agent"));
        assert!(rendered.contains("~/.prime/agent/settings.json"));
        assert!(rendered.contains(r#"await mcp.call_tool("ai-memory", "memory_query""#));
    }

    #[test]
    fn prime_agent_entry_without_a_token_is_bare_http_and_says_it_is_unlisted() {
        let entry = build_json_mcp_entry(&args_for(McpClient::PrimeAgent)).unwrap();
        assert_eq!(
            entry,
            json!({"type": "http", "url": "http://127.0.0.1:49374/mcp"})
        );
        let rendered = render_prime_agent(&args_for(McpClient::PrimeAgent)).unwrap();
        assert!(rendered.contains("not connected"), "{rendered}");
        assert!(
            !rendered.contains("export it where you launch"),
            "{rendered}"
        );
    }

    /// Prime Agent fronts several model vendors, so it has no default schema
    /// flavor, but an explicit `--flavor` reaches the URL it lists tools from.
    #[test]
    fn prime_agent_entry_carries_an_explicit_flavor_only() {
        let mut args = args_for(McpClient::PrimeAgent);
        assert_eq!(
            build_json_mcp_entry(&args).unwrap()["url"],
            "http://127.0.0.1:49374/mcp"
        );
        args.flavor = Some(SchemaFlavor::Gemini);
        assert_eq!(
            build_json_mcp_entry(&args).unwrap()["url"],
            "http://127.0.0.1:49374/mcp?flavor=gemini"
        );
    }

    #[test]
    fn prime_agent_apply_preserves_settings_and_siblings_and_is_idempotent() {
        let tmp = tempfile::TempDir::new().unwrap();
        let config_path = tmp.path().join("settings.json");
        fs::write(
            &config_path,
            r#"{"defaultModel":"glm","mcpServers":{"search":{"type":"http","url":"https://search.example/mcp","bearerTokenEnvVar":"SEARCH_TOKEN"}}}"#,
        )
        .unwrap();
        let mut args = args_with_token(McpClient::PrimeAgent);
        args.server_url = Some("https://memory.example/mcp".into());
        args.config_file = Some(config_path.clone());

        apply_to_config_file(&args).unwrap();
        let first = fs::read_to_string(&config_path).unwrap();
        apply_to_config_file(&args).unwrap();
        let second = fs::read_to_string(&config_path).unwrap();

        assert_eq!(first, second);
        assert!(!second.contains("test-token-deadbeef"), "{second}");
        let value: serde_json::Value = serde_json::from_str(&second).unwrap();
        assert_eq!(value["defaultModel"], "glm");
        assert_eq!(
            value["mcpServers"]["search"]["bearerTokenEnvVar"],
            "SEARCH_TOKEN"
        );
        assert_eq!(
            value["mcpServers"]["ai-memory"],
            json!({
                "type": "http",
                "url": "https://memory.example/mcp",
                "bearerTokenEnvVar": "AI_MEMORY_AUTH_TOKEN"
            })
        );
    }

    /// A name Prime Agent would never connect is refused before any write.
    #[test]
    fn prime_agent_rejects_server_names_it_cannot_resolve() {
        let tmp = tempfile::TempDir::new().unwrap();
        let config_path = tmp.path().join("settings.json");
        for name in [
            "",
            "-memory",
            "_memory",
            "ai memory",
            "ai.memory",
            &"m".repeat(65),
        ] {
            let mut args = args_for(McpClient::PrimeAgent);
            args.name = name.to_string();
            args.config_file = Some(config_path.clone());
            let error = apply_to_config_file(&args).unwrap_err();
            assert!(
                error.to_string().contains("Prime Agent MCP server names"),
                "{name:?}: {error:#}"
            );
            assert!(!config_path.exists(), "{name:?} must not write the file");
        }
        for name in ["ai-memory", "memory_2", "M", &"m".repeat(64)] {
            let mut args = args_for(McpClient::PrimeAgent);
            args.name = name.to_string();
            validate_args(&args).unwrap_or_else(|error| panic!("{name:?}: {error:#}"));
        }
    }

    #[test]
    fn prime_agent_dir_honours_env_override() {
        assert_eq!(
            prime_agent_dir_in(Some("/tmp/custom-prime-agent".into())).unwrap(),
            PathBuf::from("/tmp/custom-prime-agent")
        );
        let default = home_dir().unwrap().join(".prime").join("agent");
        assert_eq!(prime_agent_dir_in(Some("".into())).unwrap(), default);
        assert_eq!(prime_agent_dir_in(None).unwrap(), default);
    }

    #[test]
    fn kiro_apply_preserves_siblings_and_is_idempotent() {
        let tmp = tempfile::TempDir::new().unwrap();
        let config_path = tmp.path().join("mcp.json");
        fs::write(
            &config_path,
            r#"{"mcpServers":{"other":{"url":"https://other.example/mcp"}},"userSetting":true}"#,
        )
        .unwrap();
        let mut args = args_with_token(McpClient::KiroCli);
        args.server_url = Some("https://memory.example/mcp".into());
        args.config_file = Some(config_path.clone());

        apply_to_config_file(&args).unwrap();
        let first = fs::read_to_string(&config_path).unwrap();
        apply_to_config_file(&args).unwrap();
        let second = fs::read_to_string(&config_path).unwrap();

        assert_eq!(first, second);
        let value: serde_json::Value = serde_json::from_str(&second).unwrap();
        assert_eq!(value["userSetting"], true);
        assert_eq!(
            value["mcpServers"]["other"]["url"],
            "https://other.example/mcp"
        );
        assert_eq!(
            value["mcpServers"]["ai-memory"]["url"],
            "https://memory.example/mcp?flavor=bedrock"
        );
    }

    #[test]
    fn pi_apply_fails_closed_without_writing_even_with_config_override() {
        let tmp = tempfile::TempDir::new().unwrap();
        let path = tmp.path().join("mcp.json");
        let mut args = args_for(McpClient::Pi);
        args.apply = true;
        args.config_file = Some(path.clone());

        let err = apply_to_config_file(&args).unwrap_err().to_string();

        assert!(
            err.contains("has no native mcp.json"),
            "unexpected error: {err}"
        );
        assert!(
            err.contains("install-hooks --agent pi --apply"),
            "unexpected error: {err}"
        );
        assert!(!path.exists(), "Pi install must not write ignored config");
    }

    #[test]
    fn pi_guidance_derives_hook_url_from_mcp_url() {
        let mut args = args_for(McpClient::Pi);
        args.server_url = Some("http://host:49374/base/mcp".into());
        args.auth_token = Some("tok".into());

        let guidance = render_pi(&args).unwrap();

        assert!(guidance.contains("--server-url http://host:49374/base --auth-token <token>"));
        assert!(!guidance.contains("--server-url http://host:49374/base/mcp"));
    }

    /// The Codex apply path must emit block-form `[mcp_servers.<name>]`
    /// headers, NOT a dotted inline-table on one line. Regression
    /// guard: M22 originally created `mcp_servers = { ai-memory = {...} }`
    /// because toml_edit auto-vivifies inline tables when you assign
    /// through `doc["foo"]["bar"]`.
    #[test]
    fn codex_apply_writes_block_form_tables() {
        let args = args_with_token(McpClient::Codex);
        let mut doc: toml_edit::DocumentMut = "".parse().unwrap();
        codex_upsert_mcp_server(&mut doc, &args).unwrap();
        let out = doc.to_string();
        assert!(
            out.contains("[mcp_servers.ai-memory]"),
            "expected block-form table header, got:\n{out}"
        );
        // Auth lives on the [mcp_servers.X.http_headers] sub-table
        // with an Authorization: Bearer <token> value. The key is
        // `http_headers` (with the `http_` prefix) per Codex's
        // streamable_http schema. Two related regressions guarded
        // here:
        //   - the legacy `headers` key (no `http_` prefix) made
        //     Codex silently fall back to OAuth login;
        //   - a top-level `bearer_token = "..."` was rejected with
        //     "bearer_token is not supported for streamable_http"
        //     (that key is stdio-transport-only).
        assert!(
            out.contains("[mcp_servers.ai-memory.http_headers]"),
            "expected `[mcp_servers.X.http_headers]` sub-table, got:\n{out}"
        );
        assert!(
            out.contains("Authorization = \"Bearer test-token-deadbeef\""),
            "expected the Authorization header in the http_headers sub-table, got:\n{out}"
        );
        assert!(
            !out.contains("[mcp_servers.ai-memory.headers]"),
            "legacy `headers` key (no `http_` prefix) must not be emitted; got:\n{out}"
        );
        assert!(
            !out.contains("\nbearer_token ="),
            "top-level `bearer_token` is rejected for streamable_http; must not be emitted; got:\n{out}"
        );
        assert!(
            !out.contains("mcp_servers = {"),
            "found inline-table form (regression):\n{out}"
        );
    }

    /// Migrating from the old M22 inline-table form to block form must
    /// be idempotent — the second apply produces identical output.
    #[test]
    fn codex_apply_migrates_inline_form_and_is_idempotent() {
        let args = args_with_token(McpClient::Codex);

        // Simulate a config.toml in the *old* inline form.
        let original = "approval_policy = \"on-request\"\n\
                        mcp_servers = { ai-memory = { url = \"http://old\", \
                        headers = { Authorization = \"Bearer old\" } } }\n\
                        \n\
                        [other]\n\
                        keep = \"this\"\n";
        let mut doc: toml_edit::DocumentMut = original.parse().unwrap();
        codex_upsert_mcp_server(&mut doc, &args).unwrap();
        let first = doc.to_string();

        // After migration the inline-table form is gone.
        assert!(!first.contains("mcp_servers = {"));
        assert!(first.contains("[mcp_servers.ai-memory]"));
        // Unrelated content survives.
        assert!(first.contains("approval_policy"));
        assert!(first.contains("[other]"));
        assert!(first.contains("keep = \"this\""));

        // Re-applying produces the same bytes (idempotency contract).
        let mut doc2: toml_edit::DocumentMut = first.parse().unwrap();
        codex_upsert_mcp_server(&mut doc2, &args).unwrap();
        let second = doc2.to_string();
        assert_eq!(
            first, second,
            "second apply must produce identical bytes; diff:\n--- first\n{first}\n--- second\n{second}"
        );
    }

    /// Codex keeps auto-approving the read tools, but every tool annotated
    /// destructive gets a per-tool prompt.
    #[test]
    fn codex_apply_prompts_for_every_destructive_tool() {
        let destructive = ai_memory_mcp::AiMemoryServer::destructive_tool_names();
        assert!(
            destructive.iter().any(|tool| tool == "memory_delete_page"),
            "{destructive:?}"
        );
        let mut doc: toml_edit::DocumentMut = "".parse().unwrap();
        codex_upsert_mcp_server(&mut doc, &args_for(McpClient::Codex)).unwrap();
        let out = doc.to_string();
        assert!(
            out.contains("default_tools_approval_mode = \"approve\""),
            "{out}"
        );
        let server = &doc["mcp_servers"]["ai-memory"];
        for tool in &destructive {
            assert_eq!(
                server["tools"][tool.as_str()]["approval_mode"].as_str(),
                Some("prompt"),
                "{tool} must prompt:\n{out}"
            );
        }
        for read_tool in ["memory_query", "memory_recent", "memory_briefing"] {
            assert!(
                server["tools"].get(read_tool).is_none(),
                "{read_tool} keeps the approve default:\n{out}"
            );
        }

        let rendered = render_codex(&args_for(McpClient::Codex)).unwrap();
        for tool in &destructive {
            assert!(
                rendered.contains(&format!(
                    "[mcp_servers.ai-memory.tools.{tool}]\napproval_mode = \"prompt\""
                )),
                "{tool} missing from the printed snippet:\n{rendered}"
            );
        }
        rendered.parse::<toml_edit::DocumentMut>().unwrap();
    }

    /// A re-install keeps the per-tool choices the user already made.
    #[test]
    fn codex_apply_keeps_existing_per_tool_overrides() {
        let original = "[mcp_servers.ai-memory]\n\
                        url = \"http://old\"\n\
                        \n\
                        [mcp_servers.ai-memory.tools.memory_delete_page]\n\
                        approval_mode = \"approve\"\n\
                        \n\
                        [mcp_servers.ai-memory.tools.memory_query]\n\
                        approval_mode = \"prompt\"\n";
        let mut doc: toml_edit::DocumentMut = original.parse().unwrap();
        codex_upsert_mcp_server(&mut doc, &args_for(McpClient::Codex)).unwrap();
        let tools = &doc["mcp_servers"]["ai-memory"]["tools"];
        assert_eq!(
            tools["memory_delete_page"]["approval_mode"].as_str(),
            Some("approve")
        );
        assert_eq!(
            tools["memory_query"]["approval_mode"].as_str(),
            Some("prompt")
        );
        assert_eq!(
            tools["memory_forget_sweep"]["approval_mode"].as_str(),
            Some("prompt")
        );
    }

    /// Sibling `[mcp_servers.<other>]` entries the user has configured
    /// (e.g. a different MCP server) must survive an --apply.
    #[test]
    fn codex_apply_preserves_sibling_mcp_servers() {
        let args = args_for(McpClient::Codex);
        let original = "[mcp_servers.other-server]\n\
                        url = \"http://other\"\n";
        let mut doc: toml_edit::DocumentMut = original.parse().unwrap();
        codex_upsert_mcp_server(&mut doc, &args).unwrap();
        let out = doc.to_string();
        assert!(out.contains("[mcp_servers.other-server]"));
        assert!(out.contains("http://other"));
        assert!(out.contains("[mcp_servers.ai-memory]"));
    }

    #[test]
    fn grok_apply_writes_block_form_with_headers_not_http_headers() {
        let args = args_with_token(McpClient::Grok);
        let mut doc: toml_edit::DocumentMut = "".parse().unwrap();
        grok_upsert_mcp_server(&mut doc, &args).unwrap();
        let out = doc.to_string();
        assert!(
            out.contains("[mcp_servers.ai-memory]"),
            "expected block-form table header, got:\n{out}"
        );
        assert!(
            out.contains("enabled = true"),
            "expected enabled = true, got:\n{out}"
        );
        assert!(
            out.contains("[mcp_servers.ai-memory.headers]"),
            "expected `[mcp_servers.X.headers]` sub-table, got:\n{out}"
        );
        assert!(
            out.contains("Authorization = \"Bearer test-token-deadbeef\""),
            "expected Authorization header, got:\n{out}"
        );
        assert!(
            !out.contains("http_headers"),
            "Codex's http_headers key must not be emitted for Grok; got:\n{out}"
        );
        assert!(
            !out.contains("mcp_servers = {"),
            "found inline-table form (regression):\n{out}"
        );
    }

    #[test]
    fn grok_apply_preserves_sibling_mcp_servers_and_is_idempotent() {
        let args = args_with_token(McpClient::Grok);
        let original = "[mcp_servers.other-server]\n\
                        url = \"http://other\"\n\
                        enabled = true\n";
        let mut doc: toml_edit::DocumentMut = original.parse().unwrap();
        grok_upsert_mcp_server(&mut doc, &args).unwrap();
        let first = doc.to_string();
        assert!(first.contains("[mcp_servers.other-server]"));
        assert!(first.contains("http://other"));
        assert!(first.contains("[mcp_servers.ai-memory]"));
        assert!(first.contains("[mcp_servers.ai-memory.headers]"));

        let mut doc2: toml_edit::DocumentMut = first.parse().unwrap();
        grok_upsert_mcp_server(&mut doc2, &args).unwrap();
        assert_eq!(first, doc2.to_string());
    }

    #[test]
    fn grok_mcp_client_parses() {
        let cli = crate::cli::Cli::parse_from([
            "ai-memory",
            "install-mcp",
            "--client",
            "grok",
            "--server-url",
            "http://example.test:49374",
        ]);
        let crate::cli::Command::InstallMcp(args) = cli.command else {
            panic!("expected install-mcp");
        };
        assert!(matches!(args.client, McpClient::Grok));
    }

    #[test]
    fn devin_mcp_client_parses() {
        let cli = crate::cli::Cli::parse_from([
            "ai-memory",
            "install-mcp",
            "--client",
            "devin",
            "--server-url",
            "http://example.test:49374",
        ]);
        let crate::cli::Command::InstallMcp(mcp_args) = cli.command else {
            panic!("expected install-mcp command for devin");
        };
        assert!(matches!(mcp_args.client, crate::cli::McpClient::Devin));
    }

    #[test]
    fn devin_apply_writes_mcp_servers() {
        let args = args_with_token(McpClient::Devin);
        let tmp = tempfile::TempDir::new().unwrap();
        let config_path = tmp.path().join("config.json");

        let entry = build_json_mcp_entry(&args).unwrap();
        let root = serde_json::json!({
            "mcpServers": {
                "ai-memory": entry
            }
        });

        fs::write(&config_path, serde_json::to_string_pretty(&root).unwrap()).unwrap();

        let parsed: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        assert!(
            parsed["mcpServers"]["ai-memory"].is_object(),
            "Devin config must have mcpServers.ai-memory"
        );
        assert_eq!(
            parsed["mcpServers"]["ai-memory"]["url"],
            "http://127.0.0.1:49374/mcp"
        );
        assert_eq!(parsed["mcpServers"]["ai-memory"]["transport"], "http");
    }

    #[test]
    fn devin_apply_preserves_sibling_mcp_servers() {
        let args = args_with_token(McpClient::Devin);
        let tmp = tempfile::TempDir::new().unwrap();
        let config_path = tmp.path().join("config.json");

        // Pre-existing config with sibling MCP server
        fs::write(
            &config_path,
            r#"{"mcpServers":{"other-server":{"url":"http://example.com","transport":"http"}}}"#,
        )
        .unwrap();

        let mut args_with_path = args.clone();
        args_with_path.config_file = Some(config_path.clone());

        apply_to_config_file(&args_with_path).unwrap();

        let parsed: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&config_path).unwrap()).unwrap();
        // Sibling must be preserved
        assert!(
            parsed["mcpServers"]["other-server"].is_object(),
            "other-server must be preserved"
        );
        // ai-memory must be added
        assert!(
            parsed["mcpServers"]["ai-memory"].is_object(),
            "ai-memory must be added"
        );
    }

    #[test]
    fn devin_apply_mcp_is_idempotent() {
        let args = args_with_token(McpClient::Devin);
        let tmp = tempfile::TempDir::new().unwrap();
        let config_path = tmp.path().join("config.json");

        let mut args_with_path = args.clone();
        args_with_path.config_file = Some(config_path.clone());

        apply_to_config_file(&args_with_path).unwrap();

        let first_content = fs::read_to_string(&config_path).unwrap();

        apply_to_config_file(&args_with_path).unwrap();

        let second_content = fs::read_to_string(&config_path).unwrap();
        assert_eq!(
            first_content, second_content,
            "second apply must produce identical bytes"
        );
    }

    #[test]
    fn swival_entry_and_apply_match_upstream_json_schema() {
        let tmp = tempfile::TempDir::new().unwrap();
        let config_path = tmp.path().join(".swival").join("mcp.json");
        fs::create_dir_all(config_path.parent().unwrap()).unwrap();
        fs::write(
            &config_path,
            r#"{"mcpServers":{"other":{"command":"other-mcp"}}}"#,
        )
        .unwrap();

        let mut args = args_with_token(McpClient::Swival);
        args.config_file = Some(config_path.clone());
        apply_to_config_file(&args).unwrap();
        let first = fs::read_to_string(&config_path).unwrap();
        apply_to_config_file(&args).unwrap();
        let second = fs::read_to_string(&config_path).unwrap();

        assert_eq!(first, second, "Swival MCP apply must be idempotent");
        let value: serde_json::Value = serde_json::from_str(&second).unwrap();
        assert_eq!(value["mcpServers"]["ai-memory"]["type"], "http");
        assert_eq!(
            value["mcpServers"]["ai-memory"]["url"],
            "http://127.0.0.1:49374/mcp"
        );
        assert_eq!(
            value["mcpServers"]["ai-memory"]["headers"]["Authorization"],
            "Bearer test-token-deadbeef"
        );
        assert_eq!(
            value["mcpServers"]["other"]["command"], "other-mcp",
            "apply must preserve sibling servers"
        );
    }

    #[test]
    fn swival_project_root_matches_git_toml_and_fallback_rules() {
        let tmp = tempfile::TempDir::new().unwrap();
        let git_root = tmp.path().join("git-project");
        let git_nested = git_root.join("a").join("b");
        fs::create_dir_all(git_root.join(".git")).unwrap();
        fs::create_dir_all(&git_nested).unwrap();
        assert_eq!(
            swival_project_root(&git_nested),
            fs::canonicalize(&git_root).unwrap()
        );

        let toml_root = tmp.path().join("toml-project");
        let toml_nested = toml_root.join("src");
        fs::create_dir_all(&toml_nested).unwrap();
        fs::write(toml_root.join("swival.toml"), "").unwrap();
        assert_eq!(
            swival_project_root(&toml_nested),
            fs::canonicalize(&toml_root).unwrap()
        );

        let plain = tmp.path().join("plain");
        fs::create_dir_all(&plain).unwrap();
        assert_eq!(
            swival_project_root(&plain),
            fs::canonicalize(&plain).unwrap()
        );
    }

    #[test]
    fn codex_print_uses_apply_toml_builder_for_dotted_names_and_quotes() {
        let mut args = args_with_token(McpClient::Codex);
        args.name = "ai.memory".into();
        args.server_url = Some("https://memory.example/mcp?note=\"quoted\"".into());

        let printed = render_codex(&args).unwrap();
        let mut applied = toml_edit::DocumentMut::new();
        codex_upsert_mcp_server(&mut applied, &args).unwrap();

        // The print path and the --apply path must agree on the table name.
        let parsed: toml_edit::DocumentMut = printed
            .lines()
            .filter(|line| !line.starts_with('#'))
            .collect::<Vec<_>>()
            .join("\n")
            .parse()
            .unwrap_or_else(|error| {
                panic!("printed snippet is not valid TOML: {error}\n{printed}")
            });
        let servers = parsed.get("mcp_servers").unwrap().as_table().unwrap();
        assert_eq!(servers.len(), 1, "print output:\n{printed}");
        assert!(
            servers.get("ai.memory").is_some(),
            "print output:\n{printed}"
        );
        assert_eq!(
            servers
                .get("ai.memory")
                .and_then(|server| server.get("url"))
                .and_then(|url| url.as_str()),
            Some("https://memory.example/mcp?note=\"quoted\""),
            "print output:\n{printed}"
        );
        assert!(
            printed.contains(&format!("[mcp_servers.{:?}]", "ai.memory")),
            "print output:\n{printed}"
        );
        assert!(
            applied
                .to_string()
                .contains(&format!("[mcp_servers.{:?}]", "ai.memory")),
            "applied output:\n{applied}"
        );
    }

    #[test]
    fn codex_print_quotes_a_table_name_containing_a_space() {
        let mut args = args_for(McpClient::Codex);
        args.name = "my memory".into();

        let printed = render_codex(&args).unwrap();
        let parsed: toml_edit::DocumentMut = printed
            .lines()
            .filter(|line| !line.starts_with('#'))
            .collect::<Vec<_>>()
            .join("\n")
            .parse()
            .unwrap_or_else(|error| {
                panic!("printed snippet is not valid TOML: {error}\n{printed}")
            });
        let servers = parsed.get("mcp_servers").unwrap().as_table().unwrap();
        assert_eq!(servers.len(), 1, "print output:\n{printed}");
        assert!(
            servers.get("my memory").is_some(),
            "print output:\n{printed}"
        );
    }

    #[test]
    fn codex_print_is_byte_identical_for_an_ordinary_name() {
        let mut plain = args_for(McpClient::Codex);
        plain.server_url = Some("http://127.0.0.1:49374/mcp".into());
        assert_eq!(
            render_codex(&plain).unwrap(),
            "# Codex CLI — append to $CODEX_HOME/config.toml (default ~/.codex/config.toml)\n\
             #\n\
             [mcp_servers.ai-memory]\n\
             url = \"http://127.0.0.1:49374/mcp\"\n\
             # Skip per-call approval prompts on ai-memory's read tools;\n\
             # the destructive ones below still ask first.\n\
             default_tools_approval_mode = \"approve\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_delete_page]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_feedback]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_forget_sweep]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_handoff_accept]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_handoff_cancel]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_message_cancel]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_message_pop]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_patch_page]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_restore_page]\n\
             approval_mode = \"prompt\"\n"
        );

        let mut with_token = args_with_token(McpClient::Codex);
        with_token.server_url = Some("http://127.0.0.1:49374/mcp".into());
        assert_eq!(
            render_codex(&with_token).unwrap(),
            "# Codex CLI — append to $CODEX_HOME/config.toml (default ~/.codex/config.toml)\n\
             #\n\
             [mcp_servers.ai-memory]\n\
             url = \"http://127.0.0.1:49374/mcp\"\n\
             # Skip per-call approval prompts on ai-memory's read tools;\n\
             # the destructive ones below still ask first.\n\
             default_tools_approval_mode = \"approve\"\n\
             \n\
             [mcp_servers.ai-memory.http_headers]\n\
             Authorization = \"Bearer test-token-deadbeef\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_delete_page]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_feedback]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_forget_sweep]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_handoff_accept]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_handoff_cancel]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_message_cancel]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_message_pop]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_patch_page]\n\
             approval_mode = \"prompt\"\n\
             \n\
             [mcp_servers.ai-memory.tools.memory_restore_page]\n\
             approval_mode = \"prompt\"\n\
             # Alternative (avoids embedding the literal token):\n\
             # bearer_token_env_var = \"AI_MEMORY_AUTH_TOKEN\"\n\
             # — and export AI_MEMORY_AUTH_TOKEN in your shell init.\n"
        );

        let mut env_var = args_for(McpClient::Codex);
        env_var.server_url = Some("http://127.0.0.1:49374/mcp".into());
        env_var.token_env_var = true;
        assert_eq!(
            render_codex(&env_var).unwrap(),
            format!(
                "# Codex CLI — append to $CODEX_HOME/config.toml (default ~/.codex/config.toml)\n\
                 #\n\
                 [mcp_servers.ai-memory]\n\
                 url = \"http://127.0.0.1:49374/mcp\"\n\
                 # Skip per-call approval prompts on ai-memory's read tools;\n\
                 # the destructive ones below still ask first.\n\
                 default_tools_approval_mode = \"approve\"\n\
                 bearer_token_env_var = \"{PRIME_AGENT_TOKEN_ENV}\"\n\
                 \n\
                 [mcp_servers.ai-memory.tools.memory_delete_page]\n\
                 approval_mode = \"prompt\"\n\
                 \n\
                 [mcp_servers.ai-memory.tools.memory_feedback]\n\
                 approval_mode = \"prompt\"\n\
                 \n\
                 [mcp_servers.ai-memory.tools.memory_forget_sweep]\n\
                 approval_mode = \"prompt\"\n\
                 \n\
                 [mcp_servers.ai-memory.tools.memory_handoff_accept]\n\
                 approval_mode = \"prompt\"\n\
                 \n\
                 [mcp_servers.ai-memory.tools.memory_handoff_cancel]\n\
                 approval_mode = \"prompt\"\n\
                 \n\
                 [mcp_servers.ai-memory.tools.memory_message_cancel]\n\
                 approval_mode = \"prompt\"\n\
                 \n\
                 [mcp_servers.ai-memory.tools.memory_message_pop]\n\
                 approval_mode = \"prompt\"\n\
                 \n\
                 [mcp_servers.ai-memory.tools.memory_patch_page]\n\
                 approval_mode = \"prompt\"\n\
                 \n\
                 [mcp_servers.ai-memory.tools.memory_restore_page]\n\
                 approval_mode = \"prompt\"\n\
                 # The token is read from ${PRIME_AGENT_TOKEN_ENV}; export it where you launch codex.\n"
            )
        );
    }

    #[test]
    fn grok_print_uses_apply_toml_builder_for_dotted_names_and_quotes() {
        let mut args = args_with_token(McpClient::Grok);
        args.name = "ai.memory".into();
        args.server_url = Some("https://memory.example/mcp?note=\"quoted\"".into());

        let printed = render_grok(&args).unwrap();
        let mut applied = toml_edit::DocumentMut::new();
        grok_upsert_mcp_server(&mut applied, &args).unwrap();
        let expected = applied.to_string();

        assert!(printed.ends_with(&expected), "print output:\n{printed}");
        let parsed: toml_edit::DocumentMut = expected.parse().unwrap();
        assert!(
            parsed
                .get("mcp_servers")
                .unwrap()
                .get("ai.memory")
                .is_some()
        );
    }
}