Skip to content

The truly free, open-source, local-first, cross-platform CapCut replacement. Scriptable through a JSON-RPC API & MCP.

feat(mcp): concat-mcp, the Concat API as typed tools for AI agents over MCP stdio (#337)

Jareerdb529b219edb
diff --git a/src/Cargo.lock b/src/Cargo.lock
index 37382617..9ca2a2b6 100644
--- a/src/Cargo.lock
+++ b/src/Cargo.lock
@@ -1138,6 +1138,7 @@ dependencies = [
"concat-effects",
"concat-export",
"concat-host",
+ "concat-mcp",
"concat-media",
"concat-project",
"concat-server",
@@ -1188,6 +1189,7 @@ dependencies = [
"concat-host",
"concat-project",
"png 0.17.16",
+ "schemars",
"serde",
"serde_json",
"tempfile",
@@ -1262,6 +1264,16 @@ dependencies = [
"windows-sys 0.61.2",
]
+[[package]]
+name = "concat-mcp"
+version = "0.2.7"
+dependencies = [
+ "concat-api",
+ "concat-server",
+ "serde_json",
+ "tempfile",
+]
+
[[package]]
name = "concat-media"
version = "0.2.7"
@@ -1278,6 +1290,7 @@ name = "concat-project"
version = "0.2.7"
dependencies = [
"concat-core",
+ "schemars",
"serde",
"serde_json",
"thiserror 2.0.20",
@@ -1303,6 +1316,7 @@ dependencies = [
"getrandom 0.3.4",
"prost",
"protox",
+ "serde",
"serde_json",
"tempfile",
"tokio",
@@ -1910,6 +1924,12 @@ version = "0.8.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "edf234dd1594d6dd434a8fb8cada51ddbbc593e40e4a01556a0b31c62da2775b"
+[[package]]
+name = "dyn-clone"
+version = "1.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555"
+
[[package]]
name = "either"
version = "1.18.0"
@@ -5494,6 +5514,26 @@ dependencies = [
"thiserror 2.0.20",
]
+[[package]]
+name = "ref-cast"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e440fb4e4b4147295338efb76001ab9e4efc0e5839df2c47fc5ac2381d365c3"
+dependencies = [
+ "ref-cast-impl",
+]
+
+[[package]]
+name = "ref-cast-impl"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92ecd8964f8453721699a1ed72037b0db49ce2f5a5138486ee89bed6f67cdf3a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.4",
+]
+
[[package]]
name = "regex"
version = "1.13.1"
@@ -5768,6 +5808,31 @@ dependencies = [
"windows-sys 0.61.2",
]
+[[package]]
+name = "schemars"
+version = "1.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab508826f74a77ca9d5aba6ff19b522583ee3eaf28a19384ff3d0e5835fadf6e"
+dependencies = [
+ "dyn-clone",
+ "ref-cast",
+ "schemars_derive",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "schemars_derive"
+version = "1.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e1c3a92094fa7d61aa124645844facb6b554dfc797136d0f5fd1f890e2bffc69"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "serde_derive_internals",
+ "syn 3.0.4",
+]
+
[[package]]
name = "scoped-tls"
version = "1.0.1"
@@ -5858,6 +5923,17 @@ dependencies = [
"syn 3.0.4",
]
+[[package]]
+name = "serde_derive_internals"
+version = "0.30.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f852137cce035d6a4df67ccce505ff6b3e9fd3a10e3e52b24dc71e650bb1a9bd"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.4",
+]
+
[[package]]
name = "serde_json"
version = "1.0.151"
@@ -6417,7 +6493,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
dependencies = [
"fastrand",
- "getrandom 0.3.4",
+ "getrandom 0.4.3",
"once_cell",
"rustix 1.1.4",
"windows-sys 0.61.2",
diff --git a/src/crates/concat-mcp/Cargo.toml b/src/crates/concat-mcp/Cargo.toml
new file mode 100644
index 00000000..7fbfcb8a
--- /dev/null
+++ b/src/crates/concat-mcp/Cargo.toml
@@ -0,0 +1,22 @@
+[package]
+name = "concat-mcp"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+description = "Concat for AI agents: an MCP server over stdio whose tools are the Concat API's methods, with schemas generated from its request types."
+
+[dependencies]
+# The one source of editing semantics. `schema` gives each request and each
+# edit command its JSON Schema, which is what a tool's arguments are.
+concat-api = { workspace = true, features = ["schema"] }
+# The window's server, reached as a client, and the file that says where
+# it is.
+concat-server.workspace = true
+serde_json.workspace = true
+
+[dev-dependencies]
+tempfile = "3"
+
+[lints]
+workspace = true
diff --git a/src/crates/concat-mcp/src/backend.rs b/src/crates/concat-mcp/src/backend.rs
new file mode 100644
index 00000000..30eac5ae
--- /dev/null
+++ b/src/crates/concat-mcp/src/backend.rs
@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// SPDX-FileCopyrightText: 2026 Jareer and Concat contributors
+
+//! Where a tool's request goes: the window's server, or an API of this
+//! process's own.
+//!
+//! Both take a [`Request`] and give back its result as JSON, so a tool
+//! cannot tell them apart and the meaning of every request stays the
+//! API's. A third backend - the window's own open project, once the
+//! window can be asked to edit it ("live mode", #337) - is one more
+//! implementation of [`Backend`], with nothing above it changing.
+//!
+//! - [`Window`]: a JSON-RPC connection to the server the Automation page
+//! runs. Found through the listing the window writes
+//! (`concat_server::discovery`) or named by `CONCAT_API_ADDRESS` and
+//! `CONCAT_API_TOKEN`. Goes through the window's register of open
+//! projects, so the project on screen cannot be opened here and saved
+//! over, and through its one export slot.
+//! - [`Headless`]: an [`Api`] in this process, writing under the user's
+//! home (or `CONCAT_MCP_ROOTS`). Nothing to start first, and nothing
+//! shared with a window: a project open in the window can be opened here
+//! too, which is why the window's server is preferred when it is there.
+
+use std::net::SocketAddr;
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::time::Duration;
+
+use concat_api::{Api, ApiError, AppDirs, Request, Response, Stopper};
+use concat_server::client::Client;
+use concat_server::discovery;
+use serde_json::Value;
+
+/// How long a connection to the window's server may take to open.
+const PATIENCE: Duration = Duration::from_secs(3);
+
+/// What a tool's request is handed to.
+pub trait Backend: Send {
+ /// Runs one request; its result as the JSON the API replies with.
+ fn call(&mut self, request: Request) -> Result<Value, ApiError>;
+
+ /// What this backend is, for the agent and the log: "window" or
+ /// "headless", and where.
+ fn describe(&self) -> Value;
+
+ /// The session is over: stop what is running, and wait for it.
+ fn finish(&mut self) {}
+}
+
+/// Which backend `concat --mcp` uses.
+#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
+pub enum Mode {
+ /// The window's server when it can be reached, this process otherwise.
+ #[default]
+ Auto,
+ /// The window's server, or an error saying how to turn it on.
+ Window,
+ /// This process, whatever else is running.
+ Headless,
+}
+
+impl Mode {
+ /// The mode a word names: "auto", "window" or "headless".
+ pub fn parse(word: &str) -> Option<Mode> {
+ match word.trim().to_ascii_lowercase().as_str() {
+ "" | "auto" => Some(Mode::Auto),
+ "window" => Some(Mode::Window),
+ "headless" => Some(Mode::Headless),
+ _ => None,
+ }
+ }
+}
+
+/// The backend `mode` asks for, with the reason for whatever was not
+/// chosen written to standard error, where an MCP client shows a server's
+/// log.
+pub fn open(mode: Mode) -> Result<Box<dyn Backend>, String> {
+ match mode {
+ Mode::Headless => Ok(Box::new(Headless::start()?)),
+ Mode::Window => Ok(Box::new(Window::find()?)),
+ Mode::Auto => match Window::find() {
+ Ok(window) => Ok(Box::new(window)),
+ Err(why) => {
+ eprintln!("concat mcp: working headless: {why}");
+ Ok(Box::new(Headless::start()?))
+ }
+ },
+ }
+}
+
+/// Where the window's server is, and its token: the environment's if it
+/// names them, the window's listing otherwise.
+fn locate() -> Result<(SocketAddr, String), String> {
+ let address = std::env::var("CONCAT_API_ADDRESS").ok().filter(|text| !text.is_empty());
+ let token = std::env::var("CONCAT_API_TOKEN").ok().filter(|text| !text.is_empty());
+ if let (Some(address), Some(token)) = (&address, &token) {
+ let address = address
+ .parse()
+ .map_err(|_| format!("CONCAT_API_ADDRESS {address:?} is not an address like 127.0.0.1:7420"))?;
+ return Ok((address, token.clone()));
+ }
+ if address.is_some() != token.is_some() {
+ return Err("CONCAT_API_ADDRESS and CONCAT_API_TOKEN go together".to_owned());
+ }
+ let dirs = AppDirs::locate()?;
+ let path = discovery::path_in(&dirs.config);
+ match discovery::read(&path)? {
+ Some(listing) => Ok((listing.address, listing.token)),
+ None => Err(
+ "the Concat window is not serving the API: open Concat, then Settings > Automation, and turn on Scripts and apps"
+ .to_owned(),
+ ),
+ }
+}
+
+/// The window's server, over a connection that is reopened once if it
+/// drops - the window restarted its server, say.
+pub struct Window {
+ client: Client,
+}
+
+impl Window {
+ /// Connects to the window's server.
+ pub fn find() -> Result<Window, String> {
+ let (address, token) = locate()?;
+ let client = Client::connect(address, &token, PATIENCE).map_err(|error| {
+ format!("{error} (if the window has closed, its listing is stale)")
+ })?;
+ Ok(Window { client })
+ }
+
+ /// Connects to the server at `address` with `token`.
+ pub fn connect(address: SocketAddr, token: &str) -> Result<Window, String> {
+ Ok(Window {
+ client: Client::connect(address, token, PATIENCE)?,
+ })
+ }
+}
+
+impl Backend for Window {
+ fn call(&mut self, request: Request) -> Result<Value, ApiError> {
+ match self.client.call(&request) {
+ Err(error) if error.message.starts_with("the connection to the Concat server") => {
+ let again = Window::find().map_err(|why| {
+ ApiError::failed(format!(
+ "{} - and reconnecting failed: {why}",
+ error.message
+ ))
+ })?;
+ *self = again;
+ self.client.call(&request)
+ }
+ outcome => outcome,
+ }
+ }
+
+ fn describe(&self) -> Value {
+ serde_json::json!({ "mode": "window", "address": self.client.address().to_string() })
+ }
+}
+
+/// An API in this process.
+pub struct Headless {
+ api: Api,
+ stopper: Stopper,
+}
+
+impl Headless {
+ /// An API over this machine's app directories, writing under the
+ /// roots `CONCAT_MCP_ROOTS` names (the platform's path-list syntax),
+ /// or the user's home.
+ pub fn start() -> Result<Headless, String> {
+ Ok(Headless::with_api(Api::new(Arc::new(|_| {}))?))
+ }
+
+ /// An API made by the caller - a test's, over a scratch folder.
+ pub fn with_api(mut api: Api) -> Headless {
+ let roots: Vec<PathBuf> = std::env::var_os("CONCAT_MCP_ROOTS")
+ .map(|roots| std::env::split_paths(&roots).collect())
+ .filter(|roots: &Vec<PathBuf>| !roots.is_empty())
+ .unwrap_or_else(concat_server::home_root);
+ api.add_capability("mcp");
+ if api.roots().is_empty() {
+ api.restrict_writes_to(roots);
+ }
+ let stopper = api.stopper();
+ Headless { api, stopper }
+ }
+}
+
+impl Backend for Headless {
+ fn call(&mut self, request: Request) -> Result<Value, ApiError> {
+ match self.api.dispatch(request) {
+ Response::Result(reply) => serde_json::to_value(&reply)
+ .map_err(|error| ApiError::failed(format!("the reply did not encode: {error}"))),
+ Response::Error(error) => Err(error),
+ }
+ }
+
+ fn describe(&self) -> Value {
+ let roots: Vec<String> = self
+ .api
+ .roots()
+ .iter()
+ .map(|root| root.display().to_string())
+ .collect();
+ serde_json::json!({ "mode": "headless", "writesUnder": roots })
+ }
+
+ fn finish(&mut self) {
+ self.stopper.cancel_all();
+ self.api.finish();
+ }
+}
diff --git a/src/crates/concat-mcp/src/bin/concat-mcp.rs b/src/crates/concat-mcp/src/bin/concat-mcp.rs
new file mode 100644
index 00000000..b4d1d6d2
--- /dev/null
+++ b/src/crates/concat-mcp/src/bin/concat-mcp.rs
@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// SPDX-FileCopyrightText: 2026 Jareer and Concat contributors
+
+//! The MCP server on its own, for development and the end-to-end test.
+//! What ships is the same server inside the app: `concat --mcp`.
+//!
+//! usage: concat-mcp [auto|window|headless] (or CONCAT_MCP_MODE)
+
+use std::process::ExitCode;
+
+fn main() -> ExitCode {
+ let word = std::env::args()
+ .nth(1)
+ .or_else(|| std::env::var("CONCAT_MCP_MODE").ok())
+ .unwrap_or_default();
+ let Some(mode) = concat_mcp::Mode::parse(&word) else {
+ eprintln!("usage: concat-mcp [auto|window|headless]");
+ return ExitCode::from(2);
+ };
+ match concat_mcp::run(mode) {
+ Ok(()) => ExitCode::SUCCESS,
+ Err(error) => {
+ eprintln!("concat mcp: {error}");
+ ExitCode::FAILURE
+ }
+ }
+}
diff --git a/src/crates/concat-mcp/src/lib.rs b/src/crates/concat-mcp/src/lib.rs
new file mode 100644
index 00000000..65ad874c
--- /dev/null
+++ b/src/crates/concat-mcp/src/lib.rs
@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// SPDX-FileCopyrightText: 2026 Jareer and Concat contributors
+
+//! Concat for AI agents: a Model Context Protocol server over standard
+//! input and output, shipped inside the app as `concat --mcp`.
+//!
+//! It is a thin adapter, and deliberately so. Every tool is a
+//! [`concat_api::Request`] - a method of the API, or one of its edit
+//! commands - and its argument schema is cut out of the schema `schemars`
+//! generates from those types ([`schema`]), so an edit means here exactly
+//! what it means in the window, over JSON-RPC and over gRPC, and a field
+//! added to a command reaches agents on the next build with nothing
+//! written for it here. What this crate owns is the protocol
+//! ([`protocol`]), the choice of tools and what an agent is told about
+//! them ([`tools`]), a compact reading of a project for an agent's context
+//! ([`summary`]), and where requests go ([`backend`]): the window's own
+//! server when the Automation page has it on, or an API in this process
+//! when it does not.
+
+pub mod backend;
+pub mod protocol;
+pub mod schema;
+pub mod summary;
+pub mod tools;
+
+pub use backend::{Backend, Headless, Mode, Window};
+
+/// Serves MCP on standard input and output until the client closes its
+/// end, through the backend `mode` picks. Logs to standard error, which
+/// MCP clients show as the server's log; standard output carries nothing
+/// but protocol.
+pub fn run(mode: Mode) -> Result<(), String> {
+ let backend = backend::open(mode)?;
+ eprintln!("concat mcp: serving through {}", backend.describe());
+ protocol::serve(
+ std::io::BufReader::new(std::io::stdin()),
+ std::io::stdout(),
+ backend,
+ );
+ Ok(())
+}
diff --git a/src/crates/concat-mcp/src/protocol.rs b/src/crates/concat-mcp/src/protocol.rs
new file mode 100644
index 00000000..97c783c5
--- /dev/null
+++ b/src/crates/concat-mcp/src/protocol.rs
@@ -0,0 +1,439 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// SPDX-FileCopyrightText: 2026 Jareer and Concat contributors
+
+//! The Model Context Protocol over a pair of streams: newline-delimited
+//! JSON-RPC 2.0, one message a line, as the stdio transport has it.
+//!
+//! Both eras of the protocol are served, since clients of both are in
+//! use. A *legacy* client (protocol 2025-11-25 and earlier) opens with
+//! `initialize`, is answered with the version it asked for when this
+//! server speaks it, and sends `notifications/initialized`. A *modern*
+//! one (2026-07-28) sends no handshake: every request carries its
+//! protocol version in `params._meta`, `server/discover` says what this
+//! server is, and a version this server does not speak is refused with
+//! `UnsupportedProtocolVersion` naming the ones it does. Nothing here is
+//! kept per connection either way - the protocol version of a legacy
+//! client is only remembered to answer `initialize` - so the two can mix.
+//!
+//! Requests run one at a time, in order, on the caller's thread; a reader
+//! thread takes lines in meanwhile, so `ping` is answered and
+//! `notifications/cancelled` is heard while a long call - `export_wait` -
+//! is in progress. A cancelled call sends nothing more, as the protocol
+//! requires.
+
+use std::collections::HashSet;
+use std::io::{BufRead, Write};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::mpsc;
+use std::sync::{Arc, Mutex};
+
+use serde_json::{Map, Value, json};
+
+use crate::backend::Backend;
+use crate::tools::{Context, Toolbox};
+
+/// The newest protocol, served without a handshake.
+pub const MODERN: &str = "2026-07-28";
+/// The handshake-era protocols served, newest first.
+pub const LEGACY: [&str; 4] = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+/// The `_meta` keys a modern request carries.
+const META_VERSION: &str = "io.modelcontextprotocol/protocolVersion";
+const META_CAPABILITIES: &str = "io.modelcontextprotocol/clientCapabilities";
+const META_SERVER: &str = "io.modelcontextprotocol/serverInfo";
+/// The longest line read: a tool call's arguments are small.
+const MAX_LINE: u64 = 16 * 1024 * 1024;
+/// How many cancellations of requests not yet begun are remembered.
+const EARLY_CANCELS: usize = 1024;
+
+/// JSON-RPC's and MCP's error numbers.
+mod code {
+ pub const PARSE: i64 = -32700;
+ pub const INVALID_REQUEST: i64 = -32600;
+ pub const METHOD_NOT_FOUND: i64 = -32601;
+ pub const INVALID_PARAMS: i64 = -32602;
+ pub const INTERNAL: i64 = -32603;
+ pub const UNSUPPORTED_VERSION: i64 = -32022;
+}
+
+/// What the agent is told about this server, once, when it connects.
+const INSTRUCTIONS: &str = "Concat is a video editor; these tools edit its projects. A project is a folder: open one (project_open) or make one (project_create), then pass its folder as `path` to every other tool. Read timeline_read for the ids of lanes (tracks), clips and media. Times and durations are seconds on the timeline; positions within a clip (keyframes) are fractions from 0 to 1; sizes and offsets of titles and pictures are fractions of the frame. Every edit is one undoable step (edit_undo); edit_apply with a batch command makes several into one. Edits live in memory until project_save. To render, export_start then export_wait. preview_frame shows the frame at a time. A refused edit says why in the window's words and changes nothing.";
+
+/// The server's name and version, as `serverInfo`.
+fn server_info() -> Value {
+ json!({
+ "name": "concat",
+ "title": "Concat",
+ "version": env!("CARGO_PKG_VERSION"),
+ })
+}
+
+/// The capabilities this server has: tools, and nothing else.
+fn capabilities() -> Value {
+ json!({ "tools": { "listChanged": false } })
+}
+
+/// Every version this server speaks, newest first.
+fn supported() -> Vec<&'static str> {
+ std::iter::once(MODERN).chain(LEGACY).collect()
+}
+
+/// The one writer of the output stream: a line and a flush, under a lock,
+/// so a progress notification from a tool never lands inside a reply.
+#[derive(Clone)]
+struct Output(Arc<Mutex<Box<dyn Write + Send>>>);
+
+impl Output {
+ fn send(&self, message: &Value) {
+ if let Ok(mut out) = self.0.lock() {
+ // A line, never more: serde_json escapes the newlines a string
+ // holds, and the compact form has none of its own.
+ let _ = writeln!(out, "{message}");
+ let _ = out.flush();
+ }
+ }
+}
+
+/// Which requests were cancelled: the one running, by its flag, and ones
+/// not yet begun, by id.
+#[derive(Default)]
+struct Cancels {
+ running: Option<(String, Arc<AtomicBool>)>,
+ early: HashSet<String>,
+}
+
+/// A request handed from the reader to the worker.
+struct Incoming {
+ id: Value,
+ method: String,
+ params: Value,
+}
+
+/// Serves MCP on `input` and `output` until `input` ends, with `backend`
+/// behind every tool. Returns once the last request has been answered and
+/// the backend has finished.
+pub fn serve(
+ input: impl BufRead + Send + 'static,
+ output: impl Write + Send + 'static,
+ mut backend: Box<dyn Backend>,
+) {
+ let output = Output(Arc::new(Mutex::new(Box::new(output))));
+ let cancels: Arc<Mutex<Cancels>> = Arc::default();
+ let (requests, queue) = mpsc::channel::<Incoming>();
+ let reader = {
+ let output = output.clone();
+ let cancels = Arc::clone(&cancels);
+ std::thread::Builder::new()
+ .name("concat mcp read".to_owned())
+ .spawn(move || read(input, &output, &cancels, &requests))
+ };
+ if reader.is_err() {
+ eprintln!("concat mcp: could not start the reader");
+ return;
+ }
+ let toolbox = Toolbox::new();
+ let mut server = Server {
+ toolbox,
+ output: output.clone(),
+ cancels,
+ };
+ for incoming in queue {
+ server.handle(incoming, backend.as_mut());
+ }
+ backend.finish();
+}
+
+/// Reads lines until the input ends: answers what needs no backend at
+/// once, and queues the rest.
+fn read(
+ input: impl BufRead,
+ output: &Output,
+ cancels: &Mutex<Cancels>,
+ requests: &mpsc::Sender<Incoming>,
+) {
+ let mut input = input;
+ loop {
+ let mut line = String::new();
+ match std::io::Read::take(&mut input, MAX_LINE).read_line(&mut line) {
+ Ok(0) | Err(_) => return,
+ Ok(_) => {}
+ }
+ if line.trim().is_empty() {
+ continue;
+ }
+ let message = match serde_json::from_str::<Value>(&line) {
+ Ok(message) => message,
+ Err(error) => {
+ output.send(&failure(Value::Null, code::PARSE, &format!("not JSON: {error}"), None));
+ continue;
+ }
+ };
+ let Value::Object(mut message) = message else {
+ // A batch, or a bare value: neither is a message since
+ // 2025-06-18.
+ output.send(&failure(
+ Value::Null,
+ code::INVALID_REQUEST,
+ "a message is one JSON-RPC object; batches are not supported",
+ None,
+ ));
+ continue;
+ };
+ let method = message.get("method").and_then(Value::as_str).map(str::to_owned);
+ let id = message.remove("id");
+ let params = message.remove("params").unwrap_or(Value::Null);
+ match (method, id) {
+ // A response from the client: this server sends no requests.
+ (None, _) => {}
+ (Some(method), None) => notification(&method, &params, cancels),
+ (Some(_), Some(id)) if !(id.is_string() || id.is_i64() || id.is_u64()) => {
+ output.send(&failure(
+ Value::Null,
+ code::INVALID_REQUEST,
+ "a request's id is a string or an integer",
+ None,
+ ));
+ }
+ (Some(method), Some(id)) if method == "ping" => {
+ output.send(&success(&id, json!({}), &params));
+ }
+ (Some(method), Some(id)) => {
+ if requests.send(Incoming { id, method, params }).is_err() {
+ return;
+ }
+ }
+ }
+ }
+}
+
+/// A notification: a cancellation is acted on; the rest need nothing.
+fn notification(method: &str, params: &Value, cancels: &Mutex<Cancels>) {
+ if method != "notifications/cancelled" {
+ return;
+ }
+ let Some(id) = params.get("requestId") else {
+ return;
+ };
+ let key = id.to_string();
+ let Ok(mut cancels) = cancels.lock() else {
+ return;
+ };
+ match &cancels.running {
+ Some((running, flag)) if *running == key => flag.store(true, Ordering::Relaxed),
+ _ => {
+ if cancels.early.len() < EARLY_CANCELS {
+ cancels.early.insert(key);
+ }
+ }
+ }
+}
+
+/// A result, with the modern era's additions when the request was modern.
+fn success(id: &Value, mut result: Value, params: &Value) -> Value {
+ if modern_version(params).is_some()
+ && let Some(object) = result.as_object_mut()
+ {
+ object.insert("resultType".to_owned(), json!("complete"));
+ let meta = object
+ .entry("_meta")
+ .or_insert_with(|| Value::Object(Map::new()));
+ if let Some(meta) = meta.as_object_mut() {
+ meta.insert(META_SERVER.to_owned(), server_info());
+ }
+ }
+ json!({ "jsonrpc": "2.0", "id": id, "result": result })
+}
+
+fn failure(id: Value, code: i64, message: &str, data: Option<Value>) -> Value {
+ let mut error = json!({ "code": code, "message": message });
+ if let Some(data) = data {
+ error["data"] = data;
+ }
+ json!({ "jsonrpc": "2.0", "id": id, "error": error })
+}
+
+/// The protocol version a request names in its `_meta`, if it names one.
+fn modern_version(params: &Value) -> Option<&str> {
+ params
+ .get("_meta")
+ .and_then(|meta| meta.get(META_VERSION))
+ .and_then(Value::as_str)
+}
+
+struct Server {
+ toolbox: Toolbox,
+ output: Output,
+ cancels: Arc<Mutex<Cancels>>,
+}
+
+impl Server {
+ fn handle(&mut self, incoming: Incoming, backend: &mut dyn Backend) {
+ let Incoming { id, method, params } = incoming;
+ let key = id.to_string();
+ let flag = Arc::new(AtomicBool::new(false));
+ if let Ok(mut cancels) = self.cancels.lock() {
+ if cancels.early.remove(&key) {
+ return;
+ }
+ cancels.running = Some((key, Arc::clone(&flag)));
+ }
+ let reply = self.answer(&id, &method, &params, backend, &flag);
+ if let Ok(mut cancels) = self.cancels.lock() {
+ cancels.running = None;
+ }
+ if !flag.load(Ordering::Relaxed) {
+ self.output.send(&reply);
+ }
+ }
+
+ fn answer(
+ &mut self,
+ id: &Value,
+ method: &str,
+ params: &Value,
+ backend: &mut dyn Backend,
+ cancelled: &AtomicBool,
+ ) -> Value {
+ // A modern request is checked before anything else: its version,
+ // then the metadata every modern request must carry.
+ if let Some(version) = modern_version(params) {
+ if !supported().contains(&version) {
+ return failure(
+ id.clone(),
+ code::UNSUPPORTED_VERSION,
+ "Unsupported protocol version",
+ Some(json!({ "supported": supported(), "requested": version })),
+ );
+ }
+ if version == MODERN
+ && params
+ .pointer(&format!("/_meta/{}", META_CAPABILITIES.replace('/', "~1")))
+ .is_none()
+ {
+ return failure(
+ id.clone(),
+ code::INVALID_PARAMS,
+ &format!("a {MODERN} request carries {META_CAPABILITIES} in _meta"),
+ None,
+ );
+ }
+ }
+ match method {
+ "initialize" => {
+ let asked = params
+ .get("protocolVersion")
+ .and_then(Value::as_str)
+ .unwrap_or_default();
+ // The version asked for when it is one of the handshake
+ // era's this server speaks; the newest of them otherwise,
+ // which the client may then decline.
+ let version = LEGACY
+ .iter()
+ .find(|known| **known == asked)
+ .copied()
+ .unwrap_or(LEGACY[0]);
+ success(
+ id,
+ json!({
+ "protocolVersion": version,
+ "capabilities": capabilities(),
+ "serverInfo": server_info(),
+ "instructions": INSTRUCTIONS,
+ }),
+ params,
+ )
+ }
+ "server/discover" => {
+ let mut result = json!({
+ "supportedVersions": supported(),
+ "capabilities": capabilities(),
+ "instructions": INSTRUCTIONS,
+ });
+ let mut meta = Map::new();
+ meta.insert(META_SERVER.to_owned(), server_info());
+ result["_meta"] = Value::Object(meta);
+ let mut reply = success(id, result, params);
+ reply["result"]["resultType"] = json!("complete");
+ reply
+ }
+ "tools/list" => success(id, json!({ "tools": self.toolbox.list() }), params),
+ "tools/call" => self.call(id, params, backend, cancelled),
+ _ => failure(
+ id.clone(),
+ code::METHOD_NOT_FOUND,
+ &format!("Method not found: {method}"),
+ None,
+ ),
+ }
+ }
+
+ fn call(
+ &mut self,
+ id: &Value,
+ params: &Value,
+ backend: &mut dyn Backend,
+ cancelled: &AtomicBool,
+ ) -> Value {
+ let Some(name) = params.get("name").and_then(Value::as_str) else {
+ return failure(id.clone(), code::INVALID_PARAMS, "tools/call names a tool", None);
+ };
+ let arguments = params.get("arguments").cloned().unwrap_or(Value::Null);
+ if !(arguments.is_object() || arguments.is_null()) {
+ return failure(
+ id.clone(),
+ code::INVALID_PARAMS,
+ "a tool's arguments are an object",
+ None,
+ );
+ }
+ let token = params
+ .pointer("/_meta/progressToken")
+ .filter(|token| token.is_string() || token.is_i64() || token.is_u64())
+ .cloned();
+ let output = self.output.clone();
+ let report = move |progress: f64, total: f64, message: String| {
+ if let Some(token) = &token {
+ output.send(&json!({
+ "jsonrpc": "2.0",
+ "method": "notifications/progress",
+ "params": {
+ "progressToken": token,
+ "progress": progress,
+ "total": total,
+ "message": message,
+ },
+ }));
+ }
+ };
+ let wants_progress = params.pointer("/_meta/progressToken").is_some();
+ let context = Context {
+ backend,
+ cancelled,
+ progress: wants_progress.then_some(&report as &dyn Fn(f64, f64, String)),
+ };
+ // A panic in a tool is that call's failure, not the server's end.
+ let outcome = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+ self.toolbox.call(name, arguments, context)
+ }));
+ match outcome {
+ Ok(Some(outcome)) => {
+ let mut result = json!({ "content": outcome.content, "isError": outcome.is_error });
+ if let Some(structured) = outcome.structured {
+ result["structuredContent"] = structured;
+ }
+ success(id, result, params)
+ }
+ Ok(None) => failure(
+ id.clone(),
+ code::INVALID_PARAMS,
+ &format!("Unknown tool: {name}"),
+ None,
+ ),
+ Err(_) => failure(
+ id.clone(),
+ code::INTERNAL,
+ &format!("the {name} tool failed inside the server"),
+ None,
+ ),
+ }
+ }
+}
diff --git a/src/crates/concat-mcp/src/schema.rs b/src/crates/concat-mcp/src/schema.rs
new file mode 100644
index 00000000..29d9d7d8
--- /dev/null
+++ b/src/crates/concat-mcp/src/schema.rs
@@ -0,0 +1,475 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// SPDX-FileCopyrightText: 2026 Jareer and Concat contributors
+
+//! Tool input schemas, cut out of the API's own.
+//!
+//! [`concat_api::request_schema`] is the schema of every request, made by
+//! `schemars` from the types: one alternative per method, and every type
+//! a request carries under `$defs`. A tool that is a method takes that
+//! method's alternative with `method` taken out; a tool that is one edit
+//! command takes that command's alternative with `op` taken out and the
+//! project's `path` put in. Nothing here describes a field: a field's
+//! type, range and description are what its Rust type and doc comment
+//! say, so a tool's schema changes when - and only when - the API does.
+//!
+//! References are inlined, because not every MCP client follows `$ref`;
+//! the one that cannot be, the edit command a batch nests inside itself,
+//! stays a reference with its definition carried along under `$defs`.
+
+use std::collections::BTreeSet;
+
+use serde_json::{Map, Value, json};
+
+/// The API's request schema, ready to cut tools out of.
+pub struct Schemas {
+ /// Every type a request carries, by name.
+ defs: Map<String, Value>,
+ /// Each method's alternative.
+ methods: Vec<Value>,
+}
+
+impl Schemas {
+ /// Generates the API's schema and indexes it.
+ pub fn generate() -> Schemas {
+ Schemas::from_root(concat_api::request_schema())
+ }
+
+ fn from_root(mut root: Value) -> Schemas {
+ let defs = match root.get_mut("$defs").map(Value::take) {
+ Some(Value::Object(defs)) => defs,
+ _ => Map::new(),
+ };
+ let methods = alternatives(&root);
+ Schemas { defs, methods }
+ }
+
+ /// The arguments of `method`, as a self-contained schema: the
+ /// method's params, without `method`. `None` for a method the API does
+ /// not have.
+ pub fn method(&self, method: &str) -> Option<Value> {
+ let variant = self
+ .methods
+ .iter()
+ .find(|variant| tag_of(variant, "method") == Some(method))?;
+ Some(self.finish(without(variant.clone(), "method")))
+ }
+
+ /// The arguments of the edit command `op`, plus the project's `path`
+ /// it is applied to. `None` for a command the API does not have.
+ pub fn command(&self, op: &str) -> Option<Value> {
+ let variant = self
+ .commands()
+ .into_iter()
+ .find(|variant| tag_of(variant, "op") == Some(op))?;
+ let mut schema = without(variant, "op");
+ add_required(&mut schema, "path", self.path_property());
+ Some(self.finish(schema))
+ }
+
+ /// One type's schema by its Rust name - a `TextStyle`, say - inlined,
+ /// for a tool that builds its own arguments around it.
+ pub fn def(&self, name: &str) -> Option<Value> {
+ let def = self.defs.get(name)?.clone();
+ let mut kept = BTreeSet::new();
+ let inlined = inline(def, &self.defs, &mut vec![name.to_owned()], &mut kept);
+ // A type that nests itself would need its definitions carried; none
+ // a tool builds around does, and `finish` is for whole schemas.
+ Some(inlined)
+ }
+
+ /// Every edit command's alternative.
+ fn commands(&self) -> Vec<Value> {
+ self.defs
+ .get("Command")
+ .map(alternatives)
+ .unwrap_or_default()
+ }
+
+ /// The `path` every project method takes, as the API describes it.
+ fn path_property(&self) -> Value {
+ self.method("project.get")
+ .and_then(|schema| schema.pointer("/properties/path").cloned())
+ .unwrap_or_else(|| json!({ "type": "string", "description": "The project folder." }))
+ }
+
+ /// Inlines every reference that can be, and carries the definitions of
+ /// those that cannot. The carried ones - the whole edit vocabulary,
+ /// for a tool that takes any command - are kept as the API writes
+ /// them, each type once and referred to, with every description cut
+ /// to its first sentence: complete, and a few thousand tokens of an
+ /// agent's context rather than twenty.
+ fn finish(&self, schema: Value) -> Value {
+ let mut kept = BTreeSet::new();
+ let mut schema = inline(schema, &self.defs, &mut Vec::new(), &mut kept);
+ if schema.get("type").is_none() {
+ schema["type"] = json!("object");
+ }
+ if !kept.is_empty() {
+ let mut defs = Map::new();
+ let mut pending: Vec<String> = kept.into_iter().collect();
+ while let Some(name) = pending.pop() {
+ if defs.contains_key(&name) {
+ continue;
+ }
+ let Some(def) = self.defs.get(&name) else {
+ continue;
+ };
+ let body = compact(def.clone());
+ pending.extend(references(&body).into_iter().filter(|other| !defs.contains_key(other)));
+ defs.insert(name, body);
+ }
+ schema["$defs"] = Value::Object(defs);
+ }
+ schema
+ }
+}
+
+/// Every `#/$defs/` name `schema` refers to.
+fn references(schema: &Value) -> BTreeSet<String> {
+ let mut found = BTreeSet::new();
+ let mut stack = vec![schema];
+ while let Some(value) = stack.pop() {
+ match value {
+ Value::Object(object) => {
+ if let Some(Value::String(reference)) = object.get("$ref")
+ && let Some(name) = reference.strip_prefix("#/$defs/")
+ {
+ found.insert(name.to_owned());
+ }
+ stack.extend(object.values());
+ }
+ Value::Array(items) => stack.extend(items.iter()),
+ _ => {}
+ }
+ }
+ found
+}
+
+/// A definition made short: descriptions to their first sentence, and the
+/// defaults that are whole objects - a style's every field - left out,
+/// the field's own description saying what absent means.
+fn compact(schema: Value) -> Value {
+ match schema {
+ Value::Object(object) => Value::Object(
+ object
+ .into_iter()
+ .filter(|(key, value)| !(key == "default" && (value.is_object() || value.is_array())))
+ .map(|(key, value)| match (key.as_str(), value) {
+ ("description", Value::String(text)) => (key, Value::String(first_sentence(&text))),
+ (_, value) => (key, compact(value)),
+ })
+ .collect(),
+ ),
+ Value::Array(items) => Value::Array(items.into_iter().map(compact).collect()),
+ other => other,
+ }
+}
+
+/// The first sentence of a doc comment, on one line.
+fn first_sentence(text: &str) -> String {
+ let flat = text.split_whitespace().collect::<Vec<_>>().join(" ");
+ match flat.find(". ") {
+ Some(end) => flat[..=end].to_owned(),
+ None => flat,
+ }
+}
+
+/// The alternatives of a tagged enum's schema: `oneOf`, or `anyOf`.
+fn alternatives(schema: &Value) -> Vec<Value> {
+ ["oneOf", "anyOf"]
+ .iter()
+ .find_map(|key| schema.get(*key).and_then(Value::as_array))
+ .cloned()
+ .unwrap_or_default()
+}
+
+/// The constant an alternative's tag property holds.
+fn tag_of<'a>(variant: &'a Value, tag: &str) -> Option<&'a str> {
+ let property = variant.pointer(&format!("/properties/{tag}"))?;
+ property
+ .get("const")
+ .and_then(Value::as_str)
+ .or_else(|| {
+ property
+ .get("enum")
+ .and_then(Value::as_array)
+ .and_then(|values| values.first())
+ .and_then(Value::as_str)
+ })
+}
+
+/// An alternative without its tag: the property and its requirement.
+fn without(mut variant: Value, tag: &str) -> Value {
+ if let Some(properties) = variant.get_mut("properties").and_then(Value::as_object_mut) {
+ properties.remove(tag);
+ }
+ if let Some(required) = variant.get_mut("required").and_then(Value::as_array_mut) {
+ required.retain(|name| name.as_str() != Some(tag));
+ if required.is_empty() {
+ variant.as_object_mut().map(|object| object.remove("required"));
+ }
+ }
+ if variant.get("properties").is_none() {
+ variant["properties"] = json!({});
+ }
+ variant
+}
+
+/// Adds a required property to an object schema.
+fn add_required(schema: &mut Value, name: &str, property: Value) {
+ schema["properties"][name] = property;
+ let mut names = vec![json!(name)];
+ if let Some(Value::Array(rest)) = schema.get_mut("required").map(Value::take) {
+ names.extend(rest.into_iter().filter(|other| other.as_str() != Some(name)));
+ }
+ schema["required"] = Value::Array(names);
+}
+
+/// The types that stay references, defined once under `$defs`: the edit
+/// command, which nests inside itself and is large enough that a tool
+/// taking one should not carry it twice.
+const SHARED: &[&str] = &["Command"];
+
+/// `schema` with every `#/$defs/` reference replaced by its definition,
+/// except one to a [`SHARED`] type or inside its own definition - which
+/// stays, and is noted in `kept` - and with the `$schema` and `$defs` of a
+/// root dropped.
+fn inline(
+ schema: Value,
+ defs: &Map<String, Value>,
+ stack: &mut Vec<String>,
+ kept: &mut BTreeSet<String>,
+) -> Value {
+ match schema {
+ Value::Object(mut object) => {
+ object.remove("$schema");
+ object.remove("$defs");
+ if let Some(Value::String(reference)) = object.get("$ref")
+ && let Some(name) = reference.strip_prefix("#/$defs/")
+ {
+ let name = name.to_owned();
+ if SHARED.contains(&name.as_str()) || stack.contains(&name) || !defs.contains_key(&name) {
+ kept.insert(name);
+ return Value::Object(object);
+ }
+ object.remove("$ref");
+ stack.push(name.clone());
+ let body = inline(defs[&name].clone(), defs, stack, kept);
+ stack.pop();
+ // What sat beside the reference - a field's own
+ // description, its default - wins over the type's.
+ let mut merged = match body {
+ Value::Object(body) => body,
+ other => return other,
+ };
+ for (key, value) in object {
+ let value = inline(value, defs, stack, kept);
+ merged.insert(key, value);
+ }
+ return Value::Object(merged);
+ }
+ Value::Object(
+ object
+ .into_iter()
+ .map(|(key, value)| (key, inline(value, defs, stack, kept)))
+ .collect(),
+ )
+ }
+ Value::Array(items) => Value::Array(
+ items
+ .into_iter()
+ .map(|item| inline(item, defs, stack, kept))
+ .collect(),
+ ),
+ other => other,
+ }
+}
+
+/// A small JSON Schema checker: enough of the 2020-12 vocabulary that
+/// schemars writes - types, properties, required, items, enums and
+/// constants, the three combinators, local references - to test that what
+/// a tool's schema accepts is what its Rust type reads, and back.
+#[cfg(test)]
+pub(crate) fn check(schema: &Value, value: &Value, root: &Value, at: &str) -> Result<(), String> {
+ let fail = |why: String| Err(format!("{at}: {why}"));
+ let Some(object) = schema.as_object() else {
+ return match schema {
+ Value::Bool(false) => fail("nothing is allowed here".to_owned()),
+ _ => Ok(()),
+ };
+ };
+ if let Some(Value::String(reference)) = object.get("$ref") {
+ let name = reference.trim_start_matches("#/$defs/");
+ let Some(def) = root.pointer(&format!("/$defs/{name}")) else {
+ return fail(format!("no definition {name}"));
+ };
+ check(def, value, root, at)?;
+ }
+ if let Some(kind) = object.get("type") {
+ let kinds: Vec<&str> = match kind {
+ Value::String(kind) => vec![kind.as_str()],
+ Value::Array(kinds) => kinds.iter().filter_map(Value::as_str).collect(),
+ _ => Vec::new(),
+ };
+ let fits = |kind: &str| match kind {
+ "object" => value.is_object(),
+ "array" => value.is_array(),
+ "string" => value.is_string(),
+ "boolean" => value.is_boolean(),
+ "null" => value.is_null(),
+ "number" => value.is_number(),
+ "integer" => value.as_i64().is_some() || value.as_u64().is_some(),
+ _ => true,
+ };
+ if !kinds.iter().any(|kind| fits(kind)) {
+ return fail(format!("{value} is not {kinds:?}"));
+ }
+ }
+ if let Some(constant) = object.get("const")
+ && constant != value
+ {
+ return fail(format!("{value} is not {constant}"));
+ }
+ if let Some(Value::Array(allowed)) = object.get("enum")
+ && !allowed.contains(value)
+ {
+ return fail(format!("{value} is not one of {allowed:?}"));
+ }
+ if let Some(number) = value.as_f64() {
+ if let Some(minimum) = object.get("minimum").and_then(Value::as_f64)
+ && number < minimum
+ {
+ return fail(format!("{number} is under {minimum}"));
+ }
+ if let Some(maximum) = object.get("maximum").and_then(Value::as_f64)
+ && number > maximum
+ {
+ return fail(format!("{number} is over {maximum}"));
+ }
+ }
+ if let Value::Object(fields) = value {
+ let properties = object.get("properties").and_then(Value::as_object);
+ if let Some(Value::Array(required)) = object.get("required") {
+ for name in required.iter().filter_map(Value::as_str) {
+ if !fields.contains_key(name) {
+ return fail(format!("{name} is required"));
+ }
+ }
+ }
+ for (name, field) in fields {
+ match properties.and_then(|properties| properties.get(name)) {
+ Some(property) => check(property, field, root, &format!("{at}.{name}"))?,
+ None => {
+ if let Some(extra) = object.get("additionalProperties") {
+ check(extra, field, root, &format!("{at}.{name}"))?;
+ } else if properties.is_some()
+ && object.get("oneOf").is_none()
+ && object.get("anyOf").is_none()
+ && object.get("allOf").is_none()
+ {
+ return fail(format!("{name} is not a field the schema knows"));
+ }
+ }
+ }
+ }
+ }
+ if let (Value::Array(items), Some(item)) = (value, object.get("items")) {
+ for (index, element) in items.iter().enumerate() {
+ check(item, element, root, &format!("{at}[{index}]"))?;
+ }
+ }
+ if let Some(Value::Array(all)) = object.get("allOf") {
+ for part in all {
+ check(part, value, root, at)?;
+ }
+ }
+ for key in ["oneOf", "anyOf"] {
+ if let Some(Value::Array(choices)) = object.get(key) {
+ let fitting = choices
+ .iter()
+ .filter(|choice| check(choice, value, root, at).is_ok())
+ .count();
+ let ok = if key == "oneOf" { fitting == 1 } else { fitting >= 1 };
+ if !ok {
+ let why: Vec<String> = choices
+ .iter()
+ .filter_map(|choice| check(choice, value, root, at).err())
+ .take(3)
+ .collect();
+ return fail(format!("{fitting} alternatives of {key} fit: {why:?}"));
+ }
+ }
+ }
+ Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn a_method_is_cut_out_without_its_tag_and_with_its_references_inlined() {
+ let schemas = Schemas::generate();
+ let open = schemas.method("project.open").expect("a method");
+ assert_eq!(open["type"], "object");
+ assert!(open["properties"].get("method").is_none());
+ assert_eq!(open["required"], json!(["path"]));
+ assert!(schemas.method("project.nope").is_none());
+ let set_video = schemas.method("project.setVideo").expect("a method");
+ assert!(
+ set_video.pointer("/properties/video/properties/width").is_some(),
+ "VideoSettings inlined: {set_video}"
+ );
+ assert!(!set_video.to_string().contains("$ref"));
+ }
+
+ #[test]
+ fn a_command_carries_the_project_path() {
+ let schemas = Schemas::generate();
+ let trim = schemas.command("trimClip").expect("a command");
+ assert_eq!(trim.pointer("/properties/path/type"), Some(&json!("string")));
+ assert!(trim["properties"].get("op").is_none());
+ let required = trim["required"].as_array().expect("required");
+ assert!(required.contains(&json!("path")) && required.contains(&json!("clipId")));
+ assert!(schemas.command("doTheThing").is_none());
+ }
+
+ #[test]
+ fn the_tool_list_fits_an_agents_context() {
+ // Every tool's schema sits in the agent's context for the whole
+ // session. Measured at about 100 KB in all, 41 KB of it the whole
+ // edit vocabulary under edit_apply; a type that grows past these
+ // is worth a look before it ships.
+ let toolbox = crate::tools::Toolbox::new();
+ let sizes: Vec<(String, usize)> = toolbox
+ .list()
+ .iter()
+ .map(|tool| (tool["name"].to_string(), tool.to_string().len()))
+ .collect();
+ let total: usize = sizes.iter().map(|(_, size)| size).sum();
+ assert!(total < 160_000, "{total}: {sizes:?}");
+ for (name, size) in &sizes {
+ assert!(*size < 64_000, "{name}: {size}");
+ }
+ }
+
+ #[test]
+ fn a_batch_keeps_the_one_reference_it_must_and_carries_its_definition() {
+ let schemas = Schemas::generate();
+ let batch = schemas.command("batch").expect("a command");
+ assert_eq!(
+ batch.pointer("/properties/commands/items/$ref"),
+ Some(&json!("#/$defs/Command"))
+ );
+ let command = batch.pointer("/$defs/Command").expect("carried");
+ assert!(command.get("oneOf").or_else(|| command.get("anyOf")).is_some());
+ let sample = json!({
+ "path": "/p",
+ "commands": [
+ { "op": "addTrack" },
+ { "op": "batch", "commands": [{ "op": "addTimeline" }] }
+ ]
+ });
+ check(&batch, &sample, &batch, "batch").expect("fits");
+ }
+}
diff --git a/src/crates/concat-mcp/src/summary.rs b/src/crates/concat-mcp/src/summary.rs
new file mode 100644
index 00000000..c76aa9ec
--- /dev/null
+++ b/src/crates/concat-mcp/src/summary.rs
@@ -0,0 +1,242 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// SPDX-FileCopyrightText: 2026 Jareer and Concat contributors
+
+//! A project as an agent reads it: the active timeline's lanes and clips
+//! in time order, the bin, and what the last edit made - a page of JSON
+//! where the editor's view is the whole document.
+//!
+//! Read from the view's JSON, not its Rust types, so it reads a view from
+//! the window's server exactly as one from this process. It decides
+//! nothing about the edit; it only leaves out what an agent rarely needs:
+//! a field at its default, a title's whole style, which `project_get`
+//! still returns in full.
+
+use serde_json::{Map, Value, json};
+
+/// The summary of an editor view (`project.get`'s reply, and every
+/// edit's).
+pub fn view(view: &Value) -> Value {
+ let project = &view["project"];
+ let settings = &view["settings"];
+ let active = project["activeTimelineId"].as_str().unwrap_or_default();
+ let timelines = project["timelines"].as_array().cloned().unwrap_or_default();
+ let timeline = timelines
+ .iter()
+ .find(|timeline| timeline["id"].as_str() == Some(active))
+ .or_else(|| timelines.first())
+ .cloned()
+ .unwrap_or(Value::Null);
+
+ let mut clips: Vec<&Value> = timeline["clips"]
+ .as_array()
+ .map(|clips| clips.iter().collect())
+ .unwrap_or_default();
+ clips.sort_by(|left, right| {
+ let start = |clip: &Value| clip["start"].as_f64().unwrap_or(0.0);
+ start(left).total_cmp(&start(right))
+ });
+ let length = clips
+ .iter()
+ .map(|clip| clip["start"].as_f64().unwrap_or(0.0) + clip["duration"].as_f64().unwrap_or(0.0))
+ .fold(0.0_f64, f64::max);
+
+ let rate_num = settings["rateNum"].as_f64().unwrap_or(0.0);
+ let rate_den = settings["rateDen"].as_f64().unwrap_or(1.0).max(1.0);
+ let mut summary = json!({
+ "project": {
+ "name": settings["name"],
+ "width": settings["width"],
+ "height": settings["height"],
+ "fps": round(rate_num / rate_den, 3),
+ },
+ "canUndo": view["canUndo"],
+ "canRedo": view["canRedo"],
+ "timeline": {
+ "id": timeline["id"],
+ "name": timeline["name"],
+ "duration": round(length, 3),
+ "tracks": timeline["tracks"]
+ .as_array()
+ .map(|tracks| tracks.iter().enumerate().map(|(index, track)| track_of(index, track)).collect::<Vec<_>>())
+ .unwrap_or_default(),
+ "clips": clips.into_iter().map(clip_of).collect::<Vec<_>>(),
+ },
+ "media": project["media"]
+ .as_array()
+ .map(|media| media.iter().map(media_of).collect::<Vec<_>>())
+ .unwrap_or_default(),
+ });
+ if timelines.len() > 1 {
+ summary["timelines"] = timelines
+ .iter()
+ .map(|timeline| json!({ "id": timeline["id"], "name": timeline["name"] }))
+ .collect();
+ }
+ if let Some(created) = view.get("createdId").filter(|id| !id.is_null()) {
+ summary["createdId"] = created.clone();
+ }
+ summary
+}
+
+fn track_of(index: usize, track: &Value) -> Value {
+ let mut out = json!({ "id": track["id"], "index": index });
+ if track["visible"] == json!(false) {
+ out["hidden"] = json!(true);
+ }
+ if track["muted"] == json!(true) {
+ out["muted"] = json!(true);
+ }
+ out
+}
+
+/// One clip: where it is, what it is, and whatever about it is not the
+/// default.
+fn clip_of(clip: &Value) -> Value {
+ let start = clip["start"].as_f64().unwrap_or(0.0);
+ let duration = clip["duration"].as_f64().unwrap_or(0.0);
+ let mut out = Map::new();
+ out.insert("id".into(), clip["id"].clone());
+ out.insert("kind".into(), clip["kind"].clone());
+ out.insert("track".into(), clip["trackId"].clone());
+ out.insert("start".into(), json!(round(start, 4)));
+ out.insert("duration".into(), json!(round(duration, 4)));
+ out.insert("end".into(), json!(round(start + duration, 4)));
+ if let Some(name) = clip["name"].as_str().filter(|name| !name.is_empty()) {
+ out.insert("name".into(), json!(name));
+ }
+ if let Some(media) = clip["mediaId"].as_str().filter(|media| !media.is_empty()) {
+ out.insert("media".into(), json!(media));
+ out.insert("sourceStart".into(), json!(round(clip["sourceStart"].as_f64().unwrap_or(0.0), 4)));
+ }
+ if let Some(text) = clip.pointer("/text/content") {
+ out.insert("text".into(), text.clone());
+ }
+ if let Some(shape) = clip.pointer("/shape/kind") {
+ out.insert("shape".into(), shape.clone());
+ }
+ for (key, default) in [
+ ("speed", 1.0),
+ ("volume", 1.0),
+ ("opacity", 1.0),
+ ("scale", 1.0),
+ ("offsetX", 0.0),
+ ("offsetY", 0.0),
+ ("rotation", 0.0),
+ ("fadeIn", 0.0),
+ ("fadeOut", 0.0),
+ ] {
+ if let Some(value) = clip[key].as_f64()
+ && (value - default).abs() > 1e-9
+ {
+ out.insert(key.into(), json!(round(value, 4)));
+ }
+ }
+ if clip["muted"] == json!(true) {
+ out.insert("muted".into(), json!(true));
+ }
+ for (key, name) in [("videoEffects", "effects"), ("filters", "audioFilters")] {
+ let ids: Vec<Value> = clip[key]
+ .as_array()
+ .map(|chain| chain.iter().map(|link| link["id"].clone()).collect())
+ .unwrap_or_default();
+ if !ids.is_empty() {
+ out.insert(name.into(), Value::Array(ids));
+ }
+ }
+ if let Some(transition) = clip.get("transitionIn").filter(|value| !value.is_null()) {
+ out.insert("transitionIn".into(), transition.clone());
+ }
+ if let Some(keys) = clip["keys"].as_array().filter(|keys| !keys.is_empty()) {
+ let mut properties: Vec<Value> = Vec::new();
+ for key in keys {
+ if !properties.contains(&key["property"]) {
+ properties.push(key["property"].clone());
+ }
+ }
+ out.insert("keyframed".into(), Value::Array(properties));
+ }
+ if clip.get("cutout").is_some_and(|cutout| !cutout.is_null()) {
+ out.insert("cutout".into(), json!(true));
+ }
+ Value::Object(out)
+}
+
+fn media_of(item: &Value) -> Value {
+ let mut out = json!({
+ "id": item["id"],
+ "name": item["name"],
+ "kind": item["kind"],
+ "path": item["path"],
+ });
+ if let Some(duration) = item["duration"].as_f64() {
+ out["duration"] = json!(round(duration, 3));
+ }
+ if item["width"].is_number() {
+ out["width"] = item["width"].clone();
+ out["height"] = item["height"].clone();
+ }
+ if item["hasAudio"] == json!(true) {
+ out["hasAudio"] = json!(true);
+ }
+ if item["placeholder"] == json!(true) {
+ out["placeholder"] = json!(true);
+ }
+ out
+}
+
+fn round(value: f64, places: i32) -> f64 {
+ let scale = 10f64.powi(places);
+ (value * scale).round() / scale
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn a_view_reads_as_the_active_timeline_in_time_order() {
+ let view = json!({
+ "project": {
+ "media": [{ "id": "m1", "name": "a.mp4", "kind": "video", "path": "/a.mp4",
+ "duration": 12.5, "width": 1920, "height": 1080, "hasAudio": true }],
+ "activeTimelineId": "tl2",
+ "timelines": [
+ { "id": "tl1", "name": "One", "tracks": [], "clips": [] },
+ { "id": "tl2", "name": "Two",
+ "tracks": [{ "id": "t1", "visible": true, "muted": false },
+ { "id": "t2", "visible": false, "muted": true }],
+ "clips": [
+ { "id": "c2", "kind": "text", "trackId": "t1", "start": 4.0, "duration": 2.0,
+ "name": "Hi", "mediaId": "", "volume": 1.0, "opacity": 0.5, "speed": 1.0,
+ "text": { "content": "Hi" } },
+ { "id": "c1", "kind": "video", "trackId": "t2", "start": 0.0, "duration": 5.0,
+ "mediaId": "m1", "sourceStart": 1.0, "volume": 1.0, "opacity": 1.0, "speed": 2.0,
+ "videoEffects": [{ "id": "concat.warm" }],
+ "keys": [{ "property": "scale" }, { "property": "scale" }] }
+ ] }
+ ]
+ },
+ "canUndo": true, "canRedo": false,
+ "settings": { "name": "P", "width": 1920, "height": 1080, "rateNum": 30000, "rateDen": 1001 },
+ "createdId": "c2"
+ });
+ let summary = super::view(&view);
+ assert_eq!(summary["project"]["fps"], 29.97);
+ assert_eq!(summary["timeline"]["id"], "tl2");
+ assert_eq!(summary["timeline"]["duration"], 6.0);
+ assert_eq!(summary["createdId"], "c2");
+ assert_eq!(summary["timelines"].as_array().map(Vec::len), Some(2));
+ let clips = summary["timeline"]["clips"].as_array().expect("clips");
+ assert_eq!(clips[0]["id"], "c1", "time order");
+ assert_eq!(clips[0]["speed"], 2.0);
+ assert_eq!(clips[0]["effects"], json!(["concat.warm"]));
+ assert_eq!(clips[0]["keyframed"], json!(["scale"]));
+ assert!(clips[0].get("volume").is_none(), "a default is left out");
+ assert_eq!(clips[1]["text"], "Hi");
+ assert_eq!(clips[1]["opacity"], 0.5);
+ assert!(clips[1].get("media").is_none());
+ let tracks = summary["timeline"]["tracks"].as_array().expect("tracks");
+ assert_eq!(tracks[1], json!({ "id": "t2", "index": 1, "hidden": true, "muted": true }));
+ assert_eq!(summary["media"][0]["hasAudio"], true);
+ }
+}
diff --git a/src/crates/concat-mcp/src/tools.rs b/src/crates/concat-mcp/src/tools.rs
new file mode 100644
index 00000000..deadc103
--- /dev/null
+++ b/src/crates/concat-mcp/src/tools.rs
@@ -0,0 +1,925 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// SPDX-FileCopyrightText: 2026 Jareer and Concat contributors
+
+//! The tools: which API method or edit command each one is, and what an
+//! agent is told about it.
+//!
+//! Every tool is a [`concat_api::Request`] in the end. Most are one method
+//! or one edit command as it is, their arguments that request's fields and
+//! their schema cut from the API's ([`crate::schema`]); a handful compose,
+//! as captions are a batch of titles and waiting on an export is asking its
+//! status until it ends, and say so. None decides what an edit means.
+//!
+//! Names are stable: an agent's instructions and a user's allow-list name
+//! them. A tool is added, never renamed; a removed one would be a version
+//! bump of this server.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::{Duration, Instant};
+
+use concat_api::{ApiError, ErrorCode, Request};
+use serde_json::{Map, Value, json};
+
+use crate::backend::Backend;
+use crate::schema::Schemas;
+use crate::summary;
+
+/// The longest preview side handed back when the agent names no size: a
+/// frame an agent can look at without a 4K PNG in its context.
+const PREVIEW_SIDE: f64 = 1280.0;
+/// How often a wait asks how an export stands.
+const POLL: Duration = Duration::from_millis(250);
+/// How long `export_wait` waits when told nothing, and at most.
+const WAIT_DEFAULT: f64 = 60.0;
+const WAIT_LONGEST: f64 = 600.0;
+/// The stages of an export in order, for one progress figure across them.
+const STAGES: [&str; 4] = ["cutout", "video", "audio", "mux"];
+
+/// What a tool does with its arguments.
+#[derive(Clone, Copy, Debug)]
+pub enum Action {
+ /// An API method, its arguments the method's params.
+ Method {
+ /// The method's name, `area.verb`.
+ method: &'static str,
+ /// What the reply is shown as.
+ reply: Reply,
+ },
+ /// One edit command on a project: `edit.apply` with the command's
+ /// fields as arguments, beside the project's `path`.
+ Command {
+ /// The command's `op`.
+ op: &'static str,
+ },
+ /// `version`, with how this server reaches Concat added.
+ Version,
+ /// `project.get`, summarised.
+ TimelineRead,
+ /// Titles at the given times, as one batch.
+ Captions,
+ /// `export.status` until the job ends or the time is up.
+ ExportWait,
+ /// `preview.frame`, as an image.
+ PreviewFrame,
+}
+
+/// How a reply is shown to the agent.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Reply {
+ /// As the API sent it.
+ Raw,
+ /// An editor view, as [`summary::view`].
+ Summary,
+}
+
+/// One tool.
+#[derive(Clone, Debug)]
+pub struct Tool {
+ /// The name an agent calls it by.
+ pub name: &'static str,
+ /// The name a person is shown.
+ pub title: &'static str,
+ /// What the agent is told: what it does, its units, its ranges.
+ pub description: &'static str,
+ /// Changes nothing.
+ pub read_only: bool,
+ /// May remove or overwrite something.
+ pub destructive: bool,
+ /// Calling it twice is calling it once.
+ pub idempotent: bool,
+ /// What it does.
+ pub action: Action,
+}
+
+const fn method(
+ name: &'static str,
+ title: &'static str,
+ description: &'static str,
+ method: &'static str,
+ reply: Reply,
+) -> Tool {
+ Tool {
+ name,
+ title,
+ description,
+ read_only: false,
+ destructive: false,
+ idempotent: false,
+ action: Action::Method { method, reply },
+ }
+}
+
+const fn command(
+ name: &'static str,
+ title: &'static str,
+ description: &'static str,
+ op: &'static str,
+) -> Tool {
+ Tool {
+ name,
+ title,
+ description,
+ read_only: false,
+ destructive: false,
+ idempotent: false,
+ action: Action::Command { op },
+ }
+}
+
+impl Tool {
+ const fn reading(mut self) -> Tool {
+ self.read_only = true;
+ self.idempotent = true;
+ self
+ }
+
+ const fn destroying(mut self) -> Tool {
+ self.destructive = true;
+ self
+ }
+
+ const fn idempotent(mut self) -> Tool {
+ self.idempotent = true;
+ self
+ }
+}
+
+/// Every tool, in the order `tools/list` gives them.
+pub fn catalogue() -> Vec<Tool> {
+ use Reply::{Raw, Summary};
+ vec![
+ Tool {
+ name: "concat_version",
+ title: "Concat version",
+ description: "What this Concat speaks: the API version, the build, its capabilities, and how this MCP server reaches it (`mcp.mode`: \"window\" when it goes through the open Concat window's server, \"headless\" when it runs the editor engine itself). Call it first if unsure what is available.",
+ read_only: true,
+ destructive: false,
+ idempotent: true,
+ action: Action::Version,
+ },
+ method(
+ "project_list",
+ "Recent projects",
+ "The projects this machine opened most recently, newest first: each one's folder `path`, name, frame size and rate. A project is a folder; every other project tool names it by that `path`.",
+ "project.list",
+ Raw,
+ )
+ .reading(),
+ method(
+ "project_create",
+ "Create a project",
+ "Creates a project folder named `name` inside the existing directory `location`, and opens it. `video` sets the frame and rate (1920×1080 at 30 fps when absent). Returns the project summary; its folder is `location/name`, which is the `path` later tools take. Refuses a folder that already holds a project.",
+ "project.create",
+ Summary,
+ ),
+ method(
+ "project_open",
+ "Open a project",
+ "Opens a project folder so it can be read and edited. Opening one already open returns it as it stands, unsaved edits included. Refused when the Concat window has that project open. Returns the project summary.",
+ "project.open",
+ Summary,
+ )
+ .idempotent(),
+ method(
+ "project_save",
+ "Save a project",
+ "Writes an open project's document to its folder; edits are only in memory until this is called. `name` renames the project as it saves.",
+ "project.save",
+ Raw,
+ )
+ .idempotent(),
+ method(
+ "project_close",
+ "Close a project",
+ "Closes an open project. With `save: true` it is saved first; otherwise unsaved edits are dropped.",
+ "project.close",
+ Raw,
+ )
+ .destroying(),
+ Tool {
+ name: "timeline_read",
+ title: "Read the timeline",
+ description: "An open project's active timeline as a compact summary: frame size and fps, the lanes (`tracks`, top to bottom, with their ids), every clip in time order with its id, kind, track, start, duration and end in seconds and whatever is not at its default (speed, volume, opacity, transform, effects, keyframed properties, text), and the media bin with each item's id. Read this to learn the ids other tools need.",
+ read_only: true,
+ destructive: false,
+ idempotent: true,
+ action: Action::TimelineRead,
+ },
+ method(
+ "project_get",
+ "Get the whole project",
+ "An open project's full state: every timeline, clip field, media item and setting, as the editor holds it. Large; `timeline_read` is usually enough.",
+ "project.get",
+ Raw,
+ )
+ .reading(),
+ method(
+ "project_set_video",
+ "Set frame size and rate",
+ "Sets the active timeline's frame (width, height in pixels) and rate (rateNum/rateDen frames a second, e.g. 30000/1001 for 29.97) as one undoable edit.",
+ "project.setVideo",
+ Summary,
+ ),
+ method(
+ "media_probe",
+ "Probe a media file",
+ "Reports what is inside a video, audio or image file - duration in seconds, streams, frame size and rate, codecs - without changing any project.",
+ "media.probe",
+ Raw,
+ )
+ .reading(),
+ method(
+ "media_import",
+ "Import media",
+ "Adds a file (an absolute path) to an open project's media bin, as dropping it on the window does. The new item's id is the summary's `createdId`; place it on the timeline with `clip_add`. Importing a path already in the bin changes nothing.",
+ "media.import",
+ Summary,
+ )
+ .idempotent(),
+ method(
+ "edit_apply",
+ "Apply an edit",
+ "Applies any one edit command to an open project, as one undoable step. `command` is an object tagged by `op` - every edit the window can make is one, with the same limits and refusals; the typed tools below are the common ones. `{\"op\": \"batch\", \"commands\": [...]}` applies several commands as one atomic, undoable step: all land or none does, and `createdId` is the last id minted inside. A refusal comes back as the sentence the window would show, with nothing changed. Returns the project summary; a command that creates something puts its id in `createdId`.",
+ "edit.apply",
+ Summary,
+ ),
+ method(
+ "edit_undo",
+ "Undo",
+ "Steps an open project's history back one edit (a batch is one edit).",
+ "edit.undo",
+ Summary,
+ ),
+ method(
+ "edit_redo",
+ "Redo",
+ "Steps an open project's history forward one edit.",
+ "edit.redo",
+ Summary,
+ ),
+ command(
+ "clip_add",
+ "Place a clip",
+ "Places a clip of a media item (`mediaId`, from the bin) on a lane (`trackId`, from `timeline_read`) starting at `start` seconds. Its length is the media's (5 s for a still). `ripple: true` pushes later clips on that lane right instead of overlapping them. The new clip's id is `createdId`.",
+ "addClip",
+ ),
+ command(
+ "clip_trim",
+ "Trim a clip",
+ "Moves one edge of a clip by `delta` seconds of timeline: `edge` \"start\" with a positive delta shortens it from the head (the picture does not slide), \"end\" with a positive delta lengthens it. A clip is never shorter than 1/60 s or longer than its media allows. `ripple: true` closes or opens the gap behind it on that lane.",
+ "trimClip",
+ ),
+ command(
+ "clips_split",
+ "Split clips",
+ "Cuts each named clip in two at `time` seconds on the timeline. The first part keeps the id; the second gets a new one. Clips the time does not fall inside are left alone.",
+ "splitClips",
+ ),
+ command(
+ "clips_move",
+ "Move clips",
+ "Moves clips in one undoable step: each to a new `start` (seconds, at least 0) and `trackId`. Unknown ids are skipped.",
+ "moveClips",
+ ),
+ command(
+ "clips_remove",
+ "Delete clips",
+ "Deletes clips from the active timeline. `ripple: true` closes the gaps they leave on their lanes; false leaves the gaps.",
+ "removeClips",
+ )
+ .destroying(),
+ command(
+ "clip_update",
+ "Change a clip",
+ "Changes only the fields given in `patch`: volume (gain, 1 is unchanged, may exceed 1), fadeIn/fadeOut (seconds), opacity (0-1), muted, flipH/flipV, blend, crop (fractions off each edge, null to remove), videoEffects and filters (the whole chain: a list of {id, params}; ids from `effects_list`), transitionIn ({id, duration} on the cut into the clip, null to remove), text (a title's style, null to remove) and audioStream.",
+ "updateClip",
+ ),
+ command(
+ "clip_transform",
+ "Place, scale or rotate a clip",
+ "Sets a picture's placement; only the fields given change. scale 0.05-8 (1 fits the frame), offsetX/offsetY as fractions of the frame's width/height from the centre (positive is right/down, within ±3), rotation in degrees, stretchX/stretchY 0.1-10.",
+ "setClipTransform",
+ ),
+ command(
+ "clip_speed",
+ "Change a clip's speed",
+ "Plays a clip faster or slower: `speed` from 0.0625 to 16 (2 is double speed). The same stretch of source is kept, so the clip's length on the timeline changes.",
+ "setClipSpeed",
+ ),
+ command(
+ "title_add",
+ "Add a title",
+ "Places a title (text over the picture) at `start` seconds for `duration` seconds (4 s when absent). `style` sets the words and look - `content`, `fontFamily`, `fontSize` (fraction of frame height, 0.09 by default), `fontWeight` (100-900), `color` (\"#rrggbb\"), `align`, `background`, `strokeWidth`... - and needs only the fields that differ from the default. `offsetY` places it vertically as a fraction of frame height from the centre (positive is down). With no `trackId` and `above: true` it lands on a lane above the picture. The new clip's id is `createdId`.",
+ "addTextClip",
+ ),
+ Tool {
+ name: "captions_add",
+ title: "Add captions",
+ description: "Places a run of captions in one undoable step: one title per entry, from `start` to `end` seconds, each on a lane above the picture. `style` applies to all of them (its `content` is ignored); without one they look like the window's captions - Hanken Grotesk, weight 600, 0.04 of the frame high. `offsetY` is where they sit, as a fraction of frame height from the centre: 0.35 (the default) is near the bottom, 0 the middle, -0.35 the top.",
+ read_only: false,
+ destructive: false,
+ idempotent: false,
+ action: Action::Captions,
+ },
+ command(
+ "keyframe_set",
+ "Set a keyframe",
+ "Animates a clip: puts a key on `property` (scale, offsetX, offsetY, rotation, opacity or volume) at `at`, a fraction of the clip's length from 0 (its start) to 1 (its end), holding `value` in the property's own units - the number the inspector shows. A key already within a hair of `at` is replaced. `ease` is how the value is approached: [x1, y1, x2, y2] like a CSS cubic-bezier, linear when absent.",
+ "setClipKey",
+ ),
+ command(
+ "keyframe_clear",
+ "Remove a keyframe",
+ "Removes the key on `property` at `at` (a fraction of the clip's length), if there is one.",
+ "clearClipKey",
+ )
+ .destroying(),
+ command(
+ "effect_layer_add",
+ "Add an effect layer",
+ "Places an effect or look as a layer over the timeline: from `start` for `duration` seconds (5 s when absent), it treats everything beneath it. `effectId` is a package id from `effects_list`; the layer's opacity (via `clip_update`) is how strongly it applies. To put an effect on one clip instead, set that clip's `videoEffects` with `clip_update`.",
+ "addLayerClip",
+ ),
+ command(
+ "effect_key_set",
+ "Animate an effect parameter",
+ "Puts a key on one parameter (`key`, from `effects_list`) of one effect in a clip's chain (`entry`, its index in the clip's videoEffects, from 0) at `at` (a fraction of the clip's length, 0-1), holding `value` in the parameter's own units. Keep the value within the range `effects_list` gives.",
+ "setEffectKey",
+ ),
+ command(
+ "track_add",
+ "Add a lane",
+ "Adds a lane to the active timeline: on top, or with `bottom: true` under every other. Its id is `createdId`.",
+ "addTrack",
+ ),
+ method(
+ "effects_list",
+ "List effects",
+ "Every effect package this build has - id, name, kind (\"effect\", \"filter\", \"audio\", \"transition\" or \"generator\"), category and each parameter's key, range, default and unit - so an effect chain, a layer or a transition can be built correctly. `kind` narrows the list.",
+ "catalogue.list",
+ Raw,
+ )
+ .reading(),
+ method(
+ "template_list",
+ "List templates",
+ "The template library: each template's folder, name and the slots (placeholder media ids) a project made from it must fill.",
+ "template.list",
+ Raw,
+ )
+ .reading(),
+ method(
+ "template_instantiate",
+ "Make a project from a template",
+ "Makes a project from a template - `template` (its folder), `location` and `name` as for `project_create` - with every slot filled by a file (`fills`: [{mediaId, file}]). Opens it and returns its summary.",
+ "template.instantiate",
+ Summary,
+ ),
+ method(
+ "export_start",
+ "Start an export",
+ "Starts rendering an open project's active timeline to `output` (an .mp4 path), as the window's Export does. Returns at once with a `job` id; follow it with `export_wait` or `export_status`. Optional: crf (quality, lower is better, 20 by default), preset (x264 speed, \"medium\"), width/height, rateNum/rateDen, codec (\"h264\", \"hevc\" or \"av1\"), tenBit, colorRange, hdr. One export runs at a time; another is refused as busy.",
+ "export.run",
+ Raw,
+ ),
+ method(
+ "export_status",
+ "Export status",
+ "How an export job stands, at once: `state` (\"running\", \"done\", \"cancelled\" or \"failed\"), `stage` (\"cutout\", \"video\", \"audio\", \"mux\"), frames done of total, `fraction` of the stage (0-1), and once done the file and its size, or the error.",
+ "export.status",
+ Raw,
+ )
+ .reading(),
+ Tool {
+ name: "export_wait",
+ title: "Wait for an export",
+ description: "Waits for an export job to end, up to `timeoutSeconds` (60 by default, 600 at most), reporting progress as it goes, and returns its status as `export_status` does. If it is still running when the time is up, call it again.",
+ read_only: true,
+ destructive: false,
+ idempotent: true,
+ action: Action::ExportWait,
+ },
+ method(
+ "export_cancel",
+ "Cancel an export",
+ "Stops a running export job at its next frame; it then ends as \"cancelled\".",
+ "export.cancel",
+ Raw,
+ )
+ .destroying(),
+ Tool {
+ name: "preview_frame",
+ title: "Preview a frame",
+ description: "Renders the true composited frame at `time` seconds on an open project's timeline and returns it as an image to look at - titles, effects and transforms included. Without `width` and `height` it fits within 1280 pixels; give both for another size (8192 at most). With `output` (a .png path) it is written there instead.",
+ read_only: true,
+ destructive: false,
+ idempotent: true,
+ action: Action::PreviewFrame,
+ },
+ ]
+}
+
+/// What a tool call came to: MCP content, and whether it is an error the
+/// agent should read and correct.
+pub struct Outcome {
+ /// The content blocks.
+ pub content: Vec<Value>,
+ /// The same result as JSON, for a client that reads it structured.
+ pub structured: Option<Value>,
+ /// A tool execution error.
+ pub is_error: bool,
+}
+
+impl Outcome {
+ fn json(value: Value) -> Outcome {
+ let text = serde_json::to_string_pretty(&value).unwrap_or_else(|_| value.to_string());
+ Outcome {
+ content: vec![json!({ "type": "text", "text": text })],
+ structured: value.is_object().then_some(value),
+ is_error: false,
+ }
+ }
+
+ fn error(error: &ApiError) -> Outcome {
+ let code = serde_json::to_value(error.code)
+ .ok()
+ .and_then(|code| code.as_str().map(str::to_owned))
+ .unwrap_or_default();
+ Outcome {
+ content: vec![json!({ "type": "text", "text": format!("{} (code: {code})", error.message) })],
+ structured: Some(json!({ "error": { "code": code, "message": error.message } })),
+ is_error: true,
+ }
+ }
+}
+
+/// What a call may use besides its arguments.
+pub struct Context<'a> {
+ /// Where requests go.
+ pub backend: &'a mut dyn Backend,
+ /// Set when the client cancels the call.
+ pub cancelled: &'a AtomicBool,
+ /// Reports progress, when the client asked for it: done so far, out
+ /// of a total, and a sentence.
+ pub progress: Option<&'a dyn Fn(f64, f64, String)>,
+}
+
+/// The tools with their schemas, made once.
+pub struct Toolbox {
+ tools: Vec<(Tool, Value)>,
+ schemas: Schemas,
+}
+
+impl Toolbox {
+ /// Every tool in [`catalogue`], with the schema the API gives it.
+ /// Panics on a tool whose method or command the API does not have: a
+ /// test builds this, so the panic is a failed build, not a user's.
+ pub fn new() -> Toolbox {
+ let schemas = Schemas::generate();
+ let tools = catalogue()
+ .into_iter()
+ .map(|tool| {
+ let schema = input_schema(&schemas, &tool)
+ .unwrap_or_else(|| panic!("the API has nothing for the {} tool", tool.name));
+ (tool, schema)
+ })
+ .collect();
+ Toolbox { tools, schemas }
+ }
+
+ /// `tools/list`'s list.
+ pub fn list(&self) -> Vec<Value> {
+ self.tools
+ .iter()
+ .map(|(tool, schema)| {
+ json!({
+ "name": tool.name,
+ "title": tool.title,
+ "description": tool.description,
+ "inputSchema": schema,
+ "annotations": {
+ "title": tool.title,
+ "readOnlyHint": tool.read_only,
+ "destructiveHint": tool.destructive,
+ "idempotentHint": tool.idempotent,
+ "openWorldHint": false,
+ },
+ })
+ })
+ .collect()
+ }
+
+ /// The tool called `name`, with its schema.
+ pub fn find(&self, name: &str) -> Option<&(Tool, Value)> {
+ self.tools.iter().find(|(tool, _)| tool.name == name)
+ }
+
+ /// The schemas tools are cut from.
+ pub fn schemas(&self) -> &Schemas {
+ &self.schemas
+ }
+
+ /// Runs the tool `name`; `None` when there is no such tool.
+ pub fn call(&self, name: &str, arguments: Value, context: Context<'_>) -> Option<Outcome> {
+ let (tool, _) = self.find(name)?;
+ let arguments = match arguments {
+ Value::Null => Value::Object(Map::new()),
+ other => other,
+ };
+ Some(match run(tool, arguments, context) {
+ Ok(outcome) => outcome,
+ Err(error) => Outcome::error(&error),
+ })
+ }
+}
+
+impl Default for Toolbox {
+ fn default() -> Self {
+ Toolbox::new()
+ }
+}
+
+/// The schema a tool's arguments follow.
+fn input_schema(schemas: &Schemas, tool: &Tool) -> Option<Value> {
+ match tool.action {
+ Action::Method { method, .. } => schemas.method(method),
+ Action::Command { op } => schemas.command(op),
+ Action::Version => schemas.method("version"),
+ Action::TimelineRead => schemas.method("project.get"),
+ Action::ExportWait => {
+ let mut schema = schemas.method("export.status")?;
+ schema["properties"]["timeoutSeconds"] = json!({
+ "type": "number",
+ "minimum": 0,
+ "maximum": WAIT_LONGEST,
+ "default": WAIT_DEFAULT,
+ "description": "How long to wait, in seconds.",
+ });
+ Some(schema)
+ }
+ Action::PreviewFrame => schemas.method("preview.frame"),
+ Action::Captions => {
+ let path = schemas.method("project.get")?.pointer("/properties/path")?.clone();
+ let mut style = schemas.def("TextStyle")?;
+ style["description"] = json!(
+ "The look every caption shares, as a title's style; only the fields that differ from the default are needed. Its content is replaced by each caption's text."
+ );
+ Some(json!({
+ "type": "object",
+ "properties": {
+ "path": path,
+ "captions": {
+ "type": "array",
+ "minItems": 1,
+ "description": "The captions, each shown from start to end.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "start": { "type": "number", "minimum": 0, "description": "When it appears, in seconds on the timeline." },
+ "end": { "type": "number", "minimum": 0, "description": "When it goes, in seconds on the timeline; after start." },
+ "text": { "type": "string", "description": "The words. A newline breaks the line." },
+ },
+ "required": ["start", "end", "text"],
+ },
+ },
+ "style": style,
+ "offsetY": {
+ "type": "number",
+ "default": 0.35,
+ "minimum": -3,
+ "maximum": 3,
+ "description": "Vertical placement as a fraction of frame height from the centre, positive down.",
+ },
+ },
+ "required": ["path", "captions"],
+ }))
+ }
+ }
+}
+
+/// A request from a method's arguments.
+fn request(method: &str, mut arguments: Value) -> Result<Request, ApiError> {
+ let Some(fields) = arguments.as_object_mut() else {
+ return Err(ApiError::invalid("the arguments are an object"));
+ };
+ fields.insert("method".to_owned(), json!(method));
+ serde_json::from_value(arguments)
+ .map_err(|error| ApiError::invalid(format!("invalid arguments: {error}")))
+}
+
+/// `edit.apply` of one command, from the command's arguments and the
+/// project's `path` beside them.
+fn edit(op: &str, mut arguments: Value) -> Result<Request, ApiError> {
+ let Some(fields) = arguments.as_object_mut() else {
+ return Err(ApiError::invalid("the arguments are an object"));
+ };
+ let path = fields
+ .remove("path")
+ .ok_or_else(|| ApiError::invalid("invalid arguments: missing field `path`"))?;
+ fields.insert("op".to_owned(), json!(op));
+ request("edit.apply", json!({ "path": path, "command": arguments }))
+}
+
+fn run(tool: &Tool, arguments: Value, context: Context<'_>) -> Result<Outcome, ApiError> {
+ let backend = context.backend;
+ match tool.action {
+ Action::Method { method, reply } => {
+ let result = backend.call(request(method, arguments)?)?;
+ Ok(Outcome::json(match reply {
+ Reply::Raw => result,
+ Reply::Summary => summary::view(&result),
+ }))
+ }
+ Action::Command { op } => {
+ let result = backend.call(edit(op, arguments)?)?;
+ Ok(Outcome::json(summary::view(&result)))
+ }
+ Action::Version => {
+ let mut result = backend.call(request("version", arguments)?)?;
+ result["mcp"] = backend.describe();
+ Ok(Outcome::json(result))
+ }
+ Action::TimelineRead => {
+ let result = backend.call(request("project.get", arguments)?)?;
+ Ok(Outcome::json(summary::view(&result)))
+ }
+ Action::Captions => {
+ let result = backend.call(captions(arguments)?)?;
+ Ok(Outcome::json(summary::view(&result)))
+ }
+ Action::ExportWait => export_wait(arguments, backend, context.cancelled, context.progress),
+ Action::PreviewFrame => preview(arguments, backend),
+ }
+}
+
+/// `captions_add`: one batch of titles.
+fn captions(mut arguments: Value) -> Result<Request, ApiError> {
+ let invalid = |why: &str| ApiError::invalid(format!("invalid arguments: {why}"));
+ let fields = arguments
+ .as_object_mut()
+ .ok_or_else(|| invalid("the arguments are an object"))?;
+ let path = fields.remove("path").ok_or_else(|| invalid("missing field `path`"))?;
+ let captions = match fields.remove("captions") {
+ Some(Value::Array(captions)) if !captions.is_empty() => captions,
+ _ => return Err(invalid("`captions` is a list of {start, end, text}")),
+ };
+ let offset = match fields.remove("offsetY") {
+ None | Some(Value::Null) => 0.35,
+ Some(value) => value.as_f64().ok_or_else(|| invalid("`offsetY` is a number"))?,
+ };
+ let style = match fields.remove("style") {
+ None | Some(Value::Null) => json!({
+ "fontFamily": "Hanken Grotesk",
+ "fontSize": 0.04,
+ "fontWeight": 600,
+ }),
+ Some(Value::Object(style)) => Value::Object(style),
+ Some(_) => return Err(invalid("`style` is an object")),
+ };
+ if let Some(unknown) = fields.keys().next() {
+ return Err(invalid(&format!("unknown field `{unknown}`")));
+ }
+ let mut commands = Vec::with_capacity(captions.len());
+ for (index, caption) in captions.iter().enumerate() {
+ let number = |key: &str| caption.get(key).and_then(Value::as_f64);
+ let (Some(start), Some(end), Some(text)) = (
+ number("start"),
+ number("end"),
+ caption.get("text").and_then(Value::as_str),
+ ) else {
+ return Err(invalid(&format!(
+ "caption {index} needs a start, an end and a text"
+ )));
+ };
+ if !(start >= 0.0 && end > start) {
+ return Err(invalid(&format!(
+ "caption {index} ends at {end} s, not after its start at {start} s"
+ )));
+ }
+ let mut style = style.clone();
+ style["content"] = json!(text);
+ commands.push(json!({
+ "op": "addTextClip",
+ "trackId": null,
+ "above": true,
+ "start": start,
+ "duration": end - start,
+ "style": style,
+ "offsetY": offset,
+ }));
+ }
+ request(
+ "edit.apply",
+ json!({ "path": path, "command": { "op": "batch", "commands": commands } }),
+ )
+}
+
+/// `export_wait`: the job's status once it has ended, or when the time is
+/// up, with progress reported on the way.
+fn export_wait(
+ mut arguments: Value,
+ backend: &mut dyn Backend,
+ cancelled: &AtomicBool,
+ progress: Option<&dyn Fn(f64, f64, String)>,
+) -> Result<Outcome, ApiError> {
+ let timeout = match arguments.as_object_mut().and_then(|fields| fields.remove("timeoutSeconds")) {
+ None | Some(Value::Null) => WAIT_DEFAULT,
+ Some(value) => value
+ .as_f64()
+ .filter(|seconds| seconds.is_finite() && *seconds >= 0.0)
+ .ok_or_else(|| ApiError::invalid("invalid arguments: `timeoutSeconds` is a number of seconds"))?
+ .min(WAIT_LONGEST),
+ };
+ let status = request("export.status", arguments)?;
+ let until = Instant::now() + Duration::from_secs_f64(timeout);
+ let mut reported = -1.0_f64;
+ loop {
+ let mut current = backend.call(status.clone())?;
+ let running = current["state"] == "running";
+ if let Some(progress) = progress {
+ let stage = current["stage"].as_str().unwrap_or_default();
+ let place = STAGES.iter().position(|known| *known == stage).unwrap_or(0) as f64;
+ let fraction = current["fraction"].as_f64().unwrap_or(0.0).clamp(0.0, 1.0);
+ let overall = if running {
+ ((place + fraction) / STAGES.len() as f64 * 100.0).min(99.9)
+ } else {
+ 100.0
+ };
+ // A progress value must rise; a stage that starts over at 0
+ // says nothing new until it passes where the last one was.
+ if overall > reported {
+ reported = overall;
+ let frames = match (current["frame"].as_i64(), current["total"].as_i64()) {
+ (Some(frame), Some(total)) if total > 0 => format!(" {frame}/{total}"),
+ _ => String::new(),
+ };
+ let state = current["state"].as_str().unwrap_or_default();
+ progress(
+ (overall * 10.0).round() / 10.0,
+ 100.0,
+ format!("{state} {stage}{frames}").trim().to_owned(),
+ );
+ }
+ }
+ if !running {
+ return Ok(Outcome::json(current));
+ }
+ if cancelled.load(Ordering::Relaxed) {
+ return Err(ApiError::new(ErrorCode::Cancelled, "stopped waiting; the export goes on"));
+ }
+ if Instant::now() >= until {
+ current["note"] = json!("still running: call export_wait again, or export_status");
+ return Ok(Outcome::json(current));
+ }
+ std::thread::sleep(POLL);
+ }
+}
+
+/// `preview_frame`: the picture as an image, or the file written.
+fn preview(mut arguments: Value, backend: &mut dyn Backend) -> Result<Outcome, ApiError> {
+ let wants_file = arguments.get("output").is_some_and(|output| !output.is_null());
+ let sized = ["width", "height"]
+ .iter()
+ .all(|key| arguments.get(*key).is_some_and(|value| !value.is_null()));
+ if !wants_file && !sized {
+ // The timeline's own frame, fitted within PREVIEW_SIDE.
+ let path = arguments.get("path").cloned().unwrap_or(Value::Null);
+ let view = backend.call(request("project.get", json!({ "path": path }))?)?;
+ let width = view.pointer("/settings/width").and_then(Value::as_f64).unwrap_or(1920.0);
+ let height = view.pointer("/settings/height").and_then(Value::as_f64).unwrap_or(1080.0);
+ let scale = (PREVIEW_SIDE / width.max(height)).min(1.0);
+ if let Some(fields) = arguments.as_object_mut() {
+ fields.insert("width".to_owned(), json!(((width * scale).round() as u32).max(1)));
+ fields.insert("height".to_owned(), json!(((height * scale).round() as u32).max(1)));
+ }
+ }
+ let time = arguments.get("time").cloned().unwrap_or(Value::Null);
+ let result = backend.call(request("preview.frame", arguments)?)?;
+ let Some(png) = result.get("png").and_then(Value::as_str) else {
+ return Ok(Outcome::json(result));
+ };
+ Ok(Outcome {
+ content: vec![
+ json!({ "type": "image", "data": png, "mimeType": "image/png" }),
+ json!({
+ "type": "text",
+ "text": format!("The frame at {time} s, {}×{}.", result["width"], result["height"]),
+ }),
+ ],
+ structured: Some(json!({ "width": result["width"], "height": result["height"], "time": time })),
+ is_error: false,
+ })
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::schema::check;
+
+ /// One call each tool may take, as an agent would write it.
+ fn samples() -> Vec<(&'static str, Value)> {
+ vec![
+ ("concat_version", json!({})),
+ ("project_list", json!({})),
+ ("project_create", json!({ "location": "/tmp", "name": "Cut", "video": { "width": 1080, "height": 1920, "rateNum": 30, "rateDen": 1 } })),
+ ("project_open", json!({ "path": "/tmp/Cut" })),
+ ("project_save", json!({ "path": "/tmp/Cut" })),
+ ("project_close", json!({ "path": "/tmp/Cut", "save": true })),
+ ("timeline_read", json!({ "path": "/tmp/Cut" })),
+ ("project_get", json!({ "path": "/tmp/Cut" })),
+ ("project_set_video", json!({ "path": "/tmp/Cut", "video": { "width": 1920, "height": 1080, "rateNum": 30000, "rateDen": 1001 } })),
+ ("media_probe", json!({ "path": "/tmp/a.mp4" })),
+ ("media_import", json!({ "path": "/tmp/Cut", "file": "/tmp/a.mp4" })),
+ ("edit_apply", json!({ "path": "/tmp/Cut", "command": { "op": "addTrack" } })),
+ ("edit_undo", json!({ "path": "/tmp/Cut" })),
+ ("edit_redo", json!({ "path": "/tmp/Cut" })),
+ ("clip_add", json!({ "path": "/tmp/Cut", "mediaId": "m1", "trackId": "t1", "start": 2.5 })),
+ ("clip_trim", json!({ "path": "/tmp/Cut", "clipId": "c1", "edge": "end", "delta": -1.0, "ripple": true })),
+ ("clips_split", json!({ "path": "/tmp/Cut", "clipIds": ["c1"], "time": 3.0 })),
+ ("clips_move", json!({ "path": "/tmp/Cut", "moves": [{ "clipId": "c1", "start": 0.0, "trackId": "t2" }] })),
+ ("clips_remove", json!({ "path": "/tmp/Cut", "clipIds": ["c1"], "ripple": false })),
+ ("clip_update", json!({ "path": "/tmp/Cut", "clipId": "c1", "patch": { "volume": 0.5, "crop": null, "transitionIn": { "id": "cross-fade", "duration": 0.5 }, "videoEffects": [{ "id": "concat.warm", "params": { "amount": 0.4 } }] } })),
+ ("clip_transform", json!({ "path": "/tmp/Cut", "clipId": "c1", "scale": 1.2, "rotation": 15.0 })),
+ ("clip_speed", json!({ "path": "/tmp/Cut", "clipId": "c1", "speed": 0.5 })),
+ ("title_add", json!({ "path": "/tmp/Cut", "start": 1.0, "duration": 3.0, "above": true, "style": { "content": "Hello", "fontSize": 0.08, "align": "left" }, "offsetY": -0.3 })),
+ ("captions_add", json!({ "path": "/tmp/Cut", "captions": [{ "start": 0.0, "end": 1.5, "text": "Hi" }], "style": { "color": "#ffff00" }, "offsetY": 0.3 })),
+ ("keyframe_set", json!({ "path": "/tmp/Cut", "clipId": "c1", "property": "scale", "at": 0.0, "value": 1.0, "ease": [0.42, 0.0, 0.58, 1.0] })),
+ ("keyframe_clear", json!({ "path": "/tmp/Cut", "clipId": "c1", "property": "opacity", "at": 1.0 })),
+ ("effect_layer_add", json!({ "path": "/tmp/Cut", "start": 0.0, "duration": 2.0, "effectId": "concat.warm", "name": "Warm", "trackId": null })),
+ ("effect_key_set", json!({ "path": "/tmp/Cut", "clipId": "c1", "entry": 0, "key": "amount", "at": 0.5, "value": 0.8 })),
+ ("track_add", json!({ "path": "/tmp/Cut", "bottom": false })),
+ ("effects_list", json!({ "kind": "transition" })),
+ ("template_list", json!({})),
+ ("template_instantiate", json!({ "template": "/t", "location": "/tmp", "name": "From", "fills": [{ "mediaId": "m1", "file": "/tmp/a.mp4" }] })),
+ ("export_start", json!({ "path": "/tmp/Cut", "output": "/tmp/cut.mp4", "crf": 23, "codec": "h264" })),
+ ("export_status", json!({ "job": "j1" })),
+ ("export_wait", json!({ "job": "j1", "timeoutSeconds": 5 })),
+ ("export_cancel", json!({ "job": "j1" })),
+ ("preview_frame", json!({ "path": "/tmp/Cut", "time": 1.5, "width": 320, "height": 180 })),
+ ]
+ }
+
+ #[test]
+ fn every_tool_has_a_schema_and_a_sample_and_names_are_unique() {
+ let toolbox = Toolbox::new();
+ let listed = toolbox.list();
+ let samples = samples();
+ assert_eq!(listed.len(), samples.len(), "a sample for every tool");
+ let mut names: Vec<&str> = listed.iter().filter_map(|tool| tool["name"].as_str()).collect();
+ names.sort_unstable();
+ names.dedup();
+ assert_eq!(names.len(), listed.len(), "unique names");
+ for tool in &listed {
+ let name = tool["name"].as_str().expect("named");
+ assert!(
+ name.len() <= 64 && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_'),
+ "{name}"
+ );
+ assert_eq!(tool["inputSchema"]["type"], "object", "{name}");
+ assert!(tool["description"].as_str().is_some_and(|text| text.len() > 40), "{name}");
+ }
+ }
+
+ /// The round trip: what each tool's schema accepts is what its Rust
+ /// type reads, and what the Rust type writes the schema accepts.
+ #[test]
+ fn every_sample_fits_its_schema_and_reads_as_its_request() {
+ let toolbox = Toolbox::new();
+ for (name, sample) in samples() {
+ let (tool, schema) = toolbox.find(name).unwrap_or_else(|| panic!("no {name}"));
+ check(schema, &sample, schema, name).unwrap_or_else(|why| panic!("{why}"));
+ let built = match tool.action {
+ Action::Method { method, .. } => request(method, sample.clone()),
+ Action::Command { op } => edit(op, sample.clone()),
+ Action::Version => request("version", sample.clone()),
+ Action::TimelineRead => request("project.get", sample.clone()),
+ Action::Captions => captions(sample.clone()),
+ Action::ExportWait => {
+ let mut sample = sample.clone();
+ sample.as_object_mut().map(|fields| fields.remove("timeoutSeconds"));
+ request("export.status", sample)
+ }
+ Action::PreviewFrame => request("preview.frame", sample.clone()),
+ };
+ let built = built.unwrap_or_else(|error| panic!("{name}: {error}"));
+ // Back again: the request as the API writes it fits the API's
+ // own schema for requests.
+ let written = serde_json::to_value(&built).expect("writes");
+ let root = concat_api::request_schema();
+ check(&root, &written, &root, name).unwrap_or_else(|why| panic!("{why}"));
+ }
+ }
+
+ #[test]
+ fn a_wrong_argument_is_refused_by_the_schema_and_by_the_type_alike() {
+ let toolbox = Toolbox::new();
+ let (_, schema) = toolbox.find("clip_speed").expect("a tool");
+ let wrong = json!({ "path": "/p", "clipId": "c1", "speed": "fast" });
+ assert!(check(schema, &wrong, schema, "clip_speed").is_err());
+ let error = edit("setClipSpeed", wrong).expect_err("refused");
+ assert_eq!(error.code, ErrorCode::Invalid);
+ let missing = request("project.open", json!({}));
+ assert!(missing.expect_err("refused").message.contains("path"));
+ assert!(captions(json!({ "path": "/p", "captions": [{ "start": 2, "end": 1, "text": "x" }] })).is_err());
+ }
+}
diff --git a/src/crates/concat-mcp/tests/e2e.rs b/src/crates/concat-mcp/tests/e2e.rs
new file mode 100644
index 00000000..86c5d428
--- /dev/null
+++ b/src/crates/concat-mcp/tests/e2e.rs
@@ -0,0 +1,372 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// SPDX-FileCopyrightText: 2026 Jareer and Concat contributors
+
+//! The MCP server as an agent meets it: a process spoken to over its
+//! standard input and output, from the handshake through edits, a frame
+//! and an export to the end of the session - headless, and through a
+//! running server as the window's Automation page runs one.
+
+use std::io::{BufRead, BufReader, Write};
+use std::path::Path;
+use std::process::{Child, ChildStdin, ChildStdout, Command, Stdio};
+use std::sync::mpsc;
+use std::time::Duration;
+
+use serde_json::{Value, json};
+
+/// The server process and its two pipes.
+struct Agent {
+ child: Child,
+ input: ChildStdin,
+ lines: mpsc::Receiver<Value>,
+ next: i64,
+}
+
+impl Agent {
+ /// The MCP server with a scratch folder for a home, so it reads and
+ /// writes nowhere real.
+ fn spawn(home: &Path, mode: &str, extra: &[(&str, String)]) -> Agent {
+ let mut command = Command::new(env!("CARGO_BIN_EXE_concat-mcp"));
+ command
+ .arg(mode)
+ .env("HOME", home)
+ .env("USERPROFILE", home)
+ .env("APPDATA", home.join("AppData"))
+ .env("LOCALAPPDATA", home.join("LocalAppData"))
+ .env("XDG_CONFIG_HOME", home.join(".config"))
+ .env("XDG_DATA_HOME", home.join(".local/share"))
+ .env_remove("CONCAT_API_ADDRESS")
+ .env_remove("CONCAT_API_TOKEN")
+ .env_remove("CONCAT_MCP_ROOTS")
+ .stdin(Stdio::piped())
+ .stdout(Stdio::piped())
+ .stderr(Stdio::inherit());
+ for (key, value) in extra {
+ command.env(key, value);
+ }
+ let mut child = command.spawn().expect("the MCP server starts");
+ let input = child.stdin.take().expect("stdin");
+ let output: ChildStdout = child.stdout.take().expect("stdout");
+ let (send, lines) = mpsc::channel();
+ std::thread::spawn(move || {
+ for line in BufReader::new(output).lines() {
+ let Ok(line) = line else { return };
+ let value: Value = serde_json::from_str(&line)
+ .unwrap_or_else(|_| panic!("stdout carries only JSON-RPC: {line:?}"));
+ if send.send(value).is_err() {
+ return;
+ }
+ }
+ });
+ Agent {
+ child,
+ input,
+ lines,
+ next: 1,
+ }
+ }
+
+ fn send(&mut self, message: &Value) {
+ writeln!(self.input, "{message}").expect("writes");
+ self.input.flush().expect("flushes");
+ }
+
+ fn line(&self) -> Value {
+ self.lines
+ .recv_timeout(Duration::from_secs(120))
+ .expect("the server answers")
+ }
+
+ /// A request, and every line up to its answer: the notifications on
+ /// the way, then the answer.
+ fn ask(&mut self, method: &str, params: Value) -> (Vec<Value>, Value) {
+ let id = self.next;
+ self.next += 1;
+ self.send(&json!({ "jsonrpc": "2.0", "id": id, "method": method, "params": params }));
+ let mut notes = Vec::new();
+ loop {
+ let line = self.line();
+ if line.get("id") == Some(&json!(id)) {
+ return (notes, line);
+ }
+ notes.push(line);
+ }
+ }
+
+ /// A tool's result: its structured content when it has some, its text
+ /// otherwise. Fails on a protocol error.
+ fn tool(&mut self, name: &str, arguments: Value) -> Value {
+ let (_, reply) = self.ask("tools/call", json!({ "name": name, "arguments": arguments }));
+ let result = reply.get("result").unwrap_or_else(|| panic!("{name}: {reply}")).clone();
+ assert_eq!(result["isError"], false, "{name}: {result}");
+ result
+ }
+
+ /// Closes the server's input and waits for it to go.
+ fn end(mut self) {
+ drop(self.input);
+ for _ in 0..200 {
+ if let Ok(Some(status)) = self.child.try_wait() {
+ assert!(status.success(), "{status}");
+ return;
+ }
+ std::thread::sleep(Duration::from_millis(50));
+ }
+ let _ = self.child.kill();
+ panic!("the server did not exit when its input closed");
+ }
+}
+
+#[test]
+fn an_agent_edits_previews_and_exports_a_project_headless() {
+ let scratch = tempfile::tempdir().expect("scratch");
+ let home = scratch.path();
+ let mut agent = Agent::spawn(home, "headless", &[]);
+
+ let (_, welcome) = agent.ask(
+ "initialize",
+ json!({
+ "protocolVersion": "2025-06-18",
+ "capabilities": {},
+ "clientInfo": { "name": "e2e", "version": "1" },
+ }),
+ );
+ let welcome = &welcome["result"];
+ assert_eq!(welcome["protocolVersion"], "2025-06-18");
+ assert_eq!(welcome["serverInfo"]["name"], "concat");
+ assert!(welcome["capabilities"]["tools"].is_object());
+ assert!(welcome["instructions"].as_str().is_some_and(|text| text.contains("project")));
+ agent.send(&json!({ "jsonrpc": "2.0", "method": "notifications/initialized" }));
+
+ let (_, listed) = agent.ask("tools/list", json!({}));
+ let tools = listed["result"]["tools"].as_array().expect("tools");
+ for name in ["project_create", "edit_apply", "title_add", "preview_frame", "export_wait"] {
+ let tool = tools
+ .iter()
+ .find(|tool| tool["name"] == name)
+ .unwrap_or_else(|| panic!("no {name}"));
+ assert_eq!(tool["inputSchema"]["type"], "object");
+ }
+
+ let version = agent.tool("concat_version", json!({}));
+ assert_eq!(version["structuredContent"]["mcp"]["mode"], "headless");
+
+ let created = agent.tool(
+ "project_create",
+ json!({
+ "location": home.to_string_lossy(),
+ "name": "Agent Cut",
+ "video": { "width": 320, "height": 180, "rateNum": 30, "rateDen": 1 },
+ }),
+ );
+ assert_eq!(created["structuredContent"]["project"]["name"], "Agent Cut");
+ let path = home.join("Agent Cut").to_string_lossy().into_owned();
+
+ let titled = agent.tool(
+ "title_add",
+ json!({
+ "path": path,
+ "start": 0.0,
+ "duration": 1.0,
+ "above": true,
+ "style": { "content": "Hello, agent", "background": "#202020ff" },
+ }),
+ );
+ let title = titled["structuredContent"]["createdId"].clone();
+ assert!(title.is_string(), "{titled}");
+
+ let captioned = agent.tool(
+ "captions_add",
+ json!({
+ "path": path,
+ "captions": [
+ { "start": 0.0, "end": 0.5, "text": "one" },
+ { "start": 0.5, "end": 1.0, "text": "two" },
+ ],
+ }),
+ );
+ assert_eq!(captioned["structuredContent"]["canUndo"], true);
+
+ let keyed = agent.tool(
+ "keyframe_set",
+ json!({ "path": path, "clipId": title, "property": "opacity", "at": 1.0, "value": 0.25 }),
+ );
+ let read = agent.tool("timeline_read", json!({ "path": path }));
+ let clips = read["structuredContent"]["timeline"]["clips"]
+ .as_array()
+ .expect("clips")
+ .clone();
+ assert_eq!(clips.len(), 3, "{read}");
+ let first = clips.iter().find(|clip| clip["id"] == title).expect("the title");
+ assert_eq!(first["text"], "Hello, agent");
+ assert_eq!(first["keyframed"], json!(["opacity"]));
+ assert_eq!(keyed["structuredContent"]["timeline"], read["structuredContent"]["timeline"]);
+
+ // A wrong argument is the agent's to correct: a tool error, not a
+ // protocol one.
+ let (_, wrong) = agent.ask(
+ "tools/call",
+ json!({ "name": "clip_speed", "arguments": { "path": path, "clipId": title, "speed": "fast" } }),
+ );
+ assert_eq!(wrong["result"]["isError"], true, "{wrong}");
+ let (_, unknown) = agent.ask("tools/call", json!({ "name": "make_it_pop", "arguments": {} }));
+ assert_eq!(unknown["error"]["code"], -32602);
+
+ let undone = agent.tool("edit_undo", json!({ "path": path }));
+ let after_undo = undone["structuredContent"]["timeline"]["clips"]
+ .as_array()
+ .and_then(|clips| clips.iter().find(|clip| clip["id"] == title))
+ .expect("the title")
+ .clone();
+ assert!(after_undo.get("keyframed").is_none(), "the key is undone: {after_undo}");
+
+ let frame = agent.tool("preview_frame", json!({ "path": path, "time": 0.25 }));
+ let image = &frame["content"][0];
+ assert_eq!(image["type"], "image");
+ assert_eq!(image["mimeType"], "image/png");
+ assert!(
+ image["data"].as_str().is_some_and(|data| data.starts_with("iVBORw0KGgo")),
+ "a PNG"
+ );
+ assert_eq!(frame["structuredContent"]["width"], 320, "the timeline's own size fits");
+
+ agent.tool("project_save", json!({ "path": path }));
+ let saved = std::fs::read_to_string(Path::new(&path).join("concat.json")).expect("saved");
+ assert!(saved.contains("Hello, agent"));
+
+ let output = home.join("agent.mp4").to_string_lossy().into_owned();
+ let started = agent.tool("export_start", json!({ "path": path, "output": output, "preset": "ultrafast" }));
+ let job = started["structuredContent"]["job"].clone();
+ assert_eq!(job, "j1");
+ let (notes, waited) = agent.ask(
+ "tools/call",
+ json!({
+ "name": "export_wait",
+ "arguments": { "job": job, "timeoutSeconds": 120 },
+ "_meta": { "progressToken": "export" },
+ }),
+ );
+ let status = &waited["result"]["structuredContent"];
+ assert_ne!(status["state"], "running", "{waited}");
+ assert!(!notes.is_empty(), "progress was reported");
+ let mut last = -1.0;
+ for note in &notes {
+ assert_eq!(note["method"], "notifications/progress");
+ assert_eq!(note["params"]["progressToken"], "export");
+ let progress = note["params"]["progress"].as_f64().expect("a number");
+ assert!(progress > last, "progress rises");
+ last = progress;
+ }
+ if status["state"] == "done" {
+ assert!(Path::new(&output).exists());
+ }
+
+ // Writes stay under the home this server was given.
+ let (_, outside) = agent.ask(
+ "tools/call",
+ json!({ "name": "project_create", "arguments": { "location": "/", "name": "nope" } }),
+ );
+ assert_eq!(outside["result"]["isError"], true, "{outside}");
+
+ let (_, pong) = agent.ask("ping", json!({}));
+ assert_eq!(pong["result"], json!({}));
+ agent.end();
+}
+
+#[test]
+fn a_modern_client_discovers_and_is_told_which_versions_are_spoken() {
+ let scratch = tempfile::tempdir().expect("scratch");
+ let mut agent = Agent::spawn(scratch.path(), "headless", &[]);
+ let meta = |version: &str| {
+ json!({
+ "io.modelcontextprotocol/protocolVersion": version,
+ "io.modelcontextprotocol/clientInfo": { "name": "e2e", "version": "1" },
+ "io.modelcontextprotocol/clientCapabilities": {},
+ })
+ };
+ let (_, discovered) = agent.ask("server/discover", json!({ "_meta": meta("2026-07-28") }));
+ let result = &discovered["result"];
+ assert_eq!(result["resultType"], "complete");
+ assert!(
+ result["supportedVersions"]
+ .as_array()
+ .is_some_and(|versions| versions.contains(&json!("2026-07-28")))
+ );
+ assert_eq!(result["_meta"]["io.modelcontextprotocol/serverInfo"]["name"], "concat");
+
+ let (_, listed) = agent.ask("tools/list", json!({ "_meta": meta("2026-07-28") }));
+ assert_eq!(listed["result"]["resultType"], "complete");
+ assert!(listed["result"]["tools"].as_array().is_some_and(|tools| tools.len() > 20));
+
+ let (_, refused) = agent.ask("tools/list", json!({ "_meta": meta("1900-01-01") }));
+ assert_eq!(refused["error"]["code"], -32022);
+ assert_eq!(refused["error"]["data"]["requested"], "1900-01-01");
+
+ let (_, malformed) = agent.ask(
+ "tools/list",
+ json!({ "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28" } }),
+ );
+ assert_eq!(malformed["error"]["code"], -32602);
+
+ agent.send(&json!({ "jsonrpc": "2.0", "id": 99, "method": "no/such" }));
+ let missing = agent.line();
+ assert_eq!(missing["error"]["code"], -32601);
+ agent.send(&json!("not an object"));
+ assert_eq!(agent.line()["error"]["code"], -32600);
+ writeln!(agent.input, "{{ not json").expect("writes");
+ assert_eq!(agent.line()["error"]["code"], -32700);
+ agent.end();
+}
+
+#[test]
+fn through_a_running_server_the_agent_shares_its_api() {
+ use concat_api::{Api, AppDirs};
+ let scratch = tempfile::tempdir().expect("scratch");
+ let home = scratch.path().to_path_buf();
+ let dirs = AppDirs {
+ config: home.join("server-config"),
+ data: home.join("server-data"),
+ };
+ let server = concat_server::Server::start(
+ concat_server::Config {
+ json: Some("127.0.0.1:0".parse().expect("an address")),
+ roots: vec![home.clone()],
+ ..concat_server::Config::default()
+ },
+ move |events| Ok(Api::with_dirs(dirs, events)),
+ )
+ .expect("a server");
+ let address = server.json_addr().expect("listening").to_string();
+ let mut agent = Agent::spawn(
+ &home,
+ "window",
+ &[
+ ("CONCAT_API_ADDRESS", address.clone()),
+ ("CONCAT_API_TOKEN", server.token().to_owned()),
+ ],
+ );
+ let version = agent.tool("concat_version", json!({}));
+ assert_eq!(version["structuredContent"]["mcp"]["mode"], "window");
+ assert_eq!(version["structuredContent"]["mcp"]["address"], address);
+ agent.tool(
+ "project_create",
+ json!({ "location": home.to_string_lossy(), "name": "Shared" }),
+ );
+ // The project the agent made is open in the server's API: another
+ // caller of that server sees it.
+ let mut other = concat_server::client::Client::connect(
+ server.json_addr().expect("listening"),
+ server.token(),
+ Duration::from_secs(5),
+ )
+ .expect("in");
+ let seen = other
+ .call(&concat_api::Request::ProjectGet {
+ path: home.join("Shared").to_string_lossy().into_owned(),
+ })
+ .expect("open there");
+ assert!(seen["project"].is_object());
+ agent.end();
+ drop(other);
+ server.stop();
+}