Lutra/crates/mcp/src/jsonrpc.rs
danny 0e56c22b66 M3.8: MCP server lutra mcp
- crates/mcp (L5): JSON-RPC 2.0 over stdio, dual era: MCP 2026-07-28
  (per-request _meta, server/discover, -32022) and legacy initialize
  (2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05). Tools list_commands,
  execute_command (app.quit only with confirm: true), screenshot (image
  content), read_buffer, get_events (ring of 1000 events via
  events.subscribe); resources lutra://buffer/<path> for open buffers.
  Engine errors become tool errors with the engine code. Lines capped at
  16 MiB, guard around every request, parser and tool args fuzzed.
- lutra mcp [--port PORT] [--no-start] in apps/lutra-cli: connects through
  the rendezvous file and token, or starts Lutra.
- Engine: read-only buffer.list command.
- Tests: protocol units + proptest fuzz, integration over the token
  listener, stdio end to end. Docs: architecture (MCP), G7, ROADMAP.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 20:43:12 +02:00

230 lines
7.5 KiB
Rust

//! JSON-RPC 2.0 messages as MCP uses them on stdio: one message per line,
//! no batches.
//!
//! Every line is untrusted. [`parse`] turns any input into an
//! [`Incoming`] message or a ready error response and never panics; the
//! response helpers always produce one valid line.
use serde_json::{Map, Value, json};
/// Standard JSON-RPC error codes and the MCP codes Lutra emits.
pub mod codes {
/// The line is not valid JSON.
pub const PARSE_ERROR: i64 = -32700;
/// The JSON is not a valid request.
pub const INVALID_REQUEST: i64 = -32600;
/// No such method.
pub const METHOD_NOT_FOUND: i64 = -32601;
/// Bad params, an unknown tool or resource, or missing request
/// metadata.
pub const INVALID_PARAMS: i64 = -32602;
/// The server failed.
pub const INTERNAL_ERROR: i64 = -32603;
/// The request names a protocol version the server does not support
/// (MCP 2026-07-28).
pub const UNSUPPORTED_PROTOCOL_VERSION: i64 = -32022;
}
/// One message read from the client.
#[derive(Debug, Clone, PartialEq)]
pub enum Incoming {
/// A request, which gets exactly one response.
Request {
/// The id: a number or a string.
id: Value,
/// The method name.
method: String,
/// The params object; empty if absent.
params: Map<String, Value>,
},
/// A notification, which gets no response.
Notification {
/// The method name.
method: String,
},
/// A response to a request of ours; Lutra sends none, so it is
/// ignored.
Response,
}
/// Parses one line.
///
/// # Errors
/// The error response line to send back: a parse error for invalid
/// JSON, invalid request for anything that is not a single JSON-RPC 2.0
/// message, invalid params for params that are not an object.
pub fn parse(line: &str) -> Result<Incoming, String> {
let value: Value = serde_json::from_str(line)
.map_err(|e| error(&Value::Null, codes::PARSE_ERROR, &e.to_string(), None))?;
let Value::Object(mut object) = value else {
return Err(error(
&Value::Null,
codes::INVALID_REQUEST,
"a message must be one JSON object (batches are not supported)",
None,
));
};
let id = object.remove("id");
let id_ok = matches!(id, Some(Value::Number(_) | Value::String(_)));
let echo = if id_ok {
id.clone().unwrap_or(Value::Null)
} else {
Value::Null
};
if object.get("jsonrpc").and_then(Value::as_str) != Some("2.0") {
return Err(error(
&echo,
codes::INVALID_REQUEST,
"jsonrpc must be \"2.0\"",
None,
));
}
let method = match object.remove("method") {
Some(Value::String(method)) => method,
Some(_) => {
return Err(error(
&echo,
codes::INVALID_REQUEST,
"method must be a string",
None,
));
}
None if object.contains_key("result") || object.contains_key("error") => {
return Ok(Incoming::Response);
}
None => {
return Err(error(&echo, codes::INVALID_REQUEST, "missing method", None));
}
};
let params = match object.remove("params") {
None | Some(Value::Null) => Map::new(),
Some(Value::Object(params)) => params,
Some(_) => {
if id.is_none() {
return Ok(Incoming::Notification { method });
}
return Err(error(
&echo,
codes::INVALID_PARAMS,
"params must be an object",
None,
));
}
};
match id {
None => Ok(Incoming::Notification { method }),
Some(_) if !id_ok => Err(error(
&Value::Null,
codes::INVALID_REQUEST,
"the id must be a number or a string",
None,
)),
Some(id) => Ok(Incoming::Request { id, method, params }),
}
}
/// A success response line.
pub fn result(id: &Value, result: Value) -> String {
encode(&json!({ "jsonrpc": "2.0", "id": id, "result": result }))
}
/// An error response line, with optional `data`.
pub fn error(id: &Value, code: i64, message: &str, data: Option<Value>) -> String {
let mut error = json!({ "code": code, "message": message });
if let (Some(data), Some(object)) = (data, error.as_object_mut()) {
object.insert("data".into(), data);
}
encode(&json!({ "jsonrpc": "2.0", "id": id, "error": error }))
}
/// Serialises a message as one line. serde_json escapes control
/// characters inside strings, so the line has no embedded newline.
fn encode(message: &Value) -> String {
serde_json::to_string(message).unwrap_or_else(|_| {
String::from(
r#"{"jsonrpc":"2.0","id":null,"error":{"code":-32603,"message":"cannot encode the response"}}"#,
)
})
}
#[cfg(test)]
mod tests {
use super::*;
fn err_code(line: &str) -> (Value, i64) {
let response: Value = serde_json::from_str(&parse(line).unwrap_err()).unwrap();
(
response["id"].clone(),
response["error"]["code"].as_i64().unwrap(),
)
}
#[test]
fn parses_requests_and_notifications() {
let m = parse(r#"{"jsonrpc":"2.0","id":7,"method":"tools/list"}"#).unwrap();
assert_eq!(
m,
Incoming::Request {
id: json!(7),
method: "tools/list".into(),
params: Map::new()
}
);
let m = parse(r#"{"jsonrpc":"2.0","id":"a","method":"x","params":{"k":1}}"#).unwrap();
let Incoming::Request { id, params, .. } = m else {
panic!()
};
assert_eq!(id, json!("a"));
assert_eq!(params["k"], 1);
assert_eq!(
parse(r#"{"jsonrpc":"2.0","method":"notifications/initialized"}"#).unwrap(),
Incoming::Notification {
method: "notifications/initialized".into()
}
);
assert_eq!(
parse(r#"{"jsonrpc":"2.0","id":1,"result":{}}"#).unwrap(),
Incoming::Response
);
}
#[test]
fn rejects_bad_messages() {
assert_eq!(err_code("{"), (Value::Null, codes::PARSE_ERROR));
assert_eq!(err_code("[]"), (Value::Null, codes::INVALID_REQUEST));
assert_eq!(
err_code(r#"{"id":1,"method":"x"}"#),
(json!(1), codes::INVALID_REQUEST)
);
assert_eq!(
err_code(r#"{"jsonrpc":"2.0","id":null,"method":"x"}"#),
(Value::Null, codes::INVALID_REQUEST)
);
assert_eq!(
err_code(r#"{"jsonrpc":"2.0","id":{},"method":"x"}"#),
(Value::Null, codes::INVALID_REQUEST)
);
assert_eq!(
err_code(r#"{"jsonrpc":"2.0","id":2,"method":5}"#),
(json!(2), codes::INVALID_REQUEST)
);
assert_eq!(
err_code(r#"{"jsonrpc":"2.0","id":3,"method":"x","params":[1]}"#),
(json!(3), codes::INVALID_PARAMS)
);
assert_eq!(
err_code(r#"{"jsonrpc":"2.0","id":4}"#),
(json!(4), codes::INVALID_REQUEST)
);
}
#[test]
fn responses_are_single_lines() {
let line = result(&json!(1), json!({"text": "a\nb"}));
assert!(!line.contains('\n'));
let line = error(&json!("x"), codes::INTERNAL_ERROR, "a\nb", Some(json!(1)));
assert!(!line.contains('\n'));
let value: Value = serde_json::from_str(&line).unwrap();
assert_eq!(value["error"]["data"], 1);
}
}