//! Every launcher CLI command as an MCP tool, generated from the CLI's own definition (clap) so the //! two can't drift: the tool `mods_search` is `horizon-launcher mods search`, its arguments are the //! command's (snake_case), and a call runs that command with `--json` as a child process and //! returns what it printed. A few commands keep a process or a sign-in going for the session; //! mcp.rs runs those itself under the same names (`play`, `server`, `account_sign_in`...). use clap::{ArgAction, Command}; use serde_json::{json, Map, Value}; /// CLI commands that are not generated tools: the MCP server itself; No AI, the player's switch /// and never an agent's; and the ones mcp.rs runs in the session. const NOT_TOOLS: &[&str] = &[ "mcp", "agent-config", "no-ai", "play", "server", "account sign-in", "account list", ]; /// Commands that delete the player's things: their tools need `confirm: true`. pub const DESTRUCTIVE: &[&str] = &[ "remove", "modpack remove", "mods remove", "servers forget", "account sign-out", "data delete", ]; /// Commands that send something or reach other people: only when the player asks. pub const OPEN_WORLD: &[&str] = &[ "data allow", "data send", "data bug", "data benchmark", "servers create", ]; /// A generated tool: its name, the CLI words it runs and the clap command behind them. pub struct Tool { pub name: String, pub path: Vec, command: Command, } /// The tool name of CLI words: `mods search` gives `mods_search`. pub fn tool_name(path: &[String]) -> String { path.join("_").replace('-', "_") } /// Every generated tool, in the CLI's order. pub fn all() -> Vec { let mut out = Vec::new(); walk(&crate::cli::command(), &mut Vec::new(), &mut out); out } fn walk(cmd: &Command, path: &mut Vec, out: &mut Vec) { for sub in cmd.get_subcommands() { path.push(sub.get_name().to_owned()); if sub.has_subcommands() { walk(sub, path, out); } else if !NOT_TOOLS.contains(&path.join(" ").as_str()) { out.push(Tool { name: tool_name(path), path: path.clone(), command: sub.clone(), }); } path.pop(); } } impl Tool { fn words(&self) -> String { self.path.join(" ") } pub fn destructive(&self) -> bool { DESTRUCTIVE.contains(&self.words().as_str()) } /// The tools/list entry. pub fn describe(&self) -> Value { let mut props = Map::new(); let mut required = Vec::new(); for arg in self.command.get_arguments().filter(|a| shown(a)) { let id = arg.get_id().as_str(); let mut help = arg.get_help().map(ToString::to_string).unwrap_or_default(); let defaults: Vec = arg .get_default_values() .iter() .map(|d| d.to_string_lossy().into_owned()) .collect(); if !defaults.is_empty() { help = format!("{help} (default {})", defaults.join(", ")) .trim_start() .to_owned(); } let choices: Vec = arg .get_possible_values() .iter() .map(|v| v.get_name().to_owned()) .collect(); let one = if !choices.is_empty() { json!({ "type": "string", "enum": choices }) } else if defaults.first().is_some_and(|d| d.parse::().is_ok()) { json!({ "type": "integer" }) } else { json!({ "type": "string" }) }; let mut schema = if matches!(arg.get_action(), ArgAction::SetTrue) { json!({ "type": "boolean" }) } else if many(arg) { json!({ "type": "array", "items": one }) } else { one }; if !help.is_empty() { schema["description"] = help.into(); } props.insert(id.to_owned(), schema); if arg.is_required_set() { required.push(id.to_owned()); } } if self.destructive() { props.insert( "confirm".into(), json!({ "type": "boolean", "description": "true once the player agreed: it cannot be undone" }), ); required.push("confirm".into()); } let about = self .command .get_about() .map(ToString::to_string) .unwrap_or_default(); let mut tool = json!({ "name": self.name, "description": format!("{about}. CLI: horizon-launcher {}", self.words()), "inputSchema": { "type": "object", "properties": props, "required": required }, }); if self.destructive() { tool["annotations"] = json!({ "destructiveHint": true }); } else if OPEN_WORLD.contains(&self.words().as_str()) { tool["annotations"] = json!({ "openWorldHint": true }); } tool } /// The CLI words for a call's arguments. pub fn argv(&self, args: &Value) -> Result, String> { if self.destructive() && args.get("confirm").and_then(Value::as_bool) != Some(true) { return Err(format!( "{} cannot be undone: ask the player, then call it with confirm: true", self.name )); } let text = |v: &Value| match v { Value::String(s) => Ok(s.clone()), Value::Number(n) => Ok(n.to_string()), Value::Bool(b) => Ok(b.to_string()), other => Err(format!("{other} is not a value")), }; let mut words = self.path.clone(); let mut positional = Vec::new(); let mut last = Vec::new(); for arg in self.command.get_arguments().filter(|a| shown(a)) { let id = arg.get_id().as_str(); let Some(value) = args.get(id).filter(|v| !v.is_null()) else { if arg.is_required_set() { return Err(format!("{id} is required")); } continue; }; let values = match value { Value::Array(items) => items.iter().map(text).collect::, _>>()?, v => vec![text(v)?], }; if matches!(arg.get_action(), ArgAction::SetTrue) { if value.as_bool().ok_or(format!("{id} is true or false"))? { words.push(format!("--{}", arg.get_long().unwrap_or(id))); } } else if arg.is_positional() { let into = if arg.is_last_set() { &mut last } else { &mut positional }; into.push((arg.get_index().unwrap_or(0), values)); } else { let long = arg.get_long().unwrap_or(id); for v in values { // `=` keeps a value that starts with a dash (game arguments) a value. words.push(format!("--{long}={v}")); } } } positional.sort_by_key(|(index, _)| *index); words.extend(positional.into_iter().flat_map(|(_, v)| v)); if !last.is_empty() { words.push("--".into()); words.extend(last.into_iter().flat_map(|(_, v)| v)); } Ok(words) } /// Runs the command as `horizon-launcher --json ...` and returns what it printed. pub fn call(&self, args: &Value) -> Result { let words = self.argv(args)?; let exe = std::env::current_exe().map_err(|e| e.to_string())?; let out = horizon_launcher::process::command(exe) .arg("--json") .args(&words) .stdin(std::process::Stdio::null()) .output() .map_err(|e| format!("Could not run horizon-launcher: {e}"))?; let stdout = String::from_utf8_lossy(&out.stdout).trim().to_owned(); let stderr = String::from_utf8_lossy(&out.stderr).trim().to_owned(); let text = match (stdout.is_empty(), stderr.is_empty()) { (false, true) => stdout, (true, false) => stderr, (true, true) => "Done.".into(), (false, false) => format!("{stdout}\n{stderr}"), }; if out.status.success() { Ok(text) } else { Err(text) } } } /// The tools mcp.rs runs itself for a CLI command, and what an agent uses instead of the /// player-only ones. #[cfg(test)] fn session_tool(words: &str) -> &'static str { match words { "play" => "`play`, then the `game_*` tools", "server" => "`server`, `server_command`, `server_log`, `server_stop`", "account sign-in" => "`account_sign_in`", "account list" => "`account_list`", "mcp" => "none: this command is the MCP server", "agent-config" => "none: it prints how to connect a client to `mcp`", _ => "none: the player's switch", } } /// docs/launcher-commands.md: every CLI command, its arguments and its MCP tool, from the CLI's /// definition. A test keeps the file equal to this. #[cfg(test)] fn markdown() -> String { let mut out = String::from( "# Launcher commands\n\n\n\n\ Every command of `horizon-launcher`, and the tool `horizon-launcher mcp` offers for it. A tool's \ arguments are the command's, in snake_case. A tool runs the command with `--json` and returns what it printed. \ The tools that change the player's things for good need `confirm: true`. \ The tools that send something or reach other people say \"only when the player asks\". \ The game's own tools, `game_*`, are in [horizon-ctl-commands.md](horizon-ctl-commands.md). \ With No AI on, `mcp` and `agent-config` are hidden and refuse; every other command stays. See [agent-control.md](agent-control.md#no-ai).\n\n", ); let mut rows = Vec::new(); collect(&crate::cli::command(), &mut Vec::new(), &mut rows); let generated: Vec = all().iter().map(|t| t.words()).collect(); for (words, cmd) in rows { let usage = cmd .clone() .bin_name(format!("horizon-launcher {words}")) .render_usage() .to_string(); let usage = usage .trim_start_matches("Usage: ") .replace(" [OPTIONS]", ""); out += &format!("## `horizon-launcher {words}`\n\n"); if let Some(about) = cmd.get_about() { out += &format!("{about}.\n\n"); } out += &format!(" {usage}\n\n"); let args: Vec<&clap::Arg> = cmd.get_arguments().filter(|a| shown(a)).collect(); for arg in &args { let name = match arg.get_long() { Some(long) => format!("--{long}"), None => arg.get_id().as_str().to_uppercase(), }; let help = arg.get_help().map(ToString::to_string).unwrap_or_default(); let choices: Vec = arg .get_possible_values() .iter() .map(|v| v.get_name().to_owned()) .collect(); let choices = if choices.is_empty() || matches!(arg.get_action(), ArgAction::SetTrue) { String::new() } else { format!(" ({})", choices.join(", ")) }; let help = if help.is_empty() { String::new() } else { format!(": {help}") }; out += &format!("- `{name}`{choices}{help}\n"); } if !args.is_empty() { out += "\n"; } let mcp = if generated.contains(&words) { let path: Vec = words.split(' ').map(str::to_owned).collect(); let mut text = format!("`{}`", tool_name(&path)); if DESTRUCTIVE.contains(&words.as_str()) { text += ", needs `confirm: true`"; } else if OPEN_WORLD.contains(&words.as_str()) { text += ", only when the player asks"; } text } else { session_tool(&words).to_owned() }; out += &format!("MCP: {mcp}.\n\n"); } out.truncate(out.trim_end().len()); out.push('\n'); out } /// Every command a player can type, groups included when they run on their own. #[cfg(test)] fn collect(cmd: &Command, path: &mut Vec, out: &mut Vec<(String, Command)>) { for sub in cmd.get_subcommands().filter(|c| c.get_name() != "help") { path.push(sub.get_name().to_owned()); if sub.has_subcommands() { collect(sub, path, out); } else { out.push((path.join(" "), sub.clone())); } path.pop(); } } /// Whether an argument is part of a tool (not --help, --version or the global --json). fn shown(arg: &clap::Arg) -> bool { !arg.is_hide_set() && !matches!(arg.get_id().as_str(), "help" | "version" | "json") } /// Whether an argument takes several values (a list). fn many(arg: &clap::Arg) -> bool { matches!(arg.get_action(), ArgAction::Append) || arg.get_num_args().is_some_and(|n| n.max_values() > 1) } #[cfg(test)] mod tests { use super::*; fn tool(name: &str) -> Tool { all().into_iter().find(|t| t.name == name).unwrap() } #[test] fn every_cli_command_is_a_tool_named_after_its_words() { let names: Vec = all().into_iter().map(|t| t.name).collect(); for want in [ "versions", "install", "remove", "prepare", "notes", "update", "game_args", "settings", "logs", "mods_search", "mods_install", "modpack_import", "servers_create", "servers_run", "data_status", "data_bug", "account_select", "benchmark", ] { assert!(names.iter().any(|n| n == want), "{want} missing: {names:?}"); } for not in ["mcp", "no_ai", "play", "server", "account_sign_in"] { assert!(!names.iter().any(|n| n == not), "{not}"); } } #[test] fn arguments_become_cli_words() { let search = tool("mods_search"); let schema = search.describe(); assert_eq!(schema["inputSchema"]["properties"]["text"]["type"], "array"); let kinds = &schema["inputSchema"]["properties"]["kind"]["enum"]; assert!( kinds.as_array().unwrap().contains(&json!("modpack")) && !kinds.as_array().unwrap().contains(&json!("shader")), "{kinds}" ); assert_eq!( search .argv(&json!({ "text": ["fresh", "animations"], "kind": "resource", "everything": true })) .unwrap(), ["mods", "search", "--kind=resource", "--everything", "fresh", "animations"] ); let run = tool("servers_run"); assert_eq!( run.argv(&json!({ "server": "My server", "args": ["status"] })) .unwrap(), ["servers", "run", "My server", "--", "status"] ); assert!(run .argv(&json!({ "server": "x" })) .unwrap_err() .contains("args is required")); let logs = tool("logs").describe(); assert_eq!( logs["inputSchema"]["properties"]["lines"]["type"], "integer" ); } /// Whether the reference on disk says `want`, whatever line endings the checkout gave it: Git /// for Windows checks text out with CRLF (core.autocrlf) where .gitattributes does not pin LF. fn up_to_date(have: &str, want: &str) -> bool { have.replace("\r\n", "\n") == want } #[test] fn a_windows_checkout_of_the_reference_is_up_to_date() { let want = markdown(); assert!(up_to_date(&want, &want)); assert!(up_to_date(&want.replace('\n', "\r\n"), &want)); assert!(!up_to_date(&want.replacen("## ", "### ", 1), &want)); } #[test] fn the_launcher_reference_is_up_to_date() { let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../docs/launcher-commands.md"); let want = markdown(); if std::env::var_os("HORIZON_WRITE_DOCS").is_some() { std::fs::write(&path, &want).unwrap(); } let have = std::fs::read_to_string(&path).unwrap_or_default(); assert!( up_to_date(&have, &want), "docs/launcher-commands.md is out of date: HORIZON_WRITE_DOCS=1 cargo test --manifest-path launcher/Cargo.toml the_launcher_reference" ); for tool in all() { assert!( have.contains(&format!("`{}`", tool.name)), "{} undocumented", tool.name ); } } #[test] fn destructive_tools_need_confirm() { let remove = tool("remove"); assert_eq!(remove.describe()["annotations"]["destructiveHint"], true); assert!(remove .argv(&json!({ "tag": "v1" })) .unwrap_err() .contains("confirm")); assert_eq!( remove .argv(&json!({ "tag": "v1", "confirm": true })) .unwrap(), ["remove", "v1"] ); for words in DESTRUCTIVE.iter().chain(OPEN_WORLD) { assert!( all().iter().any(|t| t.words() == *words), "{words} is not a tool" ); } } }