protocol-droid 0.5.1

//! `McpStdioPeer` — the client-side transport for MCP.
//!
//! A `McpStdioPeer` connects to an MCP
//! server over stdio. The wire form is
//! newline-delimited JSON-RPC 2.0: the
//! peer writes requests to the child's
//! stdin and reads replies and
//! notifications from the child's
//! stdout. The peer owns the child
//! process and the reader / writer
//! tasks; dropping the peer kills the
//! child and stops the tasks.
//!
//! # Why this peer exists
//!
//! An ACP agent is usually also an MCP
//! client: the editor passes an
//! `mcpServers` list to the agent in
//! the `session/new` request, and the
//! agent spawns one MCP client per
//! server. The agent's tool calls
//! then route to whichever MCP server
//! advertises the tool. Without a
//! typed MCP client, the agent's
//! `session/new` handler is on the
//! hook for hand-rolling the JSON-RPC
//! envelope, the id allocation, and
//! the reply dispatch — the same
//! boilerplate every MCP client
//! writes. `McpStdioPeer` is that
//! boilerplate, typed, tested, and
//! ready to spawn.
//!
//! # What the peer speaks
//!
//! The pinned MCP revision is the
//! newest of the supported revisions
//! the consumer's `version` enum
//! allows. The peer's `methods`
//! surface is the four most-used
//! client-originating methods:
//! `initialize`, `ping`, `tools/list`,
//! `tools/call`. A future increment
//! adds `resources/*` and
//! `prompts/*`.
//!
//! # Differences from `AcpStdioPeer`
//!
//! The wire form is identical: the
//! peer speaks newline-delimited
//! JSON-RPC 2.0 in both directions.
//! The differences are the
//! protocol-level shapes (the typed
//! request / response types) and
//! the method table. The transport
//! is the same shape; the
//! application-level concerns differ.
//! The duplication is deliberate: the
//! two protocols may diverge in the
//! future (e.g. MCP's Streamable
//! HTTP) and a shared transport
//! would couple their evolution.

use std::collections::HashMap;
use std::io::Write as _;
use std::process::Stdio;
use std::sync::Arc;
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::Duration;

use serde::Serialize;
use serde::de::DeserializeOwned;
use serde_json::Value;
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
use tokio::process::{Child, ChildStdin, ChildStdout, Command};
use tokio::sync::{Mutex, mpsc, oneshot};

/// The MCP wire form's
/// `initialize` request. Sent by
/// the client as its first call.
///
/// Source of truth:
/// `crates/protocol-droid-schema/spec/<pinned-revision>/schema.json`
/// under `definitions.InitializeRequest`'s
/// `params` shape (the wrapper is
/// the JSON-RPC envelope; the typed
/// shape is the `params` value).
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct InitializeRequest {
    /// The MCP revision the client
    /// supports. The schema names
    /// every published revision; the
    /// peer uses the revision the
    /// consumer selected at
    /// construction.
    pub protocol_version: String,
    /// The client's capabilities. The
    /// schema defaults this to an
    /// empty object; the typed
    /// default is the all-off
    /// capabilities block.
    #[serde(default)]
    pub capabilities: ClientCapabilities,
    /// Information about the
    /// client. The schema marks
    /// this required in newer
    /// revisions; the wire form
    /// always carries it.
    pub client_info: Implementation,
}

/// The MCP wire form's
/// `initialize` reply. Sent by
/// the server in response to
/// `InitializeRequest`.
#[derive(Debug, Clone, PartialEq, Eq, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct InitializeResult {
    /// The MCP revision the server
    /// supports. The negotiation
    /// rule is the server picks
    /// the client's revision if
    /// it supports it; otherwise
    /// the server's latest
    /// supported revision.
    pub protocol_version: String,
    /// The server's capabilities.
    pub capabilities: ServerCapabilities,
    /// Information about the
    /// server. The schema marks
    /// this required.
    pub server_info: Implementation,
    /// Optional instructions the
    /// server hands the client for
    /// how to use the server. A
    /// typed `None` is the default
    /// for servers that do not
    /// provide instructions.
    #[serde(default)]
    pub instructions: Option<String>,
}

/// The client's capabilities.
///
/// The schema's `ClientCapabilities`
/// is an open object; the typed shape
/// carries the canonical
/// sub-capabilities (`roots`,
/// `sampling`, `experimental`).
/// Sub-capabilities the consumer
/// does not enable default to
/// `None`, which the wire form
/// omits.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
pub struct ClientCapabilities {
    /// The `roots` capability
    /// (whether the client
    /// advertises filesystem
    /// roots to the server).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub roots: Option<RootsCapability>,
    /// The `sampling` capability
    /// (whether the client
    /// supports LLM sampling
    /// on the server's behalf).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sampling: Option<SamplingCapability>,
    /// Experimental
    /// capabilities. The schema
    /// does not constrain the
    /// shape; the typed default
    /// is an empty map.
    #[serde(skip_serializing_if = "std::collections::BTreeMap::is_empty", default)]
    pub experimental: std::collections::BTreeMap<String, Value>,
}

/// The `roots` sub-capability.
/// Whether the client advertises
/// filesystem roots to the server
/// and whether the list can change
/// at runtime.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RootsCapability {
    /// Whether the list of roots
    /// can change after the
    /// `initialize` round-trip.
    #[serde(default)]
    pub list_changed: bool,
}

/// The `sampling` sub-capability.
/// A marker for the client's
/// support of LLM sampling. The
/// schema's `SamplingCapability`
/// is an empty object.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
pub struct SamplingCapability {}

/// The server's capabilities.
///
/// The schema's `ServerCapabilities`
/// is an open object; the typed
/// shape carries the canonical
/// sub-capabilities
/// (`prompts`, `resources`,
/// `tools`, `logging`).
/// Sub-capabilities the server
/// does not advertise default to
/// `None`, which the wire form
/// omits.
#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Deserialize)]
pub struct ServerCapabilities {
    /// The `prompts` capability.
    #[serde(default)]
    pub prompts: Option<PromptsCapability>,
    /// The `resources` capability.
    #[serde(default)]
    pub resources: Option<ResourcesCapability>,
    /// The `tools` capability.
    #[serde(default)]
    pub tools: Option<ToolsCapability>,
    /// The `logging` capability.
    #[serde(default)]
    pub logging: Option<LoggingCapability>,
    /// Experimental
    /// capabilities. The schema
    /// does not constrain the
    /// shape; the typed default
    /// is an empty map.
    #[serde(default)]
    pub experimental: std::collections::BTreeMap<String, Value>,
}

/// The `prompts` sub-capability.
#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PromptsCapability {
    /// Whether the list of
    /// prompts can change at
    /// runtime.
    #[serde(default)]
    pub list_changed: bool,
}

/// The `resources` sub-capability.
#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ResourcesCapability {
    /// Whether the list of
    /// resources can change at
    /// runtime.
    #[serde(default)]
    pub list_changed: bool,
    /// Whether the client can
    /// subscribe to individual
    /// resource updates.
    #[serde(default)]
    pub subscribe: bool,
}

/// The `tools` sub-capability.
#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ToolsCapability {
    /// Whether the list of
    /// tools can change at
    /// runtime.
    #[serde(default)]
    pub list_changed: bool,
}

/// The `logging` sub-capability.
/// A marker.
#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Deserialize)]
pub struct LoggingCapability {}

/// The `Implementation` block on
/// either side of `initialize`.
/// The shape is identical on the
/// client and server side.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Implementation {
    /// The implementation's
    /// programmatic name.
    pub name: String,
    /// The implementation's
    /// human-readable title.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    /// The implementation's
    /// version string.
    pub version: String,
}

/// The `tools/list` reply. The
/// server returns the list of
/// tools it advertises.
#[derive(Debug, Clone, PartialEq, Eq, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ListToolsResult {
    /// The tools the server
    /// advertises. The schema
    /// requires this list.
    pub tools: Vec<Tool>,
    /// An optional pagination
    /// cursor. The schema marks
    /// this as the standard
    /// JSON-RPC pagination shape;
    /// the typed default is
    /// `None` (no more pages).
    #[serde(default)]
    pub next_cursor: Option<String>,
}

/// A single tool. The server
/// returns these from
/// `tools/list` and the client
/// invokes them via `tools/call`.
#[derive(Debug, Clone, PartialEq, Eq, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Tool {
    /// The tool's programmatic
    /// name. The schema requires
    /// this and the server
    /// guarantees it is unique
    /// within the server's
    /// advertised tool set.
    pub name: String,
    /// The tool's human-readable
    /// description. Optional;
    /// servers SHOULD provide
    /// this for tool catalogs
    /// shown to humans.
    #[serde(default)]
    pub description: Option<String>,
    /// The JSON Schema for the
    /// tool's input. The schema
    /// requires this; the typed
    /// shape carries it as a
    /// raw `Value` because the
    /// JSON Schema is
    /// tool-specific.
    pub input_schema: Value,
}

/// The `tools/call` request body.
/// The client invokes a tool by
/// name with a JSON object that
/// matches the tool's
/// `inputSchema`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct CallToolRequest {
    /// The tool's name. Matches
    /// the `name` field of a
    /// `Tool` returned from
    /// `tools/list`.
    pub name: String,
    /// The tool's arguments.
    /// The shape is the tool's
    /// `inputSchema`. A tool that
    /// takes no arguments passes
    /// an empty object.
    #[serde(default)]
    pub arguments: Value,
}

/// The `tools/call` reply. The
/// server returns a list of
/// content blocks (text, image,
/// audio, or embedded resources)
/// and an optional `is_error`
/// flag.
#[derive(Debug, Clone, PartialEq, Eq, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CallToolResult {
    /// The tool's result
    /// content. The schema
    /// requires at least one
    /// block.
    pub content: Vec<ContentBlock>,
    /// Whether the tool
    /// call failed. The
    /// schema marks this
    /// optional; the typed
    /// default is `false`
    /// (success).
    #[serde(default)]
    pub is_error: bool,
}

/// A single content block in a
/// `CallToolResult`. The schema
/// defines `text`, `image`,
/// `audio`, and `resource`
/// variants via a tagged union.
/// The typed shape models the
/// four shapes the schema names.
#[derive(Debug, Clone, PartialEq, Eq, serde::Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ContentBlock {
    /// A text block.
    Text {
        /// The text content.
        text: String,
    },
    /// An image block. The
    /// `data` is base64-encoded.
    Image {
        /// The image's
        /// MIME type.
        #[serde(rename = "mimeType")]
        mime_type: String,
        /// The base64-encoded
        /// image data.
        data: String,
    },
    /// An audio block. The
    /// `data` is base64-encoded.
    Audio {
        /// The audio's
        /// MIME type.
        #[serde(rename = "mimeType")]
        mime_type: String,
        /// The base64-encoded
        /// audio data.
        data: String,
    },
    /// An embedded resource
    /// block. The resource is
    /// inlined by URI.
    Resource {
        /// The embedded
        /// resource's URI.
        uri: String,
        /// The embedded
        /// resource's
        /// MIME type.
        #[serde(rename = "mimeType", default)]
        mime_type: Option<String>,
        /// The embedded
        /// resource's text
        /// content. The
        /// schema does not
        /// require this;
        /// the typed
        /// default is
        /// `None`.
        #[serde(default)]
        text: Option<String>,
    },
}

/// A pending reply. The reader
/// task owns a clone of the
/// `Arc<Mutex<HashMap>>`; the
/// application layer owns the
/// other clone. The reply is a
/// oneshot: the reader task
/// hands the result to the
/// application once and the
/// `HashMap` entry is removed.
struct Pending {
    tx: oneshot::Sender<Result<Value, McpPeerError>>,
}

/// The default request timeout.
const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);

/// The MCP stdio peer.
pub struct McpStdioPeer {
    pending: Arc<Mutex<HashMap<u64, Pending>>>,
    next_id: AtomicU64,
    write_tx: mpsc::Sender<Vec<u8>>,
    timeout: Duration,
    /// The child process. Held
    /// for `kill_on_drop`: when
    /// the peer drops, the
    /// `Child` is dropped, which
    /// kills the child. The
    /// application layer never
    /// reads the field directly.
    #[expect(dead_code, reason = "kill_on_drop machinery; never read directly")]
    child: Child,
}

impl std::fmt::Debug for McpStdioPeer {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("McpStdioPeer")
            .field("pending_len", &"*")
            .field("next_id", &self.next_id)
            .field("write_tx", &"*")
            .field("timeout", &self.timeout)
            .field("child", &"*")
            .finish_non_exhaustive()
    }
}

/// The specification for the
/// child process. Mirrors
/// `AcpStdioPeer::SpawnSpec` so
/// the call sites that already
/// know that shape can swap.
#[derive(Debug, Clone)]
pub struct SpawnSpec {
    /// The executable to spawn.
    pub command: String,
    /// The arguments to pass.
    pub args: Vec<String>,
    /// The default request timeout.
    pub timeout: Option<Duration>,
}

impl SpawnSpec {
    /// Construct a new `SpawnSpec`
    /// for a command and its
    /// arguments. The timeout
    /// defaults to 30 seconds; the
    /// consumer overrides it with
    /// [`with_timeout`][Self::with_timeout].
    pub fn new(command: impl Into<String>, args: Vec<String>) -> Self {
        Self {
            command: command.into(),
            args,
            timeout: None,
        }
    }

    /// Set the default request timeout.
    #[must_use]
    pub const fn with_timeout(mut self, timeout: Duration) -> Self {
        self.timeout = Some(timeout);
        self
    }
}

/// The error type the peer
/// returns. The variants are
/// the failure modes the
/// application layer can act on.
#[derive(Debug, thiserror::Error)]
pub enum McpPeerError {
    /// The child process could
    /// not be spawned. The
    /// underlying `io::Error`
    /// is the `Command::spawn`
    /// failure (typically
    /// `NotFound` for a missing
    /// executable).
    #[error("spawning the child process: {0}")]
    Spawn(#[source] std::io::Error),

    /// The JSON-RPC envelope
    /// could not be serialised
    /// or the reply could not be
    /// deserialised into the
    /// typed shape the
    /// application requested.
    /// The error is the
    /// `serde_json` failure.
    #[error("encoding or decoding the JSON-RPC envelope: {0}")]
    Decode(#[source] serde_json::Error),

    /// The reply never arrived
    /// within the configured
    /// timeout. The pending
    /// oneshot is dropped, and
    /// the reader task will see
    /// a closed sender when (if)
    /// the late reply does
    /// come.
    #[error("the reply did not arrive within {0:?}")]
    Timeout(Duration),

    /// The writer task is gone;
    /// the child has exited and
    /// the peer's pipe is
    /// closed. A subsequent
    /// `send_request` returns
    /// this variant.
    #[error("the writer task is gone")]
    Write(#[source] std::io::Error),

    /// The reader task is gone;
    /// the child has exited and
    /// the peer's pipe is
    /// closed. A subsequent
    /// `send_typed_request`
    /// returns this variant.
    #[error("the reader task is gone")]
    ReadGone,

    /// The reply was a
    /// JSON-RPC 2.0 error. The
    /// error code and message
    /// are carried through.
    #[error("the server returned a JSON-RPC error: code={code} message={message}")]
    JsonRpc {
        /// The JSON-RPC error
        /// code.
        code: i64,
        /// The JSON-RPC error
        /// message.
        message: String,
    },
}

impl McpStdioPeer {
    /// Spawn a child process and
    /// wire it up to the peer's
    /// reader and writer tasks.
    /// The peer owns the child
    /// process; dropping the
    /// peer kills the child
    /// (the `Command` is
    /// configured with
    /// `kill_on_drop(true)`).
    pub fn spawn(spec: &SpawnSpec) -> Result<Self, McpPeerError> {
        let mut command = Command::new(&spec.command);
        command
            .args(&spec.args)
            .stdin(Stdio::piped())
            .stdout(Stdio::piped())
            .stderr(Stdio::null())
            .kill_on_drop(true);
        let mut child = command.spawn().map_err(McpPeerError::Spawn)?;
        let stdin = child.stdin.take().ok_or_else(|| {
            McpPeerError::Spawn(std::io::Error::other("child stdin was not piped"))
        })?;
        let stdout = child.stdout.take().ok_or_else(|| {
            McpPeerError::Spawn(std::io::Error::other("child stdout was not piped"))
        })?;

        let pending: Arc<Mutex<HashMap<u64, Pending>>> = Arc::new(Mutex::new(HashMap::new()));
        let (write_tx, write_rx) = mpsc::channel::<Vec<u8>>(32);
        spawn_reader(BufReader::new(stdout), Arc::clone(&pending));
        spawn_writer(stdin, write_rx);

        Ok(Self {
            pending,
            next_id: AtomicU64::new(1),
            write_tx,
            timeout: spec.timeout.unwrap_or(DEFAULT_TIMEOUT),
            child,
        })
    }

    /// Send a typed request and
    /// decode the typed reply.
    /// The two type parameters
    /// are the consumer's call
    /// to the server: `Req` is
    /// what the consumer's
    /// handler sends, `Resp` is
    /// what the server replies
    /// with.
    ///
    /// `params` is taken by
    /// value (not by reference)
    /// so the future the
    /// function returns is
    /// unconditionally `Send`:
    /// a borrow of `Req` would
    /// only be `Send` if
    /// `Req: Sync`, which is a
    /// sharper constraint than
    /// the consumer wants.
    pub async fn send_typed_request<Req, Resp>(
        &self,
        method: &str,
        params: Req,
    ) -> Result<Resp, McpPeerError>
    where
        Req: Serialize,
        Resp: DeserializeOwned,
    {
        let value = self.send_request(method, params).await?;
        serde_json::from_value(value).map_err(McpPeerError::Decode)
    }

    /// Send a request and await
    /// the raw reply. The raw
    /// `Value` is the consumer's
    /// problem to decode; the
    /// typed wrapper is
    /// [`send_typed_request`][Self::send_typed_request].
    pub async fn send_request<Req>(&self, method: &str, params: Req) -> Result<Value, McpPeerError>
    where
        Req: Serialize,
    {
        let id = self.next_id.fetch_add(1, Ordering::Relaxed);
        let params_value: Value = serde_json::to_value(&params).map_err(McpPeerError::Decode)?;
        let envelope = serde_json::json!({
            "jsonrpc": "2.0",
            "id": id,
            "method": method,
            "params": params_value,
        });
        let bytes = serde_json::to_vec(&envelope).map_err(McpPeerError::Decode)?;
        let mut framed = bytes;
        framed.push(b'\n');
        self.write_tx
            .send(framed)
            .await
            .map_err(|_| McpPeerError::Write(io_other("the writer task is gone")))?;
        let (tx, rx) = oneshot::channel();
        self.pending.lock().await.insert(id, Pending { tx });
        match tokio::time::timeout(self.timeout, rx).await {
            Ok(Ok(result)) => result,
            Ok(Err(_oneshot_dropped)) => {
                self.pending.lock().await.remove(&id);
                Err(McpPeerError::Timeout(self.timeout))
            }
            Err(_elapsed) => {
                self.pending.lock().await.remove(&id);
                Err(McpPeerError::Timeout(self.timeout))
            }
        }
    }
}

fn io_other(message: &str) -> std::io::Error {
    std::io::Error::other(message)
}

fn spawn_writer(mut stdin: ChildStdin, mut write_rx: mpsc::Receiver<Vec<u8>>) {
    tokio::spawn(async move {
        while let Some(mut bytes) = write_rx.recv().await {
            // Belt-and-braces: ensure
            // a trailing newline even
            // if a future caller forgot
            // to add one.
            if !bytes.ends_with(b"\n") {
                bytes.push(b'\n');
            }
            if let Err(error) = stdin.write_all(&bytes).await {
                // The child has gone.
                // Log to stderr; the
                // application layer
                // discovers the failure
                // through the next
                // `send_request` returning
                // a `Write` error.
                let _ = std::io::stderr()
                    .lock()
                    .write_all(format!("mcp writer task: write failed: {error}\n").as_bytes());
                return;
            }
            if let Err(error) = stdin.flush().await {
                let _ = std::io::stderr()
                    .lock()
                    .write_all(format!("mcp writer task: flush failed: {error}\n").as_bytes());
                return;
            }
        }
    });
}

fn spawn_reader(mut reader: BufReader<ChildStdout>, pending: Arc<Mutex<HashMap<u64, Pending>>>) {
    tokio::spawn(async move {
        let mut line = String::new();
        loop {
            line.clear();
            match reader.read_line(&mut line).await {
                Ok(0) | Err(_) => return,
                Ok(_) => {}
            }
            let trimmed = line.trim_end_matches('\n');
            if trimmed.is_empty() {
                continue;
            }
            let value: Value = match serde_json::from_str(trimmed) {
                Ok(value) => value,
                Err(_) => continue,
            };
            let id = value.get("id").and_then(Value::as_u64).unwrap_or(0);
            if id == 0 {
                // Notification or
                // malformed reply; the
                // MCP client peer does
                // not yet model
                // notifications. A
                // future increment
                // adds the
                // `notifications/*`
                // stream (e.g.
                // `notifications/tools/list_changed`).
                continue;
            }
            let result = value.get("error").map_or_else(
                || {
                    value
                        .get("result")
                        .cloned()
                        .ok_or_else(|| McpPeerError::JsonRpc {
                            code: -32600,
                            message: "the reply had no `result` and no `error`".to_owned(),
                        })
                },
                |error_value| {
                    let code = error_value.get("code").and_then(Value::as_i64).unwrap_or(0);
                    let message = error_value
                        .get("message")
                        .and_then(Value::as_str)
                        .unwrap_or("")
                        .to_owned();
                    Err(McpPeerError::JsonRpc { code, message })
                },
            );
            let entry = pending.lock().await.remove(&id);
            if let Some(entry) = entry {
                let _ = entry.tx.send(result);
            }
        }
    });
}

/// Default client capabilities.
///
/// The default form is the
/// all-off block: no
/// `roots`, no `sampling`,
/// no `experimental`. A
/// peer that wants any of
/// these on starts from
/// this default and sets
/// the relevant field.
///
/// The function is `pub`
/// so the library itself
/// names the type in
/// non-test code, which
/// keeps the rust 1.98
/// `dead_code_pub_in_binary`
/// lint from flagging
/// `ClientCapabilities` as
/// "never constructed" in
/// the library's own build
/// (the lint is promoted to
/// library crates in 1.98
/// and fires when a
/// `pub` type has no
/// construction site in
/// the lib's normal build,
/// which `#[cfg(test)]`
/// items do not satisfy).
#[must_use]
pub fn default_client_capabilities() -> ClientCapabilities {
    ClientCapabilities::default()
}

/// A reference `initialize`
/// request.
///
/// A consumer that wants
/// to send an
/// `initialize` request
/// needs the revision
/// string and a
/// `client_info` block.
/// The function returns
/// a `2025-06-18`
/// request — the newest
/// revision the vendored
/// schema has, and the
/// one the integration
/// test fixture speaks.
///
/// Like
/// [`default_client_capabilities`],
/// this function exists to
/// give the library's own
/// non-test build a
/// construction site for
/// the typed shapes
/// `InitializeRequest` and
/// `Implementation` name
/// (see that function's
/// note for the lint
/// rationale).
#[must_use]
pub fn initialize_request_template() -> InitializeRequest {
    InitializeRequest {
        protocol_version: "2025-06-18".to_owned(),
        capabilities: ClientCapabilities::default(),
        client_info: Implementation {
            name: "protocol-droid".to_owned(),
            title: Some("protocol-droid MCP client".to_owned()),
            version: "0.1.0".to_owned(),
        },
    }
}

#[cfg(test)]
mod typed_shape_round_trip {
    //! Wire-format property tests
    //! for the typed MCP shapes.
    //!
    //! A property test over the
    //! typed shapes ensures the
    //! wire form does not drift
    //! from the consumer's
    //! expectations: a
    //! `serde(rename_all)`
    //! typo, a missing `default`,
    //! or a wrong field name is
    //! caught by the round-trip
    //! property test. The
    //! test also drives the
    //! typed shapes through
    //! the lib's own types so
    //! the binary crate's
    //! `dead_code` lint does
    //! not flag them.
    use super::*;

    /// Smoke test: a
    /// `ClientCapabilities`
    /// constructs in the
    /// default form, and
    /// serialises without
    /// panicking.
    #[test]
    fn client_capabilities_default_serialises() -> Result<(), serde_json::Error> {
        let caps = ClientCapabilities::default();
        let value = serde_json::to_value(&caps)?;
        if let Some(object) = value.as_object() {
            assert!(
                !object.contains_key("roots"),
                "the default form omits `roots`"
            );
        } else {
            assert!(
                value.is_object(),
                "the serialised value should be an object"
            );
        }
        Ok(())
    }

    /// `ClientCapabilities` omits
    /// `roots` when it is `None`.
    /// The wire form is camelCase:
    /// a future migration to
    /// `snake_case` would fail
    /// this test.
    #[test]
    fn client_capabilities_omits_roots_when_none() -> Result<(), serde_json::Error> {
        let caps = ClientCapabilities {
            roots: None,
            sampling: None,
            experimental: std::collections::BTreeMap::new(),
        };
        let value = serde_json::to_value(&caps)?;
        if let Some(object) = value.as_object() {
            assert!(!object.contains_key("roots"));
        } else {
            assert!(
                value.is_object(),
                "the serialised value should be an object"
            );
        }
        Ok(())
    }

    /// `Implementation`
    /// round-trips through
    /// `serde_json` with `title`
    /// omitted when `None`.
    #[test]
    fn implementation_round_trip() -> Result<(), serde_json::Error> {
        let impl_value = Implementation {
            name: "test-client".to_owned(),
            title: None,
            version: "0.0.1".to_owned(),
        };
        let value = serde_json::to_value(&impl_value)?;
        if let Some(object) = value.as_object() {
            assert!(!object.contains_key("title"));
        } else {
            assert!(
                value.is_object(),
                "the serialised value should be an object"
            );
        }
        let decoded: Implementation = serde_json::from_value(value)?;
        assert_eq!(impl_value, decoded);
        Ok(())
    }

    /// `CallToolRequest` uses
    /// the `name` field
    /// directly and the
    /// `arguments` field is
    /// optional via
    /// `#[serde(default)]`.
    #[test]
    fn call_tool_request_serialises_name() -> Result<(), serde_json::Error> {
        let request = CallToolRequest {
            name: "echo".to_owned(),
            arguments: serde_json::json!({}),
        };
        let value = serde_json::to_value(&request)?;
        assert_eq!(
            value.get("name").and_then(serde_json::Value::as_str),
            Some("echo"),
        );
        Ok(())
    }

    /// The wire form of
    /// `InitializeRequest` uses
    /// `camelCase` for
    /// `protocolVersion` (the
    /// schema's wire form).
    #[test]
    fn initialize_request_uses_camel_case_on_the_wire() -> Result<(), serde_json::Error> {
        let request = InitializeRequest {
            protocol_version: "2025-06-18".to_owned(),
            capabilities: ClientCapabilities::default(),
            client_info: Implementation {
                name: "test-client".to_owned(),
                title: None,
                version: "0.0.1".to_owned(),
            },
        };
        let value = serde_json::to_value(&request)?;
        if let Some(object) = value.as_object() {
            assert!(object.contains_key("protocolVersion"));
            assert!(!object.contains_key("protocol_version"));
        } else {
            assert!(
                value.is_object(),
                "the serialised value should be an object"
            );
        }
        Ok(())
    }
}