From 6f2b01bb6b672ee3919a6d253537db5d927a1ba3 Mon Sep 17 00:00:00 2001 From: pakrym-oai Date: Fri, 18 Jul 2025 09:59:07 -0700 Subject: [PATCH 1/9] feat: ensure session ID header is sent in Response API request (#1614) Include the current session id in Responses API requests. --- codex-rs/core/src/client.rs | 5 ++ codex-rs/core/src/codex.rs | 1 + codex-rs/core/tests/client.rs | 117 ++++++++++++++++++++++++++++++++++ 3 files changed, 123 insertions(+) create mode 100644 codex-rs/core/tests/client.rs diff --git a/codex-rs/core/src/client.rs b/codex-rs/core/src/client.rs index 8ec68d02e8..ae7904b8ff 100644 --- a/codex-rs/core/src/client.rs +++ b/codex-rs/core/src/client.rs @@ -15,6 +15,7 @@ use tokio_util::io::ReaderStream; use tracing::debug; use tracing::trace; use tracing::warn; +use uuid::Uuid; use crate::chat_completions::AggregateStreamExt; use crate::chat_completions::stream_chat_completions; @@ -44,6 +45,7 @@ pub struct ModelClient { config: Arc, client: reqwest::Client, provider: ModelProviderInfo, + session_id: Uuid, effort: ReasoningEffortConfig, summary: ReasoningSummaryConfig, } @@ -54,11 +56,13 @@ impl ModelClient { provider: ModelProviderInfo, effort: ReasoningEffortConfig, summary: ReasoningSummaryConfig, + session_id: Uuid, ) -> Self { Self { config, client: reqwest::Client::new(), provider, + session_id, effort, summary, } @@ -143,6 +147,7 @@ impl ModelClient { .provider .create_request_builder(&self.client)? .header("OpenAI-Beta", "responses=experimental") + .header("session_id", self.session_id.to_string()) .header(reqwest::header::ACCEPT, "text/event-stream") .json(&payload); diff --git a/codex-rs/core/src/codex.rs b/codex-rs/core/src/codex.rs index d4e73b2ebf..246198c006 100644 --- a/codex-rs/core/src/codex.rs +++ b/codex-rs/core/src/codex.rs @@ -591,6 +591,7 @@ async fn submission_loop( provider.clone(), model_reasoning_effort, model_reasoning_summary, + session_id, ); // abort any current running session and clone its state diff --git a/codex-rs/core/tests/client.rs b/codex-rs/core/tests/client.rs new file mode 100644 index 0000000000..f4fb58f5a4 --- /dev/null +++ b/codex-rs/core/tests/client.rs @@ -0,0 +1,117 @@ +use std::time::Duration; + +use codex_core::Codex; +use codex_core::ModelProviderInfo; +use codex_core::exec::CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR; +use codex_core::protocol::EventMsg; +use codex_core::protocol::InputItem; +use codex_core::protocol::Op; +use codex_core::protocol::SessionConfiguredEvent; +mod test_support; +use tempfile::TempDir; +use test_support::load_default_config_for_test; +use test_support::load_sse_fixture_with_id; +use tokio::time::timeout; +use wiremock::Mock; +use wiremock::MockServer; +use wiremock::ResponseTemplate; +use wiremock::matchers::method; +use wiremock::matchers::path; + +/// Build minimal SSE stream with completed marker using the JSON fixture. +fn sse_completed(id: &str) -> String { + load_sse_fixture_with_id("tests/fixtures/completed_template.json", id) +} + +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn includes_session_id_and_model_headers_in_request() { + #![allow(clippy::unwrap_used)] + + if std::env::var(CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR).is_ok() { + println!( + "Skipping test because it cannot execute when network is disabled in a Codex sandbox." + ); + return; + } + + // Mock server + let server = MockServer::start().await; + + // First request – must NOT include `previous_response_id`. + let first = ResponseTemplate::new(200) + .insert_header("content-type", "text/event-stream") + .set_body_raw(sse_completed("resp1"), "text/event-stream"); + + Mock::given(method("POST")) + .and(path("/v1/responses")) + .respond_with(first) + .expect(1) + .mount(&server) + .await; + + // Environment + // Update environment – `set_var` is `unsafe` starting with the 2024 + // edition so we group the calls into a single `unsafe { … }` block. + unsafe { + std::env::set_var("OPENAI_REQUEST_MAX_RETRIES", "0"); + std::env::set_var("OPENAI_STREAM_MAX_RETRIES", "0"); + } + let model_provider = ModelProviderInfo { + name: "openai".into(), + base_url: format!("{}/v1", server.uri()), + // Environment variable that should exist in the test environment. + // ModelClient will return an error if the environment variable for the + // provider is not set. + env_key: Some("PATH".into()), + env_key_instructions: None, + wire_api: codex_core::WireApi::Responses, + query_params: None, + http_headers: Some( + [("originator".to_string(), "codex_cli_rs".to_string())] + .into_iter() + .collect(), + ), + env_http_headers: None, + }; + + // Init session + let codex_home = TempDir::new().unwrap(); + let mut config = load_default_config_for_test(&codex_home); + config.model_provider = model_provider; + let ctrl_c = std::sync::Arc::new(tokio::sync::Notify::new()); + let (codex, _init_id) = Codex::spawn(config, ctrl_c.clone()).await.unwrap(); + + codex + .submit(Op::UserInput { + items: vec![InputItem::Text { + text: "hello".into(), + }], + }) + .await + .unwrap(); + + let mut current_session_id = None; + // Wait for TaskComplete + loop { + let ev = timeout(Duration::from_secs(1), codex.next_event()) + .await + .unwrap() + .unwrap(); + + if let EventMsg::SessionConfigured(SessionConfiguredEvent { session_id, .. }) = ev.msg { + current_session_id = Some(session_id.to_string()); + } + if matches!(ev.msg, EventMsg::TaskComplete(_)) { + break; + } + } + + // get request from the server + let request = &server.received_requests().await.unwrap()[0]; + let request_body = request.headers.get("session_id").unwrap(); + let originator = request.headers.get("originator").unwrap(); + + assert!(current_session_id.is_some()); + assert_eq!(request_body.to_str().unwrap(), ¤t_session_id.unwrap()); + assert_eq!(originator.to_str().unwrap(), "codex_cli_rs"); +} From cc874c9205c27dd523350d4665526b776e5be921 Mon Sep 17 00:00:00 2001 From: Michael Bolin Date: Fri, 18 Jul 2025 11:13:34 -0700 Subject: [PATCH 2/9] chore: use AtomicBool instead of Mutex (#1616) --- codex-rs/tui/src/app.rs | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/codex-rs/tui/src/app.rs b/codex-rs/tui/src/app.rs index d8af5d33be..37c2616d5b 100644 --- a/codex-rs/tui/src/app.rs +++ b/codex-rs/tui/src/app.rs @@ -19,7 +19,8 @@ use crossterm::event::MouseEvent; use crossterm::event::MouseEventKind; use std::path::PathBuf; use std::sync::Arc; -use std::sync::Mutex; +use std::sync::atomic::AtomicBool; +use std::sync::atomic::Ordering; use std::sync::mpsc::Receiver; use std::sync::mpsc::channel; use std::thread; @@ -54,7 +55,7 @@ pub(crate) struct App<'a> { file_search: FileSearchManager, /// True when a redraw has been scheduled but not yet executed. - pending_redraw: Arc>, + pending_redraw: Arc, /// Stored parameters needed to instantiate the ChatWidget later, e.g., /// after dismissing the Git-repo warning. @@ -80,7 +81,7 @@ impl App<'_> { ) -> Self { let (app_event_tx, app_event_rx) = channel(); let app_event_tx = AppEventSender::new(app_event_tx); - let pending_redraw = Arc::new(Mutex::new(false)); + let pending_redraw = Arc::new(AtomicBool::new(false)); let scroll_event_helper = ScrollEventHelper::new(app_event_tx.clone()); // Spawn a dedicated thread for reading the crossterm event loop and @@ -177,13 +178,14 @@ impl App<'_> { /// Schedule a redraw if one is not already pending. #[allow(clippy::unwrap_used)] fn schedule_redraw(&self) { + // Attempt to set the flag to `true`. If it was already `true`, another + // redraw is already pending so we can return early. + if self + .pending_redraw + .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst) + .is_err() { - #[allow(clippy::unwrap_used)] - let mut flag = self.pending_redraw.lock().unwrap(); - if *flag { - return; - } - *flag = true; + return; } let tx = self.app_event_tx.clone(); @@ -191,9 +193,7 @@ impl App<'_> { thread::spawn(move || { thread::sleep(REDRAW_DEBOUNCE); tx.send(AppEvent::Redraw); - #[allow(clippy::unwrap_used)] - let mut f = pending_redraw.lock().unwrap(); - *f = false; + pending_redraw.store(false, Ordering::SeqCst); }); } From d5a2148deb836400c1af1292d0fa7cc7d86f19d4 Mon Sep 17 00:00:00 2001 From: aibrahim-oai Date: Fri, 18 Jul 2025 12:08:25 -0700 Subject: [PATCH 3/9] Fix ctrl+c interrupt while streaming (#1617) Interrupting while streaming now causes is broken because we aren't clearing the delta buffer. --- codex-rs/tui/src/chatwidget.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/codex-rs/tui/src/chatwidget.rs b/codex-rs/tui/src/chatwidget.rs index 7c825acd41..c22bbf9704 100644 --- a/codex-rs/tui/src/chatwidget.rs +++ b/codex-rs/tui/src/chatwidget.rs @@ -464,6 +464,8 @@ impl ChatWidget<'_> { if self.bottom_pane.is_task_running() { self.bottom_pane.clear_ctrl_c_quit_hint(); self.submit_op(Op::Interrupt); + self.answer_buffer.clear(); + self.reasoning_buffer.clear(); false } else if self.bottom_pane.ctrl_c_quit_hint_visible() { true From 9846adeabf8593458bc9e3cef28e0dd6c89a59d1 Mon Sep 17 00:00:00 2001 From: aibrahim-oai Date: Fri, 18 Jul 2025 12:12:39 -0700 Subject: [PATCH 4/9] Refactor env settings into config (#1601) ## Summary - add OpenAI retry and timeout fields to Config - inject these settings in tests instead of mutating env vars - plumb Config values through client and chat completions logic - document new configuration options ## Testing - `cargo test -p codex-core --no-run` ------ https://chatgpt.com/codex/tasks/task_i_68792c5b04cc832195c03050c8b6ea94 --------- Co-authored-by: Michael Bolin --- codex-rs/config.md | 28 +++++- codex-rs/core/src/chat_completions.rs | 22 ++-- codex-rs/core/src/client.rs | 105 ++++++++++++++++---- codex-rs/core/src/codex.rs | 37 +++++-- codex-rs/core/src/config.rs | 6 ++ codex-rs/core/src/flags.rs | 8 -- codex-rs/core/src/model_provider_info.rs | 48 ++++++++- codex-rs/core/tests/cli_stream.rs | 2 +- codex-rs/core/tests/client.rs | 10 +- codex-rs/core/tests/live_agent.rs | 22 +--- codex-rs/core/tests/previous_response_id.rs | 13 ++- codex-rs/core/tests/stream_no_completed.rs | 21 ++-- 12 files changed, 228 insertions(+), 94 deletions(-) diff --git a/codex-rs/config.md b/codex-rs/config.md index 438b7e767d..3d38ded1a5 100644 --- a/codex-rs/config.md +++ b/codex-rs/config.md @@ -92,6 +92,32 @@ http_headers = { "X-Example-Header" = "example-value" } env_http_headers = { "X-Example-Features": "EXAMPLE_FEATURES" } ``` +### Per-provider network tuning + +The following optional settings control retry behaviour and streaming idle timeouts **per model provider**. They must be specified inside the corresponding `[model_providers.]` block in `config.toml`. (Older releases accepted top‑level keys; those are now ignored.) + +Example: + +```toml +[model_providers.openai] +name = "OpenAI" +base_url = "https://api.openai.com/v1" +env_key = "OPENAI_API_KEY" +# network tuning overrides (all optional; falls back to built‑in defaults) +request_max_retries = 4 # retry failed HTTP requests +stream_max_retries = 10 # retry dropped SSE streams +stream_idle_timeout_ms = 300000 # 5m idle timeout +``` + +#### request_max_retries +How many times Codex will retry a failed HTTP request to the model provider. Defaults to `4`. + +#### stream_max_retries +Number of times Codex will attempt to reconnect when a streaming response is interrupted. Defaults to `10`. + +#### stream_idle_timeout_ms +How long Codex will wait for activity on a streaming response before treating the connection as lost. Defaults to `300_000` (5 minutes). + ## model_provider Identifies which provider to use from the `model_providers` map. Defaults to `"openai"`. You can override the `base_url` for the built-in `openai` provider via the `OPENAI_BASE_URL` environment variable. @@ -444,7 +470,7 @@ Currently, `"vscode"` is the default, though Codex does not verify VS Code is in ## hide_agent_reasoning -Codex intermittently emits "reasoning" events that show the model’s internal "thinking" before it produces a final answer. Some users may find these events distracting, especially in CI logs or minimal terminal output. +Codex intermittently emits "reasoning" events that show the model's internal "thinking" before it produces a final answer. Some users may find these events distracting, especially in CI logs or minimal terminal output. Setting `hide_agent_reasoning` to `true` suppresses these events in **both** the TUI as well as the headless `exec` sub-command: diff --git a/codex-rs/core/src/chat_completions.rs b/codex-rs/core/src/chat_completions.rs index ad7b55952a..35045c8e1b 100644 --- a/codex-rs/core/src/chat_completions.rs +++ b/codex-rs/core/src/chat_completions.rs @@ -21,8 +21,6 @@ use crate::client_common::ResponseEvent; use crate::client_common::ResponseStream; use crate::error::CodexErr; use crate::error::Result; -use crate::flags::OPENAI_REQUEST_MAX_RETRIES; -use crate::flags::OPENAI_STREAM_IDLE_TIMEOUT_MS; use crate::models::ContentItem; use crate::models::ResponseItem; use crate::openai_tools::create_tools_json_for_chat_completions_api; @@ -121,6 +119,7 @@ pub(crate) async fn stream_chat_completions( ); let mut attempt = 0; + let max_retries = provider.request_max_retries(); loop { attempt += 1; @@ -136,7 +135,11 @@ pub(crate) async fn stream_chat_completions( Ok(resp) if resp.status().is_success() => { let (tx_event, rx_event) = mpsc::channel::>(1600); let stream = resp.bytes_stream().map_err(CodexErr::Reqwest); - tokio::spawn(process_chat_sse(stream, tx_event)); + tokio::spawn(process_chat_sse( + stream, + tx_event, + provider.stream_idle_timeout(), + )); return Ok(ResponseStream { rx_event }); } Ok(res) => { @@ -146,7 +149,7 @@ pub(crate) async fn stream_chat_completions( return Err(CodexErr::UnexpectedStatus(status, body)); } - if attempt > *OPENAI_REQUEST_MAX_RETRIES { + if attempt > max_retries { return Err(CodexErr::RetryLimit(status)); } @@ -162,7 +165,7 @@ pub(crate) async fn stream_chat_completions( tokio::time::sleep(delay).await; } Err(e) => { - if attempt > *OPENAI_REQUEST_MAX_RETRIES { + if attempt > max_retries { return Err(e.into()); } let delay = backoff(attempt); @@ -175,14 +178,15 @@ pub(crate) async fn stream_chat_completions( /// Lightweight SSE processor for the Chat Completions streaming format. The /// output is mapped onto Codex's internal [`ResponseEvent`] so that the rest /// of the pipeline can stay agnostic of the underlying wire format. -async fn process_chat_sse(stream: S, tx_event: mpsc::Sender>) -where +async fn process_chat_sse( + stream: S, + tx_event: mpsc::Sender>, + idle_timeout: Duration, +) where S: Stream> + Unpin, { let mut stream = stream.eventsource(); - let idle_timeout = *OPENAI_STREAM_IDLE_TIMEOUT_MS; - // State to accumulate a function call across streaming chunks. // OpenAI may split the `arguments` string over multiple `delta` events // until the chunk whose `finish_reason` is `tool_calls` is emitted. We diff --git a/codex-rs/core/src/client.rs b/codex-rs/core/src/client.rs index ae7904b8ff..62fcabe05b 100644 --- a/codex-rs/core/src/client.rs +++ b/codex-rs/core/src/client.rs @@ -30,8 +30,6 @@ use crate::config_types::ReasoningSummary as ReasoningSummaryConfig; use crate::error::CodexErr; use crate::error::Result; use crate::flags::CODEX_RS_SSE_FIXTURE; -use crate::flags::OPENAI_REQUEST_MAX_RETRIES; -use crate::flags::OPENAI_STREAM_IDLE_TIMEOUT_MS; use crate::model_provider_info::ModelProviderInfo; use crate::model_provider_info::WireApi; use crate::models::ResponseItem; @@ -113,7 +111,7 @@ impl ModelClient { if let Some(path) = &*CODEX_RS_SSE_FIXTURE { // short circuit for tests warn!(path, "Streaming from fixture"); - return stream_from_fixture(path).await; + return stream_from_fixture(path, self.provider.clone()).await; } let full_instructions = prompt.get_full_instructions(&self.config.model); @@ -140,6 +138,7 @@ impl ModelClient { ); let mut attempt = 0; + let max_retries = self.provider.request_max_retries(); loop { attempt += 1; @@ -158,7 +157,11 @@ impl ModelClient { // spawn task to process SSE let stream = resp.bytes_stream().map_err(CodexErr::Reqwest); - tokio::spawn(process_sse(stream, tx_event)); + tokio::spawn(process_sse( + stream, + tx_event, + self.provider.stream_idle_timeout(), + )); return Ok(ResponseStream { rx_event }); } @@ -177,7 +180,7 @@ impl ModelClient { return Err(CodexErr::UnexpectedStatus(status, body)); } - if attempt > *OPENAI_REQUEST_MAX_RETRIES { + if attempt > max_retries { return Err(CodexErr::RetryLimit(status)); } @@ -194,7 +197,7 @@ impl ModelClient { tokio::time::sleep(delay).await; } Err(e) => { - if attempt > *OPENAI_REQUEST_MAX_RETRIES { + if attempt > max_retries { return Err(e.into()); } let delay = backoff(attempt); @@ -203,6 +206,10 @@ impl ModelClient { } } } + + pub fn get_provider(&self) -> ModelProviderInfo { + self.provider.clone() + } } #[derive(Debug, Deserialize, Serialize)] @@ -254,14 +261,16 @@ struct ResponseCompletedOutputTokensDetails { reasoning_tokens: u64, } -async fn process_sse(stream: S, tx_event: mpsc::Sender>) -where +async fn process_sse( + stream: S, + tx_event: mpsc::Sender>, + idle_timeout: Duration, +) where S: Stream> + Unpin, { let mut stream = stream.eventsource(); // If the stream stays completely silent for an extended period treat it as disconnected. - let idle_timeout = *OPENAI_STREAM_IDLE_TIMEOUT_MS; // The response id returned from the "complete" message. let mut response_completed: Option = None; @@ -322,7 +331,7 @@ where // duplicated `output` array embedded in the `response.completed` // payload. That produced two concrete issues: // 1. No real‑time streaming – the user only saw output after the - // entire turn had finished, which broke the “typing” UX and + // entire turn had finished, which broke the "typing" UX and // made long‑running turns look stalled. // 2. Duplicate `function_call_output` items – both the // individual *and* the completed array were forwarded, which @@ -395,7 +404,10 @@ where } /// used in tests to stream from a text SSE file -async fn stream_from_fixture(path: impl AsRef) -> Result { +async fn stream_from_fixture( + path: impl AsRef, + provider: ModelProviderInfo, +) -> Result { let (tx_event, rx_event) = mpsc::channel::>(1600); let f = std::fs::File::open(path.as_ref())?; let lines = std::io::BufReader::new(f).lines(); @@ -409,7 +421,11 @@ async fn stream_from_fixture(path: impl AsRef) -> Result { let rdr = std::io::Cursor::new(content); let stream = ReaderStream::new(rdr).map_err(CodexErr::Io); - tokio::spawn(process_sse(stream, tx_event)); + tokio::spawn(process_sse( + stream, + tx_event, + provider.stream_idle_timeout(), + )); Ok(ResponseStream { rx_event }) } @@ -429,7 +445,10 @@ mod tests { /// Runs the SSE parser on pre-chunked byte slices and returns every event /// (including any final `Err` from a stream-closure check). - async fn collect_events(chunks: &[&[u8]]) -> Vec> { + async fn collect_events( + chunks: &[&[u8]], + provider: ModelProviderInfo, + ) -> Vec> { let mut builder = IoBuilder::new(); for chunk in chunks { builder.read(chunk); @@ -438,7 +457,7 @@ mod tests { let reader = builder.build(); let stream = ReaderStream::new(reader).map_err(CodexErr::Io); let (tx, mut rx) = mpsc::channel::>(16); - tokio::spawn(process_sse(stream, tx)); + tokio::spawn(process_sse(stream, tx, provider.stream_idle_timeout())); let mut events = Vec::new(); while let Some(ev) = rx.recv().await { @@ -449,7 +468,10 @@ mod tests { /// Builds an in-memory SSE stream from JSON fixtures and returns only the /// successfully parsed events (panics on internal channel errors). - async fn run_sse(events: Vec) -> Vec { + async fn run_sse( + events: Vec, + provider: ModelProviderInfo, + ) -> Vec { let mut body = String::new(); for e in events { let kind = e @@ -465,7 +487,7 @@ mod tests { let (tx, mut rx) = mpsc::channel::>(8); let stream = ReaderStream::new(std::io::Cursor::new(body)).map_err(CodexErr::Io); - tokio::spawn(process_sse(stream, tx)); + tokio::spawn(process_sse(stream, tx, provider.stream_idle_timeout())); let mut out = Vec::new(); while let Some(ev) = rx.recv().await { @@ -510,7 +532,25 @@ mod tests { let sse2 = format!("event: response.output_item.done\ndata: {item2}\n\n"); let sse3 = format!("event: response.completed\ndata: {completed}\n\n"); - let events = collect_events(&[sse1.as_bytes(), sse2.as_bytes(), sse3.as_bytes()]).await; + let provider = ModelProviderInfo { + name: "test".to_string(), + base_url: "https://test.com".to_string(), + env_key: Some("TEST_API_KEY".to_string()), + env_key_instructions: None, + wire_api: WireApi::Responses, + query_params: None, + http_headers: None, + env_http_headers: None, + request_max_retries: Some(0), + stream_max_retries: Some(0), + stream_idle_timeout_ms: Some(1000), + }; + + let events = collect_events( + &[sse1.as_bytes(), sse2.as_bytes(), sse3.as_bytes()], + provider, + ) + .await; assert_eq!(events.len(), 3); @@ -551,8 +591,21 @@ mod tests { .to_string(); let sse1 = format!("event: response.output_item.done\ndata: {item1}\n\n"); + let provider = ModelProviderInfo { + name: "test".to_string(), + base_url: "https://test.com".to_string(), + env_key: Some("TEST_API_KEY".to_string()), + env_key_instructions: None, + wire_api: WireApi::Responses, + query_params: None, + http_headers: None, + env_http_headers: None, + request_max_retries: Some(0), + stream_max_retries: Some(0), + stream_idle_timeout_ms: Some(1000), + }; - let events = collect_events(&[sse1.as_bytes()]).await; + let events = collect_events(&[sse1.as_bytes()], provider).await; assert_eq!(events.len(), 2); @@ -640,7 +693,21 @@ mod tests { let mut evs = vec![case.event]; evs.push(completed.clone()); - let out = run_sse(evs).await; + let provider = ModelProviderInfo { + name: "test".to_string(), + base_url: "https://test.com".to_string(), + env_key: Some("TEST_API_KEY".to_string()), + env_key_instructions: None, + wire_api: WireApi::Responses, + query_params: None, + http_headers: None, + env_http_headers: None, + request_max_retries: Some(0), + stream_max_retries: Some(0), + stream_idle_timeout_ms: Some(1000), + }; + + let out = run_sse(evs, provider).await; assert_eq!(out.len(), case.expected_len, "case {}", case.name); assert!( (case.expect_first)(&out[0]), diff --git a/codex-rs/core/src/codex.rs b/codex-rs/core/src/codex.rs index 246198c006..df1ffad50d 100644 --- a/codex-rs/core/src/codex.rs +++ b/codex-rs/core/src/codex.rs @@ -49,7 +49,6 @@ use crate::exec::ExecToolCallOutput; use crate::exec::SandboxType; use crate::exec::process_exec_tool_call; use crate::exec_env::create_env; -use crate::flags::OPENAI_STREAM_MAX_RETRIES; use crate::mcp_connection_manager::McpConnectionManager; use crate::mcp_tool_call::handle_mcp_tool_call; use crate::models::ContentItem; @@ -1027,12 +1026,13 @@ async fn run_turn( Err(CodexErr::Interrupted) => return Err(CodexErr::Interrupted), Err(CodexErr::EnvVar(var)) => return Err(CodexErr::EnvVar(var)), Err(e) => { - if retries < *OPENAI_STREAM_MAX_RETRIES { + // Use the configured provider-specific stream retry budget. + let max_retries = sess.client.get_provider().stream_max_retries(); + if retries < max_retries { retries += 1; let delay = backoff(retries); warn!( - "stream disconnected - retrying turn ({retries}/{} in {delay:?})...", - *OPENAI_STREAM_MAX_RETRIES + "stream disconnected - retrying turn ({retries}/{max_retries} in {delay:?})...", ); // Surface retry information to any UI/front‑end so the @@ -1041,8 +1041,7 @@ async fn run_turn( sess.notify_background_event( &sub_id, format!( - "stream error: {e}; retrying {retries}/{} in {:?}…", - *OPENAI_STREAM_MAX_RETRIES, delay + "stream error: {e}; retrying {retries}/{max_retries} in {delay:?}…" ), ) .await; @@ -1124,7 +1123,28 @@ async fn try_run_turn( let mut stream = sess.client.clone().stream(&prompt).await?; let mut output = Vec::new(); - while let Some(Ok(event)) = stream.next().await { + loop { + // Poll the next item from the model stream. We must inspect *both* Ok and Err + // cases so that transient stream failures (e.g., dropped SSE connection before + // `response.completed`) bubble up and trigger the caller's retry logic. + let event = stream.next().await; + let Some(event) = event else { + // Channel closed without yielding a final Completed event or explicit error. + // Treat as a disconnected stream so the caller can retry. + return Err(CodexErr::Stream( + "stream closed before response.completed".into(), + )); + }; + + let event = match event { + Ok(ev) => ev, + Err(e) => { + // Propagate the underlying stream error to the caller (run_turn), which + // will apply the configured `stream_max_retries` policy. + return Err(e); + } + }; + match event { ResponseEvent::Created => { let mut state = sess.state.lock().unwrap(); @@ -1165,7 +1185,7 @@ async fn try_run_turn( let mut state = sess.state.lock().unwrap(); state.previous_response_id = Some(response_id); - break; + return Ok(output); } ResponseEvent::OutputTextDelta(delta) => { let event = Event { @@ -1183,7 +1203,6 @@ async fn try_run_turn( } } } - Ok(output) } async fn handle_response_item( diff --git a/codex-rs/core/src/config.rs b/codex-rs/core/src/config.rs index d67e692fc8..d5b2845398 100644 --- a/codex-rs/core/src/config.rs +++ b/codex-rs/core/src/config.rs @@ -682,6 +682,9 @@ name = "OpenAI using Chat Completions" base_url = "https://api.openai.com/v1" env_key = "OPENAI_API_KEY" wire_api = "chat" +request_max_retries = 4 # retry failed HTTP requests +stream_max_retries = 10 # retry dropped SSE streams +stream_idle_timeout_ms = 300000 # 5m idle timeout [profiles.o3] model = "o3" @@ -722,6 +725,9 @@ disable_response_storage = true query_params: None, http_headers: None, env_http_headers: None, + request_max_retries: Some(4), + stream_max_retries: Some(10), + stream_idle_timeout_ms: Some(300_000), }; let model_provider_map = { let mut model_provider_map = built_in_model_providers(); diff --git a/codex-rs/core/src/flags.rs b/codex-rs/core/src/flags.rs index c21ef67026..c150405491 100644 --- a/codex-rs/core/src/flags.rs +++ b/codex-rs/core/src/flags.rs @@ -11,14 +11,6 @@ env_flags! { pub OPENAI_TIMEOUT_MS: Duration = Duration::from_millis(300_000), |value| { value.parse().map(Duration::from_millis) }; - pub OPENAI_REQUEST_MAX_RETRIES: u64 = 4; - pub OPENAI_STREAM_MAX_RETRIES: u64 = 10; - - // We generally don't want to disconnect; this updates the timeout to be five minutes - // which matches the upstream typescript codex impl. - pub OPENAI_STREAM_IDLE_TIMEOUT_MS: Duration = Duration::from_millis(300_000), |value| { - value.parse().map(Duration::from_millis) - }; /// Fixture path for offline tests (see client.rs). pub CODEX_RS_SSE_FIXTURE: Option<&str> = None; diff --git a/codex-rs/core/src/model_provider_info.rs b/codex-rs/core/src/model_provider_info.rs index b38c912d34..72ef58c60a 100644 --- a/codex-rs/core/src/model_provider_info.rs +++ b/codex-rs/core/src/model_provider_info.rs @@ -9,6 +9,7 @@ use serde::Deserialize; use serde::Serialize; use std::collections::HashMap; use std::env::VarError; +use std::time::Duration; use crate::error::EnvVarError; use crate::openai_api_key::get_openai_api_key; @@ -16,6 +17,9 @@ use crate::openai_api_key::get_openai_api_key; /// Value for the `OpenAI-Originator` header that is sent with requests to /// OpenAI. const OPENAI_ORIGINATOR_HEADER: &str = "codex_cli_rs"; +const DEFAULT_STREAM_IDLE_TIMEOUT_MS: u64 = 300_000; +const DEFAULT_STREAM_MAX_RETRIES: u64 = 10; +const DEFAULT_REQUEST_MAX_RETRIES: u64 = 4; /// Wire protocol that the provider speaks. Most third-party services only /// implement the classic OpenAI Chat Completions JSON schema, whereas OpenAI @@ -26,7 +30,7 @@ const OPENAI_ORIGINATOR_HEADER: &str = "codex_cli_rs"; #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "lowercase")] pub enum WireApi { - /// The experimental “Responses” API exposed by OpenAI at `/v1/responses`. + /// The experimental "Responses" API exposed by OpenAI at `/v1/responses`. Responses, /// Regular Chat Completions compatible with `/v1/chat/completions`. @@ -64,6 +68,16 @@ pub struct ModelProviderInfo { /// value should be used. If the environment variable is not set, or the /// value is empty, the header will not be included in the request. pub env_http_headers: Option>, + + /// Maximum number of times to retry a failed HTTP request to this provider. + pub request_max_retries: Option, + + /// Number of times to retry reconnecting a dropped streaming response before failing. + pub stream_max_retries: Option, + + /// Idle timeout (in milliseconds) to wait for activity on a streaming response before treating + /// the connection as lost. + pub stream_idle_timeout_ms: Option, } impl ModelProviderInfo { @@ -161,6 +175,25 @@ impl ModelProviderInfo { None => Ok(None), } } + + /// Effective maximum number of request retries for this provider. + pub fn request_max_retries(&self) -> u64 { + self.request_max_retries + .unwrap_or(DEFAULT_REQUEST_MAX_RETRIES) + } + + /// Effective maximum number of stream reconnection attempts for this provider. + pub fn stream_max_retries(&self) -> u64 { + self.stream_max_retries + .unwrap_or(DEFAULT_STREAM_MAX_RETRIES) + } + + /// Effective idle timeout for streaming responses. + pub fn stream_idle_timeout(&self) -> Duration { + self.stream_idle_timeout_ms + .map(Duration::from_millis) + .unwrap_or(Duration::from_millis(DEFAULT_STREAM_IDLE_TIMEOUT_MS)) + } } /// Built-in default provider list. @@ -205,6 +238,10 @@ pub fn built_in_model_providers() -> HashMap { .into_iter() .collect(), ), + // Use global defaults for retry/timeout unless overridden in config.toml. + request_max_retries: None, + stream_max_retries: None, + stream_idle_timeout_ms: None, }, ), ] @@ -234,6 +271,9 @@ base_url = "http://localhost:11434/v1" query_params: None, http_headers: None, env_http_headers: None, + request_max_retries: None, + stream_max_retries: None, + stream_idle_timeout_ms: None, }; let provider: ModelProviderInfo = toml::from_str(azure_provider_toml).unwrap(); @@ -259,6 +299,9 @@ query_params = { api-version = "2025-04-01-preview" } }), http_headers: None, env_http_headers: None, + request_max_retries: None, + stream_max_retries: None, + stream_idle_timeout_ms: None, }; let provider: ModelProviderInfo = toml::from_str(azure_provider_toml).unwrap(); @@ -287,6 +330,9 @@ env_http_headers = { "X-Example-Env-Header" = "EXAMPLE_ENV_VAR" } env_http_headers: Some(maplit::hashmap! { "X-Example-Env-Header".to_string() => "EXAMPLE_ENV_VAR".to_string(), }), + request_max_retries: None, + stream_max_retries: None, + stream_idle_timeout_ms: None, }; let provider: ModelProviderInfo = toml::from_str(azure_provider_toml).unwrap(); diff --git a/codex-rs/core/tests/cli_stream.rs b/codex-rs/core/tests/cli_stream.rs index 3669b93f51..23ee0a3cbc 100644 --- a/codex-rs/core/tests/cli_stream.rs +++ b/codex-rs/core/tests/cli_stream.rs @@ -173,7 +173,7 @@ async fn integration_creates_and_checks_session_file() { // 5. Sessions are written asynchronously; wait briefly for the directory to appear. let sessions_dir = home.path().join("sessions"); let start = Instant::now(); - while !sessions_dir.exists() && start.elapsed() < Duration::from_secs(2) { + while !sessions_dir.exists() && start.elapsed() < Duration::from_secs(3) { std::thread::sleep(Duration::from_millis(50)); } diff --git a/codex-rs/core/tests/client.rs b/codex-rs/core/tests/client.rs index f4fb58f5a4..964710b83f 100644 --- a/codex-rs/core/tests/client.rs +++ b/codex-rs/core/tests/client.rs @@ -49,13 +49,6 @@ async fn includes_session_id_and_model_headers_in_request() { .mount(&server) .await; - // Environment - // Update environment – `set_var` is `unsafe` starting with the 2024 - // edition so we group the calls into a single `unsafe { … }` block. - unsafe { - std::env::set_var("OPENAI_REQUEST_MAX_RETRIES", "0"); - std::env::set_var("OPENAI_STREAM_MAX_RETRIES", "0"); - } let model_provider = ModelProviderInfo { name: "openai".into(), base_url: format!("{}/v1", server.uri()), @@ -72,6 +65,9 @@ async fn includes_session_id_and_model_headers_in_request() { .collect(), ), env_http_headers: None, + request_max_retries: Some(0), + stream_max_retries: Some(0), + stream_idle_timeout_ms: None, }; // Init session diff --git a/codex-rs/core/tests/live_agent.rs b/codex-rs/core/tests/live_agent.rs index c21f9d0032..26a5539dd7 100644 --- a/codex-rs/core/tests/live_agent.rs +++ b/codex-rs/core/tests/live_agent.rs @@ -45,22 +45,10 @@ async fn spawn_codex() -> Result { "OPENAI_API_KEY must be set for live tests" ); - // Environment tweaks to keep the tests snappy and inexpensive while still - // exercising retry/robustness logic. - // - // NOTE: Starting with the 2024 edition `std::env::set_var` is `unsafe` - // because changing the process environment races with any other threads - // that might be performing environment look-ups at the same time. - // Restrict the unsafety to this tiny block that happens at the very - // beginning of the test, before we spawn any background tasks that could - // observe the environment. - unsafe { - std::env::set_var("OPENAI_REQUEST_MAX_RETRIES", "2"); - std::env::set_var("OPENAI_STREAM_MAX_RETRIES", "2"); - } - let codex_home = TempDir::new().unwrap(); - let config = load_default_config_for_test(&codex_home); + let mut config = load_default_config_for_test(&codex_home); + config.model_provider.request_max_retries = Some(2); + config.model_provider.stream_max_retries = Some(2); let (agent, _init_id) = Codex::spawn(config, std::sync::Arc::new(Notify::new())).await?; Ok(agent) @@ -79,7 +67,7 @@ async fn live_streaming_and_prev_id_reset() { let codex = spawn_codex().await.unwrap(); - // ---------- Task 1 ---------- + // ---------- Task 1 ---------- codex .submit(Op::UserInput { items: vec![InputItem::Text { @@ -113,7 +101,7 @@ async fn live_streaming_and_prev_id_reset() { "Agent did not stream any AgentMessage before TaskComplete" ); - // ---------- Task 2 (same session) ---------- + // ---------- Task 2 (same session) ---------- codex .submit(Op::UserInput { items: vec![InputItem::Text { diff --git a/codex-rs/core/tests/previous_response_id.rs b/codex-rs/core/tests/previous_response_id.rs index e64271a0ff..9630cc1028 100644 --- a/codex-rs/core/tests/previous_response_id.rs +++ b/codex-rs/core/tests/previous_response_id.rs @@ -88,13 +88,8 @@ async fn keeps_previous_response_id_between_tasks() { .mount(&server) .await; - // Environment - // Update environment – `set_var` is `unsafe` starting with the 2024 - // edition so we group the calls into a single `unsafe { … }` block. - unsafe { - std::env::set_var("OPENAI_REQUEST_MAX_RETRIES", "0"); - std::env::set_var("OPENAI_STREAM_MAX_RETRIES", "0"); - } + // Configure retry behavior explicitly to avoid mutating process-wide + // environment variables. let model_provider = ModelProviderInfo { name: "openai".into(), base_url: format!("{}/v1", server.uri()), @@ -107,6 +102,10 @@ async fn keeps_previous_response_id_between_tasks() { query_params: None, http_headers: None, env_http_headers: None, + // disable retries so we don't get duplicate calls in this test + request_max_retries: Some(0), + stream_max_retries: Some(0), + stream_idle_timeout_ms: None, }; // Init session diff --git a/codex-rs/core/tests/stream_no_completed.rs b/codex-rs/core/tests/stream_no_completed.rs index 8883eff373..f2de5de188 100644 --- a/codex-rs/core/tests/stream_no_completed.rs +++ b/codex-rs/core/tests/stream_no_completed.rs @@ -32,8 +32,6 @@ fn sse_completed(id: &str) -> String { } #[tokio::test(flavor = "multi_thread", worker_threads = 2)] -// this test is flaky (has race conditions), so we ignore it for now -#[ignore] async fn retries_on_early_close() { #![allow(clippy::unwrap_used)] @@ -72,19 +70,8 @@ async fn retries_on_early_close() { .mount(&server) .await; - // Environment - // - // As of Rust 2024 `std::env::set_var` has been made `unsafe` because - // mutating the process environment is inherently racy when other threads - // are running. We therefore have to wrap every call in an explicit - // `unsafe` block. These are limited to the test-setup section so the - // scope is very small and clearly delineated. - - unsafe { - std::env::set_var("OPENAI_REQUEST_MAX_RETRIES", "0"); - std::env::set_var("OPENAI_STREAM_MAX_RETRIES", "1"); - std::env::set_var("OPENAI_STREAM_IDLE_TIMEOUT_MS", "2000"); - } + // Configure retry behavior explicitly to avoid mutating process-wide + // environment variables. let model_provider = ModelProviderInfo { name: "openai".into(), @@ -98,6 +85,10 @@ async fn retries_on_early_close() { query_params: None, http_headers: None, env_http_headers: None, + // exercise retry path: first attempt yields incomplete stream, so allow 1 retry + request_max_retries: Some(0), + stream_max_retries: Some(1), + stream_idle_timeout_ms: Some(2000), }; let ctrl_c = std::sync::Arc::new(tokio::sync::Notify::new()); From 83eefb55fb3de54d23ce914d3e04f42909ffed9d Mon Sep 17 00:00:00 2001 From: aibrahim-oai Date: Fri, 18 Jul 2025 17:04:04 -0700 Subject: [PATCH 5/9] Add session loading support to Codex (#1602) ## Summary - extend rollout format to store all session data in JSON - add resume/write helpers for rollouts - track session state after each conversation - support `LoadSession` op to resume a previous rollout - allow starting Codex with an existing session via `experimental_resume` config variable We need a way later for exploring the available sessions in a user friendly way. ## Testing - `cargo test --no-run` *(fails: `cargo: command not found`)* ------ https://chatgpt.com/codex/tasks/task_i_68792a29dd5c832190bf6930d3466fba This video is outdated. you should use `-c experimental_resume:` instead of `--resume ` https://github.com/user-attachments/assets/7a9975c7-aa04-4f4e-899a-9e87defd947a --- codex-rs/common/src/config_override.rs | 6 +- codex-rs/core/src/codex.rs | 94 ++++++++--- codex-rs/core/src/config.rs | 14 ++ codex-rs/core/src/protocol.rs | 4 + codex-rs/core/src/rollout.rs | 212 +++++++++++++++++++------ codex-rs/core/tests/cli_stream.rs | 154 ++++++++++++++---- 6 files changed, 376 insertions(+), 108 deletions(-) diff --git a/codex-rs/common/src/config_override.rs b/codex-rs/common/src/config_override.rs index 610195d6d1..c9b18edc7c 100644 --- a/codex-rs/common/src/config_override.rs +++ b/codex-rs/common/src/config_override.rs @@ -64,7 +64,11 @@ impl CliConfigOverrides { // `-c model=o3` without the quotes. let value: Value = match parse_toml_value(value_str) { Ok(v) => v, - Err(_) => Value::String(value_str.to_string()), + Err(_) => { + // Strip leading/trailing quotes if present + let trimmed = value_str.trim().trim_matches(|c| c == '"' || c == '\''); + Value::String(trimmed.to_string()) + } }; Ok((key.to_string(), value)) diff --git a/codex-rs/core/src/codex.rs b/codex-rs/core/src/codex.rs index df1ffad50d..c82f66e939 100644 --- a/codex-rs/core/src/codex.rs +++ b/codex-rs/core/src/codex.rs @@ -102,6 +102,9 @@ impl Codex { /// of `Codex` and the ID of the `SessionInitialized` event that was /// submitted to start the session. pub async fn spawn(config: Config, ctrl_c: Arc) -> CodexResult<(Codex, String)> { + // experimental resume path (undocumented) + let resume_path = config.experimental_resume.clone(); + info!("resume_path: {resume_path:?}"); let (tx_sub, rx_sub) = async_channel::bounded(64); let (tx_event, rx_event) = async_channel::bounded(1600); @@ -117,6 +120,7 @@ impl Codex { disable_response_storage: config.disable_response_storage, notify: config.notify.clone(), cwd: config.cwd.clone(), + resume_path: resume_path.clone(), }; let config = Arc::new(config); @@ -306,24 +310,30 @@ impl Session { /// transcript, if enabled. async fn record_conversation_items(&self, items: &[ResponseItem]) { debug!("Recording items for conversation: {items:?}"); - self.record_rollout_items(items).await; + self.record_state_snapshot(items).await; if let Some(transcript) = self.state.lock().unwrap().zdr_transcript.as_mut() { transcript.record_items(items); } } - /// Append the given items to the session's rollout transcript (if enabled) - /// and persist them to disk. - async fn record_rollout_items(&self, items: &[ResponseItem]) { - // Clone the recorder outside of the mutex so we don't hold the lock - // across an await point (MutexGuard is not Send). + async fn record_state_snapshot(&self, items: &[ResponseItem]) { + let snapshot = { + let state = self.state.lock().unwrap(); + crate::rollout::SessionStateSnapshot { + previous_response_id: state.previous_response_id.clone(), + } + }; + let recorder = { let guard = self.rollout.lock().unwrap(); guard.as_ref().cloned() }; if let Some(rec) = recorder { + if let Err(e) = rec.record_state(snapshot).await { + error!("failed to record rollout state: {e:#}"); + } if let Err(e) = rec.record_items(items).await { error!("failed to record rollout items: {e:#}"); } @@ -517,7 +527,7 @@ async fn submission_loop( ctrl_c: Arc, ) { // Generate a unique ID for the lifetime of this Codex session. - let session_id = Uuid::new_v4(); + let mut session_id = Uuid::new_v4(); let mut sess: Option> = None; // shorthand - send an event when there is no active session @@ -570,8 +580,11 @@ async fn submission_loop( disable_response_storage, notify, cwd, + resume_path, } => { - info!("Configuring session: model={model}; provider={provider:?}"); + info!( + "Configuring session: model={model}; provider={provider:?}; resume={resume_path:?}" + ); if !cwd.is_absolute() { let message = format!("cwd is not absolute: {cwd:?}"); error!(message); @@ -584,6 +597,41 @@ async fn submission_loop( } return; } + // Optionally resume an existing rollout. + let mut restored_items: Option> = None; + let mut restored_prev_id: Option = None; + let rollout_recorder: Option = + if let Some(path) = resume_path.as_ref() { + match RolloutRecorder::resume(path).await { + Ok((rec, saved)) => { + session_id = saved.session_id; + restored_prev_id = saved.state.previous_response_id; + if !saved.items.is_empty() { + restored_items = Some(saved.items); + } + Some(rec) + } + Err(e) => { + warn!("failed to resume rollout from {path:?}: {e}"); + None + } + } + } else { + None + }; + + let rollout_recorder = match rollout_recorder { + Some(rec) => Some(rec), + None => match RolloutRecorder::new(&config, session_id, instructions.clone()) + .await + { + Ok(r) => Some(r), + Err(e) => { + warn!("failed to initialise rollout recorder: {e}"); + None + } + }, + }; let client = ModelClient::new( config.clone(), @@ -644,21 +692,6 @@ async fn submission_loop( }); } } - - // Attempt to create a RolloutRecorder *before* moving the - // `instructions` value into the Session struct. - // TODO: if ConfigureSession is sent twice, we will create an - // overlapping rollout file. Consider passing RolloutRecorder - // from above. - let rollout_recorder = - match RolloutRecorder::new(&config, session_id, instructions.clone()).await { - Ok(r) => Some(r), - Err(e) => { - warn!("failed to initialise rollout recorder: {e}"); - None - } - }; - sess = Some(Arc::new(Session { client, tx_event: tx_event.clone(), @@ -676,6 +709,19 @@ async fn submission_loop( codex_linux_sandbox_exe: config.codex_linux_sandbox_exe.clone(), })); + // Patch restored state into the newly created session. + if let Some(sess_arc) = &sess { + if restored_prev_id.is_some() || restored_items.is_some() { + let mut st = sess_arc.state.lock().unwrap(); + st.previous_response_id = restored_prev_id; + if let (Some(hist), Some(items)) = + (st.zdr_transcript.as_mut(), restored_items.as_ref()) + { + hist.record_items(items.iter()); + } + } + } + // Gather history metadata for SessionConfiguredEvent. let (history_log_id, history_entry_count) = crate::message_history::history_metadata(&config).await; @@ -744,6 +790,8 @@ async fn submission_loop( } } Op::AddToHistory { text } => { + // TODO: What should we do if we got AddToHistory before ConfigureSession? + // currently, if ConfigureSession has resume path, this history will be ignored let id = session_id; let config = config.clone(); tokio::spawn(async move { diff --git a/codex-rs/core/src/config.rs b/codex-rs/core/src/config.rs index d5b2845398..f1d0dd9d60 100644 --- a/codex-rs/core/src/config.rs +++ b/codex-rs/core/src/config.rs @@ -137,6 +137,9 @@ pub struct Config { /// Base URL for requests to ChatGPT (as opposed to the OpenAI API). pub chatgpt_base_url: String, + + /// Experimental rollout resume path (absolute path to .jsonl; undocumented). + pub experimental_resume: Option, } impl Config { @@ -321,6 +324,9 @@ pub struct ConfigToml { /// Base URL for requests to ChatGPT (as opposed to the OpenAI API). pub chatgpt_base_url: Option, + + /// Experimental rollout resume path (absolute path to .jsonl; undocumented). + pub experimental_resume: Option, } impl ConfigToml { @@ -448,6 +454,9 @@ impl Config { .as_ref() .map(|info| info.max_output_tokens) }); + + let experimental_resume = cfg.experimental_resume; + let config = Self { model, model_context_window, @@ -494,6 +503,8 @@ impl Config { .chatgpt_base_url .or(cfg.chatgpt_base_url) .unwrap_or("https://chatgpt.com/backend-api/".to_string()), + + experimental_resume, }; Ok(config) } @@ -806,6 +817,7 @@ disable_response_storage = true model_reasoning_summary: ReasoningSummary::Detailed, model_supports_reasoning_summaries: false, chatgpt_base_url: "https://chatgpt.com/backend-api/".to_string(), + experimental_resume: None, }, o3_profile_config ); @@ -852,6 +864,7 @@ disable_response_storage = true model_reasoning_summary: ReasoningSummary::default(), model_supports_reasoning_summaries: false, chatgpt_base_url: "https://chatgpt.com/backend-api/".to_string(), + experimental_resume: None, }; assert_eq!(expected_gpt3_profile_config, gpt3_profile_config); @@ -913,6 +926,7 @@ disable_response_storage = true model_reasoning_summary: ReasoningSummary::default(), model_supports_reasoning_summaries: false, chatgpt_base_url: "https://chatgpt.com/backend-api/".to_string(), + experimental_resume: None, }; assert_eq!(expected_zdr_profile_config, zdr_profile_config); diff --git a/codex-rs/core/src/protocol.rs b/codex-rs/core/src/protocol.rs index b233d4f27b..08d55b9749 100644 --- a/codex-rs/core/src/protocol.rs +++ b/codex-rs/core/src/protocol.rs @@ -69,6 +69,10 @@ pub enum Op { /// `ConfigureSession` operation so that the business-logic layer can /// operate deterministically. cwd: std::path::PathBuf, + + /// Path to a rollout file to resume from. + #[serde(skip_serializing_if = "Option::is_none")] + resume_path: Option, }, /// Abort current task. diff --git a/codex-rs/core/src/rollout.rs b/codex-rs/core/src/rollout.rs index 0ff2e94a3a..bb2abe45cd 100644 --- a/codex-rs/core/src/rollout.rs +++ b/codex-rs/core/src/rollout.rs @@ -1,33 +1,47 @@ -//! Functionality to persist a Codex conversation *rollout* – a linear list of -//! [`ResponseItem`] objects exchanged during a session – to disk so that -//! sessions can be replayed or inspected later (mirrors the behaviour of the -//! upstream TypeScript implementation). +//! Persist Codex session rollouts (.jsonl) so sessions can be replayed or inspected later. use std::fs::File; use std::fs::{self}; use std::io::Error as IoError; +use std::path::Path; +use serde::Deserialize; use serde::Serialize; +use serde_json::Value; use time::OffsetDateTime; use time::format_description::FormatItem; use time::macros::format_description; use tokio::io::AsyncWriteExt; use tokio::sync::mpsc::Sender; use tokio::sync::mpsc::{self}; +use tracing::info; use uuid::Uuid; use crate::config::Config; use crate::models::ResponseItem; -/// Folder inside `~/.codex` that holds saved rollouts. const SESSIONS_SUBDIR: &str = "sessions"; -#[derive(Serialize)] -struct SessionMeta { - id: String, - timestamp: String, - #[serde(skip_serializing_if = "Option::is_none")] - instructions: Option, +#[derive(Serialize, Deserialize, Clone, Default)] +pub struct SessionMeta { + pub id: Uuid, + pub timestamp: String, + pub instructions: Option, +} + +#[derive(Serialize, Deserialize, Default, Clone)] +pub struct SessionStateSnapshot { + pub previous_response_id: Option, +} + +#[derive(Serialize, Deserialize, Default, Clone)] +pub struct SavedSession { + pub session: SessionMeta, + #[serde(default)] + pub items: Vec, + #[serde(default)] + pub state: SessionStateSnapshot, + pub session_id: Uuid, } /// Records all [`ResponseItem`]s for a session and flushes them to disk after @@ -41,7 +55,13 @@ struct SessionMeta { /// ``` #[derive(Clone)] pub(crate) struct RolloutRecorder { - tx: Sender, + tx: Sender, +} + +#[derive(Clone)] +enum RolloutCmd { + AddItems(Vec), + UpdateState(SessionStateSnapshot), } impl RolloutRecorder { @@ -59,7 +79,6 @@ impl RolloutRecorder { timestamp, } = create_log_file(config, uuid)?; - // Build the static session metadata JSON first. let timestamp_format: &[FormatItem] = format_description!( "[year]-[month]-[day]T[hour]:[minute]:[second].[subsecond digits:3]Z" ); @@ -69,46 +88,29 @@ impl RolloutRecorder { let meta = SessionMeta { timestamp, - id: session_id.to_string(), + id: session_id, instructions, }; // A reasonably-sized bounded channel. If the buffer fills up the send // future will yield, which is fine – we only need to ensure we do not // perform *blocking* I/O on the caller’s thread. - let (tx, mut rx) = mpsc::channel::(256); + let (tx, rx) = mpsc::channel::(256); // Spawn a Tokio task that owns the file handle and performs async // writes. Using `tokio::fs::File` keeps everything on the async I/O // driver instead of blocking the runtime. - tokio::task::spawn(async move { - let mut file = tokio::fs::File::from_std(file); + tokio::task::spawn(rollout_writer( + tokio::fs::File::from_std(file), + rx, + Some(meta), + )); - while let Some(line) = rx.recv().await { - // Write line + newline, then flush to disk. - if let Err(e) = file.write_all(line.as_bytes()).await { - tracing::warn!("rollout writer: failed to write line: {e}"); - break; - } - if let Err(e) = file.write_all(b"\n").await { - tracing::warn!("rollout writer: failed to write newline: {e}"); - break; - } - if let Err(e) = file.flush().await { - tracing::warn!("rollout writer: failed to flush: {e}"); - break; - } - } - }); - - let recorder = Self { tx }; - // Ensure SessionMeta is the first item in the file. - recorder.record_item(&meta).await?; - Ok(recorder) + Ok(Self { tx }) } - /// Append `items` to the rollout file. pub(crate) async fn record_items(&self, items: &[ResponseItem]) -> std::io::Result<()> { + let mut filtered = Vec::new(); for item in items { match item { // Note that function calls may look a bit strange if they are @@ -117,27 +119,86 @@ impl RolloutRecorder { ResponseItem::Message { .. } | ResponseItem::LocalShellCall { .. } | ResponseItem::FunctionCall { .. } - | ResponseItem::FunctionCallOutput { .. } => {} + | ResponseItem::FunctionCallOutput { .. } => filtered.push(item.clone()), ResponseItem::Reasoning { .. } | ResponseItem::Other => { // These should never be serialized. continue; } } - self.record_item(item).await?; } - Ok(()) + if filtered.is_empty() { + return Ok(()); + } + self.tx + .send(RolloutCmd::AddItems(filtered)) + .await + .map_err(|e| IoError::other(format!("failed to queue rollout items: {e}"))) } - async fn record_item(&self, item: &impl Serialize) -> std::io::Result<()> { - // Serialize the item to JSON first so that the writer thread only has - // to perform the actual write. - let json = serde_json::to_string(item) - .map_err(|e| IoError::other(format!("failed to serialize response items: {e}")))?; - + pub(crate) async fn record_state(&self, state: SessionStateSnapshot) -> std::io::Result<()> { self.tx - .send(json) + .send(RolloutCmd::UpdateState(state)) .await - .map_err(|e| IoError::other(format!("failed to queue rollout item: {e}"))) + .map_err(|e| IoError::other(format!("failed to queue rollout state: {e}"))) + } + + pub async fn resume(path: &Path) -> std::io::Result<(Self, SavedSession)> { + info!("Resuming rollout from {path:?}"); + let text = tokio::fs::read_to_string(path).await?; + let mut lines = text.lines(); + let meta_line = lines + .next() + .ok_or_else(|| IoError::other("empty session file"))?; + let session: SessionMeta = serde_json::from_str(meta_line) + .map_err(|e| IoError::other(format!("failed to parse session meta: {e}")))?; + let mut items = Vec::new(); + let mut state = SessionStateSnapshot::default(); + + for line in lines { + if line.trim().is_empty() { + continue; + } + let v: Value = match serde_json::from_str(line) { + Ok(v) => v, + Err(_) => continue, + }; + if v.get("record_type") + .and_then(|rt| rt.as_str()) + .map(|s| s == "state") + .unwrap_or(false) + { + if let Ok(s) = serde_json::from_value::(v.clone()) { + state = s + } + continue; + } + if let Ok(item) = serde_json::from_value::(v.clone()) { + match item { + ResponseItem::Message { .. } + | ResponseItem::LocalShellCall { .. } + | ResponseItem::FunctionCall { .. } + | ResponseItem::FunctionCallOutput { .. } => items.push(item), + ResponseItem::Reasoning { .. } | ResponseItem::Other => {} + } + } + } + + let saved = SavedSession { + session: session.clone(), + items: items.clone(), + state: state.clone(), + session_id: session.id, + }; + + let file = std::fs::OpenOptions::new() + .append(true) + .read(true) + .open(path)?; + + let (tx, rx) = mpsc::channel::(256); + tokio::task::spawn(rollout_writer(tokio::fs::File::from_std(file), rx, None)); + info!("Resumed rollout successfully from {path:?}"); + Ok((Self { tx }, saved)) } } @@ -185,3 +246,54 @@ fn create_log_file(config: &Config, session_id: Uuid) -> std::io::Result, + meta: Option, +) { + if let Some(meta) = meta { + if let Ok(json) = serde_json::to_string(&meta) { + let _ = file.write_all(json.as_bytes()).await; + let _ = file.write_all(b"\n").await; + let _ = file.flush().await; + } + } + while let Some(cmd) = rx.recv().await { + match cmd { + RolloutCmd::AddItems(items) => { + for item in items { + match item { + ResponseItem::Message { .. } + | ResponseItem::LocalShellCall { .. } + | ResponseItem::FunctionCall { .. } + | ResponseItem::FunctionCallOutput { .. } => { + if let Ok(json) = serde_json::to_string(&item) { + let _ = file.write_all(json.as_bytes()).await; + let _ = file.write_all(b"\n").await; + } + } + ResponseItem::Reasoning { .. } | ResponseItem::Other => {} + } + } + let _ = file.flush().await; + } + RolloutCmd::UpdateState(state) => { + #[derive(Serialize)] + struct StateLine<'a> { + record_type: &'static str, + #[serde(flatten)] + state: &'a SessionStateSnapshot, + } + if let Ok(json) = serde_json::to_string(&StateLine { + record_type: "state", + state: &state, + }) { + let _ = file.write_all(json.as_bytes()).await; + let _ = file.write_all(b"\n").await; + let _ = file.flush().await; + } + } + } + } +} diff --git a/codex-rs/core/tests/cli_stream.rs b/codex-rs/core/tests/cli_stream.rs index 23ee0a3cbc..567279ebd0 100644 --- a/codex-rs/core/tests/cli_stream.rs +++ b/codex-rs/core/tests/cli_stream.rs @@ -2,7 +2,6 @@ use assert_cmd::Command as AssertCommand; use codex_core::exec::CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR; -use serde_json::Value; use std::time::Duration; use std::time::Instant; use tempfile::TempDir; @@ -123,6 +122,7 @@ async fn responses_api_stream_cli() { assert!(stdout.contains("fixture hello")); } +/// End-to-end: create a session (writes rollout), verify the file, then resume and confirm append. #[tokio::test(flavor = "multi_thread", worker_threads = 2)] async fn integration_creates_and_checks_session_file() { // Honor sandbox network restrictions for CI parity with the other tests. @@ -170,45 +170,66 @@ async fn integration_creates_and_checks_session_file() { String::from_utf8_lossy(&output.stderr) ); - // 5. Sessions are written asynchronously; wait briefly for the directory to appear. + // Wait for sessions dir to appear. let sessions_dir = home.path().join("sessions"); - let start = Instant::now(); - while !sessions_dir.exists() && start.elapsed() < Duration::from_secs(3) { + let dir_deadline = Instant::now() + Duration::from_secs(5); + while !sessions_dir.exists() && Instant::now() < dir_deadline { std::thread::sleep(Duration::from_millis(50)); } + assert!(sessions_dir.exists(), "sessions directory never appeared"); - // 6. Scan all session files and find the one that contains our marker. - let mut matching_files = vec![]; - for entry in WalkDir::new(&sessions_dir) { - let entry = entry.unwrap(); - if entry.file_type().is_file() && entry.file_name().to_string_lossy().ends_with(".jsonl") { + // Find the session file that contains `marker`. + let deadline = Instant::now() + Duration::from_secs(10); + let mut matching_path: Option = None; + while Instant::now() < deadline && matching_path.is_none() { + for entry in WalkDir::new(&sessions_dir) { + let entry = match entry { + Ok(e) => e, + Err(_) => continue, + }; + if !entry.file_type().is_file() { + continue; + } + if !entry.file_name().to_string_lossy().ends_with(".jsonl") { + continue; + } let path = entry.path(); - let content = std::fs::read_to_string(path).unwrap(); + let Ok(content) = std::fs::read_to_string(path) else { + continue; + }; let mut lines = content.lines(); - // Skip SessionMeta (first line) - let _ = lines.next(); + if lines.next().is_none() { + continue; + } for line in lines { - let item: Value = serde_json::from_str(line).unwrap(); - if let Some("message") = item.get("type").and_then(|t| t.as_str()) { - if let Some(content) = item.get("content") { - if content.to_string().contains(&marker) { - matching_files.push(path.to_owned()); + if line.trim().is_empty() { + continue; + } + let item: serde_json::Value = match serde_json::from_str(line) { + Ok(v) => v, + Err(_) => continue, + }; + if item.get("type").and_then(|t| t.as_str()) == Some("message") { + if let Some(c) = item.get("content") { + if c.to_string().contains(&marker) { + matching_path = Some(path.to_path_buf()); break; } } } } } + if matching_path.is_none() { + std::thread::sleep(Duration::from_millis(50)); + } } - assert_eq!( - matching_files.len(), - 1, - "Expected exactly one session file containing the marker, found {}", - matching_files.len() - ); - let path = &matching_files[0]; - // 7. Verify directory structure: sessions/YYYY/MM/DD/filename.jsonl + let path = match matching_path { + Some(p) => p, + None => panic!("No session file containing the marker was found"), + }; + + // Basic sanity checks on location and metadata. let rel = match path.strip_prefix(&sessions_dir) { Ok(r) => r, Err(_) => panic!("session file should live under sessions/"), @@ -237,7 +258,6 @@ async fn integration_creates_and_checks_session_file() { day.len() == 2 && day.chars().all(|c| c.is_ascii_digit()), "Day dir not zero-padded 2-digit numeric: {day}" ); - // Range checks (best-effort; won't fail on leading zeros) if let Ok(m) = month.parse::() { assert!((1..=12).contains(&m), "Month out of range: {m}"); } @@ -245,23 +265,32 @@ async fn integration_creates_and_checks_session_file() { assert!((1..=31).contains(&d), "Day out of range: {d}"); } - // 8. Parse SessionMeta line and basic sanity checks. - let content = std::fs::read_to_string(path).unwrap(); + let content = + std::fs::read_to_string(&path).unwrap_or_else(|_| panic!("Failed to read session file")); let mut lines = content.lines(); - let meta: Value = serde_json::from_str(lines.next().unwrap()).unwrap(); + let meta_line = lines + .next() + .ok_or("missing session meta line") + .unwrap_or_else(|_| panic!("missing session meta line")); + let meta: serde_json::Value = serde_json::from_str(meta_line) + .unwrap_or_else(|_| panic!("Failed to parse session meta line as JSON")); assert!(meta.get("id").is_some(), "SessionMeta missing id"); assert!( meta.get("timestamp").is_some(), "SessionMeta missing timestamp" ); - // 9. Confirm at least one message contains the marker. let mut found_message = false; for line in lines { - let item: Value = serde_json::from_str(line).unwrap(); - if item.get("type").map(|t| t == "message").unwrap_or(false) { - if let Some(content) = item.get("content") { - if content.to_string().contains(&marker) { + if line.trim().is_empty() { + continue; + } + let Ok(item) = serde_json::from_str::(line) else { + continue; + }; + if item.get("type").and_then(|t| t.as_str()) == Some("message") { + if let Some(c) = item.get("content") { + if c.to_string().contains(&marker) { found_message = true; break; } @@ -272,4 +301,61 @@ async fn integration_creates_and_checks_session_file() { found_message, "No message found in session file containing the marker" ); + + // Second run: resume and append. + let orig_len = content.lines().count(); + let marker2 = format!("integration-resume-{}", Uuid::new_v4()); + let prompt2 = format!("echo {marker2}"); + // Cross‑platform safe resume override. On Windows, backslashes in a TOML string must be escaped + // or the parse will fail and the raw literal (including quotes) may be preserved all the way down + // to Config, which in turn breaks resume because the path is invalid. Normalize to forward slashes + // to sidestep the issue. + let resume_path_str = path.to_string_lossy().replace('\\', "/"); + let resume_override = format!("experimental_resume=\"{resume_path_str}\""); + let mut cmd2 = AssertCommand::new("cargo"); + cmd2.arg("run") + .arg("-p") + .arg("codex-cli") + .arg("--quiet") + .arg("--") + .arg("exec") + .arg("--skip-git-repo-check") + .arg("-c") + .arg(&resume_override) + .arg("-C") + .arg(env!("CARGO_MANIFEST_DIR")) + .arg(&prompt2); + cmd2.env("CODEX_HOME", home.path()) + .env("OPENAI_API_KEY", "dummy") + .env("CODEX_RS_SSE_FIXTURE", &fixture) + .env("OPENAI_BASE_URL", "http://unused.local"); + let output2 = cmd2.output().unwrap(); + assert!(output2.status.success(), "resume codex-cli run failed"); + + // The rollout writer runs on a background async task; give it a moment to flush. + let mut new_len = orig_len; + let deadline = Instant::now() + Duration::from_secs(5); + let mut content2 = String::new(); + while Instant::now() < deadline { + if let Ok(c) = std::fs::read_to_string(&path) { + let count = c.lines().count(); + if count > orig_len { + content2 = c; + new_len = count; + break; + } + } + std::thread::sleep(Duration::from_millis(50)); + } + if content2.is_empty() { + // last attempt + content2 = std::fs::read_to_string(&path).unwrap(); + new_len = content2.lines().count(); + } + assert!(new_len > orig_len, "rollout file did not grow after resume"); + assert!(content2.contains(&marker), "rollout lost original marker"); + assert!( + content2.contains(&marker2), + "rollout missing resumed marker" + ); } From 29ff032412052be0c0090e0ed2d6a28403b3713e Mon Sep 17 00:00:00 2001 From: Michael Bolin Date: Fri, 18 Jul 2025 17:05:41 -0700 Subject: [PATCH 6/9] chore: clean up generate_mcp_types.py so codegen matches existing output --- codex-rs/mcp-types/generate_mcp_types.py | 33 +++++++++++++++++------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/codex-rs/mcp-types/generate_mcp_types.py b/codex-rs/mcp-types/generate_mcp_types.py index ff11dbf0dc..be091f411d 100755 --- a/codex-rs/mcp-types/generate_mcp_types.py +++ b/codex-rs/mcp-types/generate_mcp_types.py @@ -1,6 +1,7 @@ #!/usr/bin/env python3 # flake8: noqa: E501 +import argparse import json import subprocess import sys @@ -26,19 +27,27 @@ DEFINITIONS: dict[str, Any] = {} CLIENT_REQUEST_TYPE_NAMES: list[str] = [] # Concrete *Notification types that make up the ServerNotification enum. SERVER_NOTIFICATION_TYPE_NAMES: list[str] = [] +# Enum types that will need a `allow(clippy::large_enum_variant)` annotation in +# order to compile without warnings. +LARGE_ENUMS = {"ServerResult"} def main() -> int: - num_args = len(sys.argv) - if num_args == 1: - schema_file = ( - Path(__file__).resolve().parent / "schema" / SCHEMA_VERSION / "schema.json" - ) - elif num_args == 2: - schema_file = Path(sys.argv[1]) - else: - print("Usage: python3 codegen.py ") - return 1 + parser = argparse.ArgumentParser( + description="Embed, cluster and analyse text prompts via the OpenAI API.", + ) + + default_schema_file = ( + Path(__file__).resolve().parent / "schema" / SCHEMA_VERSION / "schema.json" + ) + parser.add_argument( + "schema_file", + nargs="?", + default=default_schema_file, + help="schema.json file to process", + ) + args = parser.parse_args() + schema_file = args.schema_file lib_rs = Path(__file__).resolve().parent / "src/lib.rs" @@ -197,6 +206,8 @@ def add_definition(name: str, definition: dict[str, Any], out: list[str]) -> Non if name.endswith("Result"): out.extend(f"impl From<{name}> for serde_json::Value {{\n") out.append(f" fn from(value: {name}) -> Self {{\n") + out.append(" // Leave this as it should never fail\n") + out.append(" #[expect(clippy::unwrap_used)]\n") out.append(" serde_json::to_value(value).unwrap()\n") out.append(" }\n") out.append("}\n\n") @@ -439,6 +450,8 @@ def define_any_of( if serde := get_serde_annotation_for_anyof_type(name): out.append(serde + "\n") + if name in LARGE_ENUMS: + out.append("#[allow(clippy::large_enum_variant)]\n") out.append(f"pub enum {name} {{\n") if name == "ClientRequest": From ed18a038b8bd51aa077efaf6e0c8ae68c8346f68 Mon Sep 17 00:00:00 2001 From: Michael Bolin Date: Fri, 18 Jul 2025 17:05:41 -0700 Subject: [PATCH 7/9] chore: support MCP schema 2025-06-18 --- codex-rs/core/src/codex.rs | 24 +- codex-rs/core/src/mcp_connection_manager.rs | 4 + codex-rs/mcp-client/src/main.rs | 2 + codex-rs/mcp-server/src/codex_tool_config.rs | 4 + codex-rs/mcp-server/src/codex_tool_runner.rs | 58 +- codex-rs/mcp-server/src/lib.rs | 2 - codex-rs/mcp-server/src/message_processor.rs | 49 +- codex-rs/mcp-types/README.md | 6 +- codex-rs/mcp-types/generate_mcp_types.py | 19 +- .../mcp-types/schema/2025-06-18/schema.json | 2517 +++++++++++++++++ .../mcp-types/schema/2025-06-18/schema.ts | 1534 ++++++++++ codex-rs/mcp-types/src/lib.rs | 269 +- codex-rs/mcp-types/tests/initialize.rs | 8 +- codex-rs/tui/src/history_cell.rs | 15 +- 14 files changed, 4343 insertions(+), 168 deletions(-) create mode 100644 codex-rs/mcp-types/schema/2025-06-18/schema.json create mode 100644 codex-rs/mcp-types/schema/2025-06-18/schema.ts diff --git a/codex-rs/core/src/codex.rs b/codex-rs/core/src/codex.rs index c82f66e939..d23981b95f 100644 --- a/codex-rs/core/src/codex.rs +++ b/codex-rs/core/src/codex.rs @@ -967,15 +967,17 @@ async fn run_task(sess: Arc, sub_id: String, input: Vec) { ) => { items_to_record_in_conversation_history.push(item); let (content, success): (String, Option) = match result { - Ok(CallToolResult { content, is_error }) => { - match serde_json::to_string(content) { - Ok(content) => (content, *is_error), - Err(e) => { - warn!("Failed to serialize MCP tool call output: {e}"); - (e.to_string(), Some(true)) - } + Ok(CallToolResult { + content, + is_error, + structured_content: _, + }) => match serde_json::to_string(content) { + Ok(content) => (content, *is_error), + Err(e) => { + warn!("Failed to serialize MCP tool call output: {e}"); + (e.to_string(), Some(true)) } - } + }, Err(e) => (e.clone(), Some(true)), }; items_to_record_in_conversation_history.push( @@ -1353,7 +1355,7 @@ async fn handle_function_call( let params = match parse_container_exec_arguments(arguments, sess, &call_id) { Ok(params) => params, Err(output) => { - return output; + return *output; } }; handle_container_exec_with_params(params, sess, sub_id, call_id).await @@ -1396,7 +1398,7 @@ fn parse_container_exec_arguments( arguments: String, sess: &Session, call_id: &str, -) -> Result { +) -> Result> { // parse command match serde_json::from_str::(&arguments) { Ok(shell_tool_call_params) => Ok(to_exec_params(shell_tool_call_params, sess)), @@ -1409,7 +1411,7 @@ fn parse_container_exec_arguments( success: None, }, }; - Err(output) + Err(Box::new(output)) } } } diff --git a/codex-rs/core/src/mcp_connection_manager.rs b/codex-rs/core/src/mcp_connection_manager.rs index c8161c9b90..cb91bc6127 100644 --- a/codex-rs/core/src/mcp_connection_manager.rs +++ b/codex-rs/core/src/mcp_connection_manager.rs @@ -135,10 +135,12 @@ impl McpConnectionManager { experimental: None, roots: None, sampling: None, + elicitation: None, }, client_info: Implementation { name: "codex-mcp-client".to_owned(), version: env!("CARGO_PKG_VERSION").to_owned(), + title: Some("Codex".into()), }, protocol_version: mcp_types::MCP_SCHEMA_VERSION.to_owned(), }; @@ -288,6 +290,8 @@ mod tests { r#type: "object".to_string(), }, name: tool_name.to_string(), + output_schema: None, + title: None, }, } } diff --git a/codex-rs/mcp-client/src/main.rs b/codex-rs/mcp-client/src/main.rs index 518383d1ea..8d671b830f 100644 --- a/codex-rs/mcp-client/src/main.rs +++ b/codex-rs/mcp-client/src/main.rs @@ -57,10 +57,12 @@ async fn main() -> Result<()> { experimental: None, roots: None, sampling: None, + elicitation: None, }, client_info: Implementation { name: "codex-mcp-client".to_owned(), version: env!("CARGO_PKG_VERSION").to_owned(), + title: Some("Codex".to_string()), }, protocol_version: MCP_SCHEMA_VERSION.to_owned(), }; diff --git a/codex-rs/mcp-server/src/codex_tool_config.rs b/codex-rs/mcp-server/src/codex_tool_config.rs index 8555524942..f54d29dd88 100644 --- a/codex-rs/mcp-server/src/codex_tool_config.rs +++ b/codex-rs/mcp-server/src/codex_tool_config.rs @@ -108,7 +108,10 @@ pub(crate) fn create_tool_for_codex_tool_call_param() -> Tool { Tool { name: "codex".to_string(), + title: Some("Codex".to_string()), input_schema: tool_input_schema, + // TODO(mbolin): This should be defined. + output_schema: None, description: Some( "Run a Codex session. Accepts configuration parameters matching the Codex Config struct.".to_string(), ), @@ -179,6 +182,7 @@ mod tests { let tool_json = serde_json::to_value(&tool).expect("tool serializes"); let expected_tool_json = serde_json::json!({ "name": "codex", + "title": "Codex", "description": "Run a Codex session. Accepts configuration parameters matching the Codex Config struct.", "inputSchema": { "type": "object", diff --git a/codex-rs/mcp-server/src/codex_tool_runner.rs b/codex-rs/mcp-server/src/codex_tool_runner.rs index 88dcf649dc..00cadcf0d8 100644 --- a/codex-rs/mcp-server/src/codex_tool_runner.rs +++ b/codex-rs/mcp-server/src/codex_tool_runner.rs @@ -12,7 +12,7 @@ use codex_core::protocol::Op; use codex_core::protocol::Submission; use codex_core::protocol::TaskCompleteEvent; use mcp_types::CallToolResult; -use mcp_types::CallToolResultContent; +use mcp_types::ContentBlock; use mcp_types::JSONRPC_VERSION; use mcp_types::JSONRPCMessage; use mcp_types::JSONRPCResponse; @@ -44,12 +44,13 @@ pub async fn run_codex_tool_session( Ok(res) => res, Err(e) => { let result = CallToolResult { - content: vec![CallToolResultContent::TextContent(TextContent { + content: vec![ContentBlock::TextContent(TextContent { r#type: "text".to_string(), text: format!("Failed to start Codex session: {e}"), annotations: None, })], is_error: Some(true), + structured_content: None, }; let _ = outgoing .send(JSONRPCMessage::Response(JSONRPCResponse { @@ -88,8 +89,6 @@ pub async fn run_codex_tool_session( tracing::error!("Failed to submit initial prompt: {e}"); } - let mut last_agent_message: Option = None; - // Stream events until the task needs to pause for user interaction or // completes. loop { @@ -98,17 +97,15 @@ pub async fn run_codex_tool_session( let _ = outgoing.send(codex_event_to_notification(&event)).await; match &event.msg { - EventMsg::AgentMessage(AgentMessageEvent { message }) => { - last_agent_message = Some(message.clone()); - } EventMsg::ExecApprovalRequest(_) => { let result = CallToolResult { - content: vec![CallToolResultContent::TextContent(TextContent { + content: vec![ContentBlock::TextContent(TextContent { r#type: "text".to_string(), text: "EXEC_APPROVAL_REQUIRED".to_string(), annotations: None, })], is_error: None, + structured_content: None, }; let _ = outgoing .send(JSONRPCMessage::Response(JSONRPCResponse { @@ -121,12 +118,13 @@ pub async fn run_codex_tool_session( } EventMsg::ApplyPatchApprovalRequest(_) => { let result = CallToolResult { - content: vec![CallToolResultContent::TextContent(TextContent { + content: vec![ContentBlock::TextContent(TextContent { r#type: "text".to_string(), text: "PATCH_APPROVAL_REQUIRED".to_string(), annotations: None, })], is_error: None, + structured_content: None, }; let _ = outgoing .send(JSONRPCMessage::Response(JSONRPCResponse { @@ -137,27 +135,19 @@ pub async fn run_codex_tool_session( .await; break; } - EventMsg::TaskComplete(TaskCompleteEvent { - last_agent_message: _, - }) => { - let result = if let Some(msg) = last_agent_message { - CallToolResult { - content: vec![CallToolResultContent::TextContent(TextContent { - r#type: "text".to_string(), - text: msg, - annotations: None, - })], - is_error: None, - } - } else { - CallToolResult { - content: vec![CallToolResultContent::TextContent(TextContent { - r#type: "text".to_string(), - text: String::new(), - annotations: None, - })], - is_error: None, - } + EventMsg::TaskComplete(TaskCompleteEvent { last_agent_message }) => { + let text = match last_agent_message { + Some(msg) => msg.clone(), + None => "".to_string(), + }; + let result = CallToolResult { + content: vec![ContentBlock::TextContent(TextContent { + r#type: "text".to_string(), + text, + annotations: None, + })], + is_error: None, + structured_content: None, }; let _ = outgoing .send(JSONRPCMessage::Response(JSONRPCResponse { @@ -177,6 +167,9 @@ pub async fn run_codex_tool_session( EventMsg::AgentReasoningDelta(_) => { // TODO: think how we want to support this in the MCP } + EventMsg::AgentMessage(AgentMessageEvent { .. }) => { + // TODO: think how we want to support this in the MCP + } EventMsg::Error(_) | EventMsg::TaskStarted | EventMsg::TokenCount(_) @@ -200,12 +193,15 @@ pub async fn run_codex_tool_session( } Err(e) => { let result = CallToolResult { - content: vec![CallToolResultContent::TextContent(TextContent { + content: vec![ContentBlock::TextContent(TextContent { r#type: "text".to_string(), text: format!("Codex runtime error: {e}"), annotations: None, })], is_error: Some(true), + // TODO(mbolin): Could present the error in a more + // structured way. + structured_content: None, }; let _ = outgoing .send(JSONRPCMessage::Response(JSONRPCResponse { diff --git a/codex-rs/mcp-server/src/lib.rs b/codex-rs/mcp-server/src/lib.rs index b2a7797fe6..db41013ab6 100644 --- a/codex-rs/mcp-server/src/lib.rs +++ b/codex-rs/mcp-server/src/lib.rs @@ -70,9 +70,7 @@ pub async fn run_main(codex_linux_sandbox_exe: Option) -> IoResult<()> JSONRPCMessage::Request(r) => processor.process_request(r), JSONRPCMessage::Response(r) => processor.process_response(r), JSONRPCMessage::Notification(n) => processor.process_notification(n), - JSONRPCMessage::BatchRequest(b) => processor.process_batch_request(b), JSONRPCMessage::Error(e) => processor.process_error(e), - JSONRPCMessage::BatchResponse(b) => processor.process_batch_response(b), } } diff --git a/codex-rs/mcp-server/src/message_processor.rs b/codex-rs/mcp-server/src/message_processor.rs index bf6f42e569..dcc6ae62f9 100644 --- a/codex-rs/mcp-server/src/message_processor.rs +++ b/codex-rs/mcp-server/src/message_processor.rs @@ -6,11 +6,9 @@ use crate::codex_tool_config::create_tool_for_codex_tool_call_param; use codex_core::config::Config as CodexConfig; use mcp_types::CallToolRequestParams; use mcp_types::CallToolResult; -use mcp_types::CallToolResultContent; use mcp_types::ClientRequest; +use mcp_types::ContentBlock; use mcp_types::JSONRPC_VERSION; -use mcp_types::JSONRPCBatchRequest; -use mcp_types::JSONRPCBatchResponse; use mcp_types::JSONRPCError; use mcp_types::JSONRPCErrorError; use mcp_types::JSONRPCMessage; @@ -145,41 +143,11 @@ impl MessageProcessor { } } - /// Handle a batch of requests and/or notifications. - pub(crate) fn process_batch_request(&mut self, batch: JSONRPCBatchRequest) { - tracing::info!("<- batch request containing {} item(s)", batch.len()); - for item in batch { - match item { - mcp_types::JSONRPCBatchRequestItem::JSONRPCRequest(req) => { - self.process_request(req); - } - mcp_types::JSONRPCBatchRequestItem::JSONRPCNotification(note) => { - self.process_notification(note); - } - } - } - } - /// Handle an error object received from the peer. pub(crate) fn process_error(&mut self, err: JSONRPCError) { tracing::error!("<- error: {:?}", err); } - /// Handle a batch of responses/errors. - pub(crate) fn process_batch_response(&mut self, batch: JSONRPCBatchResponse) { - tracing::info!("<- batch response containing {} item(s)", batch.len()); - for item in batch { - match item { - mcp_types::JSONRPCBatchResponseItem::JSONRPCResponse(resp) => { - self.process_response(resp); - } - mcp_types::JSONRPCBatchResponseItem::JSONRPCError(err) => { - self.process_error(err); - } - } - } - } - fn handle_initialize( &mut self, id: RequestId, @@ -224,6 +192,7 @@ impl MessageProcessor { server_info: mcp_types::Implementation { name: "codex-mcp-server".to_string(), version: mcp_types::MCP_SCHEMA_VERSION.to_string(), + title: Some("Codex".to_string()), }, }; @@ -333,12 +302,13 @@ impl MessageProcessor { if name != "codex" { // Tool not found – return error result so the LLM can react. let result = CallToolResult { - content: vec![CallToolResultContent::TextContent(TextContent { + content: vec![ContentBlock::TextContent(TextContent { r#type: "text".to_string(), text: format!("Unknown tool '{name}'"), annotations: None, })], is_error: Some(true), + structured_content: None, }; self.send_response::(id, result); return; @@ -350,7 +320,7 @@ impl MessageProcessor { Ok(cfg) => cfg, Err(e) => { let result = CallToolResult { - content: vec![CallToolResultContent::TextContent(TextContent { + content: vec![ContentBlock::TextContent(TextContent { r#type: "text".to_owned(), text: format!( "Failed to load Codex configuration from overrides: {e}" @@ -358,6 +328,7 @@ impl MessageProcessor { annotations: None, })], is_error: Some(true), + structured_content: None, }; self.send_response::(id, result); return; @@ -365,12 +336,13 @@ impl MessageProcessor { }, Err(e) => { let result = CallToolResult { - content: vec![CallToolResultContent::TextContent(TextContent { + content: vec![ContentBlock::TextContent(TextContent { r#type: "text".to_owned(), text: format!("Failed to parse configuration for Codex tool: {e}"), annotations: None, })], is_error: Some(true), + structured_content: None, }; self.send_response::(id, result); return; @@ -378,7 +350,7 @@ impl MessageProcessor { }, None => { let result = CallToolResult { - content: vec![CallToolResultContent::TextContent(TextContent { + content: vec![ContentBlock::TextContent(TextContent { r#type: "text".to_string(), text: "Missing arguments for codex tool-call; the `prompt` field is required." @@ -386,6 +358,7 @@ impl MessageProcessor { annotations: None, })], is_error: Some(true), + structured_content: None, }; self.send_response::(id, result); return; @@ -398,7 +371,7 @@ impl MessageProcessor { // Spawn an async task to handle the Codex session so that we do not // block the synchronous message-processing loop. task::spawn(async move { - // Run the Codex session and stream events back to the client. + // Run the Codex session and stream events Fck to the client. crate::codex_tool_runner::run_codex_tool_session(id, initial_prompt, config, outgoing) .await; }); diff --git a/codex-rs/mcp-types/README.md b/codex-rs/mcp-types/README.md index 2ac613ea96..66ea540cc4 100644 --- a/codex-rs/mcp-types/README.md +++ b/codex-rs/mcp-types/README.md @@ -2,7 +2,7 @@ Types for Model Context Protocol. Inspired by https://crates.io/crates/lsp-types. -As documented on https://modelcontextprotocol.io/specification/2025-03-26/basic: +As documented on https://modelcontextprotocol.io/specification/2025-06-18/basic: -- TypeScript schema is the source of truth: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-03-26/schema.ts -- JSON schema is amenable to automated tooling: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-03-26/schema.json +- TypeScript schema is the source of truth: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-06-18/schema.ts +- JSON schema is amenable to automated tooling: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-06-18/schema.json diff --git a/codex-rs/mcp-types/generate_mcp_types.py b/codex-rs/mcp-types/generate_mcp_types.py index be091f411d..224e04c0a5 100755 --- a/codex-rs/mcp-types/generate_mcp_types.py +++ b/codex-rs/mcp-types/generate_mcp_types.py @@ -14,7 +14,7 @@ from pathlib import Path # Helper first so it is defined when other functions call it. from typing import Any, Literal -SCHEMA_VERSION = "2025-03-26" +SCHEMA_VERSION = "2025-06-18" JSONRPC_VERSION = "2.0" STANDARD_DERIVE = "#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]\n" @@ -222,20 +222,7 @@ def add_definition(name: str, definition: dict[str, Any], out: list[str]) -> Non any_of = definition.get("anyOf", []) if any_of: assert isinstance(any_of, list) - if name == "JSONRPCMessage": - # Special case for JSONRPCMessage because its definition in the - # JSON schema does not quite match how we think about this type - # definition in Rust. - deep_copied_any_of = json.loads(json.dumps(any_of)) - deep_copied_any_of[2] = { - "$ref": "#/definitions/JSONRPCBatchRequest", - } - deep_copied_any_of[5] = { - "$ref": "#/definitions/JSONRPCBatchResponse", - } - out.extend(define_any_of(name, deep_copied_any_of, description)) - else: - out.extend(define_any_of(name, any_of, description)) + out.extend(define_any_of(name, any_of, description)) return type_prop = definition.get("type", None) @@ -609,6 +596,8 @@ def rust_prop_name(name: str, is_optional: bool) -> RustProp: prop_name = "r#type" elif name == "ref": prop_name = "r#ref" + elif name == "enum": + prop_name = "r#enum" elif snake_case := to_snake_case(name): prop_name = snake_case is_rename = True diff --git a/codex-rs/mcp-types/schema/2025-06-18/schema.json b/codex-rs/mcp-types/schema/2025-06-18/schema.json new file mode 100644 index 0000000000..24ba4f6309 --- /dev/null +++ b/codex-rs/mcp-types/schema/2025-06-18/schema.json @@ -0,0 +1,2517 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "definitions": { + "Annotations": { + "description": "Optional annotations for the client. The client can use annotations to inform how objects are used or displayed", + "properties": { + "audience": { + "description": "Describes who the intended customer of this object or data is.\n\nIt can include multiple entries to indicate content useful for multiple audiences (e.g., `[\"user\", \"assistant\"]`).", + "items": { + "$ref": "#/definitions/Role" + }, + "type": "array" + }, + "lastModified": { + "description": "The moment the resource was last modified, as an ISO 8601 formatted string.\n\nShould be an ISO 8601 formatted string (e.g., \"2025-01-12T15:00:58Z\").\n\nExamples: last activity timestamp in an open file, timestamp when the resource\nwas attached, etc.", + "type": "string" + }, + "priority": { + "description": "Describes how important this data is for operating the server.\n\nA value of 1 means \"most important,\" and indicates that the data is\neffectively required, while 0 means \"least important,\" and indicates that\nthe data is entirely optional.", + "maximum": 1, + "minimum": 0, + "type": "number" + } + }, + "type": "object" + }, + "AudioContent": { + "description": "Audio provided to or from an LLM.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "data": { + "description": "The base64-encoded audio data.", + "format": "byte", + "type": "string" + }, + "mimeType": { + "description": "The MIME type of the audio. Different providers may support different audio types.", + "type": "string" + }, + "type": { + "const": "audio", + "type": "string" + } + }, + "required": [ + "data", + "mimeType", + "type" + ], + "type": "object" + }, + "BaseMetadata": { + "description": "Base interface for metadata with name (identifier) and title (display name) properties.", + "properties": { + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "BlobResourceContents": { + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "blob": { + "description": "A base64-encoded string representing the binary data of the item.", + "format": "byte", + "type": "string" + }, + "mimeType": { + "description": "The MIME type of this resource, if known.", + "type": "string" + }, + "uri": { + "description": "The URI of this resource.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "blob", + "uri" + ], + "type": "object" + }, + "BooleanSchema": { + "properties": { + "default": { + "type": "boolean" + }, + "description": { + "type": "string" + }, + "title": { + "type": "string" + }, + "type": { + "const": "boolean", + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "CallToolRequest": { + "description": "Used by the client to invoke a tool provided by the server.", + "properties": { + "method": { + "const": "tools/call", + "type": "string" + }, + "params": { + "properties": { + "arguments": { + "additionalProperties": {}, + "type": "object" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "CallToolResult": { + "description": "The server's response to a tool call.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "content": { + "description": "A list of content objects that represent the unstructured result of the tool call.", + "items": { + "$ref": "#/definitions/ContentBlock" + }, + "type": "array" + }, + "isError": { + "description": "Whether the tool call ended in an error.\n\nIf not set, this is assumed to be false (the call was successful).\n\nAny errors that originate from the tool SHOULD be reported inside the result\nobject, with `isError` set to true, _not_ as an MCP protocol-level error\nresponse. Otherwise, the LLM would not be able to see that an error occurred\nand self-correct.\n\nHowever, any errors in _finding_ the tool, an error indicating that the\nserver does not support tool calls, or any other exceptional conditions,\nshould be reported as an MCP error response.", + "type": "boolean" + }, + "structuredContent": { + "additionalProperties": {}, + "description": "An optional JSON object that represents the structured result of the tool call.", + "type": "object" + } + }, + "required": [ + "content" + ], + "type": "object" + }, + "CancelledNotification": { + "description": "This notification can be sent by either side to indicate that it is cancelling a previously-issued request.\n\nThe request SHOULD still be in-flight, but due to communication latency, it is always possible that this notification MAY arrive after the request has already finished.\n\nThis notification indicates that the result will be unused, so any associated processing SHOULD cease.\n\nA client MUST NOT attempt to cancel its `initialize` request.", + "properties": { + "method": { + "const": "notifications/cancelled", + "type": "string" + }, + "params": { + "properties": { + "reason": { + "description": "An optional string describing the reason for the cancellation. This MAY be logged or presented to the user.", + "type": "string" + }, + "requestId": { + "$ref": "#/definitions/RequestId", + "description": "The ID of the request to cancel.\n\nThis MUST correspond to the ID of a request previously issued in the same direction." + } + }, + "required": [ + "requestId" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "ClientCapabilities": { + "description": "Capabilities a client may support. Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities.", + "properties": { + "elicitation": { + "additionalProperties": true, + "description": "Present if the client supports elicitation from the server.", + "properties": {}, + "type": "object" + }, + "experimental": { + "additionalProperties": { + "additionalProperties": true, + "properties": {}, + "type": "object" + }, + "description": "Experimental, non-standard capabilities that the client supports.", + "type": "object" + }, + "roots": { + "description": "Present if the client supports listing roots.", + "properties": { + "listChanged": { + "description": "Whether the client supports notifications for changes to the roots list.", + "type": "boolean" + } + }, + "type": "object" + }, + "sampling": { + "additionalProperties": true, + "description": "Present if the client supports sampling from an LLM.", + "properties": {}, + "type": "object" + } + }, + "type": "object" + }, + "ClientNotification": { + "anyOf": [ + { + "$ref": "#/definitions/CancelledNotification" + }, + { + "$ref": "#/definitions/InitializedNotification" + }, + { + "$ref": "#/definitions/ProgressNotification" + }, + { + "$ref": "#/definitions/RootsListChangedNotification" + } + ] + }, + "ClientRequest": { + "anyOf": [ + { + "$ref": "#/definitions/InitializeRequest" + }, + { + "$ref": "#/definitions/PingRequest" + }, + { + "$ref": "#/definitions/ListResourcesRequest" + }, + { + "$ref": "#/definitions/ListResourceTemplatesRequest" + }, + { + "$ref": "#/definitions/ReadResourceRequest" + }, + { + "$ref": "#/definitions/SubscribeRequest" + }, + { + "$ref": "#/definitions/UnsubscribeRequest" + }, + { + "$ref": "#/definitions/ListPromptsRequest" + }, + { + "$ref": "#/definitions/GetPromptRequest" + }, + { + "$ref": "#/definitions/ListToolsRequest" + }, + { + "$ref": "#/definitions/CallToolRequest" + }, + { + "$ref": "#/definitions/SetLevelRequest" + }, + { + "$ref": "#/definitions/CompleteRequest" + } + ] + }, + "ClientResult": { + "anyOf": [ + { + "$ref": "#/definitions/Result" + }, + { + "$ref": "#/definitions/CreateMessageResult" + }, + { + "$ref": "#/definitions/ListRootsResult" + }, + { + "$ref": "#/definitions/ElicitResult" + } + ] + }, + "CompleteRequest": { + "description": "A request from the client to the server, to ask for completion options.", + "properties": { + "method": { + "const": "completion/complete", + "type": "string" + }, + "params": { + "properties": { + "argument": { + "description": "The argument's information", + "properties": { + "name": { + "description": "The name of the argument", + "type": "string" + }, + "value": { + "description": "The value of the argument to use for completion matching.", + "type": "string" + } + }, + "required": [ + "name", + "value" + ], + "type": "object" + }, + "context": { + "description": "Additional, optional context for completions", + "properties": { + "arguments": { + "additionalProperties": { + "type": "string" + }, + "description": "Previously-resolved variables in a URI template or prompt.", + "type": "object" + } + }, + "type": "object" + }, + "ref": { + "anyOf": [ + { + "$ref": "#/definitions/PromptReference" + }, + { + "$ref": "#/definitions/ResourceTemplateReference" + } + ] + } + }, + "required": [ + "argument", + "ref" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "CompleteResult": { + "description": "The server's response to a completion/complete request", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "completion": { + "properties": { + "hasMore": { + "description": "Indicates whether there are additional completion options beyond those provided in the current response, even if the exact total is unknown.", + "type": "boolean" + }, + "total": { + "description": "The total number of completion options available. This can exceed the number of values actually sent in the response.", + "type": "integer" + }, + "values": { + "description": "An array of completion values. Must not exceed 100 items.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "values" + ], + "type": "object" + } + }, + "required": [ + "completion" + ], + "type": "object" + }, + "ContentBlock": { + "anyOf": [ + { + "$ref": "#/definitions/TextContent" + }, + { + "$ref": "#/definitions/ImageContent" + }, + { + "$ref": "#/definitions/AudioContent" + }, + { + "$ref": "#/definitions/ResourceLink" + }, + { + "$ref": "#/definitions/EmbeddedResource" + } + ] + }, + "CreateMessageRequest": { + "description": "A request from the server to sample an LLM via the client. The client has full discretion over which model to select. The client should also inform the user before beginning sampling, to allow them to inspect the request (human in the loop) and decide whether to approve it.", + "properties": { + "method": { + "const": "sampling/createMessage", + "type": "string" + }, + "params": { + "properties": { + "includeContext": { + "description": "A request to include context from one or more MCP servers (including the caller), to be attached to the prompt. The client MAY ignore this request.", + "enum": [ + "allServers", + "none", + "thisServer" + ], + "type": "string" + }, + "maxTokens": { + "description": "The maximum number of tokens to sample, as requested by the server. The client MAY choose to sample fewer tokens than requested.", + "type": "integer" + }, + "messages": { + "items": { + "$ref": "#/definitions/SamplingMessage" + }, + "type": "array" + }, + "metadata": { + "additionalProperties": true, + "description": "Optional metadata to pass through to the LLM provider. The format of this metadata is provider-specific.", + "properties": {}, + "type": "object" + }, + "modelPreferences": { + "$ref": "#/definitions/ModelPreferences", + "description": "The server's preferences for which model to select. The client MAY ignore these preferences." + }, + "stopSequences": { + "items": { + "type": "string" + }, + "type": "array" + }, + "systemPrompt": { + "description": "An optional system prompt the server wants to use for sampling. The client MAY modify or omit this prompt.", + "type": "string" + }, + "temperature": { + "type": "number" + } + }, + "required": [ + "maxTokens", + "messages" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "CreateMessageResult": { + "description": "The client's response to a sampling/create_message request from the server. The client should inform the user before returning the sampled message, to allow them to inspect the response (human in the loop) and decide whether to allow the server to see it.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "content": { + "anyOf": [ + { + "$ref": "#/definitions/TextContent" + }, + { + "$ref": "#/definitions/ImageContent" + }, + { + "$ref": "#/definitions/AudioContent" + } + ] + }, + "model": { + "description": "The name of the model that generated the message.", + "type": "string" + }, + "role": { + "$ref": "#/definitions/Role" + }, + "stopReason": { + "description": "The reason why sampling stopped, if known.", + "type": "string" + } + }, + "required": [ + "content", + "model", + "role" + ], + "type": "object" + }, + "Cursor": { + "description": "An opaque token used to represent a cursor for pagination.", + "type": "string" + }, + "ElicitRequest": { + "description": "A request from the server to elicit additional information from the user via the client.", + "properties": { + "method": { + "const": "elicitation/create", + "type": "string" + }, + "params": { + "properties": { + "message": { + "description": "The message to present to the user.", + "type": "string" + }, + "requestedSchema": { + "description": "A restricted subset of JSON Schema.\nOnly top-level properties are allowed, without nesting.", + "properties": { + "properties": { + "additionalProperties": { + "$ref": "#/definitions/PrimitiveSchemaDefinition" + }, + "type": "object" + }, + "required": { + "items": { + "type": "string" + }, + "type": "array" + }, + "type": { + "const": "object", + "type": "string" + } + }, + "required": [ + "properties", + "type" + ], + "type": "object" + } + }, + "required": [ + "message", + "requestedSchema" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "ElicitResult": { + "description": "The client's response to an elicitation request.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "action": { + "description": "The user action in response to the elicitation.\n- \"accept\": User submitted the form/confirmed the action\n- \"decline\": User explicitly declined the action\n- \"cancel\": User dismissed without making an explicit choice", + "enum": [ + "accept", + "cancel", + "decline" + ], + "type": "string" + }, + "content": { + "additionalProperties": { + "type": [ + "string", + "integer", + "boolean" + ] + }, + "description": "The submitted form data, only present when action is \"accept\".\nContains values matching the requested schema.", + "type": "object" + } + }, + "required": [ + "action" + ], + "type": "object" + }, + "EmbeddedResource": { + "description": "The contents of a resource, embedded into a prompt or tool call result.\n\nIt is up to the client how best to render embedded resources for the benefit\nof the LLM and/or the user.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "resource": { + "anyOf": [ + { + "$ref": "#/definitions/TextResourceContents" + }, + { + "$ref": "#/definitions/BlobResourceContents" + } + ] + }, + "type": { + "const": "resource", + "type": "string" + } + }, + "required": [ + "resource", + "type" + ], + "type": "object" + }, + "EmptyResult": { + "$ref": "#/definitions/Result" + }, + "EnumSchema": { + "properties": { + "description": { + "type": "string" + }, + "enum": { + "items": { + "type": "string" + }, + "type": "array" + }, + "enumNames": { + "items": { + "type": "string" + }, + "type": "array" + }, + "title": { + "type": "string" + }, + "type": { + "const": "string", + "type": "string" + } + }, + "required": [ + "enum", + "type" + ], + "type": "object" + }, + "GetPromptRequest": { + "description": "Used by the client to get a prompt provided by the server.", + "properties": { + "method": { + "const": "prompts/get", + "type": "string" + }, + "params": { + "properties": { + "arguments": { + "additionalProperties": { + "type": "string" + }, + "description": "Arguments to use for templating the prompt.", + "type": "object" + }, + "name": { + "description": "The name of the prompt or prompt template.", + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "GetPromptResult": { + "description": "The server's response to a prompts/get request from the client.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "description": { + "description": "An optional description for the prompt.", + "type": "string" + }, + "messages": { + "items": { + "$ref": "#/definitions/PromptMessage" + }, + "type": "array" + } + }, + "required": [ + "messages" + ], + "type": "object" + }, + "ImageContent": { + "description": "An image provided to or from an LLM.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "data": { + "description": "The base64-encoded image data.", + "format": "byte", + "type": "string" + }, + "mimeType": { + "description": "The MIME type of the image. Different providers may support different image types.", + "type": "string" + }, + "type": { + "const": "image", + "type": "string" + } + }, + "required": [ + "data", + "mimeType", + "type" + ], + "type": "object" + }, + "Implementation": { + "description": "Describes the name and version of an MCP implementation, with an optional title for UI representation.", + "properties": { + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + }, + "version": { + "type": "string" + } + }, + "required": [ + "name", + "version" + ], + "type": "object" + }, + "InitializeRequest": { + "description": "This request is sent from the client to the server when it first connects, asking it to begin initialization.", + "properties": { + "method": { + "const": "initialize", + "type": "string" + }, + "params": { + "properties": { + "capabilities": { + "$ref": "#/definitions/ClientCapabilities" + }, + "clientInfo": { + "$ref": "#/definitions/Implementation" + }, + "protocolVersion": { + "description": "The latest version of the Model Context Protocol that the client supports. The client MAY decide to support older versions as well.", + "type": "string" + } + }, + "required": [ + "capabilities", + "clientInfo", + "protocolVersion" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "InitializeResult": { + "description": "After receiving an initialize request from the client, the server sends this response.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "capabilities": { + "$ref": "#/definitions/ServerCapabilities" + }, + "instructions": { + "description": "Instructions describing how to use the server and its features.\n\nThis can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a \"hint\" to the model. For example, this information MAY be added to the system prompt.", + "type": "string" + }, + "protocolVersion": { + "description": "The version of the Model Context Protocol that the server wants to use. This may not match the version that the client requested. If the client cannot support this version, it MUST disconnect.", + "type": "string" + }, + "serverInfo": { + "$ref": "#/definitions/Implementation" + } + }, + "required": [ + "capabilities", + "protocolVersion", + "serverInfo" + ], + "type": "object" + }, + "InitializedNotification": { + "description": "This notification is sent from the client to the server after initialization has finished.", + "properties": { + "method": { + "const": "notifications/initialized", + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "JSONRPCError": { + "description": "A response to a request that indicates an error occurred.", + "properties": { + "error": { + "properties": { + "code": { + "description": "The error type that occurred.", + "type": "integer" + }, + "data": { + "description": "Additional information about the error. The value of this member is defined by the sender (e.g. detailed error information, nested errors etc.)." + }, + "message": { + "description": "A short description of the error. The message SHOULD be limited to a concise single sentence.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" + }, + "id": { + "$ref": "#/definitions/RequestId" + }, + "jsonrpc": { + "const": "2.0", + "type": "string" + } + }, + "required": [ + "error", + "id", + "jsonrpc" + ], + "type": "object" + }, + "JSONRPCMessage": { + "anyOf": [ + { + "$ref": "#/definitions/JSONRPCRequest" + }, + { + "$ref": "#/definitions/JSONRPCNotification" + }, + { + "$ref": "#/definitions/JSONRPCResponse" + }, + { + "$ref": "#/definitions/JSONRPCError" + } + ], + "description": "Refers to any valid JSON-RPC object that can be decoded off the wire, or encoded to be sent." + }, + "JSONRPCNotification": { + "description": "A notification which does not expect a response.", + "properties": { + "jsonrpc": { + "const": "2.0", + "type": "string" + }, + "method": { + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "jsonrpc", + "method" + ], + "type": "object" + }, + "JSONRPCRequest": { + "description": "A request that expects a response.", + "properties": { + "id": { + "$ref": "#/definitions/RequestId" + }, + "jsonrpc": { + "const": "2.0", + "type": "string" + }, + "method": { + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "progressToken": { + "$ref": "#/definitions/ProgressToken", + "description": "If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications." + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "id", + "jsonrpc", + "method" + ], + "type": "object" + }, + "JSONRPCResponse": { + "description": "A successful (non-error) response to a request.", + "properties": { + "id": { + "$ref": "#/definitions/RequestId" + }, + "jsonrpc": { + "const": "2.0", + "type": "string" + }, + "result": { + "$ref": "#/definitions/Result" + } + }, + "required": [ + "id", + "jsonrpc", + "result" + ], + "type": "object" + }, + "ListPromptsRequest": { + "description": "Sent from the client to request a list of prompts and prompt templates the server has.", + "properties": { + "method": { + "const": "prompts/list", + "type": "string" + }, + "params": { + "properties": { + "cursor": { + "description": "An opaque token representing the current pagination position.\nIf provided, the server should return results starting after this cursor.", + "type": "string" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "ListPromptsResult": { + "description": "The server's response to a prompts/list request from the client.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "nextCursor": { + "description": "An opaque token representing the pagination position after the last returned result.\nIf present, there may be more results available.", + "type": "string" + }, + "prompts": { + "items": { + "$ref": "#/definitions/Prompt" + }, + "type": "array" + } + }, + "required": [ + "prompts" + ], + "type": "object" + }, + "ListResourceTemplatesRequest": { + "description": "Sent from the client to request a list of resource templates the server has.", + "properties": { + "method": { + "const": "resources/templates/list", + "type": "string" + }, + "params": { + "properties": { + "cursor": { + "description": "An opaque token representing the current pagination position.\nIf provided, the server should return results starting after this cursor.", + "type": "string" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "ListResourceTemplatesResult": { + "description": "The server's response to a resources/templates/list request from the client.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "nextCursor": { + "description": "An opaque token representing the pagination position after the last returned result.\nIf present, there may be more results available.", + "type": "string" + }, + "resourceTemplates": { + "items": { + "$ref": "#/definitions/ResourceTemplate" + }, + "type": "array" + } + }, + "required": [ + "resourceTemplates" + ], + "type": "object" + }, + "ListResourcesRequest": { + "description": "Sent from the client to request a list of resources the server has.", + "properties": { + "method": { + "const": "resources/list", + "type": "string" + }, + "params": { + "properties": { + "cursor": { + "description": "An opaque token representing the current pagination position.\nIf provided, the server should return results starting after this cursor.", + "type": "string" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "ListResourcesResult": { + "description": "The server's response to a resources/list request from the client.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "nextCursor": { + "description": "An opaque token representing the pagination position after the last returned result.\nIf present, there may be more results available.", + "type": "string" + }, + "resources": { + "items": { + "$ref": "#/definitions/Resource" + }, + "type": "array" + } + }, + "required": [ + "resources" + ], + "type": "object" + }, + "ListRootsRequest": { + "description": "Sent from the server to request a list of root URIs from the client. Roots allow\nservers to ask for specific directories or files to operate on. A common example\nfor roots is providing a set of repositories or directories a server should operate\non.\n\nThis request is typically used when the server needs to understand the file system\nstructure or access specific locations that the client has permission to read from.", + "properties": { + "method": { + "const": "roots/list", + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "progressToken": { + "$ref": "#/definitions/ProgressToken", + "description": "If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications." + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "ListRootsResult": { + "description": "The client's response to a roots/list request from the server.\nThis result contains an array of Root objects, each representing a root directory\nor file that the server can operate on.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "roots": { + "items": { + "$ref": "#/definitions/Root" + }, + "type": "array" + } + }, + "required": [ + "roots" + ], + "type": "object" + }, + "ListToolsRequest": { + "description": "Sent from the client to request a list of tools the server has.", + "properties": { + "method": { + "const": "tools/list", + "type": "string" + }, + "params": { + "properties": { + "cursor": { + "description": "An opaque token representing the current pagination position.\nIf provided, the server should return results starting after this cursor.", + "type": "string" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "ListToolsResult": { + "description": "The server's response to a tools/list request from the client.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "nextCursor": { + "description": "An opaque token representing the pagination position after the last returned result.\nIf present, there may be more results available.", + "type": "string" + }, + "tools": { + "items": { + "$ref": "#/definitions/Tool" + }, + "type": "array" + } + }, + "required": [ + "tools" + ], + "type": "object" + }, + "LoggingLevel": { + "description": "The severity of a log message.\n\nThese map to syslog message severities, as specified in RFC-5424:\nhttps://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1", + "enum": [ + "alert", + "critical", + "debug", + "emergency", + "error", + "info", + "notice", + "warning" + ], + "type": "string" + }, + "LoggingMessageNotification": { + "description": "Notification of a log message passed from server to client. If no logging/setLevel request has been sent from the client, the server MAY decide which messages to send automatically.", + "properties": { + "method": { + "const": "notifications/message", + "type": "string" + }, + "params": { + "properties": { + "data": { + "description": "The data to be logged, such as a string message or an object. Any JSON serializable type is allowed here." + }, + "level": { + "$ref": "#/definitions/LoggingLevel", + "description": "The severity of this log message." + }, + "logger": { + "description": "An optional name of the logger issuing this message.", + "type": "string" + } + }, + "required": [ + "data", + "level" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "ModelHint": { + "description": "Hints to use for model selection.\n\nKeys not declared here are currently left unspecified by the spec and are up\nto the client to interpret.", + "properties": { + "name": { + "description": "A hint for a model name.\n\nThe client SHOULD treat this as a substring of a model name; for example:\n - `claude-3-5-sonnet` should match `claude-3-5-sonnet-20241022`\n - `sonnet` should match `claude-3-5-sonnet-20241022`, `claude-3-sonnet-20240229`, etc.\n - `claude` should match any Claude model\n\nThe client MAY also map the string to a different provider's model name or a different model family, as long as it fills a similar niche; for example:\n - `gemini-1.5-flash` could match `claude-3-haiku-20240307`", + "type": "string" + } + }, + "type": "object" + }, + "ModelPreferences": { + "description": "The server's preferences for model selection, requested of the client during sampling.\n\nBecause LLMs can vary along multiple dimensions, choosing the \"best\" model is\nrarely straightforward. Different models excel in different areas—some are\nfaster but less capable, others are more capable but more expensive, and so\non. This interface allows servers to express their priorities across multiple\ndimensions to help clients make an appropriate selection for their use case.\n\nThese preferences are always advisory. The client MAY ignore them. It is also\nup to the client to decide how to interpret these preferences and how to\nbalance them against other considerations.", + "properties": { + "costPriority": { + "description": "How much to prioritize cost when selecting a model. A value of 0 means cost\nis not important, while a value of 1 means cost is the most important\nfactor.", + "maximum": 1, + "minimum": 0, + "type": "number" + }, + "hints": { + "description": "Optional hints to use for model selection.\n\nIf multiple hints are specified, the client MUST evaluate them in order\n(such that the first match is taken).\n\nThe client SHOULD prioritize these hints over the numeric priorities, but\nMAY still use the priorities to select from ambiguous matches.", + "items": { + "$ref": "#/definitions/ModelHint" + }, + "type": "array" + }, + "intelligencePriority": { + "description": "How much to prioritize intelligence and capabilities when selecting a\nmodel. A value of 0 means intelligence is not important, while a value of 1\nmeans intelligence is the most important factor.", + "maximum": 1, + "minimum": 0, + "type": "number" + }, + "speedPriority": { + "description": "How much to prioritize sampling speed (latency) when selecting a model. A\nvalue of 0 means speed is not important, while a value of 1 means speed is\nthe most important factor.", + "maximum": 1, + "minimum": 0, + "type": "number" + } + }, + "type": "object" + }, + "Notification": { + "properties": { + "method": { + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "NumberSchema": { + "properties": { + "description": { + "type": "string" + }, + "maximum": { + "type": "integer" + }, + "minimum": { + "type": "integer" + }, + "title": { + "type": "string" + }, + "type": { + "enum": [ + "integer", + "number" + ], + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "PaginatedRequest": { + "properties": { + "method": { + "type": "string" + }, + "params": { + "properties": { + "cursor": { + "description": "An opaque token representing the current pagination position.\nIf provided, the server should return results starting after this cursor.", + "type": "string" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "PaginatedResult": { + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "nextCursor": { + "description": "An opaque token representing the pagination position after the last returned result.\nIf present, there may be more results available.", + "type": "string" + } + }, + "type": "object" + }, + "PingRequest": { + "description": "A ping, issued by either the server or the client, to check that the other party is still alive. The receiver must promptly respond, or else may be disconnected.", + "properties": { + "method": { + "const": "ping", + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "progressToken": { + "$ref": "#/definitions/ProgressToken", + "description": "If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications." + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "PrimitiveSchemaDefinition": { + "anyOf": [ + { + "$ref": "#/definitions/StringSchema" + }, + { + "$ref": "#/definitions/NumberSchema" + }, + { + "$ref": "#/definitions/BooleanSchema" + }, + { + "$ref": "#/definitions/EnumSchema" + } + ], + "description": "Restricted schema definitions that only allow primitive types\nwithout nested objects or arrays." + }, + "ProgressNotification": { + "description": "An out-of-band notification used to inform the receiver of a progress update for a long-running request.", + "properties": { + "method": { + "const": "notifications/progress", + "type": "string" + }, + "params": { + "properties": { + "message": { + "description": "An optional message describing the current progress.", + "type": "string" + }, + "progress": { + "description": "The progress thus far. This should increase every time progress is made, even if the total is unknown.", + "type": "number" + }, + "progressToken": { + "$ref": "#/definitions/ProgressToken", + "description": "The progress token which was given in the initial request, used to associate this notification with the request that is proceeding." + }, + "total": { + "description": "Total number of items to process (or total progress required), if known.", + "type": "number" + } + }, + "required": [ + "progress", + "progressToken" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "ProgressToken": { + "description": "A progress token, used to associate progress notifications with the original request.", + "type": [ + "string", + "integer" + ] + }, + "Prompt": { + "description": "A prompt or prompt template that the server offers.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "arguments": { + "description": "A list of arguments to use for templating the prompt.", + "items": { + "$ref": "#/definitions/PromptArgument" + }, + "type": "array" + }, + "description": { + "description": "An optional description of what this prompt provides", + "type": "string" + }, + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "PromptArgument": { + "description": "Describes an argument that a prompt can accept.", + "properties": { + "description": { + "description": "A human-readable description of the argument.", + "type": "string" + }, + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "required": { + "description": "Whether this argument must be provided.", + "type": "boolean" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "PromptListChangedNotification": { + "description": "An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This may be issued by servers without any previous subscription from the client.", + "properties": { + "method": { + "const": "notifications/prompts/list_changed", + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "PromptMessage": { + "description": "Describes a message returned as part of a prompt.\n\nThis is similar to `SamplingMessage`, but also supports the embedding of\nresources from the MCP server.", + "properties": { + "content": { + "$ref": "#/definitions/ContentBlock" + }, + "role": { + "$ref": "#/definitions/Role" + } + }, + "required": [ + "content", + "role" + ], + "type": "object" + }, + "PromptReference": { + "description": "Identifies a prompt.", + "properties": { + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + }, + "type": { + "const": "ref/prompt", + "type": "string" + } + }, + "required": [ + "name", + "type" + ], + "type": "object" + }, + "ReadResourceRequest": { + "description": "Sent from the client to the server, to read a specific resource URI.", + "properties": { + "method": { + "const": "resources/read", + "type": "string" + }, + "params": { + "properties": { + "uri": { + "description": "The URI of the resource to read. The URI can use any protocol; it is up to the server how to interpret it.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "uri" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "ReadResourceResult": { + "description": "The server's response to a resources/read request from the client.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "contents": { + "items": { + "anyOf": [ + { + "$ref": "#/definitions/TextResourceContents" + }, + { + "$ref": "#/definitions/BlobResourceContents" + } + ] + }, + "type": "array" + } + }, + "required": [ + "contents" + ], + "type": "object" + }, + "Request": { + "properties": { + "method": { + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "progressToken": { + "$ref": "#/definitions/ProgressToken", + "description": "If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications." + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "RequestId": { + "description": "A uniquely identifying ID for a request in JSON-RPC.", + "type": [ + "string", + "integer" + ] + }, + "Resource": { + "description": "A known resource that the server is capable of reading.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "description": { + "description": "A description of what this resource represents.\n\nThis can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a \"hint\" to the model.", + "type": "string" + }, + "mimeType": { + "description": "The MIME type of this resource, if known.", + "type": "string" + }, + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "size": { + "description": "The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.\n\nThis can be used by Hosts to display file sizes and estimate context window usage.", + "type": "integer" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + }, + "uri": { + "description": "The URI of this resource.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "name", + "uri" + ], + "type": "object" + }, + "ResourceContents": { + "description": "The contents of a specific resource or sub-resource.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "mimeType": { + "description": "The MIME type of this resource, if known.", + "type": "string" + }, + "uri": { + "description": "The URI of this resource.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "uri" + ], + "type": "object" + }, + "ResourceLink": { + "description": "A resource that the server is capable of reading, included in a prompt or tool call result.\n\nNote: resource links returned by tools are not guaranteed to appear in the results of `resources/list` requests.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "description": { + "description": "A description of what this resource represents.\n\nThis can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a \"hint\" to the model.", + "type": "string" + }, + "mimeType": { + "description": "The MIME type of this resource, if known.", + "type": "string" + }, + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "size": { + "description": "The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.\n\nThis can be used by Hosts to display file sizes and estimate context window usage.", + "type": "integer" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + }, + "type": { + "const": "resource_link", + "type": "string" + }, + "uri": { + "description": "The URI of this resource.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "name", + "type", + "uri" + ], + "type": "object" + }, + "ResourceListChangedNotification": { + "description": "An optional notification from the server to the client, informing it that the list of resources it can read from has changed. This may be issued by servers without any previous subscription from the client.", + "properties": { + "method": { + "const": "notifications/resources/list_changed", + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "ResourceTemplate": { + "description": "A template description for resources available on the server.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "description": { + "description": "A description of what this template is for.\n\nThis can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a \"hint\" to the model.", + "type": "string" + }, + "mimeType": { + "description": "The MIME type for all resources that match this template. This should only be included if all resources matching this template have the same type.", + "type": "string" + }, + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + }, + "uriTemplate": { + "description": "A URI template (according to RFC 6570) that can be used to construct resource URIs.", + "format": "uri-template", + "type": "string" + } + }, + "required": [ + "name", + "uriTemplate" + ], + "type": "object" + }, + "ResourceTemplateReference": { + "description": "A reference to a resource or resource template definition.", + "properties": { + "type": { + "const": "ref/resource", + "type": "string" + }, + "uri": { + "description": "The URI or URI template of the resource.", + "format": "uri-template", + "type": "string" + } + }, + "required": [ + "type", + "uri" + ], + "type": "object" + }, + "ResourceUpdatedNotification": { + "description": "A notification from the server to the client, informing it that a resource has changed and may need to be read again. This should only be sent if the client previously sent a resources/subscribe request.", + "properties": { + "method": { + "const": "notifications/resources/updated", + "type": "string" + }, + "params": { + "properties": { + "uri": { + "description": "The URI of the resource that has been updated. This might be a sub-resource of the one that the client actually subscribed to.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "uri" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "Result": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + } + }, + "type": "object" + }, + "Role": { + "description": "The sender or recipient of messages and data in a conversation.", + "enum": [ + "assistant", + "user" + ], + "type": "string" + }, + "Root": { + "description": "Represents a root directory or file that the server can operate on.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "name": { + "description": "An optional name for the root. This can be used to provide a human-readable\nidentifier for the root, which may be useful for display purposes or for\nreferencing the root in other parts of the application.", + "type": "string" + }, + "uri": { + "description": "The URI identifying the root. This *must* start with file:// for now.\nThis restriction may be relaxed in future versions of the protocol to allow\nother URI schemes.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "uri" + ], + "type": "object" + }, + "RootsListChangedNotification": { + "description": "A notification from the client to the server, informing it that the list of roots has changed.\nThis notification should be sent whenever the client adds, removes, or modifies any root.\nThe server should then request an updated list of roots using the ListRootsRequest.", + "properties": { + "method": { + "const": "notifications/roots/list_changed", + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "SamplingMessage": { + "description": "Describes a message issued to or received from an LLM API.", + "properties": { + "content": { + "anyOf": [ + { + "$ref": "#/definitions/TextContent" + }, + { + "$ref": "#/definitions/ImageContent" + }, + { + "$ref": "#/definitions/AudioContent" + } + ] + }, + "role": { + "$ref": "#/definitions/Role" + } + }, + "required": [ + "content", + "role" + ], + "type": "object" + }, + "ServerCapabilities": { + "description": "Capabilities that a server may support. Known capabilities are defined here, in this schema, but this is not a closed set: any server can define its own, additional capabilities.", + "properties": { + "completions": { + "additionalProperties": true, + "description": "Present if the server supports argument autocompletion suggestions.", + "properties": {}, + "type": "object" + }, + "experimental": { + "additionalProperties": { + "additionalProperties": true, + "properties": {}, + "type": "object" + }, + "description": "Experimental, non-standard capabilities that the server supports.", + "type": "object" + }, + "logging": { + "additionalProperties": true, + "description": "Present if the server supports sending log messages to the client.", + "properties": {}, + "type": "object" + }, + "prompts": { + "description": "Present if the server offers any prompt templates.", + "properties": { + "listChanged": { + "description": "Whether this server supports notifications for changes to the prompt list.", + "type": "boolean" + } + }, + "type": "object" + }, + "resources": { + "description": "Present if the server offers any resources to read.", + "properties": { + "listChanged": { + "description": "Whether this server supports notifications for changes to the resource list.", + "type": "boolean" + }, + "subscribe": { + "description": "Whether this server supports subscribing to resource updates.", + "type": "boolean" + } + }, + "type": "object" + }, + "tools": { + "description": "Present if the server offers any tools to call.", + "properties": { + "listChanged": { + "description": "Whether this server supports notifications for changes to the tool list.", + "type": "boolean" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "ServerNotification": { + "anyOf": [ + { + "$ref": "#/definitions/CancelledNotification" + }, + { + "$ref": "#/definitions/ProgressNotification" + }, + { + "$ref": "#/definitions/ResourceListChangedNotification" + }, + { + "$ref": "#/definitions/ResourceUpdatedNotification" + }, + { + "$ref": "#/definitions/PromptListChangedNotification" + }, + { + "$ref": "#/definitions/ToolListChangedNotification" + }, + { + "$ref": "#/definitions/LoggingMessageNotification" + } + ] + }, + "ServerRequest": { + "anyOf": [ + { + "$ref": "#/definitions/PingRequest" + }, + { + "$ref": "#/definitions/CreateMessageRequest" + }, + { + "$ref": "#/definitions/ListRootsRequest" + }, + { + "$ref": "#/definitions/ElicitRequest" + } + ] + }, + "ServerResult": { + "anyOf": [ + { + "$ref": "#/definitions/Result" + }, + { + "$ref": "#/definitions/InitializeResult" + }, + { + "$ref": "#/definitions/ListResourcesResult" + }, + { + "$ref": "#/definitions/ListResourceTemplatesResult" + }, + { + "$ref": "#/definitions/ReadResourceResult" + }, + { + "$ref": "#/definitions/ListPromptsResult" + }, + { + "$ref": "#/definitions/GetPromptResult" + }, + { + "$ref": "#/definitions/ListToolsResult" + }, + { + "$ref": "#/definitions/CallToolResult" + }, + { + "$ref": "#/definitions/CompleteResult" + } + ] + }, + "SetLevelRequest": { + "description": "A request from the client to the server, to enable or adjust logging.", + "properties": { + "method": { + "const": "logging/setLevel", + "type": "string" + }, + "params": { + "properties": { + "level": { + "$ref": "#/definitions/LoggingLevel", + "description": "The level of logging that the client wants to receive from the server. The server should send all logs at this level and higher (i.e., more severe) to the client as notifications/message." + } + }, + "required": [ + "level" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "StringSchema": { + "properties": { + "description": { + "type": "string" + }, + "format": { + "enum": [ + "date", + "date-time", + "email", + "uri" + ], + "type": "string" + }, + "maxLength": { + "type": "integer" + }, + "minLength": { + "type": "integer" + }, + "title": { + "type": "string" + }, + "type": { + "const": "string", + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "SubscribeRequest": { + "description": "Sent from the client to request resources/updated notifications from the server whenever a particular resource changes.", + "properties": { + "method": { + "const": "resources/subscribe", + "type": "string" + }, + "params": { + "properties": { + "uri": { + "description": "The URI of the resource to subscribe to. The URI can use any protocol; it is up to the server how to interpret it.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "uri" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "TextContent": { + "description": "Text provided to or from an LLM.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "text": { + "description": "The text content of the message.", + "type": "string" + }, + "type": { + "const": "text", + "type": "string" + } + }, + "required": [ + "text", + "type" + ], + "type": "object" + }, + "TextResourceContents": { + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "mimeType": { + "description": "The MIME type of this resource, if known.", + "type": "string" + }, + "text": { + "description": "The text of the item. This must only be set if the item can actually be represented as text (not binary data).", + "type": "string" + }, + "uri": { + "description": "The URI of this resource.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "text", + "uri" + ], + "type": "object" + }, + "Tool": { + "description": "Definition for a tool the client can call.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/ToolAnnotations", + "description": "Optional additional tool information.\n\nDisplay name precedence order is: title, annotations.title, then name." + }, + "description": { + "description": "A human-readable description of the tool.\n\nThis can be used by clients to improve the LLM's understanding of available tools. It can be thought of like a \"hint\" to the model.", + "type": "string" + }, + "inputSchema": { + "description": "A JSON Schema object defining the expected parameters for the tool.", + "properties": { + "properties": { + "additionalProperties": { + "additionalProperties": true, + "properties": {}, + "type": "object" + }, + "type": "object" + }, + "required": { + "items": { + "type": "string" + }, + "type": "array" + }, + "type": { + "const": "object", + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "outputSchema": { + "description": "An optional JSON Schema object defining the structure of the tool's output returned in\nthe structuredContent field of a CallToolResult.", + "properties": { + "properties": { + "additionalProperties": { + "additionalProperties": true, + "properties": {}, + "type": "object" + }, + "type": "object" + }, + "required": { + "items": { + "type": "string" + }, + "type": "array" + }, + "type": { + "const": "object", + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + } + }, + "required": [ + "inputSchema", + "name" + ], + "type": "object" + }, + "ToolAnnotations": { + "description": "Additional properties describing a Tool to clients.\n\nNOTE: all properties in ToolAnnotations are **hints**.\nThey are not guaranteed to provide a faithful description of\ntool behavior (including descriptive properties like `title`).\n\nClients should never make tool use decisions based on ToolAnnotations\nreceived from untrusted servers.", + "properties": { + "destructiveHint": { + "description": "If true, the tool may perform destructive updates to its environment.\nIf false, the tool performs only additive updates.\n\n(This property is meaningful only when `readOnlyHint == false`)\n\nDefault: true", + "type": "boolean" + }, + "idempotentHint": { + "description": "If true, calling the tool repeatedly with the same arguments\nwill have no additional effect on the its environment.\n\n(This property is meaningful only when `readOnlyHint == false`)\n\nDefault: false", + "type": "boolean" + }, + "openWorldHint": { + "description": "If true, this tool may interact with an \"open world\" of external\nentities. If false, the tool's domain of interaction is closed.\nFor example, the world of a web search tool is open, whereas that\nof a memory tool is not.\n\nDefault: true", + "type": "boolean" + }, + "readOnlyHint": { + "description": "If true, the tool does not modify its environment.\n\nDefault: false", + "type": "boolean" + }, + "title": { + "description": "A human-readable title for the tool.", + "type": "string" + } + }, + "type": "object" + }, + "ToolListChangedNotification": { + "description": "An optional notification from the server to the client, informing it that the list of tools it offers has changed. This may be issued by servers without any previous subscription from the client.", + "properties": { + "method": { + "const": "notifications/tools/list_changed", + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "UnsubscribeRequest": { + "description": "Sent from the client to request cancellation of resources/updated notifications from the server. This should follow a previous resources/subscribe request.", + "properties": { + "method": { + "const": "resources/unsubscribe", + "type": "string" + }, + "params": { + "properties": { + "uri": { + "description": "The URI of the resource to unsubscribe from.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "uri" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + } + } +} + diff --git a/codex-rs/mcp-types/schema/2025-06-18/schema.ts b/codex-rs/mcp-types/schema/2025-06-18/schema.ts new file mode 100644 index 0000000000..ea3fe5b44f --- /dev/null +++ b/codex-rs/mcp-types/schema/2025-06-18/schema.ts @@ -0,0 +1,1534 @@ +/* JSON-RPC types */ + +/** + * Refers to any valid JSON-RPC object that can be decoded off the wire, or encoded to be sent. + * + * @internal + */ +export type JSONRPCMessage = + | JSONRPCRequest + | JSONRPCNotification + | JSONRPCResponse + | JSONRPCError; + +/** @internal */ +export const LATEST_PROTOCOL_VERSION = "2025-06-18"; +/** @internal */ +export const JSONRPC_VERSION = "2.0"; + +/** + * A progress token, used to associate progress notifications with the original request. + */ +export type ProgressToken = string | number; + +/** + * An opaque token used to represent a cursor for pagination. + */ +export type Cursor = string; + +/** @internal */ +export interface Request { + method: string; + params?: { + /** + * See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { + /** + * If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications. + */ + progressToken?: ProgressToken; + [key: string]: unknown; + }; + [key: string]: unknown; + }; +} + +/** @internal */ +export interface Notification { + method: string; + params?: { + /** + * See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; + [key: string]: unknown; + }; +} + +export interface Result { + /** + * See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; + [key: string]: unknown; +} + +/** + * A uniquely identifying ID for a request in JSON-RPC. + */ +export type RequestId = string | number; + +/** + * A request that expects a response. + */ +export interface JSONRPCRequest extends Request { + jsonrpc: typeof JSONRPC_VERSION; + id: RequestId; +} + +/** + * A notification which does not expect a response. + */ +export interface JSONRPCNotification extends Notification { + jsonrpc: typeof JSONRPC_VERSION; +} + +/** + * A successful (non-error) response to a request. + */ +export interface JSONRPCResponse { + jsonrpc: typeof JSONRPC_VERSION; + id: RequestId; + result: Result; +} + +// Standard JSON-RPC error codes +/** @internal */ +export const PARSE_ERROR = -32700; +/** @internal */ +export const INVALID_REQUEST = -32600; +/** @internal */ +export const METHOD_NOT_FOUND = -32601; +/** @internal */ +export const INVALID_PARAMS = -32602; +/** @internal */ +export const INTERNAL_ERROR = -32603; + +/** + * A response to a request that indicates an error occurred. + */ +export interface JSONRPCError { + jsonrpc: typeof JSONRPC_VERSION; + id: RequestId; + error: { + /** + * The error type that occurred. + */ + code: number; + /** + * A short description of the error. The message SHOULD be limited to a concise single sentence. + */ + message: string; + /** + * Additional information about the error. The value of this member is defined by the sender (e.g. detailed error information, nested errors etc.). + */ + data?: unknown; + }; +} + +/* Empty result */ +/** + * A response that indicates success but carries no data. + */ +export type EmptyResult = Result; + +/* Cancellation */ +/** + * This notification can be sent by either side to indicate that it is cancelling a previously-issued request. + * + * The request SHOULD still be in-flight, but due to communication latency, it is always possible that this notification MAY arrive after the request has already finished. + * + * This notification indicates that the result will be unused, so any associated processing SHOULD cease. + * + * A client MUST NOT attempt to cancel its `initialize` request. + * + * @category notifications/cancelled + */ +export interface CancelledNotification extends Notification { + method: "notifications/cancelled"; + params: { + /** + * The ID of the request to cancel. + * + * This MUST correspond to the ID of a request previously issued in the same direction. + */ + requestId: RequestId; + + /** + * An optional string describing the reason for the cancellation. This MAY be logged or presented to the user. + */ + reason?: string; + }; +} + +/* Initialization */ +/** + * This request is sent from the client to the server when it first connects, asking it to begin initialization. + * + * @category initialize + */ +export interface InitializeRequest extends Request { + method: "initialize"; + params: { + /** + * The latest version of the Model Context Protocol that the client supports. The client MAY decide to support older versions as well. + */ + protocolVersion: string; + capabilities: ClientCapabilities; + clientInfo: Implementation; + }; +} + +/** + * After receiving an initialize request from the client, the server sends this response. + * + * @category initialize + */ +export interface InitializeResult extends Result { + /** + * The version of the Model Context Protocol that the server wants to use. This may not match the version that the client requested. If the client cannot support this version, it MUST disconnect. + */ + protocolVersion: string; + capabilities: ServerCapabilities; + serverInfo: Implementation; + + /** + * Instructions describing how to use the server and its features. + * + * This can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a "hint" to the model. For example, this information MAY be added to the system prompt. + */ + instructions?: string; +} + +/** + * This notification is sent from the client to the server after initialization has finished. + * + * @category notifications/initialized + */ +export interface InitializedNotification extends Notification { + method: "notifications/initialized"; +} + +/** + * Capabilities a client may support. Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities. + */ +export interface ClientCapabilities { + /** + * Experimental, non-standard capabilities that the client supports. + */ + experimental?: { [key: string]: object }; + /** + * Present if the client supports listing roots. + */ + roots?: { + /** + * Whether the client supports notifications for changes to the roots list. + */ + listChanged?: boolean; + }; + /** + * Present if the client supports sampling from an LLM. + */ + sampling?: object; + /** + * Present if the client supports elicitation from the server. + */ + elicitation?: object; +} + +/** + * Capabilities that a server may support. Known capabilities are defined here, in this schema, but this is not a closed set: any server can define its own, additional capabilities. + */ +export interface ServerCapabilities { + /** + * Experimental, non-standard capabilities that the server supports. + */ + experimental?: { [key: string]: object }; + /** + * Present if the server supports sending log messages to the client. + */ + logging?: object; + /** + * Present if the server supports argument autocompletion suggestions. + */ + completions?: object; + /** + * Present if the server offers any prompt templates. + */ + prompts?: { + /** + * Whether this server supports notifications for changes to the prompt list. + */ + listChanged?: boolean; + }; + /** + * Present if the server offers any resources to read. + */ + resources?: { + /** + * Whether this server supports subscribing to resource updates. + */ + subscribe?: boolean; + /** + * Whether this server supports notifications for changes to the resource list. + */ + listChanged?: boolean; + }; + /** + * Present if the server offers any tools to call. + */ + tools?: { + /** + * Whether this server supports notifications for changes to the tool list. + */ + listChanged?: boolean; + }; +} + +/** + * Base interface for metadata with name (identifier) and title (display name) properties. + * + * @internal + */ +export interface BaseMetadata { + /** + * Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present). + */ + name: string; + + /** + * Intended for UI and end-user contexts — optimized to be human-readable and easily understood, + * even by those unfamiliar with domain-specific terminology. + * + * If not provided, the name should be used for display (except for Tool, + * where `annotations.title` should be given precedence over using `name`, + * if present). + */ + title?: string; +} + +/** + * Describes the name and version of an MCP implementation, with an optional title for UI representation. + */ +export interface Implementation extends BaseMetadata { + version: string; +} + +/* Ping */ +/** + * A ping, issued by either the server or the client, to check that the other party is still alive. The receiver must promptly respond, or else may be disconnected. + * + * @category ping + */ +export interface PingRequest extends Request { + method: "ping"; +} + +/* Progress notifications */ +/** + * An out-of-band notification used to inform the receiver of a progress update for a long-running request. + * + * @category notifications/progress + */ +export interface ProgressNotification extends Notification { + method: "notifications/progress"; + params: { + /** + * The progress token which was given in the initial request, used to associate this notification with the request that is proceeding. + */ + progressToken: ProgressToken; + /** + * The progress thus far. This should increase every time progress is made, even if the total is unknown. + * + * @TJS-type number + */ + progress: number; + /** + * Total number of items to process (or total progress required), if known. + * + * @TJS-type number + */ + total?: number; + /** + * An optional message describing the current progress. + */ + message?: string; + }; +} + +/* Pagination */ +/** @internal */ +export interface PaginatedRequest extends Request { + params?: { + /** + * An opaque token representing the current pagination position. + * If provided, the server should return results starting after this cursor. + */ + cursor?: Cursor; + }; +} + +/** @internal */ +export interface PaginatedResult extends Result { + /** + * An opaque token representing the pagination position after the last returned result. + * If present, there may be more results available. + */ + nextCursor?: Cursor; +} + +/* Resources */ +/** + * Sent from the client to request a list of resources the server has. + * + * @category resources/list + */ +export interface ListResourcesRequest extends PaginatedRequest { + method: "resources/list"; +} + +/** + * The server's response to a resources/list request from the client. + * + * @category resources/list + */ +export interface ListResourcesResult extends PaginatedResult { + resources: Resource[]; +} + +/** + * Sent from the client to request a list of resource templates the server has. + * + * @category resources/templates/list + */ +export interface ListResourceTemplatesRequest extends PaginatedRequest { + method: "resources/templates/list"; +} + +/** + * The server's response to a resources/templates/list request from the client. + * + * @category resources/templates/list + */ +export interface ListResourceTemplatesResult extends PaginatedResult { + resourceTemplates: ResourceTemplate[]; +} + +/** + * Sent from the client to the server, to read a specific resource URI. + * + * @category resources/read + */ +export interface ReadResourceRequest extends Request { + method: "resources/read"; + params: { + /** + * The URI of the resource to read. The URI can use any protocol; it is up to the server how to interpret it. + * + * @format uri + */ + uri: string; + }; +} + +/** + * The server's response to a resources/read request from the client. + * + * @category resources/read + */ +export interface ReadResourceResult extends Result { + contents: (TextResourceContents | BlobResourceContents)[]; +} + +/** + * An optional notification from the server to the client, informing it that the list of resources it can read from has changed. This may be issued by servers without any previous subscription from the client. + * + * @category notifications/resources/list_changed + */ +export interface ResourceListChangedNotification extends Notification { + method: "notifications/resources/list_changed"; +} + +/** + * Sent from the client to request resources/updated notifications from the server whenever a particular resource changes. + * + * @category resources/subscribe + */ +export interface SubscribeRequest extends Request { + method: "resources/subscribe"; + params: { + /** + * The URI of the resource to subscribe to. The URI can use any protocol; it is up to the server how to interpret it. + * + * @format uri + */ + uri: string; + }; +} + +/** + * Sent from the client to request cancellation of resources/updated notifications from the server. This should follow a previous resources/subscribe request. + * + * @category resources/unsubscribe + */ +export interface UnsubscribeRequest extends Request { + method: "resources/unsubscribe"; + params: { + /** + * The URI of the resource to unsubscribe from. + * + * @format uri + */ + uri: string; + }; +} + +/** + * A notification from the server to the client, informing it that a resource has changed and may need to be read again. This should only be sent if the client previously sent a resources/subscribe request. + * + * @category notifications/resources/updated + */ +export interface ResourceUpdatedNotification extends Notification { + method: "notifications/resources/updated"; + params: { + /** + * The URI of the resource that has been updated. This might be a sub-resource of the one that the client actually subscribed to. + * + * @format uri + */ + uri: string; + }; +} + +/** + * A known resource that the server is capable of reading. + */ +export interface Resource extends BaseMetadata { + /** + * The URI of this resource. + * + * @format uri + */ + uri: string; + + /** + * A description of what this resource represents. + * + * This can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a "hint" to the model. + */ + description?: string; + + /** + * The MIME type of this resource, if known. + */ + mimeType?: string; + + /** + * Optional annotations for the client. + */ + annotations?: Annotations; + + /** + * The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known. + * + * This can be used by Hosts to display file sizes and estimate context window usage. + */ + size?: number; + + /** + * See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/** + * A template description for resources available on the server. + */ +export interface ResourceTemplate extends BaseMetadata { + /** + * A URI template (according to RFC 6570) that can be used to construct resource URIs. + * + * @format uri-template + */ + uriTemplate: string; + + /** + * A description of what this template is for. + * + * This can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a "hint" to the model. + */ + description?: string; + + /** + * The MIME type for all resources that match this template. This should only be included if all resources matching this template have the same type. + */ + mimeType?: string; + + /** + * Optional annotations for the client. + */ + annotations?: Annotations; + + /** + * See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/** + * The contents of a specific resource or sub-resource. + */ +export interface ResourceContents { + /** + * The URI of this resource. + * + * @format uri + */ + uri: string; + /** + * The MIME type of this resource, if known. + */ + mimeType?: string; + + /** + * See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +export interface TextResourceContents extends ResourceContents { + /** + * The text of the item. This must only be set if the item can actually be represented as text (not binary data). + */ + text: string; +} + +export interface BlobResourceContents extends ResourceContents { + /** + * A base64-encoded string representing the binary data of the item. + * + * @format byte + */ + blob: string; +} + +/* Prompts */ +/** + * Sent from the client to request a list of prompts and prompt templates the server has. + * + * @category prompts/list + */ +export interface ListPromptsRequest extends PaginatedRequest { + method: "prompts/list"; +} + +/** + * The server's response to a prompts/list request from the client. + * + * @category prompts/list + */ +export interface ListPromptsResult extends PaginatedResult { + prompts: Prompt[]; +} + +/** + * Used by the client to get a prompt provided by the server. + * + * @category prompts/get + */ +export interface GetPromptRequest extends Request { + method: "prompts/get"; + params: { + /** + * The name of the prompt or prompt template. + */ + name: string; + /** + * Arguments to use for templating the prompt. + */ + arguments?: { [key: string]: string }; + }; +} + +/** + * The server's response to a prompts/get request from the client. + * + * @category prompts/get + */ +export interface GetPromptResult extends Result { + /** + * An optional description for the prompt. + */ + description?: string; + messages: PromptMessage[]; +} + +/** + * A prompt or prompt template that the server offers. + */ +export interface Prompt extends BaseMetadata { + /** + * An optional description of what this prompt provides + */ + description?: string; + /** + * A list of arguments to use for templating the prompt. + */ + arguments?: PromptArgument[]; + + /** + * See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/** + * Describes an argument that a prompt can accept. + */ +export interface PromptArgument extends BaseMetadata { + /** + * A human-readable description of the argument. + */ + description?: string; + /** + * Whether this argument must be provided. + */ + required?: boolean; +} + +/** + * The sender or recipient of messages and data in a conversation. + */ +export type Role = "user" | "assistant"; + +/** + * Describes a message returned as part of a prompt. + * + * This is similar to `SamplingMessage`, but also supports the embedding of + * resources from the MCP server. + */ +export interface PromptMessage { + role: Role; + content: ContentBlock; +} + +/** + * A resource that the server is capable of reading, included in a prompt or tool call result. + * + * Note: resource links returned by tools are not guaranteed to appear in the results of `resources/list` requests. + */ +export interface ResourceLink extends Resource { + type: "resource_link"; +} + +/** + * The contents of a resource, embedded into a prompt or tool call result. + * + * It is up to the client how best to render embedded resources for the benefit + * of the LLM and/or the user. + */ +export interface EmbeddedResource { + type: "resource"; + resource: TextResourceContents | BlobResourceContents; + + /** + * Optional annotations for the client. + */ + annotations?: Annotations; + + /** + * See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} +/** + * An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This may be issued by servers without any previous subscription from the client. + * + * @category notifications/prompts/list_changed + */ +export interface PromptListChangedNotification extends Notification { + method: "notifications/prompts/list_changed"; +} + +/* Tools */ +/** + * Sent from the client to request a list of tools the server has. + * + * @category tools/list + */ +export interface ListToolsRequest extends PaginatedRequest { + method: "tools/list"; +} + +/** + * The server's response to a tools/list request from the client. + * + * @category tools/list + */ +export interface ListToolsResult extends PaginatedResult { + tools: Tool[]; +} + +/** + * The server's response to a tool call. + * + * @category tools/call + */ +export interface CallToolResult extends Result { + /** + * A list of content objects that represent the unstructured result of the tool call. + */ + content: ContentBlock[]; + + /** + * An optional JSON object that represents the structured result of the tool call. + */ + structuredContent?: { [key: string]: unknown }; + + /** + * Whether the tool call ended in an error. + * + * If not set, this is assumed to be false (the call was successful). + * + * Any errors that originate from the tool SHOULD be reported inside the result + * object, with `isError` set to true, _not_ as an MCP protocol-level error + * response. Otherwise, the LLM would not be able to see that an error occurred + * and self-correct. + * + * However, any errors in _finding_ the tool, an error indicating that the + * server does not support tool calls, or any other exceptional conditions, + * should be reported as an MCP error response. + */ + isError?: boolean; +} + +/** + * Used by the client to invoke a tool provided by the server. + * + * @category tools/call + */ +export interface CallToolRequest extends Request { + method: "tools/call"; + params: { + name: string; + arguments?: { [key: string]: unknown }; + }; +} + +/** + * An optional notification from the server to the client, informing it that the list of tools it offers has changed. This may be issued by servers without any previous subscription from the client. + * + * @category notifications/tools/list_changed + */ +export interface ToolListChangedNotification extends Notification { + method: "notifications/tools/list_changed"; +} + +/** + * Additional properties describing a Tool to clients. + * + * NOTE: all properties in ToolAnnotations are **hints**. + * They are not guaranteed to provide a faithful description of + * tool behavior (including descriptive properties like `title`). + * + * Clients should never make tool use decisions based on ToolAnnotations + * received from untrusted servers. + */ +export interface ToolAnnotations { + /** + * A human-readable title for the tool. + */ + title?: string; + + /** + * If true, the tool does not modify its environment. + * + * Default: false + */ + readOnlyHint?: boolean; + + /** + * If true, the tool may perform destructive updates to its environment. + * If false, the tool performs only additive updates. + * + * (This property is meaningful only when `readOnlyHint == false`) + * + * Default: true + */ + destructiveHint?: boolean; + + /** + * If true, calling the tool repeatedly with the same arguments + * will have no additional effect on the its environment. + * + * (This property is meaningful only when `readOnlyHint == false`) + * + * Default: false + */ + idempotentHint?: boolean; + + /** + * If true, this tool may interact with an "open world" of external + * entities. If false, the tool's domain of interaction is closed. + * For example, the world of a web search tool is open, whereas that + * of a memory tool is not. + * + * Default: true + */ + openWorldHint?: boolean; +} + +/** + * Definition for a tool the client can call. + */ +export interface Tool extends BaseMetadata { + /** + * A human-readable description of the tool. + * + * This can be used by clients to improve the LLM's understanding of available tools. It can be thought of like a "hint" to the model. + */ + description?: string; + + /** + * A JSON Schema object defining the expected parameters for the tool. + */ + inputSchema: { + type: "object"; + properties?: { [key: string]: object }; + required?: string[]; + }; + + /** + * An optional JSON Schema object defining the structure of the tool's output returned in + * the structuredContent field of a CallToolResult. + */ + outputSchema?: { + type: "object"; + properties?: { [key: string]: object }; + required?: string[]; + }; + + /** + * Optional additional tool information. + * + * Display name precedence order is: title, annotations.title, then name. + */ + annotations?: ToolAnnotations; + + /** + * See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/* Logging */ +/** + * A request from the client to the server, to enable or adjust logging. + * + * @category logging/setLevel + */ +export interface SetLevelRequest extends Request { + method: "logging/setLevel"; + params: { + /** + * The level of logging that the client wants to receive from the server. The server should send all logs at this level and higher (i.e., more severe) to the client as notifications/message. + */ + level: LoggingLevel; + }; +} + +/** + * Notification of a log message passed from server to client. If no logging/setLevel request has been sent from the client, the server MAY decide which messages to send automatically. + * + * @category notifications/message + */ +export interface LoggingMessageNotification extends Notification { + method: "notifications/message"; + params: { + /** + * The severity of this log message. + */ + level: LoggingLevel; + /** + * An optional name of the logger issuing this message. + */ + logger?: string; + /** + * The data to be logged, such as a string message or an object. Any JSON serializable type is allowed here. + */ + data: unknown; + }; +} + +/** + * The severity of a log message. + * + * These map to syslog message severities, as specified in RFC-5424: + * https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1 + */ +export type LoggingLevel = + | "debug" + | "info" + | "notice" + | "warning" + | "error" + | "critical" + | "alert" + | "emergency"; + +/* Sampling */ +/** + * A request from the server to sample an LLM via the client. The client has full discretion over which model to select. The client should also inform the user before beginning sampling, to allow them to inspect the request (human in the loop) and decide whether to approve it. + * + * @category sampling/createMessage + */ +export interface CreateMessageRequest extends Request { + method: "sampling/createMessage"; + params: { + messages: SamplingMessage[]; + /** + * The server's preferences for which model to select. The client MAY ignore these preferences. + */ + modelPreferences?: ModelPreferences; + /** + * An optional system prompt the server wants to use for sampling. The client MAY modify or omit this prompt. + */ + systemPrompt?: string; + /** + * A request to include context from one or more MCP servers (including the caller), to be attached to the prompt. The client MAY ignore this request. + */ + includeContext?: "none" | "thisServer" | "allServers"; + /** + * @TJS-type number + */ + temperature?: number; + /** + * The maximum number of tokens to sample, as requested by the server. The client MAY choose to sample fewer tokens than requested. + */ + maxTokens: number; + stopSequences?: string[]; + /** + * Optional metadata to pass through to the LLM provider. The format of this metadata is provider-specific. + */ + metadata?: object; + }; +} + +/** + * The client's response to a sampling/create_message request from the server. The client should inform the user before returning the sampled message, to allow them to inspect the response (human in the loop) and decide whether to allow the server to see it. + * + * @category sampling/createMessage + */ +export interface CreateMessageResult extends Result, SamplingMessage { + /** + * The name of the model that generated the message. + */ + model: string; + /** + * The reason why sampling stopped, if known. + */ + stopReason?: "endTurn" | "stopSequence" | "maxTokens" | string; +} + +/** + * Describes a message issued to or received from an LLM API. + */ +export interface SamplingMessage { + role: Role; + content: TextContent | ImageContent | AudioContent; +} + +/** + * Optional annotations for the client. The client can use annotations to inform how objects are used or displayed + */ +export interface Annotations { + /** + * Describes who the intended customer of this object or data is. + * + * It can include multiple entries to indicate content useful for multiple audiences (e.g., `["user", "assistant"]`). + */ + audience?: Role[]; + + /** + * Describes how important this data is for operating the server. + * + * A value of 1 means "most important," and indicates that the data is + * effectively required, while 0 means "least important," and indicates that + * the data is entirely optional. + * + * @TJS-type number + * @minimum 0 + * @maximum 1 + */ + priority?: number; + + /** + * The moment the resource was last modified, as an ISO 8601 formatted string. + * + * Should be an ISO 8601 formatted string (e.g., "2025-01-12T15:00:58Z"). + * + * Examples: last activity timestamp in an open file, timestamp when the resource + * was attached, etc. + */ + lastModified?: string; +} + +export type ContentBlock = + | TextContent + | ImageContent + | AudioContent + | ResourceLink + | EmbeddedResource; + +/** + * Text provided to or from an LLM. + */ +export interface TextContent { + type: "text"; + + /** + * The text content of the message. + */ + text: string; + + /** + * Optional annotations for the client. + */ + annotations?: Annotations; + + /** + * See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/** + * An image provided to or from an LLM. + */ +export interface ImageContent { + type: "image"; + + /** + * The base64-encoded image data. + * + * @format byte + */ + data: string; + + /** + * The MIME type of the image. Different providers may support different image types. + */ + mimeType: string; + + /** + * Optional annotations for the client. + */ + annotations?: Annotations; + + /** + * See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/** + * Audio provided to or from an LLM. + */ +export interface AudioContent { + type: "audio"; + + /** + * The base64-encoded audio data. + * + * @format byte + */ + data: string; + + /** + * The MIME type of the audio. Different providers may support different audio types. + */ + mimeType: string; + + /** + * Optional annotations for the client. + */ + annotations?: Annotations; + + /** + * See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/** + * The server's preferences for model selection, requested of the client during sampling. + * + * Because LLMs can vary along multiple dimensions, choosing the "best" model is + * rarely straightforward. Different models excel in different areas—some are + * faster but less capable, others are more capable but more expensive, and so + * on. This interface allows servers to express their priorities across multiple + * dimensions to help clients make an appropriate selection for their use case. + * + * These preferences are always advisory. The client MAY ignore them. It is also + * up to the client to decide how to interpret these preferences and how to + * balance them against other considerations. + */ +export interface ModelPreferences { + /** + * Optional hints to use for model selection. + * + * If multiple hints are specified, the client MUST evaluate them in order + * (such that the first match is taken). + * + * The client SHOULD prioritize these hints over the numeric priorities, but + * MAY still use the priorities to select from ambiguous matches. + */ + hints?: ModelHint[]; + + /** + * How much to prioritize cost when selecting a model. A value of 0 means cost + * is not important, while a value of 1 means cost is the most important + * factor. + * + * @TJS-type number + * @minimum 0 + * @maximum 1 + */ + costPriority?: number; + + /** + * How much to prioritize sampling speed (latency) when selecting a model. A + * value of 0 means speed is not important, while a value of 1 means speed is + * the most important factor. + * + * @TJS-type number + * @minimum 0 + * @maximum 1 + */ + speedPriority?: number; + + /** + * How much to prioritize intelligence and capabilities when selecting a + * model. A value of 0 means intelligence is not important, while a value of 1 + * means intelligence is the most important factor. + * + * @TJS-type number + * @minimum 0 + * @maximum 1 + */ + intelligencePriority?: number; +} + +/** + * Hints to use for model selection. + * + * Keys not declared here are currently left unspecified by the spec and are up + * to the client to interpret. + */ +export interface ModelHint { + /** + * A hint for a model name. + * + * The client SHOULD treat this as a substring of a model name; for example: + * - `claude-3-5-sonnet` should match `claude-3-5-sonnet-20241022` + * - `sonnet` should match `claude-3-5-sonnet-20241022`, `claude-3-sonnet-20240229`, etc. + * - `claude` should match any Claude model + * + * The client MAY also map the string to a different provider's model name or a different model family, as long as it fills a similar niche; for example: + * - `gemini-1.5-flash` could match `claude-3-haiku-20240307` + */ + name?: string; +} + +/* Autocomplete */ +/** + * A request from the client to the server, to ask for completion options. + * + * @category completion/complete + */ +export interface CompleteRequest extends Request { + method: "completion/complete"; + params: { + ref: PromptReference | ResourceTemplateReference; + /** + * The argument's information + */ + argument: { + /** + * The name of the argument + */ + name: string; + /** + * The value of the argument to use for completion matching. + */ + value: string; + }; + + /** + * Additional, optional context for completions + */ + context?: { + /** + * Previously-resolved variables in a URI template or prompt. + */ + arguments?: { [key: string]: string }; + }; + }; +} + +/** + * The server's response to a completion/complete request + * + * @category completion/complete + */ +export interface CompleteResult extends Result { + completion: { + /** + * An array of completion values. Must not exceed 100 items. + */ + values: string[]; + /** + * The total number of completion options available. This can exceed the number of values actually sent in the response. + */ + total?: number; + /** + * Indicates whether there are additional completion options beyond those provided in the current response, even if the exact total is unknown. + */ + hasMore?: boolean; + }; +} + +/** + * A reference to a resource or resource template definition. + */ +export interface ResourceTemplateReference { + type: "ref/resource"; + /** + * The URI or URI template of the resource. + * + * @format uri-template + */ + uri: string; +} + +/** + * Identifies a prompt. + */ +export interface PromptReference extends BaseMetadata { + type: "ref/prompt"; +} + +/* Roots */ +/** + * Sent from the server to request a list of root URIs from the client. Roots allow + * servers to ask for specific directories or files to operate on. A common example + * for roots is providing a set of repositories or directories a server should operate + * on. + * + * This request is typically used when the server needs to understand the file system + * structure or access specific locations that the client has permission to read from. + * + * @category roots/list + */ +export interface ListRootsRequest extends Request { + method: "roots/list"; +} + +/** + * The client's response to a roots/list request from the server. + * This result contains an array of Root objects, each representing a root directory + * or file that the server can operate on. + * + * @category roots/list + */ +export interface ListRootsResult extends Result { + roots: Root[]; +} + +/** + * Represents a root directory or file that the server can operate on. + */ +export interface Root { + /** + * The URI identifying the root. This *must* start with file:// for now. + * This restriction may be relaxed in future versions of the protocol to allow + * other URI schemes. + * + * @format uri + */ + uri: string; + /** + * An optional name for the root. This can be used to provide a human-readable + * identifier for the root, which may be useful for display purposes or for + * referencing the root in other parts of the application. + */ + name?: string; + + /** + * See [specification/2025-06-18/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/** + * A notification from the client to the server, informing it that the list of roots has changed. + * This notification should be sent whenever the client adds, removes, or modifies any root. + * The server should then request an updated list of roots using the ListRootsRequest. + * + * @category notifications/roots/list_changed + */ +export interface RootsListChangedNotification extends Notification { + method: "notifications/roots/list_changed"; +} + +/** + * A request from the server to elicit additional information from the user via the client. + * + * @category elicitation/create + */ +export interface ElicitRequest extends Request { + method: "elicitation/create"; + params: { + /** + * The message to present to the user. + */ + message: string; + /** + * A restricted subset of JSON Schema. + * Only top-level properties are allowed, without nesting. + */ + requestedSchema: { + type: "object"; + properties: { + [key: string]: PrimitiveSchemaDefinition; + }; + required?: string[]; + }; + }; +} + +/** + * Restricted schema definitions that only allow primitive types + * without nested objects or arrays. + */ +export type PrimitiveSchemaDefinition = + | StringSchema + | NumberSchema + | BooleanSchema + | EnumSchema; + +export interface StringSchema { + type: "string"; + title?: string; + description?: string; + minLength?: number; + maxLength?: number; + format?: "email" | "uri" | "date" | "date-time"; +} + +export interface NumberSchema { + type: "number" | "integer"; + title?: string; + description?: string; + minimum?: number; + maximum?: number; +} + +export interface BooleanSchema { + type: "boolean"; + title?: string; + description?: string; + default?: boolean; +} + +export interface EnumSchema { + type: "string"; + title?: string; + description?: string; + enum: string[]; + enumNames?: string[]; // Display names for enum values +} + +/** + * The client's response to an elicitation request. + * + * @category elicitation/create + */ +export interface ElicitResult extends Result { + /** + * The user action in response to the elicitation. + * - "accept": User submitted the form/confirmed the action + * - "decline": User explicitly declined the action + * - "cancel": User dismissed without making an explicit choice + */ + action: "accept" | "decline" | "cancel"; + + /** + * The submitted form data, only present when action is "accept". + * Contains values matching the requested schema. + */ + content?: { [key: string]: string | number | boolean }; +} + +/* Client messages */ +/** @internal */ +export type ClientRequest = + | PingRequest + | InitializeRequest + | CompleteRequest + | SetLevelRequest + | GetPromptRequest + | ListPromptsRequest + | ListResourcesRequest + | ListResourceTemplatesRequest + | ReadResourceRequest + | SubscribeRequest + | UnsubscribeRequest + | CallToolRequest + | ListToolsRequest; + +/** @internal */ +export type ClientNotification = + | CancelledNotification + | ProgressNotification + | InitializedNotification + | RootsListChangedNotification; + +/** @internal */ +export type ClientResult = + | EmptyResult + | CreateMessageResult + | ListRootsResult + | ElicitResult; + +/* Server messages */ +/** @internal */ +export type ServerRequest = + | PingRequest + | CreateMessageRequest + | ListRootsRequest + | ElicitRequest; + +/** @internal */ +export type ServerNotification = + | CancelledNotification + | ProgressNotification + | LoggingMessageNotification + | ResourceUpdatedNotification + | ResourceListChangedNotification + | ToolListChangedNotification + | PromptListChangedNotification; + +/** @internal */ +export type ServerResult = + | EmptyResult + | InitializeResult + | CompleteResult + | GetPromptResult + | ListPromptsResult + | ListResourceTemplatesResult + | ListResourcesResult + | ReadResourceResult + | CallToolResult + | ListToolsResult; diff --git a/codex-rs/mcp-types/src/lib.rs b/codex-rs/mcp-types/src/lib.rs index 0ed518535f..6341fb62b4 100644 --- a/codex-rs/mcp-types/src/lib.rs +++ b/codex-rs/mcp-types/src/lib.rs @@ -10,7 +10,7 @@ use serde::Serialize; use serde::de::DeserializeOwned; use std::convert::TryFrom; -pub const MCP_SCHEMA_VERSION: &str = "2025-03-26"; +pub const MCP_SCHEMA_VERSION: &str = "2025-06-18"; pub const JSONRPC_VERSION: &str = "2.0"; /// Paired request/response types for the Model Context Protocol (MCP). @@ -35,6 +35,12 @@ fn default_jsonrpc() -> String { pub struct Annotations { #[serde(default, skip_serializing_if = "Option::is_none")] pub audience: Option>, + #[serde( + rename = "lastModified", + default, + skip_serializing_if = "Option::is_none" + )] + pub last_modified: Option, #[serde(default, skip_serializing_if = "Option::is_none")] pub priority: Option, } @@ -50,6 +56,14 @@ pub struct AudioContent { pub r#type: String, // &'static str = "audio" } +/// Base interface for metadata with name (identifier) and title (display name) properties. +#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] +pub struct BaseMetadata { + pub name: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub title: Option, +} + #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub struct BlobResourceContents { pub blob: String, @@ -58,6 +72,17 @@ pub struct BlobResourceContents { pub uri: String, } +#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] +pub struct BooleanSchema { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub default: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub description: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub title: Option, + pub r#type: String, // &'static str = "boolean" +} + #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub enum CallToolRequest {} @@ -75,29 +100,17 @@ pub struct CallToolRequestParams { } /// The server's response to a tool call. -/// -/// Any errors that originate from the tool SHOULD be reported inside the result -/// object, with `isError` set to true, _not_ as an MCP protocol-level error -/// response. Otherwise, the LLM would not be able to see that an error occurred -/// and self-correct. -/// -/// However, any errors in _finding_ the tool, an error indicating that the -/// server does not support tool calls, or any other exceptional conditions, -/// should be reported as an MCP error response. #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub struct CallToolResult { - pub content: Vec, + pub content: Vec, #[serde(rename = "isError", default, skip_serializing_if = "Option::is_none")] pub is_error: Option, -} - -#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] -#[serde(untagged)] -pub enum CallToolResultContent { - TextContent(TextContent), - ImageContent(ImageContent), - AudioContent(AudioContent), - EmbeddedResource(EmbeddedResource), + #[serde( + rename = "structuredContent", + default, + skip_serializing_if = "Option::is_none" + )] + pub structured_content: Option, } impl From for serde_json::Value { @@ -127,6 +140,8 @@ pub struct CancelledNotificationParams { /// Capabilities a client may support. Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities. #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub struct ClientCapabilities { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub elicitation: Option, #[serde(default, skip_serializing_if = "Option::is_none")] pub experimental: Option, #[serde(default, skip_serializing_if = "Option::is_none")] @@ -194,6 +209,7 @@ pub enum ClientResult { Result(Result), CreateMessageResult(CreateMessageResult), ListRootsResult(ListRootsResult), + ElicitResult(ElicitResult), } #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] @@ -208,9 +224,18 @@ impl ModelContextProtocolRequest for CompleteRequest { #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub struct CompleteRequestParams { pub argument: CompleteRequestParamsArgument, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub context: Option, pub r#ref: CompleteRequestParamsRef, } +/// Additional, optional context for completions +#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] +pub struct CompleteRequestParamsContext { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub arguments: Option, +} + /// The argument's information #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub struct CompleteRequestParamsArgument { @@ -222,7 +247,7 @@ pub struct CompleteRequestParamsArgument { #[serde(untagged)] pub enum CompleteRequestParamsRef { PromptReference(PromptReference), - ResourceReference(ResourceReference), + ResourceTemplateReference(ResourceTemplateReference), } /// The server's response to a completion/complete request @@ -248,6 +273,16 @@ impl From for serde_json::Value { } } +#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] +#[serde(untagged)] +pub enum ContentBlock { + TextContent(TextContent), + ImageContent(ImageContent), + AudioContent(AudioContent), + ResourceLink(ResourceLink), + EmbeddedResource(EmbeddedResource), +} + #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub enum CreateMessageRequest {} @@ -325,6 +360,48 @@ impl From for serde_json::Value { #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub struct Cursor(String); +#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] +pub enum ElicitRequest {} + +impl ModelContextProtocolRequest for ElicitRequest { + const METHOD: &'static str = "elicitation/create"; + type Params = ElicitRequestParams; + type Result = ElicitResult; +} + +#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] +pub struct ElicitRequestParams { + pub message: String, + #[serde(rename = "requestedSchema")] + pub requested_schema: ElicitRequestParamsRequestedSchema, +} + +/// A restricted subset of JSON Schema. +/// Only top-level properties are allowed, without nesting. +#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] +pub struct ElicitRequestParamsRequestedSchema { + pub properties: serde_json::Value, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub required: Option>, + pub r#type: String, // &'static str = "object" +} + +/// The client's response to an elicitation request. +#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] +pub struct ElicitResult { + pub action: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub content: Option, +} + +impl From for serde_json::Value { + fn from(value: ElicitResult) -> Self { + // Leave this as it should never fail + #[expect(clippy::unwrap_used)] + serde_json::to_value(value).unwrap() + } +} + /// The contents of a resource, embedded into a prompt or tool call result. /// /// It is up to the client how best to render embedded resources for the benefit @@ -346,6 +423,18 @@ pub enum EmbeddedResourceResource { pub type EmptyResult = Result; +#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] +pub struct EnumSchema { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub description: Option, + pub r#enum: Vec, + #[serde(rename = "enumNames", default, skip_serializing_if = "Option::is_none")] + pub enum_names: Option>, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub title: Option, + pub r#type: String, // &'static str = "string" +} + #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub enum GetPromptRequest {} @@ -389,10 +478,12 @@ pub struct ImageContent { pub r#type: String, // &'static str = "image" } -/// Describes the name and version of an MCP implementation. +/// Describes the name and version of an MCP implementation, with an optional title for UI representation. #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub struct Implementation { pub name: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub title: Option, pub version: String, } @@ -442,24 +533,6 @@ impl ModelContextProtocolNotification for InitializedNotification { type Params = Option; } -#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] -#[serde(untagged)] -pub enum JSONRPCBatchRequestItem { - JSONRPCRequest(JSONRPCRequest), - JSONRPCNotification(JSONRPCNotification), -} - -pub type JSONRPCBatchRequest = Vec; - -#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] -#[serde(untagged)] -pub enum JSONRPCBatchResponseItem { - JSONRPCResponse(JSONRPCResponse), - JSONRPCError(JSONRPCError), -} - -pub type JSONRPCBatchResponse = Vec; - /// A response to a request that indicates an error occurred. #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub struct JSONRPCError { @@ -483,10 +556,8 @@ pub struct JSONRPCErrorError { pub enum JSONRPCMessage { Request(JSONRPCRequest), Notification(JSONRPCNotification), - BatchRequest(JSONRPCBatchRequest), Response(JSONRPCResponse), Error(JSONRPCError), - BatchResponse(JSONRPCBatchResponse), } /// A notification which does not expect a response. @@ -777,6 +848,19 @@ pub struct Notification { pub params: Option, } +#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] +pub struct NumberSchema { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub description: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub maximum: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub minimum: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub title: Option, + pub r#type: String, +} + #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub struct PaginatedRequest { pub method: String, @@ -817,6 +901,17 @@ impl ModelContextProtocolRequest for PingRequest { type Result = Result; } +/// Restricted schema definitions that only allow primitive types +/// without nested objects or arrays. +#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] +#[serde(untagged)] +pub enum PrimitiveSchemaDefinition { + StringSchema(StringSchema), + NumberSchema(NumberSchema), + BooleanSchema(BooleanSchema), + EnumSchema(EnumSchema), +} + #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub enum ProgressNotification {} @@ -851,6 +946,8 @@ pub struct Prompt { #[serde(default, skip_serializing_if = "Option::is_none")] pub description: Option, pub name: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub title: Option, } /// Describes an argument that a prompt can accept. @@ -861,6 +958,8 @@ pub struct PromptArgument { pub name: String, #[serde(default, skip_serializing_if = "Option::is_none")] pub required: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub title: Option, } #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] @@ -877,23 +976,16 @@ impl ModelContextProtocolNotification for PromptListChangedNotification { /// resources from the MCP server. #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub struct PromptMessage { - pub content: PromptMessageContent, + pub content: ContentBlock, pub role: Role, } -#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] -#[serde(untagged)] -pub enum PromptMessageContent { - TextContent(TextContent), - ImageContent(ImageContent), - AudioContent(AudioContent), - EmbeddedResource(EmbeddedResource), -} - /// Identifies a prompt. #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub struct PromptReference { pub name: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub title: Option, pub r#type: String, // &'static str = "ref/prompt" } @@ -958,6 +1050,8 @@ pub struct Resource { pub name: String, #[serde(default, skip_serializing_if = "Option::is_none")] pub size: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub title: Option, pub uri: String, } @@ -969,6 +1063,26 @@ pub struct ResourceContents { pub uri: String, } +/// A resource that the server is capable of reading, included in a prompt or tool call result. +/// +/// Note: resource links returned by tools are not guaranteed to appear in the results of `resources/list` requests. +#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] +pub struct ResourceLink { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub annotations: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub description: Option, + #[serde(rename = "mimeType", default, skip_serializing_if = "Option::is_none")] + pub mime_type: Option, + pub name: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub size: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub title: Option, + pub r#type: String, // &'static str = "resource_link" + pub uri: String, +} + #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub enum ResourceListChangedNotification {} @@ -977,13 +1091,6 @@ impl ModelContextProtocolNotification for ResourceListChangedNotification { type Params = Option; } -/// A reference to a resource or resource template definition. -#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] -pub struct ResourceReference { - pub r#type: String, // &'static str = "ref/resource" - pub uri: String, -} - /// A template description for resources available on the server. #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub struct ResourceTemplate { @@ -994,10 +1101,19 @@ pub struct ResourceTemplate { #[serde(rename = "mimeType", default, skip_serializing_if = "Option::is_none")] pub mime_type: Option, pub name: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub title: Option, #[serde(rename = "uriTemplate")] pub uri_template: String, } +/// A reference to a resource or resource template definition. +#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] +pub struct ResourceTemplateReference { + pub r#type: String, // &'static str = "ref/resource" + pub uri: String, +} + #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub enum ResourceUpdatedNotification {} @@ -1140,6 +1256,7 @@ pub enum ServerRequest { PingRequest(PingRequest), CreateMessageRequest(CreateMessageRequest), ListRootsRequest(ListRootsRequest), + ElicitRequest(ElicitRequest), } #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] @@ -1172,6 +1289,21 @@ pub struct SetLevelRequestParams { pub level: LoggingLevel, } +#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] +pub struct StringSchema { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub description: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub format: Option, + #[serde(rename = "maxLength", default, skip_serializing_if = "Option::is_none")] + pub max_length: Option, + #[serde(rename = "minLength", default, skip_serializing_if = "Option::is_none")] + pub min_length: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub title: Option, + pub r#type: String, // &'static str = "string" +} + #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] pub enum SubscribeRequest {} @@ -1213,6 +1345,25 @@ pub struct Tool { #[serde(rename = "inputSchema")] pub input_schema: ToolInputSchema, pub name: String, + #[serde( + rename = "outputSchema", + default, + skip_serializing_if = "Option::is_none" + )] + pub output_schema: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub title: Option, +} + +/// An optional JSON Schema object defining the structure of the tool's output returned in +/// the structuredContent field of a CallToolResult. +#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)] +pub struct ToolOutputSchema { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub properties: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub required: Option>, + pub r#type: String, // &'static str = "object" } /// A JSON Schema object defining the expected parameters for the tool. diff --git a/codex-rs/mcp-types/tests/initialize.rs b/codex-rs/mcp-types/tests/initialize.rs index 27902dce50..3d77b5d8fa 100644 --- a/codex-rs/mcp-types/tests/initialize.rs +++ b/codex-rs/mcp-types/tests/initialize.rs @@ -18,7 +18,7 @@ fn deserialize_initialize_request() { "params": { "capabilities": {}, "clientInfo": { "name": "acme-client", "version": "1.2.3" }, - "protocolVersion": "2025-03-26" + "protocolVersion": "2025-06-18" } }"#; @@ -38,7 +38,7 @@ fn deserialize_initialize_request() { params: Some(json!({ "capabilities": {}, "clientInfo": { "name": "acme-client", "version": "1.2.3" }, - "protocolVersion": "2025-03-26" + "protocolVersion": "2025-06-18" })), }; @@ -57,12 +57,14 @@ fn deserialize_initialize_request() { experimental: None, roots: None, sampling: None, + elicitation: None, }, client_info: Implementation { name: "acme-client".into(), + title: Some("Acme".to_string()), version: "1.2.3".into(), }, - protocol_version: "2025-03-26".into(), + protocol_version: "2025-06-18".into(), } ); } diff --git a/codex-rs/tui/src/history_cell.rs b/codex-rs/tui/src/history_cell.rs index 0bfbc414b9..b481313405 100644 --- a/codex-rs/tui/src/history_cell.rs +++ b/codex-rs/tui/src/history_cell.rs @@ -17,6 +17,7 @@ use image::GenericImageView; use image::ImageReader; use lazy_static::lazy_static; use mcp_types::EmbeddedResourceResource; +use mcp_types::ResourceLink; use ratatui::prelude::*; use ratatui::style::Color; use ratatui::style::Modifier; @@ -331,8 +332,7 @@ impl HistoryCell { ) -> Option { match result { Ok(mcp_types::CallToolResult { content, .. }) => { - if let Some(mcp_types::CallToolResultContent::ImageContent(image)) = content.first() - { + if let Some(mcp_types::ContentBlock::ImageContent(image)) = content.first() { let raw_data = match base64::engine::general_purpose::STANDARD.decode(&image.data) { Ok(data) => data, @@ -405,21 +405,21 @@ impl HistoryCell { for tool_call_result in content { let line_text = match tool_call_result { - mcp_types::CallToolResultContent::TextContent(text) => { + mcp_types::ContentBlock::TextContent(text) => { format_and_truncate_tool_result( &text.text, TOOL_CALL_MAX_LINES, num_cols as usize, ) } - mcp_types::CallToolResultContent::ImageContent(_) => { + mcp_types::ContentBlock::ImageContent(_) => { // TODO show images even if they're not the first result, will require a refactor of `CompletedMcpToolCall` "".to_string() } - mcp_types::CallToolResultContent::AudioContent(_) => { + mcp_types::ContentBlock::AudioContent(_) => { "