Skip to main content

r3bl_rust_analyzer_mcp_server/
lib.rs

1// Copyright (c) 2026 R3BL LLC. Licensed under Apache License, Version 2.0.
2
3//! [`rust-analyzer`] Model Context Protocol (MCP) Server
4//!
5//! This module provides a Model Context Protocol (MCP) server that acts as a lightweight,
6//! synchronous translation bridge between an AI / LLM coding agent or IDE client and the
7//! [`rust-analyzer`] language server subprocess.
8//!
9//! # Architecture: A 3-Process UNIX Pipe Bridge
10//!
11//! The complete interaction workflow consists of five distinct steps:
12//!
13//! 1. **User Launches Agent**
14//!     - The user starts their AI / LLM coding agent (such as Google Antigravity `agy`,
15//!       Claude Code, Cursor, or VS Code) in a local folder containing a Rust project.
16//! 2. **Agent Configuration**
17//!     - The user configures the agent to register `rust-analyzer-mcp-server` as a local
18//!       tool provider (via its MCP settings or configuration file).
19//! 3. **User Prompts the Agent**
20//!     - In an active coding session, the user issues a prompt requiring Rust semantic
21//!       analysis (e.g., _"Find all references to `MyStruct` and refactor its
22//!       constructor"_).
23//! 4. **Agent Spawns Bridge Process**
24//!     - To execute the requested tools, the AI / LLM coding agent spawns
25//!       `rust-analyzer-mcp-server` as a dedicated 1:1 child process communicating over
26//!       `stdio` (`stdin` and `stdout`).
27//! 5. **Bridge Translates MCP to LSP**
28//!     - The MCP server receives JSON-RPC tool calls over `stdin`, converts them into LSP
29//!       queries for `rust-analyzer`, and writes formatted responses to `stdout`:
30//!
31//! ```text
32//! ┌────────────────────────────────────────────────────────┐
33//! │          HOST PROCESS: AI / LLM CODING AGENT           │
34//! │            (Antigravity / VSCode / Claude)             │
35//! └───────────────────────────┬────────────────────────────┘
36//!                             │
37//!         [Launches rust-analyzer-mcp-server binary]
38//!               (1:1 dedicated child process)
39//!                             │
40//!            stdin / stdout pipes (MCP JSON-RPC)
41//!                             │
42//!                             ▼
43//! ┌────────────────────────────────────────────────────────┐
44//! │                rust-analyzer-mcp-server                │
45//! │   (3 OS threads: Main, stdout-reader, stderr-reader)   │
46//! │                                                        │
47//! │  1. Reads MCP JSON-RPC tool calls from stdin           │
48//! │  2. Converts tool calls into LSP JSON-RPC queries      │
49//! │  3. Writes LSP requests to rust-analyzer stdin         │
50//! │  4. Receives LSP responses from background thread      │
51//! │  5. Formats and writes MCP responses to stdout         │
52//! └───────────────────────────┬────────────────────────────┘
53//!                             │
54//!             [Spawns rust-analyzer subprocess]
55//!               (1:1 dedicated child process)
56//!                             │
57//!             stdin / stdout pipes (LSP Framing)
58//!                             │
59//!                             ▼
60//! ┌────────────────────────────────────────────────────────┐
61//! │       LANGUAGE SERVER: rust-analyzer subprocess        │
62//! │               (The Rust Language Server)               │
63//! └────────────────────────────────────────────────────────┘
64//! ```
65//!
66//! # How MCP Layers on Top of Language Servers
67//!
68//! The Model Context Protocol (MCP) does not define language-server-specific endpoints.
69//! Instead, MCP provides generic JSON-RPC primitives:
70//!
71//! 1. `initialize` (Handshake & capability negotiation)
72//! 2. `tools/list` (Dynamic tool discovery via JSON Schemas)
73//! 3. `tools/call` (Tool execution request & response)
74//!
75//! This crate (`rust-analyzer-mcp-server`) serves as an **adapter**. It implements those
76//! standard MCP endpoints on the outside and internally translates them into
77//! [`rust-analyzer`]'s Language Server Protocol (LSP 3.17) queries.
78//!
79//! ## Protocol Layering Flow
80//!
81//! ```text
82//! ┌────────────────────────────────────────────────────────┐
83//! │               AI / LLM CODING AGENT (agy)              │
84//! └───────────────────────────┬────────────────────────────┘
85//!                             │
86//!               1. "tools/list" (Standard MCP)
87//!                             │
88//!                             ▼
89//! ┌────────────────────────────────────────────────────────┐
90//! │                rust-analyzer-mcp-server                │
91//! │                                                        │
92//! │  Returns list of 10 tool schemas:                      │
93//! │   • rust_analyzer_hover                                │
94//! │   • rust_analyzer_definition                           │
95//! │   • rust_analyzer_references                           │
96//! │   • rust_analyzer_diagnostics                          │
97//! │   • ...                                                │
98//! └───────────────────────────┬────────────────────────────┘
99//!                             │
100//!               2. Agent injects tool schemas into LLM
101//!                             │
102//!               3. LLM decides: call "rust_analyzer_hover"
103//!                             │
104//!               4. "tools/call" (Standard MCP)
105//!                             │
106//!                             ▼
107//! ┌────────────────────────────────────────────────────────┐
108//! │                rust-analyzer-mcp-server                │
109//! │                                                        │
110//! │  Translates tools/call -> textDocument/hover (LSP)     │
111//! └───────────────────────────┬────────────────────────────┘
112//!                             │
113//!               5. LSP JSON-RPC over stdio
114//!                             │
115//!                             ▼
116//! ┌────────────────────────────────────────────────────────┐
117//! │                 rust-analyzer subprocess               │
118//! └────────────────────────────────────────────────────────┘
119//! ```
120//!
121//! The sections below trace this chronological execution flow across four distinct steps:
122//!
123//! 1. Discovery (`tools/list`): The AI / LLM coding agent queries capabilities; our MCP
124//!    server immediately replies with tool schemas that we define, without invoking
125//!    [`rust-analyzer`].
126//! 2. Tool Request (`tools/call`): The AI / LLM coding agent dispatches a tool execution
127//!    request, e.g., `rust_analyzer_hover` with a file path and coordinates (`line: 42,
128//!    character: 10`).
129//! 3. Bridge Translation (MCP -> LSP): Our MCP server translates the MCP tool call into
130//!    an LSP query (`textDocument/hover`), writes it to [`rust-analyzer`], and awaits the
131//!    AST response.
132//! 4. Tool Response (`CallToolResult`): [`rust-analyzer`] produces the symbol information
133//!    (with hover documentation and type signatures natively formatted in Markdown). Our
134//!    MCP server packages this into a standard MCP `CallToolResult` and returns the
135//!    JSON-RPC response to the AI / LLM coding agent with the matching request ID.
136//!
137//! ## 1. Dynamic Tool Discovery (`tools/list`)
138//!
139//! When the AI / LLM coding agent (e.g. `agy`) spawns our MCP server, it queries
140//! available tools by sending an MCP `tools/list` request over `stdin`:
141//!
142//! ```json
143//! {"jsonrpc": "2.0", "id": 1, "method": "tools/list"}
144//! ```
145//!
146//! > [`rust-analyzer`] is not used at all to produce this response. Because
147//! > [`rust-analyzer`] is a pure LSP language server with zero awareness of MCP, our
148//! > bridge binary (`rust-analyzer-mcp-server`) statically defines and serves all 10 tool
149//! > descriptors, documentation, and JSON Schemas directly from its internal catalog
150//! > ([`get_tools`]).
151//!
152//! Our MCP server writes this JSON-RPC response back to the AI / LLM coding agent over
153//! `stdout`:
154//!
155//! ```json
156//! {
157//!   "jsonrpc": "2.0",
158//!   "id": 1,
159//!   "result": {
160//!     "tools": [
161//!       {
162//!         "name": "rust_analyzer_hover",
163//!         "description": "Hover documentation, types, and signatures for a symbol.",
164//!         "inputSchema": {
165//!           "type": "object",
166//!           "properties": {
167//!             "file_path": { "type": "string", "description": "Absolute file path" },
168//!             "line": { "type": "integer", "description": "0-based line number" },
169//!             "character": { "type": "integer", "description": "0-based character offset" }
170//!           },
171//!           "required": ["file_path", "line", "character"]
172//!         }
173//!       },
174//!       {
175//!         "name": "rust_analyzer_definition",
176//!         "description": "Find symbol definition location.",
177//!         "inputSchema": {}
178//!       }
179//!     ]
180//!   }
181//! }
182//! ```
183//!
184//! The coding agent registers these schemas with the LLM, enabling the model to invoke
185//! any of the 10 tools when inspecting code.
186//!
187//! ## 2. Tool Execution (`tools/call`)
188//!
189//! When the LLM decides to inspect a symbol at line 42, character 10, the coding agent
190//! sends a standard MCP `tools/call` request to our MCP server's `stdin`:
191//!
192//! ```json
193//! {
194//!   "jsonrpc": "2.0",
195//!   "id": 2,
196//!   "method": "tools/call",
197//!   "params": {
198//!     "name": "rust_analyzer_hover",
199//!     "arguments": {
200//!       "file_path": "/path/to/main.rs",
201//!       "line": 42,
202//!       "character": 10
203//!     }
204//!   }
205//! }
206//! ```
207//!
208//! ## 3. The Bridge Translation: MCP to LSP
209//!
210//! Our MCP server translates the tool name and arguments into an LSP 3.17 request:
211//!
212//! | Standard MCP Method / Tool Name                      | Translates To LSP 3.17 Method                |
213//! | :--------------------------------------------------- | :------------------------------------------- |
214//! | `tools/call` (`rust_analyzer_hover`)                 | `textDocument/hover`                         |
215//! | `tools/call` (`rust_analyzer_definition`)            | `textDocument/definition`                    |
216//! | `tools/call` (`rust_analyzer_references`)            | `textDocument/references`                    |
217//! | `tools/call` (`rust_analyzer_symbols`)               | `textDocument/documentSymbol`                |
218//! | `tools/call` (`rust_analyzer_completion`)            | `textDocument/completion`                    |
219//! | `tools/call` (`rust_analyzer_format`)                | `textDocument/formatting`                    |
220//! | `tools/call` (`rust_analyzer_code_actions`)          | `textDocument/codeAction`                    |
221//! | `tools/call` (`rust_analyzer_diagnostics`)           | `textDocument/diagnostic` (or push fallback) |
222//! | `tools/call` (`rust_analyzer_workspace_diagnostics`) | `workspace/diagnostic`                       |
223//! | `tools/call` (`rust_analyzer_set_workspace`)         | `workspace/didChangeConfiguration`           |
224//!
225//! ## 4. Returning the Response to the AI / LLM Coding Agent
226//!
227//! [`rust-analyzer`] answers the LSP query with symbol data (for `textDocument/hover`, it
228//! natively formats the Rust signature and doc comments as Markdown in its
229//! `MarkupContent` response). Our MCP server packages this into a standard MCP
230//! `CallToolResult` text payload and returns it:
231//!
232//! ```json
233//! {
234//!   "jsonrpc": "2.0",
235//!   "id": 2,
236//!   "result": {
237//!     "content": [
238//!       {
239//!         "type": "text",
240//!         "text": "...fn foo() -> bool...Do stuff..."
241//!       }
242//!     ]
243//!   }
244//! }
245//! ```
246//!
247//! The coding agent passes this text directly back into the LLM context so it can
248//! continue reasoning.
249//!
250//! ## Why Asynchronous Request Multiplexing is Unnecessary Over `stdio`
251//!
252//! Neither JSON-RPC 2.0 nor the MCP specification dictates the transport layer. You can
253//! run JSON-RPC over `WebSockets`, TCP, Unix domain sockets, or `stdio`. Over network
254//! sockets (such as TCP or `WebSockets`), async request multiplexing makes complete
255//! sense: thousands of remote clients connect to a single daemon, each over its own
256//! independent socket connection.
257//!
258//! However, when an AI / LLM coding agent launches our MCP server locally, communication
259//! relies on **OS anonymous pipes** (`stdin` and `stdout`). An OS pipe is a
260//! unidirectional, in-memory FIFO buffer in the kernel (typically 64 KB on Linux).
261//! Because these are single serialized byte streams, communication between the coding
262//! agent and our server is inherently sequential by design:
263//!
264//! 1. **`stdin` (Accepting Requests from the Coding Agent):** The coding agent writes MCP
265//!    JSON-RPC requests into our MCP server's `stdin` pipe, delimited by newlines (`\n`).
266//!    Reading from `stdin` must be serialized: multiple concurrent reader threads would
267//!    race to consume chunks from the byte stream, splitting JSON lines in half and
268//!    breaking JSON parsing. A single synchronous reader loop in our main thread
269//!    naturally consumes incoming requests line-by-line with zero synchronization
270//!    overhead.
271//!
272//! 2. **`stdout` (Returning Responses to the Coding Agent):** Our MCP server writes
273//!    JSON-RPC tool responses back to the coding agent over `stdout`. Multiple concurrent
274//!    threads or tasks cannot write to `stdout` simultaneously without garbling the
275//!    response stream. Even if a multi-threaded async runtime executes tool queries
276//!    concurrently, all tasks must ultimately synchronize on a mutex to write their
277//!    responses line-by-line. An async runtime cannot provide parallel I/O throughput
278//!    over a single pipe; it simply adds mutex contention and task scheduling overhead.
279//!
280//! 3. **Turn-Based Agent Structure:** LLM workflows operate in discrete conversational
281//!    turns. When the LLM generates a tool call, the coding agent writes the request to
282//!    our MCP server's `stdin` and waits for the tool output before prompting the model
283//!    for the next reasoning step. Because AST tool execution is so fast (1 to 10 ms)
284//!    compared to LLM inference (500 to 3,000 ms), sequential execution latency is
285//!    completely imperceptible to the user.
286//!
287//! 4. **The Synchronous Event Loop:** In
288//!    [`RustAnalyzerMCPServer::enter_main_event_loop`], the main thread runs a
289//!    single-threaded line reader with no lock contention. Each MCP request is consumed,
290//!    translated into an LSP request, synchronously resolved against [`rust-analyzer`],
291//!    and the response is written back to `stdout` before the next line is read.
292//!    - This doesn't add perceptible latency in agent loops. LLM inference (e.g. Claude,
293//!      Gemini, etc.) may take 500 ms to 3,000 ms+ per conversational turn to reason and
294//!      generate tokens. A tool execution latency of 1 to 10 ms represents less than 1%
295//!      of that turn latency. Even if an agent issues a batch of 3 sequential tool calls
296//!      (3 × 5 ms = 15 ms total), the execution time is completely imperceptible compared
297//!      to the seconds spent in LLM network inference.
298//!
299//! # Threading Model
300//!
301//! Because [`rust-analyzer`] communicates asynchronously over `stdio` with
302//! out-of-order responses and unprompted notifications (such as compiler diagnostics),
303//! the server utilizes exactly 3 threads:
304//!
305//! 1. Main Thread (`main`):
306//!    - Spawned by: OS (Process entry).
307//!    - Function: [`RustAnalyzerMCPServer::enter_main_event_loop`].
308//!    - Purpose: Drives the MCP event loop: reads newline-delimited MCP requests from
309//!      client `stdin`, translates them to LSP requests, writes to [`rust-analyzer`]
310//!      `stdin`, waits on reply channels, and writes MCP responses to client `stdout`.
311//! 2. Stdout Reader Thread (`lsp-stdout-reader`):
312//!    - Spawned by: [`RustAnalyzerClient::start`].
313//!    - Function: [`spawn_stdout_reader_thread`].
314//!    - Purpose: Continuously reads `Content-Length` framed JSON-RPC from
315//!      [`rust-analyzer`]'s `stdout`: dispatches response payloads to the waiting main
316//!      thread via `pending_requests`, and stores compiler diagnostics in `diagnostics`.
317//! 3. Stderr Reader Thread (`lsp-stderr-reader`):
318//!    - Spawned by: [`RustAnalyzerClient::start`].
319//!    - Function: [`spawn_stderr_reader_thread`].
320//!    - Purpose: Continuously drains [`rust-analyzer`]'s `stderr` pipe to prevent OS
321//!      kernel pipe buffer deadlocks (64 KB limit), and outputs structured logs when
322//!      [`DEBUG_LSP_CLIENT`] is active.
323//!
324//! ## Request-Response Correlation
325//!
326//! When the main thread sends an LSP request:
327//! 1. A single-use [`sync_channel(1)`] pair is created.
328//! 2. The transmitter (`SyncSender`) is registered in the `pending_requests` [`HashMap`]
329//!    keyed by the unique `request_id`.
330//! 3. The request is written to [`rust-analyzer`]'s `stdin`.
331//! 4. The main thread blocks waiting on the receiver with a timeout.
332//! 5. When [`rust-analyzer`] writes the response to `stdout`, the `lsp-stdout-reader`
333//!    thread matches the `request_id`, removes the transmitter from `pending_requests`,
334//!    and delivers the payload to unblock the main thread.
335//!
336//! ## Server Readiness & Background Indexing Synchronization
337//!
338//! On cold startup or initial workspace loading, [`rust-analyzer`] operates
339//! asynchronously, performing background crate indexing, proc-macro expansion, and
340//! workspace metadata resolution. During this initial scan:
341//!
342//! 1. **Eager Subprocess Startup**: The MCP server eagerly spawns and initializes
343//!    [`rust-analyzer`] upon main loop entry
344//!    ([`RustAnalyzerMCPServer::enter_main_event_loop`]).
345//! 2. **Readiness Monitoring**: The server subscribes to `experimental/serverStatus`
346//!    notifications and monitors indexing progress via [`ServerReadinessMonitor`].
347//! 3. **AST Query Gating**: AST inspection tools (`hover`, `definition`, `references`,
348//!    `symbols`, `completion`, `code_actions`) synchronize with indexing status. If a
349//!    query returns empty results while [`rust-analyzer`] is still indexing, the server
350//!    provides a clear indexing progress notification instead of a false negative ("not
351//!    found").
352//!
353//! ```text
354//! ┌─────────────────────────────────────────────────────────────────────────────────┐
355//! │ 1. Eager Startup (RustAnalyzerMCPServer::enter_main_event_loop)                 │
356//! │    - Immediately spawn rust-analyzer child process upon server start.           │
357//! │    - Perform initialize handshake in parallel with MCP client connection.       │
358//! │    - Advertise capability: "experimental": { "serverStatusNotification": true } │
359//! └──────────────────────────────────────┬──────────────────────────────────────────┘
360//!                                        │
361//!                                        ▼
362//! ┌─────────────────────────────────────────────────────────────────────────────┐
363//! │ 2. Background Status Ingestion (lsp::transport::process_incoming_json)      │
364//! │    - Parse incoming "experimental/serverStatus" notifications.              │
365//! │    - Atomically update ServerReadinessMonitor (Mutex<ServerReadiness>).     │
366//! │    - Call condvar.notify_all() whenever status transitions to Complete.     │
367//! └──────────────────────────────────────┬──────────────────────────────────────┘
368//!                                        │
369//!                                        ▼
370//! ┌─────────────────────────────────────────────────────────────────────────────┐
371//! │ 3. AST Tool Readiness Gating (hover, definition, references, symbols, etc.) │
372//! │    - Check if server indexing is Complete.                                  │
373//! │      ├── If Complete: Execute AST query immediately (0ms overhead).         │
374//! │      └── If InProgress: Wait on Condvar (up to 5s warmup timeout).          │
375//! │    - After wait:                                                            │
376//! │      ├── If Complete: Execute query immediately.                            │
377//! │      └── If timeout expired (InProgress):                                   │
378//! │          ├── Attempt best-effort query anyway.                              │
379//! │          ├── If results returned: Return results (e.g. syntax symbols).     │
380//! │          └── If empty/null: Return informative indexing progress message    │
381//! │              with live rust-analyzer progress instead of false negative.    │
382//! └─────────────────────────────────────────────────────────────────────────────┘
383//! ```
384//!
385//! # Module Organization
386//!
387//! - [`cli_arg`]: Command-line argument parsing for workspace paths and logging.
388//! - [`constants`]: Namespaced timing, protocol, framing, and tool identifier constants.
389//! - [`error`]: Strongly-typed error enum ([`McpServerError`]) and diagnostic
390//!   conversions.
391//! - [`lsp`]: Subprocess management, framing, AST queries, diagnostics, and server
392//!   readiness monitor.
393//! - [`mcp`]: `stdio` JSON-RPC event loop, tool registry, and MCP wire envelopes.
394//! - [`value_ext`]: Extension trait on [`serde_json::Value`] for parameter extraction.
395//!
396//! [`cli_arg`]: crate::cli_arg
397//! [`constants`]: crate::constants
398//! [`DEBUG_LSP_CLIENT`]: crate::constants::debug_flags::DEBUG_LSP_CLIENT
399//! [`error`]: crate::error
400//! [`HashMap`]: std::collections::HashMap
401//! [`lsp`]: crate::lsp
402//! [`mcp`]: crate::mcp
403//! [`McpServerError`]: crate::error::McpServerError
404//! [`rust-analyzer`]: https://rust-analyzer.github.io/
405//! [`RustAnalyzerClient::start`]: crate::lsp::RustAnalyzerClient::start
406//! [`RustAnalyzerMCPServer::enter_main_event_loop`]:
407//!     crate::mcp::RustAnalyzerMCPServer::enter_main_event_loop
408//! [`ServerReadinessMonitor`]: crate::lsp::ServerReadinessMonitor
409//! [`spawn_stderr_reader_thread`]:
410//!     crate::lsp::RustAnalyzerClient::spawn_stderr_reader_thread
411//! [`spawn_stdout_reader_thread`]:
412//!     crate::lsp::RustAnalyzerClient::spawn_stdout_reader_thread
413//! [`sync_channel(1)`]: std::sync::mpsc::sync_channel
414//! [`value_ext`]: crate::value_ext
415
416// Attach modules.
417pub mod cli_arg;
418pub mod constants;
419pub mod error;
420pub mod lsp;
421pub mod mcp;
422pub mod value_ext;
423
424// Re-export public API for flat module interface.
425pub use cli_arg::*;
426pub use constants::*;
427pub use error::*;
428pub use lsp::*;
429pub use mcp::*;
430pub use value_ext::*;