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::*;