oxy mcp: an MCP server for a repository, signing as its configured identity (closes #159) 91334b7fa574

//! A Model Context Protocol server over stdio (oxygen#159): JSON-RPC 2.0,

//! one message per line, as MCP's stdio transport has it. This is only the

//! protocol: `initialize`, `ping`, `tools/list` and `tools/call`, with the

//! tools themselves supplied by the caller (`oxy mcp`, and `oh mcp` in the

//! hub, which reaches this module through its pinned oxygen).

//!

//! Nothing is written to stdout but protocol messages: a tool's own

//! output goes into its result.

use serde_json::{json, Value};

use std::io::{BufRead, Write};

/// The protocol versions this server speaks, newest first. A client asking

/// for one of them gets it back; any other gets the newest.

pub const PROTOCOL_VERSIONS: &[&str] = &["2025-06-18", "2025-03-26", "2024-11-05"];

/// One tool as `tools/list` describes it.

#[derive(Clone, Debug)]

pub struct Tool {

    pub name: String,

    pub description: String,

    /// A JSON Schema object for the arguments.

    pub input_schema: Value,

    /// Reads only: no change to the repository, the remote or the hub.

    pub read_only: bool,

    /// May lose work or history (undo, abandon, deletes).

    pub destructive: bool,

}

impl Tool {

    fn describe(&self) -> Value {

        json!({

            "name": self.name,

            "description": self.description,

            "inputSchema": self.input_schema,

            "annotations": {

                "readOnlyHint": self.read_only,

                "destructiveHint": self.destructive,

            },

        })

    }

}

/// What a tool call produced: text for the model to read, the same as JSON

/// when there is some, and whether it failed. A failed tool is a result, not

/// a protocol error, so the model sees why.

#[derive(Clone, Debug, Default, PartialEq)]

pub struct ToolOutput {

    pub text: String,

    pub structured: Option<Value>,

    pub is_error: bool,

}

impl ToolOutput {

    pub fn ok(text: impl Into<String>) -> ToolOutput {

        ToolOutput {

            text: text.into(),

            structured: None,

            is_error: false,

        }

    }

    pub fn error(text: impl Into<String>) -> ToolOutput {

        ToolOutput {

            text: text.into(),

            structured: None,

            is_error: true,

        }

    }

    fn to_json(&self) -> Value {

        let mut out = json!({

            "content": [{ "type": "text", "text": self.text }],

            "isError": self.is_error,

        });

        // Structured content must be an object; an array is wrapped.

        if let Some(s) = &self.structured {

            let obj = if s.is_object() {

                s.clone()

            } else {

                json!({ "result": s })

            };

            out["structuredContent"] = obj;

        }

        out

    }

}

/// The tools a server offers.

pub trait Tools {

    fn list(&self) -> Vec<Tool>;

    /// Run a tool. `None` when no tool has that name.

    fn call(&self, name: &str, args: &Value) -> Option<ToolOutput>;

}

/// Who the server is, for `initialize`.

#[derive(Clone, Debug)]

pub struct ServerInfo {

    pub name: String,

    pub version: String,

    /// Shown to the model: what the server is for and how to use it safely.

    pub instructions: String,

}

const PARSE_ERROR: i64 = -32700;

const INVALID_REQUEST: i64 = -32600;

const METHOD_NOT_FOUND: i64 = -32601;

const INVALID_PARAMS: i64 = -32602;

fn error(id: Value, code: i64, message: &str) -> Value {

    json!({ "jsonrpc": "2.0", "id": id, "error": { "code": code, "message": message } })

}

fn result(id: Value, result: Value) -> Value {

    json!({ "jsonrpc": "2.0", "id": id, "result": result })

}

/// Answer one message; `None` for a notification (no reply is due).

pub fn handle(info: &ServerInfo, tools: &dyn Tools, message: &Value) -> Option<Value> {

    let Some(obj) = message.as_object() else {

        return Some(error(

            Value::Null,

            INVALID_REQUEST,

            "a message is a JSON object",

        ));

    };

    let method = obj.get("method").and_then(Value::as_str);

    let id = obj.get("id").cloned();

    let Some(method) = method else {

        // A response to something we never sent, or nonsense: a request

        // without a method gets an error, anything else is ignored.

        return id.map(|id| error(id, INVALID_REQUEST, "a request needs a method"));

    };

    // Notifications (initialized, cancelled, …) carry no id and get no reply.

    let id = id?;

    let params = obj.get("params").cloned().unwrap_or(Value::Null);

    Some(match method {

        "initialize" => {

            let asked = params.get("protocolVersion").and_then(Value::as_str);

            let version = asked

                .filter(|v| PROTOCOL_VERSIONS.contains(v))

                .unwrap_or(PROTOCOL_VERSIONS[0]);

            result(

                id,

                json!({

                    "protocolVersion": version,

                    "capabilities": { "tools": { "listChanged": false } },

                    "serverInfo": { "name": info.name, "version": info.version },

                    "instructions": info.instructions,

                }),

            )

        }

        "ping" => result(id, json!({})),

        "tools/list" => result(

            id,

            json!({ "tools": tools.list().iter().map(Tool::describe).collect::<Vec<_>>() }),

        ),

        "tools/call" => {

            let Some(name) = params.get("name").and_then(Value::as_str) else {

                return Some(error(

                    id,

                    INVALID_PARAMS,

                    "tools/call needs the tool's name",

                ));

            };

            let args = params

                .get("arguments")

                .cloned()

                .unwrap_or_else(|| json!({}));

            if !args.is_object() {

                return Some(error(

                    id,

                    INVALID_PARAMS,

                    "a tool's arguments are a JSON object",

                ));

            }

            match tools.call(name, &args) {

                Some(out) => result(id, out.to_json()),

                None => error(id, INVALID_PARAMS, &format!("no tool named {name}")),

            }

        }

        other => error(id, METHOD_NOT_FOUND, &format!("{other} is not supported")),

    })

}

/// Serve until the input ends: read a message per line, write a reply per

/// request. A line that is not JSON gets a parse error; blank lines are

/// skipped.

pub fn serve(

    info: &ServerInfo,

    tools: &dyn Tools,

    input: impl BufRead,

    mut output: impl Write,

) -> std::io::Result<()> {

    for line in input.lines() {

        let line = line?;

        if line.trim().is_empty() {

            continue;

        }

        let reply = match serde_json::from_str::<Value>(&line) {

            Ok(Value::Array(batch)) => {

                let replies: Vec<Value> = batch

                    .iter()

                    .filter_map(|m| handle(info, tools, m))

                    .collect();

                (!replies.is_empty()).then_some(Value::Array(replies))

            }

            Ok(message) => handle(info, tools, &message),

            Err(e) => Some(error(Value::Null, PARSE_ERROR, &format!("not JSON: {e}"))),

        };

        if let Some(reply) = reply {

            writeln!(output, "{reply}")?;

            output.flush()?;

        }

    }

    Ok(())

}

/// A string argument, if given and a string.

pub fn arg_str<'a>(args: &'a Value, key: &str) -> Option<&'a str> {

    args.get(key).and_then(Value::as_str)

}

/// A list of strings, if given; a single string counts as a list of one.

pub fn arg_strings(args: &Value, key: &str) -> Result<Vec<String>, String> {

    match args.get(key) {

        None | Some(Value::Null) => Ok(vec![]),

        Some(Value::String(s)) => Ok(vec![s.clone()]),

        Some(Value::Array(a)) => a

            .iter()

            .map(|v| {

                v.as_str()

                    .map(str::to_string)

                    .ok_or_else(|| format!("{key} must be a list of strings"))

            })

            .collect(),

        Some(_) => Err(format!("{key} must be a list of strings")),

    }

}

#[cfg(test)]

mod tests {

    use super::*;

    struct Echo;

    impl Tools for Echo {

        fn list(&self) -> Vec<Tool> {

            vec![Tool {

                name: "echo".into(),

                description: "says it back".into(),

                input_schema: json!({"type": "object"}),

                read_only: true,

                destructive: false,

            }]

        }

        fn call(&self, name: &str, args: &Value) -> Option<ToolOutput> {

            (name == "echo").then(|| ToolOutput {

                text: args.to_string(),

                structured: Some(json!([1, 2])),

                is_error: false,

            })

        }

    }

    fn info() -> ServerInfo {

        ServerInfo {

            name: "t".into(),

            version: "1".into(),

            instructions: "be careful".into(),

        }

    }

    fn talk(lines: &str) -> Vec<Value> {

        let mut out = Vec::new();

        serve(&info(), &Echo, lines.as_bytes(), &mut out).unwrap();

        String::from_utf8(out)

            .unwrap()

            .lines()

            .map(|l| serde_json::from_str(l).unwrap())

            .collect()

    }

    #[test]

    fn a_session_initializes_lists_and_calls() {

        let r = talk(concat!(

            r#"{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"c","version":"0"}}}"#,

            "\n",

            r#"{"jsonrpc":"2.0","method":"notifications/initialized"}"#,

            "\n\n",

            r#"{"jsonrpc":"2.0","id":2,"method":"tools/list"}"#,

            "\n",

            r#"{"jsonrpc":"2.0","id":"three","method":"tools/call","params":{"name":"echo","arguments":{"a":1}}}"#,

            "\n",

        ));

        assert_eq!(r.len(), 3, "the notification gets no reply: {r:?}");

        assert_eq!(

            r[0]["result"]["protocolVersion"], "2025-03-26",

            "a version we speak is kept"

        );

        assert_eq!(r[0]["result"]["instructions"], "be careful");

        assert_eq!(r[1]["result"]["tools"][0]["name"], "echo");

        assert_eq!(

            r[1]["result"]["tools"][0]["annotations"]["readOnlyHint"],

            true

        );

        assert_eq!(r[2]["id"], "three");

        assert_eq!(r[2]["result"]["content"][0]["text"], r#"{"a":1}"#);

        assert_eq!(

            r[2]["result"]["structuredContent"],

            json!({"result": [1, 2]}),

            "an array is wrapped in an object"

        );

        assert_eq!(r[2]["result"]["isError"], false);

    }

    #[test]

    fn errors_are_protocol_errors_and_unknown_versions_get_the_newest() {

        let r = talk(concat!(

            "not json\n",

            r#"{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"1999-01-01"}}"#,

            "\n",

            r#"{"jsonrpc":"2.0","id":2,"method":"resources/list"}"#,

            "\n",

            r#"{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"nope"}}"#,

            "\n",

            r#"{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"echo","arguments":[1]}}"#,

            "\n",

            r#"[{"jsonrpc":"2.0","id":5,"method":"ping"},{"jsonrpc":"2.0","method":"notifications/cancelled"}]"#,

            "\n",

        ));

        assert_eq!(r[0]["error"]["code"], PARSE_ERROR);

        assert_eq!(r[1]["result"]["protocolVersion"], PROTOCOL_VERSIONS[0]);

        assert_eq!(r[2]["error"]["code"], METHOD_NOT_FOUND);

        assert_eq!(r[3]["error"]["code"], INVALID_PARAMS);

        assert_eq!(r[4]["error"]["code"], INVALID_PARAMS);

        assert_eq!(

            r[5],

            json!([{"jsonrpc": "2.0", "id": 5, "result": {}}]),

            "a batch is answered as a batch"

        );

    }

    #[test]

    fn string_arguments_and_lists() {

        let a = json!({"one": "x", "many": ["a", "b"], "bad": [1]});

        assert_eq!(arg_str(&a, "one"), Some("x"));

        assert_eq!(arg_strings(&a, "one").unwrap(), vec!["x"]);

        assert_eq!(arg_strings(&a, "many").unwrap(), vec!["a", "b"]);

        assert_eq!(arg_strings(&a, "missing").unwrap(), Vec::<String>::new());

        assert!(arg_strings(&a, "bad").is_err());

    }

}

# oxy mcp: Oxygen for AI agents

`oxy mcp` serves one repository to an AI agent over the

[Model Context Protocol](https://modelcontextprotocol.io) (MCP), on stdio

(oxygen#159). The agent calls typed tools (`status`, `log`, `commit`, …)

and gets JSON back, instead of running `oxy` in a shell and reading its

output.

## Who changes are signed as

The server signs as whatever identity its environment configures, exactly

as `oxy` would: it runs each tool as this same `oxy` binary, in the

repository, with the server's environment. Start it from an agent home and

every change the agent makes is sealed **via the agent**, with no

`OXY_HOME` to remember on each command:

```sh

OXY_HOME=~/.oxy-agents/claude oxy mcp ~/development/myproject

```

The server says who it signs as in its `initialize` reply (the first line

of `oxy identity show`), and the `identity` tool shows the rest. Without an

identity, reading works and committing is refused with oxy's own message.

## Tools

Each tool returns the command's `--json` output as structured content (an

array comes wrapped as `{"result": […]}`) and as text. A failed command is a

tool result with `isError: true` and oxy's error, so the agent sees why.

| Tool | Runs | Arguments |

|---|---|---|

| `status` | `oxy status --json` | |

| `diff` | `oxy diff [CHANGE] --json` | `change` |

| `log` | `oxy log --json` | `revset`, `path`, `limit` (default 20, at most 1000) |

| `show` | `oxy show CHANGE --json` | `change` (default `@`), `stat` |

| `cat` | `oxy cat PATH [-r CHANGE]` | `path`, `change` |

| `blame` | `oxy blame PATH --json` | `path` |

| `bookmarks` | `oxy bookmark list --json` | `all` |

| `tags` | `oxy tag list --json` | |

| `conflicts` | `oxy resolve --json` (report only) | |

| `op_log` | `oxy op log --json` | `limit` |

| `identity` | `oxy identity show` | |

| `commit` | `oxy commit -m MESSAGE PATHS…` | `message`, and `paths` or `all: true` |

| `amend` | `oxy amend [-m] PATHS…` | `paths` or `all: true`, `message` |

| `describe` | `oxy describe [CHANGE] -m MESSAGE` | `message`, `change` |

| `fetch`, `pull` | `oxy fetch\|pull [REMOTE] --json` | `remote` |

| `push` | `oxy push [REMOTE] --json` | `remote`, `bookmark`, `force` |

| `tlog_verify` | `oxy tlog verify --json` | |

| `undo` | `oxy undo` | only with `--allow-destructive` |

## Safety

- **Commits are deliberate.** `commit` and `amend` take the paths to

  include, or `all: true`; never neither.

- **Nothing destructive by default.** `undo` is not offered, and `push`

  refuses `force`, unless the server is started with `--allow-destructive`.

  Tag withdrawal, bookmark deletion and history rewriting are not tools at

  all. Each tool carries MCP's `readOnlyHint` and `destructiveHint`.

- **Values are never flags.** Arguments are passed as `--flag=value` and

  after `--`, so a path or message starting with `-` stays a value.

- **Your policy still applies.** Pushes go through the remote's checks and

  the repository's trust policy like any other; an agent's delegation

  scope limits what its seals may do.

- **Output is bounded.** A tool's text stops at 256 KiB, saying to narrow

  the request.

## Adding it to an agent

Claude Code, for one project (run in the project's root):

```sh

claude mcp add oxy -- env OXY_HOME=$HOME/.oxy-agents/claude oxy mcp

```

Any MCP client that starts stdio servers takes the same command: `oxy mcp

[DIR] [--allow-destructive]`, with `OXY_HOME` set for an agent's identity.

`DIR` defaults to the current directory and must be a repository's root.

//! `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"]

        );

    }

}

//! `oxy mcp` (oxygen#159) end to end: an MCP client talks to the server over

//! stdio, lists its tools, reads the repository, commits by path as the

//! configured identity, and is refused what it may not do.

use serde_json::{json, Value};

use std::io::{BufRead, BufReader, Write};

use std::path::Path;

use std::process::{Command, Stdio};

fn oxy(dir: &Path, home: &Path, args: &[&str]) -> i32 {

    Command::new(env!("CARGO_BIN_EXE_oxy"))

        .arg("--plain")

        .args(args)

        .current_dir(dir)

        .env("OXY_HOME", home)

        .env("NO_COLOR", "1")

        .status()

        .unwrap()

        .code()

        .unwrap_or(-1)

}

/// Send each request in turn and collect the replies, one per request (the

/// notification gets none).

fn session(dir: &Path, home: &Path, extra: &[&str], requests: &[Value]) -> Vec<Value> {

    let mut child = Command::new(env!("CARGO_BIN_EXE_oxy"))

        .arg("mcp")

        .args(extra)

        .current_dir(dir)

        .env("OXY_HOME", home)

        .env("NO_COLOR", "1")

        .stdin(Stdio::piped())

        .stdout(Stdio::piped())

        .stderr(Stdio::null())

        .spawn()

        .unwrap();

    let mut stdin = child.stdin.take().unwrap();

    let mut stdout = BufReader::new(child.stdout.take().unwrap());

    let mut replies = vec![];

    for r in requests {

        writeln!(stdin, "{r}").unwrap();

        stdin.flush().unwrap();

        if r.get("id").is_some() {

            let mut line = String::new();

            stdout.read_line(&mut line).unwrap();

            replies.push(

                serde_json::from_str(&line).unwrap_or_else(|e| panic!("not JSON ({e}): {line}")),

            );

        }

    }

    drop(stdin);

    assert!(

        child.wait().unwrap().success(),

        "the server ends cleanly when its input does"

    );

    replies

}

fn call(id: u64, name: &str, args: Value) -> Value {

    json!({"jsonrpc": "2.0", "id": id, "method": "tools/call", "params": {"name": name, "arguments": args}})

}

#[test]

fn an_agent_reads_and_commits_through_mcp() {

    let tmp = tempfile::tempdir().unwrap();

    let home = tmp.path().join("home");

    std::fs::create_dir_all(&home).unwrap();

    let repo = tmp.path().join("repo");

    assert_eq!(oxy(tmp.path(), &home, &["init", repo.to_str().unwrap()]), 0);

    assert_eq!(

        oxy(

            &repo,

            &home,

            &[

                "identity",

                "create",

                "--name",

                "Ada",

                "--email",

                "[email protected]"

            ]

        ),

        0

    );

    assert_eq!(

        oxy(&repo, &home, &["config", "--user", "core.sign", "change"]),

        0

    );

    std::fs::write(repo.join("a.txt"), "one\n").unwrap();

    std::fs::write(repo.join("b.txt"), "two\n").unwrap();

    let r = session(

        &repo,

        &home,

        &[],

        &[

            json!({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test", "version": "0"}}}),

            json!({"jsonrpc": "2.0", "method": "notifications/initialized"}),

            json!({"jsonrpc": "2.0", "id": 2, "method": "tools/list"}),

            call(3, "status", json!({})),

            call(4, "commit", json!({"message": "everything"})),

            call(5, "commit", json!({"message": "Add a", "paths": ["a.txt"]})),

            call(6, "log", json!({"limit": 5})),

            call(7, "status", json!({})),

            call(8, "undo", json!({})),

            call(9, "push", json!({"force": true})),

            call(10, "cat", json!({"path": "a.txt", "change": "@"})),

        ],

    );

    let init = &r[0]["result"];

    assert_eq!(init["serverInfo"]["name"], "oxy");

    let said = init["instructions"].as_str().unwrap();

    assert!(

        said.contains("Ada"),

        "initialize says who changes are signed as: {said}"

    );

    assert!(

        said.contains("Destructive tools (undo, forced push) are off"),

        "{said}"

    );

    let names: Vec<&str> = r[1]["result"]["tools"]

        .as_array()

        .unwrap()

        .iter()

        .map(|t| t["name"].as_str().unwrap())

        .collect();

    for t in [

        "status",

        "diff",

        "log",

        "show",

        "cat",

        "blame",

        "bookmarks",

        "commit",

        "amend",

        "push",

        "pull",

        "tlog_verify",

    ] {

        assert!(names.contains(&t), "{t} is offered: {names:?}");

    }

    assert!(!names.contains(&"undo"), "undo needs --allow-destructive");

    let before = &r[2]["result"];

    assert_eq!(before["isError"], false, "{before}");

    assert!(

        before["structuredContent"].is_object(),

        "status comes back as JSON: {before}"

    );

    assert!(before["content"][0]["text"]

        .as_str()

        .unwrap()

        .contains("b.txt"));

    assert_eq!(

        r[3]["result"]["isError"], true,

        "a commit names its paths or all: {}",

        r[3]

    );

    assert!(r[3]["result"]["content"][0]["text"]

        .as_str()

        .unwrap()

        .contains("all: true"));

    assert_eq!(r[4]["result"]["isError"], false, "commit by path: {}", r[4]);

    let log = r[5]["result"]["content"][0]["text"].as_str().unwrap();

    assert!(log.contains("Add a"), "{log}");

    assert!(

        r[5]["result"]["structuredContent"].is_object(),

        "a JSON array comes wrapped: {}",

        r[5]

    );

    let after = r[6]["result"]["content"][0]["text"].as_str().unwrap();

    assert!(

        after.contains("b.txt") && !after.contains("a.txt"),

        "only a.txt went in: {after}"

    );

    assert!(

        r[7]["error"]["message"]

            .as_str()

            .unwrap()

            .contains("no tool named undo"),

        "{}",

        r[7]

    );

    assert_eq!(r[8]["result"]["isError"], true);

    assert!(r[8]["result"]["content"][0]["text"]

        .as_str()

        .unwrap()

        .contains("--allow-destructive"));

    assert_eq!(r[9]["result"]["content"][0]["text"], "one\n");

}

#[test]

fn destructive_tools_come_with_the_flag_and_a_bad_directory_is_refused() {

    let tmp = tempfile::tempdir().unwrap();

    let home = tmp.path().join("home");

    std::fs::create_dir_all(&home).unwrap();

    let repo = tmp.path().join("repo");

    assert_eq!(oxy(tmp.path(), &home, &["init", repo.to_str().unwrap()]), 0);

    let r = session(

        &repo,

        &home,

        &["--allow-destructive"],

        &[json!({"jsonrpc": "2.0", "id": 1, "method": "tools/list"})],

    );

    let undo = r[0]["result"]["tools"]

        .as_array()

        .unwrap()

        .iter()

        .find(|t| t["name"] == "undo")

        .cloned();

    assert_eq!(

        undo.expect("undo is offered")["annotations"]["destructiveHint"],

        true

    );

    let out = Command::new(env!("CARGO_BIN_EXE_oxy"))

        .args(["mcp", tmp.path().to_str().unwrap()])

        .env("OXY_HOME", &home)

        .output()

        .unwrap();

    assert!(!out.status.success());

    assert!(String::from_utf8_lossy(&out.stderr).contains("not the root of an Oxygen repository"));

}

- **Added: `oxy mcp`, Oxygen for AI agents (#159).** An MCP server over stdio for a repository: an agent calls typed tools (status, diff, log, show, cat, blame, bookmarks, tags, conflicts, op log, identity, commit, amend, describe, fetch, pull, push, tlog verify) and gets each command's JSON back instead of reading a shell. It signs as the identity its environment configures, so started with an agent home every change is sealed via the agent with nothing to forget per command, and says who in its `initialize` reply. Commits name their paths (or `all: true`); undo and forced pushes are off unless started with `--allow-destructive`. The protocol itself is oxy-core's `mcp` module, for `oh mcp` to reuse. See docs/mcp.md.

An agent can also work through `oxy mcp`, an MCP server for the repository: typed tools instead of a shell, signing as the identity it was started with, and nothing destructive unless you allow it (see [docs/mcp.md](docs/mcp.md)).

| `docs/mcp.md` | `oxy mcp`: the repository as tools for AI agents |

pub mod mcp;

oxy mcp [DIR] [--allow-destructive] serve the repository to an AI agent (MCP, stdio)

**Agents.** `oxy mcp` serves the repository to an AI agent over the Model Context Protocol on stdio (docs/mcp.md): each tool runs one of the commands above with `--json`, in the repository and with the server's environment, so it signs as the identity `OXY_HOME` configures (an agent home seals every change via the agent). `commit` and `amend` take explicit paths or `all: true`; `undo` and a forced push are offered only with `--allow-destructive`.

mod mcp;

    /// Serve this repository to an AI agent over the Model Context Protocol (stdio), signing as this checkout's identity

    Mcp {

        /// The repository's root (default: the current directory)

        dir: Option<PathBuf>,

        /// Also offer tools that can lose work: undo, and a forced push

        #[arg(long)]

        allow_destructive: bool,

    },

        Cmd::Mcp {

            dir,

            allow_destructive,

        } => mcp::serve(dir, allow_destructive),