laburnum 1.17.0

// Copyright Two Neutron Stars Incorporated and contributors
// SPDX-License-Identifier: BlueOak-1.0.0

//! MCP (Model Context Protocol) server for laburnum.
//!
//! Exposes a curated subset of LSP capabilities to AI agents as
//! [MCP](https://modelcontextprotocol.io) tools. Gated behind the `mcp`
//! Cargo feature. See ADR0010 for the design rationale and the
//! exclusion list (LSP methods that are deliberately not surfaced).
//!
//! # Process model
//!
//! Each implementing crate ships a CLI subcommand (e.g. `patina mcp`) that
//! spawns an `McpServer` and runs it on stdin/stdout. The MCP server is a
//! separate process from the language-server daemon — it connects to the
//! daemon as a regular IPC client (with the new
//! [`ClientKind::Mcp`](crate::connect::lsp::ClientKind) variant) and forwards
//! curated requests on the agent's behalf.
//!
//! ```text
//!   AI agent ──── MCP/stdio (NDJSON) ────► McpServer ──── LSP/IPC ────► laburnum daemon
//!                                          (this crate)                  (ClientKind::Mcp)
//! ```
//!
//! Notifications from the daemon (`publishDiagnostics`, `$/progress`,
//! `$/serverShutdown`, etc.) are not forwarded to MCP — MCP is
//! request/response with no push channel. Diagnostics are exposed via the
//! pull-mode `file_diagnostics` / `workspace_diagnostics` tools.
//!
//! # Quickstart
//!
//! ```ignore
//! use laburnum::{
//!   connect::mcp::McpServer,
//!   daemon::DaemonConfig,
//!   protocol::mcp::Implementation,
//! };
//!
//! # async fn run(workspace_id: String) -> Result<(), Box<dyn std::error::Error>> {
//! let server = McpServer::connect(
//!   DaemonConfig::new("patina", workspace_id),
//!   Implementation {
//!     name:    "patina-mcp".to_string(),
//!     version: env!("CARGO_PKG_VERSION").to_string(),
//!   },
//! )
//! .await?
//! .with_default_tools()
//! .build();
//!
//! server.run_stdio().await?;
//! # Ok(())
//! # }
//! ```
//!
//! [`McpServer::connect`] handles the full bring-up: IPC handshake (as
//! [`ClientKind::Mcp`](crate::connect::lsp::ClientKind::Mcp) — the daemon
//! skips notification broadcasts to MCP clients), LSP `initialize`, and
//! UTF-8 position-encoding negotiation.
//!
//! # Position encoding
//!
//! Per ADR0010 the MCP server requests UTF-8 from the daemon during
//! `initialize`, so the `character` field of `Position` in every tool's
//! input is a UTF-8 byte offset within the line (not the LSP default
//! UTF-16). If the daemon won't negotiate UTF-8, [`McpServer::connect`]
//! returns [`ConnectError::PositionEncoding`] — no silent fallback.
//!
//! # Built-in tool catalog
//!
//! [`McpServerBuilder::with_default_tools`] registers a language-agnostic
//! catalog wrapping LSP requests. See [`tools`] for the full list and the
//! comment block in `tools/mod.rs` for what's deliberately excluded and
//! why. Highlights:
//!
//! - `find_symbol`, `document_symbols`
//! - `goto_definition` / `goto_declaration` / `goto_type_definition` /
//!   `goto_implementation`
//! - `find_references`, `hover`
//! - `file_diagnostics`, `workspace_diagnostics`
//! - `call_hierarchy_incoming` / `call_hierarchy_outgoing`
//! - `type_hierarchy_supertypes` / `type_hierarchy_subtypes`
//! - `code_actions`
//! - `prepare_rename`, `rename` (returns the `WorkspaceEdit` JSON; the
//!   agent applies edits with its own file-write tools)
//!
//! # Adding language-specific tools
//!
//! Implement [`Tool`] on a zero-sized marker type. `Input` and `Output`
//! should be LSP types from [`crate::protocol::lsp`] wherever possible —
//! the framework deserializes/serializes them at the wire boundary so
//! tool bodies stay typed end-to-end.
//!
//! ```ignore
//! use laburnum::{
//!   connect::{
//!     lsp::{LspClient, request::WorkspaceSymbolRequest},
//!     mcp::{schema, Tool, ToolError},
//!   },
//!   protocol::lsp::{WorkspaceSymbolParams, WorkspaceSymbolResponse},
//! };
//!
//! pub enum FindCrateRoots {}
//!
//! impl Tool for FindCrateRoots {
//!   type Input  = WorkspaceSymbolParams;
//!   type Output = Option<WorkspaceSymbolResponse>;
//!
//!   const NAME: &'static str = "find_crate_roots";
//!   const DESCRIPTION: &'static str =
//!     "Find Cargo.toml files defining workspace crate roots.";
//!
//!   fn input_schema() -> serde_json::Value {
//!     serde_json::json!({
//!       "type": "object",
//!       "properties": { "query": { "type": "string" } },
//!       "required": ["query"]
//!     })
//!   }
//!
//!   async fn call(
//!     client: &LspClient,
//!     input: Self::Input,
//!   ) -> Result<Self::Output, ToolError> {
//!     Ok(client.send_request::<WorkspaceSymbolRequest>(input).await?)
//!   }
//! }
//!
//! # use laburnum::{connect::mcp::McpServer, daemon::DaemonConfig, protocol::mcp::Implementation};
//! # async fn build() -> Result<(), Box<dyn std::error::Error>> {
//! McpServer::connect(DaemonConfig::new("patina", "ws"), Implementation {
//!   name: "patina-mcp".into(), version: env!("CARGO_PKG_VERSION").into(),
//! })
//! .await?
//! .with_default_tools()
//! .tool::<FindCrateRoots>()
//! .build();
//! # Ok(()) }
//! ```
//!
//! [`crate::connect::mcp::schema`] provides composable JSON Schema fragments for
//! LSP primitives (`uri`, `position`, `range`, `text_document_position`,
//! `hierarchy_item`) — use them so your tool's schema stays in sync with
//! the LSP types it accepts.
//!
//! # Exposing language-specific commands
//!
//! For tools that wrap your language server's `workspace/executeCommand`
//! handlers, use [`CommandDescriptor`] instead of the [`Tool`] trait. Each
//! descriptor becomes a typed MCP tool named `execute_<command>` (with
//! `/`, `.`, `-`, and spaces sanitized to `_`):
//!
//! ```ignore
//! # use laburnum::{
//! #   connect::mcp::{McpServer, CommandDescriptor},
//! #   daemon::DaemonConfig,
//! #   protocol::mcp::Implementation,
//! # };
//! # async fn build() -> Result<(), Box<dyn std::error::Error>> {
//! McpServer::connect(DaemonConfig::new("patina", "ws"), Implementation {
//!   name: "patina-mcp".into(), version: env!("CARGO_PKG_VERSION").into(),
//! })
//! .await?
//! .with_default_tools()
//! .commands([
//!   CommandDescriptor {
//!     command: "patina.runTests".into(),
//!     description: "Run the test suite for the current package.".into(),
//!     input_schema: serde_json::json!({
//!       "type": "object",
//!       "properties": { "package": { "type": "string" } },
//!       "required": ["package"]
//!     }),
//!   },
//! ])
//! .build();
//! # Ok(()) }
//! ```
//!
//! If you never call `.commands(...)`, no `execute_*` tool appears in the
//! agent's tool list. The implementing crate owns the schema and the
//! safety judgement for each command it registers — the framework has no
//! way to validate whether a given command is safe to invoke from an
//! agent context.
//!
//! # Errors
//!
//! Two error channels per the MCP spec:
//!
//! - **Protocol errors** (unknown tool, malformed arguments) flow back as
//!   JSON-RPC errors on the wire. The dispatcher handles these.
//! - **Tool execution errors** (LSP timeout, deserialization failure,
//!   business-logic failure) flow back as
//!   `CallToolResult { is_error: true, content: [{ text: ... }] }`.
//!   Surface them from your `Tool::call` by returning
//!   `Err(ToolError::Other(...))` or letting the `?` operator convert an
//!   `LspClientError`.

pub mod schema;
pub mod tool;
pub mod tools;
pub mod transport;

pub use {
  crate::protocol::mcp::PROTOCOL_VERSION,
  tool::{
    Tool,
    ToolError,
    ToolRegistry,
  },
  tools::execute_command::CommandDescriptor,
};

use {
  crate::{
    connect::{
      ipc::IpcHandle,
      lsp::{
        ClientKind,
        DaemonConnection,
        LspClient,
        errors::LspClientError,
      },
    },
    daemon::DaemonConfig,
    protocol::{
      jsonrpc::{
        self,
        Error,
        ErrorCode,
        Id,
        Message,
        Response,
      },
      lsp::{
        ClientCapabilities,
        ClientInfo,
        GeneralClientCapabilities,
        InitializeParams,
        PositionEncodingKind,
      },
      mcp::{
        CallToolParams,
        CallToolResult,
        Implementation,
        InitializeResult,
        ListToolsResult,
        ServerCapabilities,
        ToolsCapability,
      },
    },
  },
  std::{
    collections::HashMap,
    io,
  },
};

/// Errors from [`McpServer::connect`].
#[derive(Debug)]
pub enum ConnectError {
  /// IPC transport failure (socket, handshake, etc.).
  Io(io::Error),
  /// LSP `initialize` request failed.
  Initialize(LspClientError),
  /// The daemon did not negotiate the position encoding required by ADR0010
  /// (the MCP server always requests `utf-8`). Starting fails fast — no
  /// silent fallback to UTF-16.
  PositionEncoding {
    want: PositionEncodingKind,
    got:  Option<PositionEncodingKind>,
  },
}

impl From<io::Error> for ConnectError {
  fn from(value: io::Error) -> Self {
    Self::Io(value)
  }
}

impl std::fmt::Display for ConnectError {
  fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
    match self {
      | Self::Io(e) => write!(f, "failed to connect to laburnum daemon: {e}"),
      | Self::Initialize(e) => write!(f, "LSP initialize failed: {e}"),
      | Self::PositionEncoding { want, got } => write!(
        f,
        "daemon did not negotiate required position encoding {want:?} \
         (got {got:?})"
      ),
    }
  }
}

impl std::error::Error for ConnectError {}

/// MCP server bound to a single LSP connection.
///
/// One `McpServer` serves one MCP client at a time over stdio — matching
/// how agents spawn MCP servers as child processes.
pub struct McpServer {
  client:      LspClient,
  registry:    ToolRegistry,
  server_info: Implementation,
  /// Held to keep IPC I/O tasks alive for the lifetime of the server.
  /// `None` only for in-process test connections that don't have I/O
  /// tasks to keep alive.
  _ipc_handle: Option<IpcHandle>,
}

impl McpServer {
  /// Connect to a laburnum daemon and prepare an MCP server.
  ///
  /// Performs the IPC handshake as [`ClientKind::Mcp`] (so the daemon
  /// skips LSP notification broadcasts to this client), sends LSP
  /// `initialize` requesting [`PositionEncodingKind::UTF8`], and verifies
  /// the daemon agreed. Fails fast on encoding mismatch — no silent
  /// UTF-16 fallback (see ADR0010).
  ///
  /// `server_info.version` is used as both the IPC handshake version
  /// (compatibility check) and the LSP `client_info.version` (informational).
  pub async fn connect(
    daemon_config: DaemonConfig,
    server_info: Implementation,
  ) -> Result<McpServerBuilder, ConnectError> {
    let mut metadata = HashMap::new();
    metadata.insert("client_name".to_string(), server_info.name.clone());
    metadata.insert("client_version".to_string(), server_info.version.clone());

    let connection = DaemonConnection::connect_as(
      daemon_config,
      &server_info.version,
      ClientKind::Mcp,
      metadata,
    )
    .await?;

    let init_params = InitializeParams {
      capabilities: ClientCapabilities {
        general: Some(GeneralClientCapabilities {
          position_encodings: Some(vec![PositionEncodingKind::UTF8]),
          ..Default::default()
        }),
        ..Default::default()
      },
      client_info: Some(ClientInfo {
        name:    server_info.name.clone(),
        version: Some(server_info.version.clone()),
      }),
      ..Default::default()
    };

    let init_result = connection
      .client
      .start(init_params)
      .await
      .map_err(ConnectError::Initialize)?;

    let got = init_result.capabilities.position_encoding.clone();
    if got.as_ref() != Some(&PositionEncodingKind::UTF8) {
      return Err(ConnectError::PositionEncoding {
        want: PositionEncodingKind::UTF8,
        got,
      });
    }

    Ok(McpServerBuilder {
      client:      connection.client,
      registry:    ToolRegistry::new(),
      server_info,
      ipc_handle:  Some(connection.handle),
    })
  }

  /// Test-only: build a server directly from a prebuilt `LspClient`,
  /// skipping the daemon connection and LSP handshake.
  #[cfg(test)]
  #[doc(hidden)]
  pub(crate) fn from_client_for_test(client: LspClient) -> McpServerBuilder {
    McpServerBuilder {
      client,
      registry: ToolRegistry::new(),
      server_info: Implementation {
        name:    "laburnum-mcp-test".to_string(),
        version: env!("CARGO_PKG_VERSION").to_string(),
      },
      ipc_handle: None,
    }
  }

  /// Run the MCP server loop on stdin/stdout until the agent closes its
  /// end of the pipe.
  ///
  /// Requests are dispatched sequentially: the next message is read only
  /// after the current tool call resolves. This matches MCP's typical
  /// agent-side usage pattern (one tool call at a time) and avoids
  /// interleaved writes on stdout.
  pub async fn run_stdio(self) -> io::Result<()> {
    let mut stdin =
      smol::io::BufReader::new(smol::Unblock::new(std::io::stdin()));
    let mut stdout = smol::Unblock::new(std::io::stdout());
    self.run(&mut stdin, &mut stdout).await
  }

  /// Run against arbitrary async streams. Useful for tests with in-memory
  /// pipes.
  pub async fn run<R, W>(self, reader: &mut R, writer: &mut W) -> io::Result<()>
  where
    R: smol::io::AsyncBufReadExt + Unpin,
    W: smol::io::AsyncWriteExt + Unpin,
  {
    while let Some(msg) = transport::read_message(reader).await? {
      match msg {
        | Message::Request(req) => {
          let (method, id, params) = req.into_parts();
          let response = self.dispatch_request(&method, id, params).await;
          transport::write_message(writer, &Message::Response(response)).await?;
        },
        | Message::Notification(_) => {
          // initialized / cancelled accepted as no-ops in v1.
        },
        | Message::Response(_) => {
          // We don't issue requests to the agent.
        },
      }
    }
    Ok(())
  }

  #[doc(hidden)] // pub(crate) so tests can drive dispatch without the transport
  pub(crate) async fn dispatch_request(
    &self,
    method: &str,
    id: Id,
    params: Option<serde_json::Value>,
  ) -> Response {
    match method {
      | "initialize" => self.handle_initialize(id),
      | "tools/list" => self.handle_list_tools(id),
      | "tools/call" => self.handle_call_tool(id, params).await,
      | other => Response::from_error(
        id,
        Error {
          code:    ErrorCode::MethodNotFound,
          message: format!("unknown method: {other}").into(),
          data:    None,
        },
      ),
    }
  }

  fn handle_initialize(&self, id: Id) -> Response {
    let result = InitializeResult {
      protocol_version: PROTOCOL_VERSION.to_string(),
      capabilities:    ServerCapabilities {
        tools: Some(ToolsCapability { list_changed: false }),
      },
      server_info:     self.server_info.clone(),
    };
    Response::from_ok(id, json_or_internal_error(&result))
  }

  fn handle_list_tools(&self, id: Id) -> Response {
    let result = ListToolsResult {
      tools:       self.registry.descriptors(),
      next_cursor: None,
    };
    Response::from_ok(id, json_or_internal_error(&result))
  }

  async fn handle_call_tool(
    &self,
    id: Id,
    params: Option<serde_json::Value>,
  ) -> Response {
    let params: CallToolParams = match params {
      | Some(v) => match serde_json::from_value(v) {
        | Ok(p) => p,
        | Err(e) => return Response::from_error(id, invalid_params(e.to_string())),
      },
      | None => {
        return Response::from_error(
          id,
          invalid_params("tools/call requires a params object"),
        );
      },
    };

    let Some(tool) = self.registry.get(&params.name) else {
      return Response::from_error(
        id,
        Error {
          code:    ErrorCode::InvalidParams,
          message: format!("unknown tool: {}", params.name).into(),
          data:    None,
        },
      );
    };

    let result: CallToolResult = tool.call(&self.client, params.arguments).await;
    Response::from_ok(id, json_or_internal_error(&result))
  }
}

fn invalid_params(message: impl Into<String>) -> Error {
  Error {
    code:    ErrorCode::InvalidParams,
    message: message.into().into(),
    data:    None,
  }
}

fn json_or_internal_error<T: serde::Serialize>(value: &T) -> serde_json::Value {
  serde_json::to_value(value)
    .unwrap_or_else(|e| serde_json::json!({ "error": e.to_string() }))
}

pub struct McpServerBuilder {
  client:      LspClient,
  registry:    ToolRegistry,
  server_info: Implementation,
  ipc_handle:  Option<IpcHandle>,
}

impl McpServerBuilder {
  /// Register the language-agnostic default tools (see
  /// [`tools::register_defaults`]).
  #[must_use]
  pub fn with_default_tools(mut self) -> Self {
    tools::register_defaults(&mut self.registry);
    self
  }

  /// Register a single custom tool by its zero-sized marker type.
  ///
  /// ```ignore
  /// builder.tool::<MyCustomTool>()
  /// ```
  #[must_use]
  pub fn tool<T: Tool>(mut self) -> Self {
    self.registry.register::<T>();
    self
  }

  /// Register implementer-supplied `workspace/executeCommand` wrappers.
  ///
  /// Each `CommandDescriptor` becomes its own typed MCP tool. If this
  /// method is never called, no `execute_*` tool appears in the catalog.
  #[must_use]
  pub fn commands(
    mut self,
    commands: impl IntoIterator<Item = CommandDescriptor>,
  ) -> Self {
    tools::execute_command::register_commands(&mut self.registry, commands);
    self
  }

  pub fn build(self) -> McpServer {
    McpServer {
      client:      self.client,
      registry:    self.registry,
      server_info: self.server_info,
      _ipc_handle: self.ipc_handle,
    }
  }
}

// Re-export the type so doc links resolve.
#[allow(unused_imports)]
use jsonrpc as _jsonrpc;

#[cfg(test)]
mod tests {
  use {
    super::*,
    crate::connect::ipc::Connection,
    serde::{
      Deserialize,
      Serialize,
    },
  };

  fn server_with_echo() -> McpServer {
    let (server_conn, _client_conn) = Connection::memory();
    McpServer::from_client_for_test(LspClient::new(server_conn))
      .tool::<EchoTool>()
      .build()
  }

  #[derive(Deserialize, Serialize)]
  struct EchoInput {
    message: String,
  }

  enum EchoTool {}
  impl Tool for EchoTool {
    type Input = EchoInput;
    type Output = EchoInput;
    const NAME: &'static str = "echo";
    const DESCRIPTION: &'static str = "Echoes its arguments back as text.";
    fn input_schema() -> serde_json::Value {
      serde_json::json!({
        "type": "object",
        "properties": { "message": { "type": "string" } },
        "required": ["message"]
      })
    }
    async fn call(
      _client: &LspClient,
      input: Self::Input,
    ) -> Result<Self::Output, ToolError> {
      Ok(input)
    }
  }

  #[test]
  fn initialize_declares_tools_capability() {
    smol::block_on(async {
      let server = server_with_echo();
      let resp = server.dispatch_request("initialize", Id::Number(1), None).await;
      let body = serde_json::to_value(&resp).unwrap();
      assert_eq!(body["id"], 1);
      let result = &body["result"];
      assert_eq!(result["protocolVersion"], PROTOCOL_VERSION);
      assert!(result["capabilities"]["tools"].is_object());
      assert!(result["serverInfo"]["name"].is_string());
    });
  }

  #[test]
  fn tools_list_returns_registered_tools_sorted() {
    smol::block_on(async {
      let server = server_with_echo();
      let resp = server.dispatch_request("tools/list", Id::Number(2), None).await;
      let body = serde_json::to_value(&resp).unwrap();
      let tools = body["result"]["tools"].as_array().unwrap();
      assert_eq!(tools.len(), 1);
      assert_eq!(tools[0]["name"], "echo");
      assert!(tools[0]["description"].is_string());
      assert!(tools[0]["inputSchema"].is_object());
    });
  }

  #[test]
  fn tools_call_dispatches_to_tool() {
    smol::block_on(async {
      let server = server_with_echo();
      let params = serde_json::json!({
        "name": "echo",
        "arguments": { "message": "hello" }
      });
      let resp = server
        .dispatch_request("tools/call", Id::Number(3), Some(params))
        .await;
      let body = serde_json::to_value(&resp).unwrap();
      let content = &body["result"]["content"][0];
      assert_eq!(content["type"], "text");
      assert!(content["text"].as_str().unwrap().contains("\"hello\""));
      assert_eq!(body["result"]["isError"], false);
    });
  }

  #[test]
  fn tools_call_unknown_tool_returns_invalid_params() {
    smol::block_on(async {
      let server = server_with_echo();
      let params = serde_json::json!({ "name": "missing", "arguments": {} });
      let resp = server
        .dispatch_request("tools/call", Id::Number(4), Some(params))
        .await;
      let body = serde_json::to_value(&resp).unwrap();
      assert_eq!(body["error"]["code"], -32602);
      assert!(body["error"]["message"].as_str().unwrap().contains("missing"));
    });
  }

  #[test]
  fn tools_call_invalid_args_returns_is_error() {
    // Using a real tool from the default set so we exercise the parse_args
    // path — args missing required "query" field should come back as a
    // tool-execution error (is_error: true), not a protocol error.
    smol::block_on(async {
      let (server_conn, _client_conn) = Connection::memory();
      let server = McpServer::from_client_for_test(LspClient::new(server_conn))
        .with_default_tools()
        .build();
      let params = serde_json::json!({
        "name": "find_symbol",
        "arguments": {}
      });
      let resp = server
        .dispatch_request("tools/call", Id::Number(6), Some(params))
        .await;
      let body = serde_json::to_value(&resp).unwrap();
      // ok response wrapping is_error: true result
      assert!(body["error"].is_null());
      assert_eq!(body["result"]["isError"], true);
      assert!(
        body["result"]["content"][0]["text"]
          .as_str()
          .unwrap()
          .contains("invalid arguments")
      );
    });
  }

  #[test]
  fn unknown_method_returns_method_not_found() {
    smol::block_on(async {
      let server = server_with_echo();
      let resp = server
        .dispatch_request("bogus/method", Id::Number(5), None)
        .await;
      let body = serde_json::to_value(&resp).unwrap();
      assert_eq!(body["error"]["code"], -32601);
    });
  }
}