agentmux_srv/backend/

mcp_seed.rs

// Copyright 2025-2026, AgentMux Corp.
// SPDX-License-Identifier: Apache-2.0

//! Starter MCP Servers catalog seed: preloads a small set of curated global,
//! credential-free MCP servers (`db_mcp_servers`, the v1 standalone catalog)
//! on fresh install.
//!
//! Mirrors `skill_seed.rs` exactly, for the same reasons documented there:
//! the actual "run exactly once, ever" gating lives in
//! `migrations::m0016_seed_starter_mcp_servers`, tracked in the channel's
//! `db_migrations` table — NOT in this module, and NOT gated on "is the
//! catalog currently empty" (that gate can't distinguish "never seeded" from
//! "seeded then the user deleted every starter server on purpose", which
//! would silently resurrect the defaults on the next restart after a full
//! deletion — see `m0015_seed_starter_skills.rs`'s history, reagent P2 on
//! PR #2141 round 2, for why this shape was chosen over a simpler one). This
//! module exposes only the pure insert logic; the migration owns invocation.
//!
//! Only credential-free, fully local servers belong in this manifest — see
//! docs/specs/SPEC_ARMORY_MCP_SERVER_DEFAULT_SEED_CATALOG_2026_07_13.md §2:
//! every `is_global` MCP server is auto-injected into every agent's
//! `.mcp.json` at launch with no per-agent opt-in, so a seeded row needing an
//! API key or OAuth token would break every agent's launch by default. The
//! Filesystem reference server is deliberately NOT included despite being
//! credential-free — it requires an allowlisted directory as a CLI arg with
//! no environment-agnostic default (spec §9 open question 3); it can be
//! added once that's resolved, either by computing a per-agent default at
//! config-build time or shipping it with an explicit prereq the user fills
//! in via the existing catalog-picker mechanism instead.
//!
//! **Ids are deterministic, not randomly minted** — same reasoning as
//! `skill_seed.rs::starter_skill_id`, mirrored here for MCP servers via
//! `entry.name` (there is no separate slug field for a server the way a
//! skill has `trigger`; `name` already plays that role — it's the catalog
//! key `mcp_server_upsert_unique_global` enforces uniqueness on). See Phase 1
//! of `SPEC_DURABLE_BINDINGS_2026_09_10.md`.

use std::sync::Arc;

use serde::Deserialize;
use uuid::Uuid;

use super::storage::mcp_servers::McpServer;
use super::storage::store::Store;
use super::storage::StoreError;

/// One entry in the embedded starter-mcp-servers manifest. `config` is a raw
/// JSON object here (command/args/env) and gets re-serialized to a string to
/// match `McpServer.config`'s storage shape.
#[derive(Debug, Deserialize)]
struct StarterMcpServer {
    name: String,
    transport: String,
    config: serde_json::Value,
}

/// The embedded starter-mcp-servers manifest JSON. Content is authored
/// externally and must not be edited here — see
/// `crates/srv/src/config/starter-mcp-servers.json`.
const STARTER_MCP_SERVERS_JSON: &str = include_str!("../config/starter-mcp-servers.json");

/// Deterministic row id for a starter MCP server, derived from its `name`.
/// See `skill_seed::starter_skill_id`'s doc comment for the full reasoning —
/// this is the identical derivation keyed on the server's catalog name
/// instead of a skill's trigger, in its own, distinct namespace so a skill
/// and an MCP server that happened to share a stable-key string could never
/// collide on id.
pub(crate) fn starter_mcp_server_id(name: &str) -> Uuid {
    let namespace = Uuid::new_v5(&Uuid::NAMESPACE_URL, b"https://agentmux.ai/catalog/mcp-servers/v1");
    Uuid::new_v5(&namespace, name.as_bytes())
}

/// True if `name` matches a starter MCP server's `name` in the embedded
/// manifest. Mirrors `skill_seed::starter_skill_trigger_for_name` — see its
/// doc comment for why the durable-bindings carry-across migration needs
/// this distinction (recognized starters converge on
/// [`starter_mcp_server_id`]; everything else keeps first-wins dedup).
#[cfg(test)]
pub(crate) fn is_starter_mcp_server_name(name: &str) -> bool {
    let Ok(manifest) = serde_json::from_str::<Vec<StarterMcpServer>>(STARTER_MCP_SERVERS_JSON) else {
        return false;
    };
    manifest.iter().any(|s| s.name == name)
}

/// Guard against a manifest-authoring mistake: two entries sharing a `name`.
/// Mirrors `skill_seed::reject_duplicate_triggers` exactly — see its doc
/// comment for the full failure mode this closes (reagent P2, PR #3175).
/// `name` here plays the role `trigger` plays for skills: it is both the
/// stable key `starter_mcp_server_id` derives from AND the field
/// `mcp_server_upsert_unique_global`'s own duplicate check is keyed on,
/// which is exactly the combination that turned "id collision" into
/// "duplicate-check bypass" for skills.
fn reject_duplicate_names(manifest: &[StarterMcpServer]) -> Result<(), StoreError> {
    let mut seen: std::collections::HashSet<&str> = std::collections::HashSet::new();
    for entry in manifest {
        if !seen.insert(entry.name.as_str()) {
            return Err(StoreError::Other(format!(
                "mcp server seed: manifest has more than one entry named '{}' — \
                 this is an authoring bug in starter-mcp-servers.json, not a \
                 runtime condition to recover from",
                entry.name
            )));
        }
    }
    Ok(())
}

/// True if any global MCP server whose name matches a starter entry's name
/// already exists — i.e. this channel already effectively has the starter
/// set (or a name collision with it). The caller
/// (`migrations::m0016_seed_starter_mcp_servers`) uses this to skip seeding
/// entirely rather than attempting an insert that would collide on
/// `mcp_server_upsert_unique_global`'s name-uniqueness check and permanently
/// fail the migration on every subsequent boot — same self-heal
/// `skill_seed.rs::any_starter_skill_name_exists` provides (reagent P1, PR
/// #2144).
pub(crate) fn any_starter_mcp_server_name_exists(mstore: &Arc<Store>) -> Result<bool, StoreError> {
    let manifest: Vec<StarterMcpServer> = serde_json::from_str(STARTER_MCP_SERVERS_JSON)
        .map_err(|e| StoreError::Other(format!("mcp server seed: parse manifest: {e}")))?;
    // Pre-dates Phase 2 of SPEC_DURABLE_BINDINGS_2026_09_10.md's catalog
    // redirect — see skill_seed.rs's identical note.
    let existing = mstore.mcp_server_list_global(mstore)?;
    Ok(manifest
        .iter()
        .any(|entry| existing.iter().any(|item| item.server.name == entry.name)))
}

/// Parse the embedded manifest and insert every entry as a global MCP server
/// via the validated `mcp_server_upsert_unique_global` path. Does NOT check
/// whether the catalog is already populated — the caller
/// (`migrations::m0016_seed_starter_mcp_servers`) owns run-once gating via
/// `db_migrations` tracking, not catalog contents. Exposed at `pub(crate)`
/// so the migration and tests can call it directly.
///
/// All-or-nothing: `mcp_server_upsert_unique_global` commits each insert in
/// its own transaction, so a mid-loop failure can't be rolled back by the
/// database itself. If any insert fails, this compensates by deleting every
/// server already inserted in THIS call before returning the error —
/// otherwise a retry (the migration framework re-runs `up()` on the next
/// boot when a migration returns `Err`, since it's never marked applied)
/// would hit the name-uniqueness rejection on the servers already stranded
/// from the failed attempt. Mirrors `skill_seed::seed_starter_skills`
/// exactly (reagent P2, PR #2141 round 1).
pub(crate) fn seed_starter_mcp_servers(mstore: &Arc<Store>) -> Result<usize, StoreError> {
    let manifest: Vec<StarterMcpServer> = serde_json::from_str(STARTER_MCP_SERVERS_JSON)
        .map_err(|e| StoreError::Other(format!("mcp server seed: parse manifest: {e}")))?;
    reject_duplicate_names(&manifest)?;

    let now = agentmux_common::time::now_ms();

    let mut inserted_ids: Vec<String> = Vec::with_capacity(manifest.len());
    for entry in &manifest {
        let config = serde_json::to_string(&entry.config)
            .map_err(|e| StoreError::Other(format!("mcp server seed: serialize config for '{}': {e}", entry.name)))?;
        let server = McpServer {
            id: starter_mcp_server_id(&entry.name).to_string(),
            name: entry.name.clone(),
            transport: entry.transport.clone(),
            config,
            is_global: true,
            created_at: now,
            updated_at: now,
        };
        if let Err(e) = mstore.mcp_server_upsert_unique_global(&server) {
            for id in &inserted_ids {
                if let Err(cleanup_err) = mstore.mcp_server_delete(mstore, id) {
                    tracing::error!(
                        "mcp server seed: cleanup after partial failure could not remove {id}: {cleanup_err}"
                    );
                }
            }
            return Err(e);
        }
        inserted_ids.push(server.id);
    }

    Ok(inserted_ids.len())
}

#[cfg(test)]
mod tests {
    use super::*;

    fn starter(name: &str) -> StarterMcpServer {
        StarterMcpServer {
            name: name.to_string(),
            transport: "stdio".to_string(),
            config: serde_json::json!({"command": "true"}),
        }
    }

    #[test]
    fn reject_duplicate_names_fails_loudly_on_a_colliding_manifest() {
        // reagent P2, PR #3175 — mirrors skill_seed's equivalent test. See
        // reject_duplicate_names's own doc comment for the mechanism.
        let manifest = vec![starter("dup"), starter("dup")];
        let err = reject_duplicate_names(&manifest).unwrap_err();
        assert!(format!("{err}").contains("dup"), "error must name the offending server: {err}");
    }

    #[test]
    fn reject_duplicate_names_accepts_the_real_manifest() {
        let manifest: Vec<StarterMcpServer> = serde_json::from_str(STARTER_MCP_SERVERS_JSON).unwrap();
        assert!(reject_duplicate_names(&manifest).is_ok());
    }

    #[test]
    fn starter_mcp_server_ids_are_identical_across_two_independently_seeded_stores() {
        // Mirrors skill_seed.rs's equivalent test — the property Phase 1 of
        // SPEC_DURABLE_BINDINGS_2026_09_10.md exists for.
        let store_a = Arc::new(Store::open_in_memory().unwrap());
        let store_b = Arc::new(Store::open_in_memory().unwrap());

        seed_starter_mcp_servers(&store_a).unwrap();
        seed_starter_mcp_servers(&store_b).unwrap();

        let mut ids_a: Vec<(String, String)> = store_a
            .mcp_server_list_global(&store_a)
            .unwrap()
            .into_iter()
            .map(|item| (item.server.name, item.server.id))
            .collect();
        let mut ids_b: Vec<(String, String)> = store_b
            .mcp_server_list_global(&store_b)
            .unwrap()
            .into_iter()
            .map(|item| (item.server.name, item.server.id))
            .collect();
        ids_a.sort();
        ids_b.sort();

        assert_eq!(ids_a.len(), 6);
        assert_eq!(ids_a, ids_b, "the same starter server must get the same id in every store");
    }

    #[test]
    fn a_skill_and_an_mcp_server_sharing_a_stable_key_do_not_collide() {
        // Different namespaces for the two catalogs — if a skill's trigger
        // and a server's name were ever the same literal string, they must
        // still land on different ids, since they're different resources in
        // different tables.
        assert_ne!(
            crate::backend::skill_seed::starter_skill_id("git"),
            starter_mcp_server_id("git"),
        );
    }

    #[test]
    fn seeds_six_mcp_servers_into_an_empty_catalog() {
        let mstore = Arc::new(Store::open_in_memory().unwrap());
        assert!(mstore.mcp_server_list_global(&mstore).unwrap().is_empty());

        let created = seed_starter_mcp_servers(&mstore).unwrap();

        assert_eq!(created, 6);
        let after = mstore.mcp_server_list_global(&mstore).unwrap();
        assert_eq!(after.len(), 6, "all six starter MCP servers should be seeded");
        assert!(after.iter().all(|item| item.server.is_global));
        assert!(
            after.iter().all(|item| item.server.transport == "stdio"),
            "every Tier A entry is a local stdio process"
        );
    }

    #[test]
    fn seeded_config_round_trips_as_valid_json() {
        let mstore = Arc::new(Store::open_in_memory().unwrap());
        seed_starter_mcp_servers(&mstore).unwrap();

        let after = mstore.mcp_server_list_global(&mstore).unwrap();
        let git = after
            .iter()
            .find(|item| item.server.name == "git")
            .expect("git should be seeded");
        let parsed: serde_json::Value = serde_json::from_str(&git.server.config).unwrap();
        assert_eq!(parsed["command"], "uvx");
        assert_eq!(parsed["args"][0], "mcp-server-git");
    }

    #[test]
    fn a_failed_insert_rolls_back_the_ones_already_seeded_this_call() {
        // Same failure mode as skill_seed.rs's equivalent test (reagent P2,
        // PR #2141 round 1): mcp_server_upsert_unique_global commits each
        // insert in its own transaction, so a mid-loop failure can't be
        // rolled back by the database. Simulate it by pre-inserting a global
        // server whose NAME collides with one of the starter entries — this
        // forces seed_starter_mcp_servers to fail partway through the
        // manifest, and the catalog must end up back at exactly the one
        // pre-existing server, not a stranded partial starter set.
        let mstore = Arc::new(Store::open_in_memory().unwrap());
        let now = agentmux_common::time::now_ms();

        // "fetch" is the second entry in the manifest — colliding on it
        // guarantees at least one successful insert ("git") precedes the
        // failure, so the rollback path actually has something to clean up.
        let colliding = McpServer {
            id: "pre-existing-collision".to_string(),
            name: "fetch".to_string(),
            transport: "stdio".to_string(),
            config: "{}".to_string(),
            is_global: true,
            created_at: now,
            updated_at: now,
        };
        mstore.mcp_server_upsert_unique_global(&colliding).unwrap();

        let result = seed_starter_mcp_servers(&mstore);
        assert!(result.is_err(), "seeding must fail when a name collides");

        let after = mstore.mcp_server_list_global(&mstore).unwrap();
        assert_eq!(
            after.len(),
            1,
            "a failed seed must roll back every server it inserted this call, leaving only the pre-existing one"
        );
        assert_eq!(after[0].server.id, "pre-existing-collision");
    }

    #[test]
    fn any_starter_mcp_server_name_exists_detects_a_collision_without_inserting() {
        let mstore = Arc::new(Store::open_in_memory().unwrap());
        assert!(!any_starter_mcp_server_name_exists(&mstore).unwrap());

        let now = agentmux_common::time::now_ms();
        let user_created = McpServer {
            id: "user-server".to_string(),
            name: "memory".to_string(),
            transport: "stdio".to_string(),
            config: "{}".to_string(),
            is_global: true,
            created_at: now,
            updated_at: now,
        };
        mstore.mcp_server_upsert_unique_global(&user_created).unwrap();

        assert!(any_starter_mcp_server_name_exists(&mstore).unwrap());
        assert_eq!(
            mstore.mcp_server_list_global(&mstore).unwrap().len(),
            1,
            "the check itself must not insert anything"
        );
    }
}