mcp.rs 75.2%

237 of 315 lines run, 79 of 123 functions · run #423 on main · run missed

//! `oxy mcp` (oxygen#159): a Model Context Protocol server over stdio for
//! the repository it starts in, so an agent works through typed tools
//! instead of parsing a shell's output.
//!
//! Each tool runs this same oxy binary with the command's `--json`, in the
//! repository, with the server's environment: so a tool returns exactly
//! what the command does, and signs as whatever `OXY_HOME` configures. In
//! an agent home every change is sealed via the agent, with no environment
//! variable to forget per call. Tools that can lose work (undo, a forced
//! push) are offered only with `--allow-destructive`.

use anyhow::{bail, Result};
use oxy_core::mcp::{self, arg_str, arg_strings, ServerInfo, Tool, ToolOutput, Tools};
use serde_json::{json, Value};
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};

/// A tool's text is cut here; its structured result is then left out.
const MAX_TEXT: usize = 256 * 1024;

type Build = fn(&Value, bool) -> Result<Vec<String>, String>;

struct Spec {
    name: &'static str,
    description: &'static str,
    schema: fn() -> Value,
    build: Build,
    json: bool,
    read_only: bool,
    destructive: bool,
}

fn obj(props: Value, required: &[&str]) -> Value {
    json!({ "type": "object", "properties": props, "required": required, "additionalProperties": false })
}

fn none() -> Value {
    obj(json!({}), &[])
}

/// An option's value as `--flag=value`, so a value starting with `-` is
/// never read as another flag.
fn opt(flag: &str, value: &str) -> String {
    format!("{flag}={value}")
}

/// Positional values after `--`, for the same reason.
fn positional(out: &mut Vec<String>, values: Vec<String>) {
    if !values.is_empty() {
        out.push("--".into());
        out.extend(values);
    }
}

fn required<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
    arg_str(args, key)
        .filter(|s| !s.trim().is_empty())
        .ok_or_else(|| format!("{key} is required"))
}

/// Paths to act on, or every path when `all` is true; never neither, so a
/// commit or amend is always a deliberate choice of what goes in.
fn paths_or_all(args: &Value) -> Result<Vec<String>, String> {
    let paths = arg_strings(args, "paths")?;
    let all = args.get("all").and_then(Value::as_bool).unwrap_or(false);
    match (paths.is_empty(), all) {
        (false, false) => Ok(paths),
        (true, true) => Ok(vec![]),
        (false, true) => Err("give paths or all: true, not both".into()),
        (true, false) => {
            Err("give the paths to include, or all: true for every changed path".into())
        }
    }
}

fn limit(args: &Value, default: u64) -> String {
    args.get("limit")
        .and_then(Value::as_u64)
        .unwrap_or(default)
        .clamp(1, 1000)
        .to_string()
}

fn specs() -> Vec<Spec> {
    vec![
        Spec {
            name: "status",
            description: "The working copy: the bookmark, changed paths, and every conflict with its kind and the changes behind it.",
            schema: none,
            build: |_, _| Ok(vec!["status".into(), "--json".into()]),
            json: true,
            read_only: true,
            destructive: false,
        },
        Spec {
            name: "diff",
            description: "Uncommitted edits in the working copy, or one change's edits when `change` is given (a ChangeId or #hash prefix).",
            schema: || obj(json!({ "change": { "type": "string" } }), &[]),
            build: |a, _| {
                let mut v = vec!["diff".into(), "--json".into()];
                positional(&mut v, arg_str(a, "change").map(|c| vec![c.to_string()]).unwrap_or_default());
                Ok(v)
            },
            json: true,
            read_only: true,
            destructive: false,
        },
        Spec {
            name: "log",
            description: "Changes, newest first: a revset (`main`, `@`, …) or the current bookmark, optionally only those touching `path`; `limit` defaults to 20.",
            schema: || obj(json!({ "revset": { "type": "string" }, "path": { "type": "string" }, "limit": { "type": "integer", "minimum": 1 } }), &[]),
            build: |a, _| {
                let mut v = vec!["log".into(), "--json".into(), opt("--limit", &limit(a, 20))];
                if let Some(r) = arg_str(a, "revset") {
                    v.push(opt("--revset", r));
                }
                if let Some(p) = arg_str(a, "path") {
                    v.push(opt("--path", p));
                }
                Ok(v)
            },
            json: true,
            read_only: true,
            destructive: false,
        },
        Spec {
            name: "show",
            description: "One change: its message, author, signatures and edits (`stat: true` for files and line counts only). `change` defaults to @, the working copy.",
            schema: || obj(json!({ "change": { "type": "string" }, "stat": { "type": "boolean" } }), &[]),
            build: |a, _| {
                let mut v = vec!["show".into(), "--json".into()];
                if a.get("stat").and_then(Value::as_bool).unwrap_or(false) {
                    v.push("--stat".into());
                }
                positional(&mut v, vec![arg_str(a, "change").unwrap_or("@").to_string()]);
                Ok(v)
            },
            json: true,
            read_only: true,
            destructive: false,
        },
        Spec {
            name: "cat",
            description: "A file's content as a bookmark, tag or change has it (`change`), or as committed on the working copy's base.",
            schema: || obj(json!({ "path": { "type": "string" }, "change": { "type": "string" } }), &["path"]),
            build: |a, _| {
                let mut v = vec!["cat".into()];
                if let Some(c) = arg_str(a, "change") {
                    v.push(opt("--change", c));
                }
                positional(&mut v, vec![required(a, "path")?.to_string()]);
                Ok(v)
            },
            json: false,
            read_only: true,
            destructive: false,
        },
        Spec {
            name: "blame",
            description: "Which change wrote each line of a file, with its line atoms.",
            schema: || obj(json!({ "path": { "type": "string" } }), &["path"]),
            build: |a, _| {
                let mut v = vec!["blame".into(), "--json".into()];
                positional(&mut v, vec![required(a, "path")?.to_string()]);
                Ok(v)
            },
            json: true,
            read_only: true,
            destructive: false,
        },
        Spec {
            name: "bookmarks",
            description: "Bookmarks with their heads and how far each is ahead of or behind its remote; `all: true` adds remotes' bookmarks.",
            schema: || obj(json!({ "all": { "type": "boolean" } }), &[]),
            build: |a, _| {
                let mut v = vec!["bookmark".into(), "list".into(), "--json".into()];
                if a.get("all").and_then(Value::as_bool).unwrap_or(false) {
                    v.push("--all".into());
                }
                Ok(v)
            },
            json: true,
            read_only: true,
            destructive: false,
        },
        Spec {
            name: "tags",
            description: "Tags with their states, messages and signers.",
            schema: none,
            build: |_, _| Ok(vec!["tag".into(), "list".into(), "--json".into()]),
            json: true,
            read_only: true,
            destructive: false,
        },
        Spec {
            name: "conflicts",
            description: "Which conflicts of the working copy's base the current files resolve, and which remain.",
            schema: none,
            build: |_, _| Ok(vec!["resolve".into(), "--json".into()]),
            json: true,
            read_only: true,
            destructive: false,
        },
        Spec {
            name: "op_log",
            description: "The operation log, newest first (what undo would take back); `limit` defaults to 20.",
            schema: || obj(json!({ "limit": { "type": "integer", "minimum": 1 } }), &[]),
            build: |a, _| Ok(vec!["op".into(), "log".into(), "--json".into(), opt("--limit", &limit(a, 20))]),
            json: true,
            read_only: true,
            destructive: false,
        },
        Spec {
            name: "identity",
            description: "Who changes are signed as here: the author, the key, delegates and the signer (an agent home signs keyless, via the agent).",
            schema: none,
            build: |_, _| Ok(vec!["identity".into(), "show".into()]),
            json: false,
            read_only: true,
            destructive: false,
        },
        Spec {
            name: "commit",
            description: "Record a change with a message: only `paths`, or every changed path with `all: true`. Signed as this server's identity.",
            schema: || obj(json!({ "message": { "type": "string" }, "paths": { "type": "array", "items": { "type": "string" } }, "all": { "type": "boolean" } }), &["message"]),
            build: |a, _| {
                let mut v = vec!["commit".into(), opt("--message", required(a, "message")?)];
                positional(&mut v, paths_or_all(a)?);
                Ok(v)
            },
            json: false,
            read_only: false,
            destructive: false,
        },
        Spec {
            name: "amend",
            description: "Fold edits into the change the working copy sits on: only `paths`, or all with `all: true`; `message` replaces its message too.",
            schema: || obj(json!({ "message": { "type": "string" }, "paths": { "type": "array", "items": { "type": "string" } }, "all": { "type": "boolean" } }), &[]),
            build: |a, _| {
                let mut v = vec!["amend".into()];
                if let Some(m) = arg_str(a, "message") {
                    v.push(opt("--message", m));
                }
                positional(&mut v, paths_or_all(a)?);
                Ok(v)
            },
            json: false,
            read_only: false,
            destructive: false,
        },
        Spec {
            name: "describe",
            description: "Change a head's message (`change` defaults to the one the working copy sits on).",
            schema: || obj(json!({ "message": { "type": "string" }, "change": { "type": "string" } }), &["message"]),
            build: |a, _| {
                let mut v = vec!["describe".into(), "--json".into(), opt("--message", required(a, "message")?)];
                positional(&mut v, arg_str(a, "change").map(|c| vec![c.to_string()]).unwrap_or_default());
                Ok(v)
            },
            json: true,
            read_only: false,
            destructive: false,
        },
        Spec {
            name: "fetch",
            description: "Fetch from a remote (default origin) without moving local bookmarks.",
            schema: || obj(json!({ "remote": { "type": "string" } }), &[]),
            build: |a, _| remote_cmd("fetch", a),
            json: true,
            read_only: false,
            destructive: false,
        },
        Spec {
            name: "pull",
            description: "Fetch from a remote (default origin) and bring the current bookmark and working copy up to date.",
            schema: || obj(json!({ "remote": { "type": "string" } }), &[]),
            build: |a, _| remote_cmd("pull", a),
            json: true,
            read_only: false,
            destructive: false,
        },
        Spec {
            name: "push",
            description: "Push the current bookmark (or `bookmark`) to a remote (default origin). Changes are sealed at push as this server's identity. `force` (drop heads the remote has) needs the server started with --allow-destructive.",
            schema: || obj(json!({ "remote": { "type": "string" }, "bookmark": { "type": "string" }, "force": { "type": "boolean" } }), &[]),
            build: |a, destructive| {
                let mut v = vec!["push".to_string(), "--json".into()];
                if let Some(b) = arg_str(a, "bookmark") {
                    v.push(opt("--bookmark", b));
                }
                if a.get("force").and_then(Value::as_bool).unwrap_or(false) {
                    if !destructive {
                        return Err("a forced push can drop the remote's heads; start oxy mcp with --allow-destructive to allow it".into());
                    }
                    v.push("--force".into());
                }
                positional(&mut v, arg_str(a, "remote").map(|r| vec![r.to_string()]).unwrap_or_default());
                Ok(v)
            },
            json: true,
            read_only: false,
            destructive: false,
        },
        Spec {
            name: "tlog_verify",
            description: "Check the hub's transparency log: that it shows everyone the same history, with this repository's entries and each witness's cosignature.",
            schema: none,
            build: |_, _| Ok(vec!["tlog".into(), "verify".into(), "--json".into()]),
            json: true,
            read_only: true,
            destructive: false,
        },
        Spec {
            name: "undo",
            description: "Take back the last operation (see op_log). Offered only when the server was started with --allow-destructive.",
            schema: none,
            build: |_, _| Ok(vec!["undo".into()]),
            json: false,
            read_only: false,
            destructive: true,
        },
    ]
}

fn remote_cmd(command: &str, a: &Value) -> Result<Vec<String>, String> {
    let mut v = vec![command.to_string(), "--json".into()];
    positional(
        &mut v,
        arg_str(a, "remote")
            .map(|r| vec![r.to_string()])
            .unwrap_or_default(),
    );
    Ok(v)
}

struct OxyTools {
    exe: PathBuf,
    dir: PathBuf,
    allow_destructive: bool,
}

impl OxyTools {
    fn offered(&self) -> impl Iterator<Item = Spec> + '_ {
        specs()
            .into_iter()
            .filter(|s| self.allow_destructive || !s.destructive)
    }

    fn run(&self, spec: &Spec, argv: Vec<String>) -> ToolOutput {
        let out = Command::new(&self.exe)
            .arg("--plain")
            .args(&argv)
            .current_dir(&self.dir)
            .stdin(Stdio::null())
            .output();
        let out = match out {
            Ok(o) => o,
            Err(e) => return ToolOutput::error(format!("could not run oxy: {e}")),
        };
        let stdout = String::from_utf8_lossy(&out.stdout).into_owned();
        let stderr = String::from_utf8_lossy(&out.stderr).into_owned();
        if !out.status.success() {
            let why = if stderr.trim().is_empty() {
                stdout
            } else {
                stderr
            };
            return ToolOutput::error(format!("oxy {} failed: {}", argv.join(" "), why.trim()));
        }
        let mut result = ToolOutput::ok(stdout.clone());
        if spec.json {
            result.structured = serde_json::from_str(&stdout).ok();
        } else if !stderr.trim().is_empty() && stdout.trim().is_empty() {
            // Commands that report on stderr (commit's summary) still say what they did.
            result.text = stderr;
        }
        if result.text.len() > MAX_TEXT {
            let mut cut = MAX_TEXT;
            while !result.text.is_char_boundary(cut) {
                cut -= 1;
            }
            result.text.truncate(cut);
            result.text.push_str(
                "\n… (cut at 256 KiB: narrow the request, e.g. a smaller limit or one path)",
            );
            result.structured = None;
        }
        result
    }
}

impl Tools for OxyTools {
    fn list(&self) -> Vec<Tool> {
        self.offered()
            .map(|s| Tool {
                name: s.name.into(),
                description: s.description.into(),
                input_schema: (s.schema)(),
                read_only: s.read_only,
                destructive: s.destructive,
            })
            .collect()
    }

    fn call(&self, name: &str, args: &Value) -> Option<ToolOutput> {
        let spec = self.offered().find(|s| s.name == name)?;
        Some(match (spec.build)(args, self.allow_destructive) {
            Ok(argv) => self.run(&spec, argv),
            Err(why) => ToolOutput::error(why),
        })
    }
}

/// The first line of `oxy identity show`, said in `initialize` so the client
/// knows who its changes will be signed as.
fn signer_line(exe: &Path, dir: &Path) -> String {
    let out = Command::new(exe)
        .args(["--plain", "identity", "show"])
        .current_dir(dir)
        .stdin(Stdio::null())
        .output();
    match out {
        Ok(o) if o.status.success() => {
            let text = String::from_utf8_lossy(&o.stdout);
            let who = text.lines().next().unwrap_or("").trim_start_matches(['#', '▍', ' ']).trim().to_string();
            let signing = text.lines().find(|l| l.trim_start().starts_with("signing")).map(|l| l.trim().to_string());
            match signing {
                Some(s) => format!("{who}; {s}"),
                None => who,
            }
        }
        _ => "no identity is configured: commits will be refused until one is (oxy identity create, or an agent home with OXY_HOME)".into(),
    }
}

pub fn serve(dir: Option<PathBuf>, allow_destructive: bool) -> Result<i32> {
    let dir = match dir {
        Some(d) => d,
        None => std::env::current_dir()?,
    };
    if !dir.join(oxy_core::repo::OXY_DIR).is_dir() {
        bail!("{} is not the root of an Oxygen repository (no {}): start oxy mcp in a checkout's root, or name it", dir.display(), oxy_core::repo::OXY_DIR);
    }
    let exe = std::env::current_exe()?;
    let signer = signer_line(&exe, &dir);
    let info = ServerInfo {
        name: "oxy".into(),
        version: env!("CARGO_PKG_VERSION").into(),
        instructions: format!(
            "Oxygen version control for the repository at {}. Changes are signed as: {signer}. Prefer these tools to running oxy in a shell. \
             commit and amend take explicit paths (or all: true). {}",
            dir.display(),
            if allow_destructive { "Destructive tools (undo, forced push) are enabled: use them only when asked." } else { "Destructive tools (undo, forced push) are off." }
        ),
    };
    let tools = OxyTools {
        exe,
        dir,
        allow_destructive,
    };
    let stdin = std::io::stdin();
    mcp::serve(&info, &tools, stdin.lock(), std::io::stdout().lock())?;
    Ok(0)
}

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

    fn build(name: &str, args: Value, destructive: bool) -> Result<Vec<String>, String> {
        let spec = specs().into_iter().find(|s| s.name == name).unwrap();
        (spec.build)(&args, destructive)
    }

    #[test]
    fn values_never_read_as_flags() {
        assert_eq!(
            build(
                "commit",
                json!({"message": "-m oops", "paths": ["-rf"]}),
                false
            )
            .unwrap(),
            ["commit", "--message=-m oops", "--", "-rf"]
        );
        assert_eq!(
            build("cat", json!({"path": "--help", "change": "main"}), false).unwrap(),
            ["cat", "--change=main", "--", "--help"]
        );
        assert_eq!(
            build("log", json!({"limit": 5000}), false).unwrap(),
            ["log", "--json", "--limit=1000"],
            "limit is capped"
        );
    }

    #[test]
    fn commits_name_what_goes_in() {
        assert!(build("commit", json!({"message": "x"}), false)
            .unwrap_err()
            .contains("all: true"));
        assert!(build(
            "commit",
            json!({"message": "x", "paths": ["a"], "all": true}),
            false
        )
        .is_err());
        assert_eq!(
            build("commit", json!({"message": "x", "all": true}), false).unwrap(),
            ["commit", "--message=x"]
        );
        assert!(build("commit", json!({"message": " ", "all": true}), false)
            .unwrap_err()
            .contains("message"));
    }

    #[test]
    fn destructive_tools_need_the_flag() {
        let off = OxyTools {
            exe: "oxy".into(),
            dir: ".".into(),
            allow_destructive: false,
        };
        let on = OxyTools {
            exe: "oxy".into(),
            dir: ".".into(),
            allow_destructive: true,
        };
        assert!(!off.list().iter().any(|t| t.name == "undo"));
        assert!(
            off.call("undo", &json!({})).is_none(),
            "an unoffered tool is unknown"
        );
        assert!(on.list().iter().any(|t| t.name == "undo" && t.destructive));
        assert!(build("push", json!({"force": true}), false)
            .unwrap_err()
            .contains("--allow-destructive"));
        assert_eq!(
            build("push", json!({"force": true, "remote": "earth"}), true).unwrap(),
            ["push", "--json", "--force", "--", "earth"]
        );
    }
}

`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet

1		//! `oxy mcp` (oxygen#159): a Model Context Protocol server over stdio for
2		//! the repository it starts in, so an agent works through typed tools
3		//! instead of parsing a shell's output.
4		//!
5		//! Each tool runs this same oxy binary with the command's `--json`, in the
6		//! repository, with the server's environment: so a tool returns exactly
7		//! what the command does, and signs as whatever `OXY_HOME` configures. In
8		//! an agent home every change is sealed via the agent, with no environment
9		//! variable to forget per call. Tools that can lose work (undo, a forced
10		//! push) are offered only with `--allow-destructive`.
11
12		use anyhow::{bail, Result};
13		use oxy_core::mcp::{self, arg_str, arg_strings, ServerInfo, Tool, ToolOutput, Tools};
14		use serde_json::{json, Value};
15		use std::path::{Path, PathBuf};
16		use std::process::{Command, Stdio};
17
18		/// A tool's text is cut here; its structured result is then left out.
19		const MAX_TEXT: usize = 256 * 1024;
20
21		type Build = fn(&Value, bool) -> Result<Vec<String>, String>;
22
23		struct Spec {
24		name: &'static str,
25		description: &'static str,
26		schema: fn() -> Value,
27		build: Build,
28		json: bool,
29		read_only: bool,
30		destructive: bool,
31		}
32
33	74×	fn obj(props: Value, required: &[&str]) -> Value {
34	74×	json!({ "type": "object", "properties": props, "required": required, "additionalProperties": false })
35	74×	}
36
37	22×	fn none() -> Value {
38	22×	obj(json!({}), &[])
39	22×	}
40
41		/// An option's value as `--flag=value`, so a value starting with `-` is
42		/// never read as another flag.
43	10×	fn opt(flag: &str, value: &str) -> String {
44	10×	format!("{flag}={value}")
45	10×	}
46
47		/// Positional values after `--`, for the same reason.
48	6×	fn positional(out: &mut Vec<String>, values: Vec<String>) {
49	6×	if !values.is_empty() {
50	5×	out.push("--".into());
51	5×	out.extend(values);
52	5×	}
53	6×	}
54
55	9×	fn required<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
56	9×	arg_str(args, key)
57	9×	.filter(\|s\| !s.trim().is_empty())
58	9×	.ok_or_else(\|\| format!("{key} is required"))
59	9×	}
60
61		/// Paths to act on, or every path when `all` is true; never neither, so a
62		/// commit or amend is always a deliberate choice of what goes in.
63	6×	fn paths_or_all(args: &Value) -> Result<Vec<String>, String> {
64	6×	let paths = arg_strings(args, "paths")?;
65	6×	let all = args.get("all").and_then(Value::as_bool).unwrap_or(false);
66	6×	match (paths.is_empty(), all) {
67	2×	(false, false) => Ok(paths),
68	1×	(true, true) => Ok(vec![]),
69	1×	(false, true) => Err("give paths or all: true, not both".into()),
70		(true, false) => {
71	2×	Err("give the paths to include, or all: true for every changed path".into())
72		}
73		}
74	6×	}
75
76	2×	fn limit(args: &Value, default: u64) -> String {
77	2×	args.get("limit")
78	2×	.and_then(Value::as_u64)
79	2×	.unwrap_or(default)
80	2×	.clamp(1, 1000)
81	2×	.to_string()
82	2×	}
83
84	22×	fn specs() -> Vec<Spec> {
85	22×	vec![
86		Spec {
87		name: "status",
88		description: "The working copy: the bookmark, changed paths, and every conflict with its kind and the changes behind it.",
89	22×	schema: none,
90	2×	build: \|_, _\| Ok(vec!["status".into(), "--json".into()]),
91		json: true,
92		read_only: true,
93		destructive: false,
94		},
95		Spec {
96		name: "diff",
97		description: "Uncommitted edits in the working copy, or one change's edits when `change` is given (a ChangeId or #hash prefix).",
98	4×	schema: \|\| obj(json!({ "change": { "type": "string" } }), &[]),
99	0×	build: \|a, _\| {
100	0×	let mut v = vec!["diff".into(), "--json".into()];
101	0×	positional(&mut v, arg_str(a, "change").map(\|c\| vec![c.to_string()]).unwrap_or_default());
102	0×	Ok(v)
103	0×	},
104		json: true,
105		read_only: true,
106		destructive: false,
107		},
108		Spec {
109		name: "log",
110		description: "Changes, newest first: a revset (`main`, `@`, …) or the current bookmark, optionally only those touching `path`; `limit` defaults to 20.",
111	4×	schema: \|\| obj(json!({ "revset": { "type": "string" }, "path": { "type": "string" }, "limit": { "type": "integer", "minimum": 1 } }), &[]),
112	2×	build: \|a, _\| {
113	2×	let mut v = vec!["log".into(), "--json".into(), opt("--limit", &limit(a, 20))];
114	2×	if let Some(r) = arg_str(a, "revset") {
115	0×	v.push(opt("--revset", r));
116	2×	}
117	2×	if let Some(p) = arg_str(a, "path") {
118	0×	v.push(opt("--path", p));
119	2×	}
120	2×	Ok(v)
121	2×	},
122		json: true,
123		read_only: true,
124		destructive: false,
125		},
126		Spec {
127		name: "show",
128		description: "One change: its message, author, signatures and edits (`stat: true` for files and line counts only). `change` defaults to @, the working copy.",
129	4×	schema: \|\| obj(json!({ "change": { "type": "string" }, "stat": { "type": "boolean" } }), &[]),
130	0×	build: \|a, _\| {
131	0×	let mut v = vec!["show".into(), "--json".into()];
132	0×	if a.get("stat").and_then(Value::as_bool).unwrap_or(false) {
133	0×	v.push("--stat".into());
134	0×	}
135	0×	positional(&mut v, vec![arg_str(a, "change").unwrap_or("@").to_string()]);
136	0×	Ok(v)
137	0×	},
138		json: true,
139		read_only: true,
140		destructive: false,
141		},
142		Spec {
143		name: "cat",
144		description: "A file's content as a bookmark, tag or change has it (`change`), or as committed on the working copy's base.",
145	4×	schema: \|\| obj(json!({ "path": { "type": "string" }, "change": { "type": "string" } }), &["path"]),
146	2×	build: \|a, _\| {
147	2×	let mut v = vec!["cat".into()];
148	2×	if let Some(c) = arg_str(a, "change") {
149	2×	v.push(opt("--change", c));
150	2×	}
151	2×	positional(&mut v, vec![required(a, "path")?.to_string()]);
152	2×	Ok(v)
153	2×	},
154		json: false,
155		read_only: true,
156		destructive: false,
157		},
158		Spec {
159		name: "blame",
160		description: "Which change wrote each line of a file, with its line atoms.",
161	4×	schema: \|\| obj(json!({ "path": { "type": "string" } }), &["path"]),
162	0×	build: \|a, _\| {
163	0×	let mut v = vec!["blame".into(), "--json".into()];
164	0×	positional(&mut v, vec![required(a, "path")?.to_string()]);
165	0×	Ok(v)
166	0×	},
167		json: true,
168		read_only: true,
169		destructive: false,
170		},
171		Spec {
172		name: "bookmarks",
173		description: "Bookmarks with their heads and how far each is ahead of or behind its remote; `all: true` adds remotes' bookmarks.",
174	4×	schema: \|\| obj(json!({ "all": { "type": "boolean" } }), &[]),
175	0×	build: \|a, _\| {
176	0×	let mut v = vec!["bookmark".into(), "list".into(), "--json".into()];
177	0×	if a.get("all").and_then(Value::as_bool).unwrap_or(false) {
178	0×	v.push("--all".into());
179	0×	}
180	0×	Ok(v)
181	0×	},
182		json: true,
183		read_only: true,
184		destructive: false,
185		},
186		Spec {
187		name: "tags",
188		description: "Tags with their states, messages and signers.",
189	22×	schema: none,
190	0×	build: \|_, _\| Ok(vec!["tag".into(), "list".into(), "--json".into()]),
191		json: true,
192		read_only: true,
193		destructive: false,
194		},
195		Spec {
196		name: "conflicts",
197		description: "Which conflicts of the working copy's base the current files resolve, and which remain.",
198	22×	schema: none,
199	0×	build: \|_, _\| Ok(vec!["resolve".into(), "--json".into()]),
200		json: true,
201		read_only: true,
202		destructive: false,
203		},
204		Spec {
205		name: "op_log",
206		description: "The operation log, newest first (what undo would take back); `limit` defaults to 20.",
207	4×	schema: \|\| obj(json!({ "limit": { "type": "integer", "minimum": 1 } }), &[]),
208	0×	build: \|a, _\| Ok(vec!["op".into(), "log".into(), "--json".into(), opt("--limit", &limit(a, 20))]),
209		json: true,
210		read_only: true,
211		destructive: false,
212		},
213		Spec {
214		name: "identity",
215		description: "Who changes are signed as here: the author, the key, delegates and the signer (an agent home signs keyless, via the agent).",
216	22×	schema: none,
217	0×	build: \|_, _\| Ok(vec!["identity".into(), "show".into()]),
218		json: false,
219		read_only: true,
220		destructive: false,
221		},
222		Spec {
223		name: "commit",
224		description: "Record a change with a message: only `paths`, or every changed path with `all: true`. Signed as this server's identity.",
225	4×	schema: \|\| obj(json!({ "message": { "type": "string" }, "paths": { "type": "array", "items": { "type": "string" } }, "all": { "type": "boolean" } }), &["message"]),
226	7×	build: \|a, _\| {
227	7×	let mut v = vec!["commit".into(), opt("--message", required(a, "message")?)];
228	6×	positional(&mut v, paths_or_all(a)?);
229	3×	Ok(v)
230	7×	},
231		json: false,
232		read_only: false,
233		destructive: false,
234		},
235		Spec {
236		name: "amend",
237		description: "Fold edits into the change the working copy sits on: only `paths`, or all with `all: true`; `message` replaces its message too.",
238	4×	schema: \|\| obj(json!({ "message": { "type": "string" }, "paths": { "type": "array", "items": { "type": "string" } }, "all": { "type": "boolean" } }), &[]),
239	0×	build: \|a, _\| {
240	0×	let mut v = vec!["amend".into()];
241	0×	if let Some(m) = arg_str(a, "message") {
242	0×	v.push(opt("--message", m));
243	0×	}
244	0×	positional(&mut v, paths_or_all(a)?);
245	0×	Ok(v)
246	0×	},
247		json: false,
248		read_only: false,
249		destructive: false,
250		},
251		Spec {
252		name: "describe",
253		description: "Change a head's message (`change` defaults to the one the working copy sits on).",
254	4×	schema: \|\| obj(json!({ "message": { "type": "string" }, "change": { "type": "string" } }), &["message"]),
255	0×	build: \|a, _\| {
256	0×	let mut v = vec!["describe".into(), "--json".into(), opt("--message", required(a, "message")?)];
257	0×	positional(&mut v, arg_str(a, "change").map(\|c\| vec![c.to_string()]).unwrap_or_default());
258	0×	Ok(v)
259	0×	},
260		json: true,
261		read_only: false,
262		destructive: false,
263		},
264		Spec {
265		name: "fetch",
266		description: "Fetch from a remote (default origin) without moving local bookmarks.",
267	4×	schema: \|\| obj(json!({ "remote": { "type": "string" } }), &[]),
268	0×	build: \|a, _\| remote_cmd("fetch", a),
269		json: true,
270		read_only: false,
271		destructive: false,
272		},
273		Spec {
274		name: "pull",
275		description: "Fetch from a remote (default origin) and bring the current bookmark and working copy up to date.",
276	4×	schema: \|\| obj(json!({ "remote": { "type": "string" } }), &[]),
277	0×	build: \|a, _\| remote_cmd("pull", a),
278		json: true,
279		read_only: false,
280		destructive: false,
281		},
282		Spec {
283		name: "push",
284		description: "Push the current bookmark (or `bookmark`) to a remote (default origin). Changes are sealed at push as this server's identity. `force` (drop heads the remote has) needs the server started with --allow-destructive.",
285	4×	schema: \|\| obj(json!({ "remote": { "type": "string" }, "bookmark": { "type": "string" }, "force": { "type": "boolean" } }), &[]),
286	3×	build: \|a, destructive\| {
287	3×	let mut v = vec!["push".to_string(), "--json".into()];
288	3×	if let Some(b) = arg_str(a, "bookmark") {
289	0×	v.push(opt("--bookmark", b));
290	3×	}
291	3×	if a.get("force").and_then(Value::as_bool).unwrap_or(false) {
292	3×	if !destructive {
293	2×	return Err("a forced push can drop the remote's heads; start oxy mcp with --allow-destructive to allow it".into());
294	1×	}
295	1×	v.push("--force".into());
296	0×	}
297	1×	positional(&mut v, arg_str(a, "remote").map(\|r\| vec![r.to_string()]).unwrap_or_default());
298	1×	Ok(v)
299	3×	},
300		json: true,
301		read_only: false,
302		destructive: false,
303		},
304		Spec {
305		name: "tlog_verify",
306		description: "Check the hub's transparency log: that it shows everyone the same history, with this repository's entries and each witness's cosignature.",
307	22×	schema: none,
308	0×	build: \|_, _\| Ok(vec!["tlog".into(), "verify".into(), "--json".into()]),
309		json: true,
310		read_only: true,
311		destructive: false,
312		},
313		Spec {
314		name: "undo",
315		description: "Take back the last operation (see op_log). Offered only when the server was started with --allow-destructive.",
316	22×	schema: none,
317	0×	build: \|_, _\| Ok(vec!["undo".into()]),
318		json: false,
319		read_only: false,
320		destructive: true,
321		},
322		]
323	22×	}
324
325	0×	fn remote_cmd(command: &str, a: &Value) -> Result<Vec<String>, String> {
326	0×	let mut v = vec![command.to_string(), "--json".into()];
327	0×	positional(
328	0×	&mut v,
329	0×	arg_str(a, "remote")
330	0×	.map(\|r\| vec![r.to_string()])
331	0×	.unwrap_or_default(),
332		);
333	0×	Ok(v)
334	0×	}
335
336		struct OxyTools {
337		exe: PathBuf,
338		dir: PathBuf,
339		allow_destructive: bool,
340		}
341
342		impl OxyTools {
343	13×	fn offered(&self) -> impl Iterator<Item = Spec> + '_ {
344	13×	specs()
345	13×	.into_iter()
346	165×	.filter(\|s\| self.allow_destructive \|\| !s.destructive)
347	13×	}
348
349	5×	fn run(&self, spec: &Spec, argv: Vec<String>) -> ToolOutput {
350	5×	let out = Command::new(&self.exe)
351	5×	.arg("--plain")
352	5×	.args(&argv)
353	5×	.current_dir(&self.dir)
354	5×	.stdin(Stdio::null())
355	5×	.output();
356	5×	let out = match out {
357	5×	Ok(o) => o,
358	0×	Err(e) => return ToolOutput::error(format!("could not run oxy: {e}")),
359		};
360	5×	let stdout = String::from_utf8_lossy(&out.stdout).into_owned();
361	5×	let stderr = String::from_utf8_lossy(&out.stderr).into_owned();
362	5×	if !out.status.success() {
363	0×	let why = if stderr.trim().is_empty() {
364	0×	stdout
365		} else {
366	0×	stderr
367		};
368	0×	return ToolOutput::error(format!("oxy {} failed: {}", argv.join(" "), why.trim()));
369	5×	}
370	5×	let mut result = ToolOutput::ok(stdout.clone());
371	5×	if spec.json {
372	3×	result.structured = serde_json::from_str(&stdout).ok();
373	3×	} else if !stderr.trim().is_empty() && stdout.trim().is_empty() {
374	0×	// Commands that report on stderr (commit's summary) still say what they did.
375	0×	result.text = stderr;
376	2×	}
377	5×	if result.text.len() > MAX_TEXT {
378	0×	let mut cut = MAX_TEXT;
379	0×	while !result.text.is_char_boundary(cut) {
380	0×	cut -= 1;
381	0×	}
382	0×	result.text.truncate(cut);
383	0×	result.text.push_str(
384	0×	"\n… (cut at 256 KiB: narrow the request, e.g. a smaller limit or one path)",
385		);
386	0×	result.structured = None;
387	5×	}
388	5×	result
389	5×	}
390		}
391
392		impl Tools for OxyTools {
393	4×	fn list(&self) -> Vec<Tool> {
394	4×	self.offered()
395	4×	.map(\|s\| Tool {
396	74×	name: s.name.into(),
397	74×	description: s.description.into(),
398	74×	input_schema: (s.schema)(),
399	74×	read_only: s.read_only,
400	74×	destructive: s.destructive,
401	74×	})
402	4×	.collect()
403	4×	}
404
405	9×	fn call(&self, name: &str, args: &Value) -> Option<ToolOutput> {
406	87×	let spec = self.offered().find(\|s\| s.name == name)?;
407	7×	Some(match (spec.build)(args, self.allow_destructive) {
408	5×	Ok(argv) => self.run(&spec, argv),
409	2×	Err(why) => ToolOutput::error(why),
410		})
411	9×	}
412		}
413
414		/// The first line of `oxy identity show`, said in `initialize` so the client
415		/// knows who its changes will be signed as.
416	2×	fn signer_line(exe: &Path, dir: &Path) -> String {
417	2×	let out = Command::new(exe)
418	2×	.args(["--plain", "identity", "show"])
419	2×	.current_dir(dir)
420	2×	.stdin(Stdio::null())
421	2×	.output();
422	2×	match out {
423	2×	Ok(o) if o.status.success() => {
424	2×	let text = String::from_utf8_lossy(&o.stdout);
425	2×	let who = text.lines().next().unwrap_or("").trim_start_matches(['#', '▍', ' ']).trim().to_string();
426	6×	let signing = text.lines().find(\|l\| l.trim_start().starts_with("signing")).map(\|l\| l.trim().to_string());
427	2×	match signing {
428	1×	Some(s) => format!("{who}; {s}"),
429	1×	None => who,
430		}
431		}
432	0×	_ => "no identity is configured: commits will be refused until one is (oxy identity create, or an agent home with OXY_HOME)".into(),
433		}
434	2×	}
435
436	3×	pub fn serve(dir: Option<PathBuf>, allow_destructive: bool) -> Result<i32> {
437	3×	let dir = match dir {
438	1×	Some(d) => d,
439	2×	None => std::env::current_dir()?,
440		};
441	3×	if !dir.join(oxy_core::repo::OXY_DIR).is_dir() {
442	1×	bail!("{} is not the root of an Oxygen repository (no {}): start oxy mcp in a checkout's root, or name it", dir.display(), oxy_core::repo::OXY_DIR);
443	2×	}
444	2×	let exe = std::env::current_exe()?;
445	2×	let signer = signer_line(&exe, &dir);
446	2×	let info = ServerInfo {
447	2×	name: "oxy".into(),
448	2×	version: env!("CARGO_PKG_VERSION").into(),
449	2×	instructions: format!(
450		"Oxygen version control for the repository at {}. Changes are signed as: {signer}. Prefer these tools to running oxy in a shell. \
451		commit and amend take explicit paths (or all: true). {}",
452	2×	dir.display(),
453	2×	if allow_destructive { "Destructive tools (undo, forced push) are enabled: use them only when asked." } else { "Destructive tools (undo, forced push) are off." }
454		),
455		};
456	2×	let tools = OxyTools {
457	2×	exe,
458	2×	dir,
459	2×	allow_destructive,
460	2×	};
461	2×	let stdin = std::io::stdin();
462	2×	mcp::serve(&info, &tools, stdin.lock(), std::io::stdout().lock())?;
463	2×	Ok(0)
464	3×	}
465
466		#[cfg(test)]
467		mod tests {
468		use super::*;
469
470	9×	fn build(name: &str, args: Value, destructive: bool) -> Result<Vec<String>, String> {
471	102×	let spec = specs().into_iter().find(\|s\| s.name == name).unwrap();
472	9×	(spec.build)(&args, destructive)
473	9×	}
474
475		#[test]
476	1×	fn values_never_read_as_flags() {
477	1×	assert_eq!(
478	1×	build(
479	1×	"commit",
480	1×	json!({"message": "-m oops", "paths": ["-rf"]}),
481		false
482		)
483	1×	.unwrap(),
484		["commit", "--message=-m oops", "--", "-rf"]
485		);
486	1×	assert_eq!(
487	1×	build("cat", json!({"path": "--help", "change": "main"}), false).unwrap(),
488		["cat", "--change=main", "--", "--help"]
489		);
490	1×	assert_eq!(
491	1×	build("log", json!({"limit": 5000}), false).unwrap(),
492		["log", "--json", "--limit=1000"],
493		"limit is capped"
494		);
495	1×	}
496
497		#[test]
498	1×	fn commits_name_what_goes_in() {
499	1×	assert!(build("commit", json!({"message": "x"}), false)
500	1×	.unwrap_err()
501	1×	.contains("all: true"));
502	1×	assert!(build(
503	1×	"commit",
504	1×	json!({"message": "x", "paths": ["a"], "all": true}),
505	1×	false
506	1×	)
507	1×	.is_err());
508	1×	assert_eq!(
509	1×	build("commit", json!({"message": "x", "all": true}), false).unwrap(),
510		["commit", "--message=x"]
511		);
512	1×	assert!(build("commit", json!({"message": " ", "all": true}), false)
513	1×	.unwrap_err()
514	1×	.contains("message"));
515	1×	}
516
517		#[test]
518	1×	fn destructive_tools_need_the_flag() {
519	1×	let off = OxyTools {
520	1×	exe: "oxy".into(),
521	1×	dir: ".".into(),
522	1×	allow_destructive: false,
523	1×	};
524	1×	let on = OxyTools {
525	1×	exe: "oxy".into(),
526	1×	dir: ".".into(),
527	1×	allow_destructive: true,
528	1×	};
529	18×	assert!(!off.list().iter().any(\|t\| t.name == "undo"));
530	1×	assert!(
531	1×	off.call("undo", &json!({})).is_none(),
532		"an unoffered tool is unknown"
533		);
534	19×	assert!(on.list().iter().any(\|t\| t.name == "undo" && t.destructive));
535	1×	assert!(build("push", json!({"force": true}), false)
536	1×	.unwrap_err()
537	1×	.contains("--allow-destructive"));
538	1×	assert_eq!(
539	1×	build("push", json!({"force": true, "remote": "earth"}), true).unwrap(),
540		["push", "--json", "--force", "--", "earth"]
541		);
542	1×	}
543		}

Coverage / src/cli/mcp.rs 75.2%

Keyboard