xianyun_mcp/

config.rs

//! Builds the [`brontes::Config`] that governs which `xianyun` subcommands
//! become MCP tools, how they're annotated, and which ones require explicit
//! client confirmation before they run.
//!
//! # The allowlist, in full
//!
//! `brontes::Config::default()` (equivalently, passing `None` to
//! [`brontes::command`]) exposes *every* reachable command as a tool. This
//! module never does that: [`build`] always returns a `Config` whose
//! [`Selector::cmd`] matchers are an explicit allowlist, built from
//! [`selectors::allow_cmds`] over exact, fully-qualified command paths. A
//! command that isn't named in one of the three groups below is invisible
//! to MCP clients, full stop — see `tests::guardrail` in the crate's
//! integration tests for the check that keeps a newly added `xianyun`
//! subcommand from silently falling through the cracks.
//!
//! Three allowlist tiers, each with its own annotation shape:
//!
//! - [`READ_ONLY`]: pure queries. `readOnlyHint: true`.
//! - [`STATE_CHANGING`]: expected, reversible side effects (a local cluster
//!   comes up, a Helm chart gets upgraded, a CA key gets lazily generated).
//!   `destructiveHint: false`, but *not* `readOnlyHint`.
//! - [`GATED`]: commands that tear something down, rewrite a file outside
//!   the project (`/etc/hosts`), or touch the host's trust store (often
//!   under `sudo`). `destructiveHint: true`, and wrapped in the
//!   confirmation-gating [`Middleware`] from
//!   [`middleware`].
//!
//! Everything else in `xianyun`'s command tree — `run`, `tool`, `kubectl`,
//! `k9s`, `stern`, `edit-mode-process-supervisor` — is deliberately excluded.
//! See [`EXCLUDED`] for the reasons, one per command.

use std::collections::BTreeMap;
use std::sync::Arc;

use brontes::{
    Config, ElicitRequest, ElicitRequestParams, ElicitResult, ElicitationAction, ElicitationSchema,
    InputRequest, InputRequests, InputRequiredResult, Middleware, MiddlewareOutcome, Selector,
    ToolAnnotations, ToolOutput, selectors,
};

/// Commands that only read state: exact `xianyun`-rooted paths, matching the
/// `path` strings [`brontes`'s walker](brontes) produces (space-joined,
/// starting at the CLI's own name).
pub const READ_ONLY: &[&str] = &[
    "xianyun version",
    "xianyun status",
    "xianyun logs",
    "xianyun doctor",
    "xianyun config validate",
    "xianyun config print",
    "xianyun registry status",
];

/// Commands with real side effects that are expected, local-only, and
/// reversible by running the CLI again (bringing a cluster up, redeploying,
/// pulling repository updates, merging a kubeconfig entry, migrating a
/// config file to the latest schema, or lazily generating/reading the dev CA
/// — `ca inspect` can write a CA keypair to disk on first run via
/// `xianyun_pki::ca::load_or_generate`, which disqualifies it from
/// [`READ_ONLY`] despite its name).
pub const STATE_CHANGING: &[&str] = &[
    "xianyun up",
    "xianyun deploy",
    "xianyun update",
    "xianyun set-kube-context",
    "xianyun config migrate",
    "xianyun registry start",
    "xianyun registry stop",
    "xianyun ca inspect",
];

/// Commands that tear down a cluster and its data, rewrite `/etc/hosts`, or
/// install/remove a certificate in the host's trust store (the latter two
/// typically require `sudo`). Allowlisted, but every call through
/// `middleware::confirmation_gate` first.
pub const GATED: &[&str] = &[
    "xianyun down",
    "xianyun destroy",
    "xianyun update-etc-hosts",
    "xianyun ca trust",
    "xianyun ca untrust",
];

/// Commands intentionally excluded from the MCP tool surface, with the
/// reason each one is excluded. Checked against the real command tree by
/// the crate's guardrail test, so an unclassified new subcommand fails that
/// test instead of silently inheriting `brontes`'s open-by-default exposure.
///
/// Paths are given without the `xianyun ` root prefix, matching how
/// [`brontes::Config`] accepts bare command names — these are informational
/// only, deliberately *not* fed into any selector.
pub const EXCLUDED: &[(&str, &str)] = &[
    (
        "run",
        "long-running, interactive reloader supervisor; holds the process until interrupted, which has no sane mapping onto a single request/response tools/call.",
    ),
    (
        "tool",
        "runs an arbitrary executable named by its first positional argument with access to the cluster -- exactly the glab #8153 shape (an unreviewed command becoming an arbitrary-command-execution primitive). Never allowlist this.",
    ),
    (
        "kubectl",
        "forwards all trailing arguments verbatim to a real kubectl binary; the flags are not clap-typed (trailing_var_arg), so brontes can't derive a meaningful schema, and an LLM-driven kubectl invocation is its own unreviewed command-execution surface on top of that.",
    ),
    (
        "k9s",
        "interactive, full-screen terminal UI that needs a live TTY and runs indefinitely; not a request/response fit, and brontes's subprocess exec has no terminal to hand it.",
    ),
    (
        "stern",
        "streams logs indefinitely until interrupted; a tools/call that never returns blocks the MCP connection for no benefit over just running `xianyun logs` (which IS allowlisted, see READ_ONLY).",
    ),
    (
        "edit-mode-process-supervisor",
        "hidden internal plumbing `xianyun run` spawns one of per reloader; not a user-facing command (clap's `hide = true` means brontes's own `is_hide_set` filter already drops it from the walked tree, but it's listed here too so the guardrail test's reasoning is complete without needing to know that detail).",
    ),
];

/// Key under which the gated middleware's elicitation answer is looked up in
/// `ctx.input_responses`.
const CONFIRM: &str = "confirm";

/// Per-command-path confirmation message shown to the MCP client before a
/// [`GATED`] command actually runs.
fn consequence_for(path: &str) -> &'static str {
    match path {
        "xianyun down" => {
            "This stops the local cluster. Deployed state is preserved and `xianyun up` will bring it back."
        }
        "xianyun destroy" => {
            "This destroys the local cluster AND DELETES ALL ITS DATA. This cannot be undone."
        }
        "xianyun update-etc-hosts" => {
            "This rewrites /etc/hosts to add or remove cluster hostnames, typically requiring elevated privileges."
        }
        "xianyun ca trust" => {
            "This installs the Caproni dev CA certificate into the system trust store, typically under sudo."
        }
        "xianyun ca untrust" => {
            "This removes the Caproni dev CA certificate from the system trust store, typically under sudo."
        }
        _ => "This performs a destructive or privileged action.",
    }
}

/// Builds the confirmation-gating [`Middleware`] applied to every selector
/// over [`GATED`] commands.
///
/// Mirrors the shipped MRTR example from `brontes`'s own docs: the first
/// call (no `ctx.input_responses`) returns
/// [`MiddlewareOutcome::InputRequired`] carrying an elicitation request; a
/// retry that carries an accepted answer under `CONFIRM` proceeds to
/// `next(ctx)`; a retry carrying a decline returns
/// [`MiddlewareOutcome::Complete`] with a non-zero exit and no side effects.
pub fn middleware() -> Middleware {
    Arc::new(|ctx, next| {
        Box::pin(async move {
            let Some(answers) = ctx.input_responses.as_ref() else {
                let mut requests = InputRequests::new();
                requests.insert(
                    CONFIRM.to_owned(),
                    InputRequest::Elicitation(ElicitRequest::new(
                        ElicitRequestParams::FormElicitationParams {
                            meta: None,
                            message: format!(
                                "Really run `{}`? {}",
                                ctx.tool_name,
                                consequence_for(&path_for_tool_name(&ctx.tool_name))
                            ),
                            requested_schema: ElicitationSchema::new(BTreeMap::new()),
                        },
                    )),
                );
                return Ok(InputRequiredResult::new(Some(requests), None).into());
            };

            let accepted = answers
                .get(CONFIRM)
                .cloned()
                .and_then(|v| serde_json::from_value::<ElicitResult>(v).ok())
                .is_some_and(|r| r.action == ElicitationAction::Accept);

            if accepted {
                next(ctx).await
            } else {
                Ok(MiddlewareOutcome::Complete(ToolOutput {
                    stdout: String::new(),
                    stderr: "aborted at the user's request\n".to_owned(),
                    exit_code: 1,
                }))
            }
        })
    })
}

/// Reconstructs a `"xianyun ..."` command path from a `brontes` tool name
/// (`xianyun_ca_trust` -> `"xianyun ca trust"`), purely for picking a
/// consequence message. Falls back to replacing every underscore with a
/// space if the name doesn't start with the expected root token, which
/// still produces a reasonable (if slightly wrong on hyphenated segments)
/// message rather than panicking.
fn path_for_tool_name(tool_name: &str) -> String {
    tool_name.replace('_', " ")
}

/// Annotation applied to every [`READ_ONLY`] command.
fn read_only_annotation() -> ToolAnnotations {
    ToolAnnotations {
        title: None,
        read_only_hint: Some(true),
        destructive_hint: Some(false),
        idempotent_hint: Some(true),
        open_world_hint: Some(false),
    }
}

/// Annotation applied to every [`STATE_CHANGING`] command.
fn state_changing_annotation() -> ToolAnnotations {
    ToolAnnotations {
        title: None,
        read_only_hint: Some(false),
        destructive_hint: Some(false),
        idempotent_hint: Some(true),
        open_world_hint: Some(false),
    }
}

/// Annotation applied to every [`GATED`] command.
fn gated_annotation() -> ToolAnnotations {
    ToolAnnotations {
        title: None,
        read_only_hint: Some(false),
        destructive_hint: Some(true),
        idempotent_hint: Some(true),
        open_world_hint: Some(false),
    }
}

/// Builds the full [`brontes::Config`] for the `xianyun` command tree:
/// the three-tier allowlist above, an annotation for every allowlisted
/// command, and the confirmation-gating middleware wired to [`GATED`] alone.
#[must_use]
pub fn build() -> Config {
    let mut cfg = Config::default()
        .selector(Selector {
            cmd: Some(selectors::allow_cmds(READ_ONLY.iter().copied())),
            ..Default::default()
        })
        .selector(Selector {
            cmd: Some(selectors::allow_cmds(STATE_CHANGING.iter().copied())),
            ..Default::default()
        })
        .selector(Selector {
            cmd: Some(selectors::allow_cmds(GATED.iter().copied())),
            middleware: Some(middleware()),
            ..Default::default()
        });

    for path in READ_ONLY {
        cfg = cfg.annotation(*path, read_only_annotation());
    }
    for path in STATE_CHANGING {
        cfg = cfg.annotation(*path, state_changing_annotation());
    }
    for path in GATED {
        cfg = cfg.annotation(*path, gated_annotation());
    }

    cfg
}

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

    #[test]
    fn allowlist_tiers_are_disjoint() {
        let mut seen = std::collections::HashSet::new();
        for path in READ_ONLY.iter().chain(STATE_CHANGING).chain(GATED) {
            assert!(seen.insert(*path), "{path} listed in more than one tier");
        }
    }

    #[test]
    fn excluded_reasons_are_non_empty() {
        for (name, reason) in EXCLUDED {
            assert!(!reason.is_empty(), "{name} has no exclusion reason");
        }
    }

    #[test]
    fn build_does_not_panic() {
        let _ = build();
    }

    #[test]
    fn path_for_tool_name_round_trips_simple_cases() {
        assert_eq!(path_for_tool_name("xianyun_status"), "xianyun status");
        assert_eq!(path_for_tool_name("xianyun_ca_trust"), "xianyun ca trust");
    }
}