//! `lutra mcp [--port PORT] [--no-start]`: the MCP server on stdio. //! //! The server itself is `lutra_mcp::Server`; this module connects it to //! Lutra. By default it reaches the running instance through the //! single-instance rendezvous file (token-authenticated) and starts Lutra //! when none runs, exactly as `lutra PATH` does. `--port PORT` uses an //! open `--control PORT` channel instead (development and live checks), //! and `--no-start` never starts Lutra. use std::io; use std::path::PathBuf; use std::time::Duration; use lutra_control::client::{self, Client, ClientError}; use lutra_control::rendezvous; use lutra_mcp::{CallError, Connection, Connector, Server}; use serde_json::Value; use crate::launch; use crate::open::Failure; /// Usage text of `lutra mcp`. pub const USAGE: &str = "usage: lutra mcp [--port PORT] [--no-start] Serves the Model Context Protocol on stdin/stdout for agents, e.g. claude mcp add lutra -- lutra mcp --port PORT use the --control PORT channel instead of the running instance's rendezvous file --no-start do not start Lutra when it is not running Tools: list_commands, execute_command, screenshot, read_buffer, get_events. Resources: the open buffers (lutra://buffer/PATH)."; /// Options of `lutra mcp`. #[derive(Debug, Clone, PartialEq, Eq, Default)] pub struct Options { /// The `--control` port to use instead of the rendezvous file. pub port: Option, /// Whether Lutra may be started. pub start: bool, /// `--help` was given. pub help: bool, } /// Parses the arguments after `mcp`. /// /// # Errors /// A message for an unknown argument or a bad port. pub fn parse(args: &[String]) -> Result { let mut options = Options { start: true, ..Options::default() }; let mut args = args.iter(); while let Some(arg) = args.next() { match arg.as_str() { "--port" => { let port = args.next().ok_or("--port needs a port number")?; options.port = Some( port.parse::() .ok() .filter(|p| *p != 0) .ok_or_else(|| format!("{port} is not a port number"))?, ); } "--no-start" => options.start = false, "--help" | "-h" => options.help = true, other => return Err(format!("unknown argument {other} for lutra mcp")), } } Ok(options) } /// Runs the server on stdin and stdout until stdin closes. /// /// # Errors /// [`Failure::Error`] for a missing data directory or an I/O error on /// stdin or stdout. pub fn run(options: &Options) -> Result<(), Failure> { let target = match options.port { Some(port) => Target::Port(port), None => Target::Rendezvous( rendezvous::dir() .ok_or_else(|| Failure::Error("cannot find the Lutra data directory".into()))?, ), }; let connector = ControlConnector { target, start: options.start, }; let mut server = Server::new(std::sync::Arc::new(connector)); let stdin = io::stdin().lock(); let stdout = io::stdout().lock(); server .serve(stdin, stdout) .map_err(|e| Failure::Error(format!("mcp: {e}"))) } /// Where Lutra listens. #[derive(Debug, Clone)] enum Target { /// The instance named by the rendezvous file in this directory. Rendezvous(PathBuf), /// An open `--control` port. Port(u16), } /// Connects to Lutra through the control channel. #[derive(Debug)] struct ControlConnector { /// Where to connect. target: Target, /// Whether a missing Lutra may be started. start: bool, } impl Connector for ControlConnector { fn connect(&self, start: bool) -> Result, String> { let client = match &self.target { Target::Port(port) => Client::connect(*port, client::DEFAULT_TIMEOUT) .map_err(|e| format!("Lutra does not answer on control port {port}: {e}"))?, Target::Rendezvous(dir) => match client::connect_live(dir, client::DEFAULT_TIMEOUT) { Ok((_, client)) => client, Err(why) if start && self.start => { let desktop = launch::find_desktop() .map_err(|e| format!("{why}, and it cannot be started: {e}"))?; launch::start(&desktop, dir)? } Err(why) => return Err(why.to_string()), }, }; Ok(Box::new(ControlConnection { client })) } } /// A control channel client as an MCP connection. #[derive(Debug)] struct ControlConnection { /// The client. client: Client, } /// Maps a client error: an error answer stays remote, anything else means /// the connection is gone. fn call_error(error: ClientError) -> CallError { match error { ClientError::Remote { code, message } => CallError::Remote { code, message }, other => CallError::Lost(other.to_string()), } } impl Connection for ControlConnection { fn request(&mut self, method: &str, params: Value) -> Result { self.client.request(method, params).map_err(call_error) } fn next_event(&mut self, timeout: Duration) -> Result, CallError> { self.client.next_event(Some(timeout)).map_err(call_error) } } #[cfg(test)] mod tests { use super::*; fn p(args: &[&str]) -> Result { parse(&args.iter().map(|s| (*s).to_string()).collect::>()) } #[test] fn parses_options() { assert_eq!( p(&[]).unwrap(), Options { port: None, start: true, help: false } ); let o = p(&["--port", "7938", "--no-start"]).unwrap(); assert_eq!(o.port, Some(7938)); assert!(!o.start); assert!(p(&["-h"]).unwrap().help); assert!(p(&["--port"]).is_err()); assert!(p(&["--port", "0"]).is_err()); assert!(p(&["--port", "70000"]).is_err()); assert!(p(&["file.php"]).is_err()); } }