Struct Translator 

pub struct Translator { /* private fields */ }

Translator handles MCP tool calls by converting them to LSP requests.

All fields use interior mutability so Translator can be shared via a plain Arc<Translator> with no outer lock: every LSP tool call would otherwise serialize behind a single mutex for its entire round trip (including the LSP request timeout), which is the root cause fixed here. Each field is locked independently and only for the short, synchronous section that touches it. In particular, the actual LSP request/response round trip (client.request(...)) always runs with no lock held.

document_tracker is no exception: DocumentTracker locks its own state per-path internally (see its docs), so prepare_document’s call into ensure_open never holds a lock shared across unrelated paths or languages while it does that document’s disk I/O and textDocument/didOpen/didChange notify.

Implementations

impl Translator

pub async fn resolve_symbol_target( &self, file_path: &ClientPath, target: SymbolTarget, tool: AddressableTool, ) -> Result<ResolvedTarget>

Resolve how a tool is to be aimed: a position passes through untouched, a name is resolved against the file’s document symbols.

The routed server’s capability for tool is checked before anything else, so a name-addressed call fails like the position form does, and no document-symbol request is made for a tool that could not run.

Errors

The routing, capability and document errors of the position form, the document-symbol request’s own errors, and Error::SymbolResolution when the name does not resolve to exactly one verifiable position.

Examples

use std::path::PathBuf;

use mcpls_core::bridge::{
    AddressableTool, ClientPath, Position, SymbolTarget, Translator,
};

let file = ClientPath::try_from(PathBuf::from("/ws/src/lib.rs"))?;
let target = SymbolTarget::Position(Position::from_client(3, 5)?);
let resolved = translator
    .resolve_symbol_target(&file, target, AddressableTool::Hover)
    .await?;
assert!(resolved.resolved.is_none());

pub async fn with_resolved_target<T, F, Fut>( &self, file_path: ClientPath, target: SymbolTarget, tool: AddressableTool, call: F, ) -> Result<Addressed<T>>

where F: FnOnce(ClientPath, Position) -> Fut, Fut: Future<Output = Result<T>>,

Run call at the position target resolves to for tool, attaching the resolved symbol to the result when the call was name-addressed.

Errors

As Self::resolve_symbol_target, then whatever call returns.

impl Translator

pub async fn handle_completions( &self, file_path: ClientPath, position: Position, trigger: Option<CompletionTrigger>, ) -> Result<CompletionsResult>

Handle completions request.

Errors

Returns an error if the LSP request fails, the file cannot be opened, the routed server does not advertise completionProvider support, or the server is still indexing the workspace (see wait_for_indexing_ready).

pub async fn handle_signature_help( &self, file_path: ClientPath, position: Position, ) -> Result<Indexed<SignatureHelpResult>>

Handle signature help request (textDocument/signatureHelp).

Returns parameter signatures and documentation while typing a function call. context is omitted (None) — the server infers trigger state from position.

Errors

Returns an error if the LSP request fails, the file cannot be opened, or the routed server does not advertise signatureHelpProvider support.

pub async fn handle_inlay_hints( &self, file_path: ClientPath, range: PositionRange, ) -> Result<Indexed<InlayHintsResult>>

Handle inlay hints request (textDocument/inlayHint).

Returns inferred type and parameter annotations the editor would render inline. Output positions are in MCP 1-based form.

Errors

Returns an error if the LSP request fails, the file cannot be opened, or the routed server does not advertise inlayHintProvider support.

impl Translator

pub async fn handle_call_hierarchy_prepare( &self, file_path: ClientPath, position: Position, ) -> Result<Indexed<CallHierarchyPrepareResult>>

Handle call hierarchy prepare request.

Errors

Returns an error if the LSP request fails, the file cannot be opened, or the routed server does not advertise callHierarchyProvider support.

pub async fn handle_incoming_calls( &self, item: CheckedHierarchyItem, ) -> Result<IncomingCallsResult>

Handle incoming calls request.

Routing through prepare_gated_document_for_path means this now stats, reads, and didOpens the item’s own file as a side effect, even though a call-hierarchy item is opaque per the LSP spec and needs no open document – accepted for chokepoint/gating consistency with handle_references and the other whole-workspace tools; it does mean a replayed item whose file has since been deleted now fails on that stat instead of just proceeding.

Errors

Returns an error if the LSP request fails, the routed server does not advertise callHierarchyProvider support, or the server is still indexing the workspace after INDEXING_READY_TIMEOUT.

pub async fn handle_outgoing_calls( &self, item: CheckedHierarchyItem, ) -> Result<OutgoingCallsResult>

Handle outgoing calls request.

Same didOpen-as-side-effect trade-off as handle_incoming_calls – see that method’s doc.

Errors

See Self::handle_incoming_calls.

impl Translator

pub async fn cached_diagnostics_uri( workspace_roots: &WorkspaceRoots, file_path: &ClientPath, ) -> Result<Uri>

Resolve the LSP-side cache key (URI) for a cached-diagnostics lookup.

Split out from the cache read itself so callers (e.g. the get_cached_diagnostics MCP tool) can do the path canonicalize() and workspace-boundary check before taking the NotificationCache lock — that lock is also needed by diagnostics_pump to store incoming notifications, so nothing that isn’t a plain map lookup should run while it’s held.

Errors

Returns an error if the path is invalid or outside workspace boundaries.

pub async fn handle_diagnostics( &self, file_path: ClientPath, context: ResultContext, notification_cache: &Mutex<NotificationCache>, ) -> Result<DocumentDiagnosticsResult>

Handle diagnostics request.

Pulls textDocument/diagnostic, stores a full report as the file’s pulled slot in notification_cache next to whatever the server pushed (NotificationCache::store_pulled_diagnostics), and returns the merged view of both – the same diagnostics get_cached_diagnostics and resources/read return for the file right after. The push side is merged in because rust-analyzer’s pull endpoint omits flycheck/clippy-sourced diagnostics, and empirically some native ones, that are only ever delivered via push (#244). When the merged view changed, subscribers of the file’s lsp-diagnostics:// resource are notified before this returns (#574).

A report is not stored when it is not a full report (unchanged and partial results), when a pull issued later or a server clear got there first, or when the document was resynced to another version while the request was in flight; the result then still contains the report, but the cache and the subscribers are left alone. If the pull request itself fails (e.g. a timeout), a non-empty cache entry is returned as a cache-only result instead of propagating the error, since the cache is not required to be fresher than the pull response to be useful here.

A server that advertises no diagnosticProvider is probed with its first pull: -32601 is not an error but the learned fact that it is push-only, so this and every later call answers from the push cache without a request (#666); the DiagnosticsAnswer says so in its origin and says in its availability whether the cache knows the file.

The cache is locked once, after the pull request settles (success or failure), for the store and the snapshot – never across the LSP round-trip – matching the lock-ordering discipline documented on cached_diagnostics_uri. Merging, conversion and publishing run after the lock is dropped. Like get_cached_diagnostics, the cache is treated as eventually consistent: a pushed entry may reflect a slightly older document version than the fresh pull result if an edit landed inside the server’s flycheck debounce window.

Deliberately not gated on workspace-indexing readiness the way IndexingGate::Required whole-workspace queries are (#445, see routing::IndexingGate’s doc): this is a poll-based read, not a live whole-workspace LSP request, so blocking it on Translator::wait_for_indexing_ready would be the wrong fix shape. The get_diagnostics MCP tool instead surfaces the routed server’s indexing state as an explicit indexing_in_progress flag alongside this method’s result.

Errors

Returns an error if the LSP pull request fails and the cache holds no diagnostics for the file either, or if the file cannot be opened.

pub async fn diagnostics_from_cache_entry( diag_info: Option<&DiagnosticInfo>, encoding: PositionEncoding, tracker: &Arc<DocumentTracker>, ) -> DiagnosticsResult

Convert a cached diagnostics entry into the MCP-facing result shape.

Takes an already-cloned Option<&DiagnosticInfo> (out of the NotificationCache lock) rather than the cache itself, so this mapping — which is not a bounded operation for a large diagnostics set — never runs while the cache is locked.

encoding is the negotiated encoding of the server that published these diagnostics; pass PositionEncoding::Utf16 when no live server context is available (e.g. a cache-only read with no resolved owner).

pub fn handle_server_logs( cache: &NotificationCache, limit: usize, min_level: Option<LogLevel>, ) -> ServerLogsResult

Handle server logs request.

Logs at least as severe as min_level are returned, or all of them when it is None.

pub fn handle_server_messages( cache: &NotificationCache, limit: usize, ) -> Result<ServerMessagesResult>

Handle server messages request.

Errors

This method does not return errors.

impl Translator

pub async fn handle_rename( &self, file_path: ClientPath, position: Position, new_name: NewName, ) -> Result<RenameResult>

Handle rename request.

Errors

Returns an error if the LSP request fails, the file cannot be opened, the routed server does not advertise renameProvider support, or the server is still indexing the workspace (see Translator::wait_for_indexing_ready) – a rename needs the same whole-workspace reference index as get_references.

pub async fn handle_prepare_rename( &self, file_path: ClientPath, position: Position, ) -> Result<PrepareRenameResult>

Handle a prepare rename request: whether the symbol at position can be renamed, and the range a rename would replace.

Routes with rename_symbol (the Rename route), so the verdict comes from the server that would perform the rename. A null answer, or defaultBehavior: false, carries no range and no permission to rename, so both read as not renameable.

Errors

Returns an error if the position is invalid or its line lies beyond the end of the document (Error::PositionBeyondDocument), the LSP request fails for a reason other than rejecting the position, the file cannot be opened, the routed server does not advertise rename preparation support (renameProvider.prepareProvider), or the server is still indexing the workspace.

pub async fn handle_format_document( &self, file_path: ClientPath, tab_size: TabSize, insert_spaces: bool, ) -> Result<FormatDocumentResult>

Handle format document request.

Errors

Returns an error if the LSP request fails, the file cannot be opened, or the routed server does not advertise documentFormattingProvider support.

pub async fn handle_format_range( &self, file_path: ClientPath, range: BoundedRange, tab_size: TabSize, insert_spaces: bool, ) -> Result<FormatDocumentResult>

Handle format range request: formatting edits for only start..end.

Errors

Returns an error if the range is invalid (zero or oversized positions, start after end), a line lies beyond the end of the document (Error::PositionBeyondDocument), the LSP request fails, the file cannot be opened, or the routed server does not advertise documentRangeFormattingProvider support.

pub async fn handle_code_actions( &self, file_path: ClientPath, range: BoundedRange, kind_filter: Option<CodeActionKindFilter>, ) -> Result<CodeActionsResult>

Handle code actions request.

For an action returned with data present but edit absent, and only when the routed server’s codeActionProvider advertises resolveProvider: true, follows up with a codeAction/resolve request to populate the edit before returning the action (#432).

Errors

Returns an error if the LSP request fails, the file cannot be opened, the routed server does not advertise codeActionProvider support, or the server is still indexing the workspace (see wait_for_indexing_ready).

impl Translator

pub async fn handle_folding_range( &self, file_path: ClientPath, filter: FoldingKindFilter, ) -> Result<FoldingRangesResult>

Handle a folding range request: the foldable regions of a file.

Regions that end before they start are dropped, the rest are filtered by filter, ordered by ascending start line then descending end line, and capped (truncated is set when more remain). A kind the server does not name, or names with a custom value, is FoldingKind::Unspecified. Both answers are syntactic, so the request does not wait for indexing.

Errors

Returns an error if the LSP request fails, the file cannot be opened, or the routed server does not advertise foldingRangeProvider support.

impl Translator

pub async fn handle_document_highlights( &self, file_path: ClientPath, position: Position, ) -> Result<DocumentHighlightsResult>

Handle a document highlights request.

Errors

Returns an error if the position is invalid, the LSP request fails, the file cannot be opened, or the routed server does not advertise documentHighlightProvider support.

impl Translator

pub async fn handle_hover( &self, file_path: ClientPath, position: Position, ) -> Result<HoverResult>

Handle hover request.

Errors

Returns an error if the LSP request fails, the file cannot be opened, the routed server does not advertise hoverProvider support, or the server is still indexing the workspace after INDEXING_READY_TIMEOUT.

pub async fn handle_definition( &self, file_path: ClientPath, position: Position, context: ResultContext, ) -> Result<DefinitionResult>

Handle definition request.

Errors

Returns an error if the LSP request fails, the file cannot be opened, the routed server does not advertise definitionProvider support, or the server is still indexing the workspace after INDEXING_READY_TIMEOUT.

pub async fn handle_references( &self, file_path: ClientPath, position: Position, include_declaration: bool, context: ResultContext, ) -> Result<ReferencesResult>

Handle references request.

Errors

Returns an error if the LSP request fails, the file cannot be opened, the routed server does not advertise referencesProvider support, or the server is still indexing the workspace after INDEXING_READY_TIMEOUT.

pub async fn handle_implementation( &self, file_path: ClientPath, position: Position, context: ResultContext, ) -> Result<LocationsResult>

Handle go-to-implementation request (textDocument/implementation).

Returns the locations of trait method or interface member implementations.

Errors

Returns an error if the LSP request fails, the file cannot be opened, the routed server does not advertise implementationProvider support, or the server is still indexing the workspace after INDEXING_READY_TIMEOUT.

pub async fn handle_type_definition( &self, file_path: ClientPath, position: Position, context: ResultContext, ) -> Result<LocationsResult>

Handle go-to-type-definition request (textDocument/typeDefinition).

Returns the type definition location of the expression at position. Distinct from go-to-definition for variable bindings where definition and type differ.

Errors

Returns an error if the LSP request fails, the file cannot be opened, the routed server does not advertise typeDefinitionProvider support, or the server is still indexing the workspace after INDEXING_READY_TIMEOUT.

pub async fn handle_declaration( &self, file_path: ClientPath, position: Position, context: ResultContext, ) -> Result<LocationsResult>

Handle go-to-declaration request (textDocument/declaration).

Returns the declaration location of the symbol at position. Differs from go-to-definition for languages that separate declaration from definition (C/C++ headers, interface members).

Errors

Returns an error if the LSP request fails, the file cannot be opened, the routed server does not advertise declarationProvider support, or the server is still indexing the workspace after INDEXING_READY_TIMEOUT.

impl Translator

pub async fn restart_servers( &self, target: RestartTarget, ) -> Result<RestartServerResult>

Restart the servers named by target, each independently.

The old process tree is stopped (graceful shutdown/exit bounded by the LSP shutdown deadline, then the whole process group is killed) and a replacement is spawned and initialized from the server’s existing config. Requests in flight on the old process fail with a retryable Error::ServerRestarted; documents are re-opened on the new process on next access. Servers not named are untouched. Restarts of the same server are serialized, and a request that queued behind another restart of the same server is reported as coalesced.

Errors

Error::UnknownServers when target names a server that is not configured; nothing is restarted then. Per-server failures are reported in the result, not as errors.

Examples

use mcpls_core::bridge::{RestartTarget, Translator};

let result = translator.restart_servers(RestartTarget::All).await?;
for entry in &result.servers {
    println!("{}: {:?}", entry.server_id, entry.outcome);
}

impl Translator

pub async fn handle_selection_range( &self, file_path: ClientPath, position: Position, ) -> Result<SelectionRangesResult>

Handle a selection range request: the ranges enclosing position, innermost first.

One position is sent per request. The chain is returned as the server reported it, cut to MAX_SELECTION_CHAIN ranges (the outermost are dropped and truncated is set); an empty or null answer is an empty chain. Both answers are syntactic, so the request does not wait for indexing.

Errors

Returns an error if the LSP request fails, the file cannot be opened, or the routed server does not advertise selectionRangeProvider support.

impl Translator

pub async fn handle_document_symbols( &self, file_path: ClientPath, ) -> Result<DocumentSymbolsResult>

Handle document symbols request.

Errors

Returns an error if the LSP request fails, the file cannot be opened, or the routed server does not advertise documentSymbolProvider support.

pub async fn handle_workspace_symbol( &self, query: String, kind_filter: Option<SymbolKindFilter>, limit: u32, ) -> Result<WorkspaceSymbolResult>

Handle workspace symbol search.

Deliberately not gated on indexing readiness, unlike other whole-workspace queries (e.g. references, call hierarchy incoming/outgoing calls): it resolves via resolve_any rather than a per-file route, so it never goes through prepare_gated_document (the only chokepoint IndexingGate applies to) at all. Whether/how to gate it was deferred as a separate open question (spec FR-008) and remains a known limitation (#423).

Errors

Returns an error if the LSP request fails, no server is configured, or the routed server does not advertise workspaceSymbolProvider support.

impl Translator

pub async fn handle_type_hierarchy_prepare( &self, file_path: ClientPath, position: Position, ) -> Result<Indexed<TypeHierarchyResult>>

Handle a type hierarchy prepare request.

Errors

Returns an error if the position is invalid, the LSP request fails, the file cannot be opened, or the routed server does not advertise typeHierarchyProvider support.

pub async fn handle_supertypes( &self, item: CheckedHierarchyItem, ) -> Result<TypeHierarchyResult>

Handle a supertypes request for an item from a previous prepare or walk.

Opens the item’s own file on the routed server as a side effect, like handle_incoming_calls.

Errors

Returns an error if the item’s URI is not a workspace file, the LSP request fails, the routed server does not advertise typeHierarchyProvider support, or the server is still indexing the workspace after INDEXING_READY_TIMEOUT.

pub async fn handle_subtypes( &self, item: CheckedHierarchyItem, ) -> Result<TypeHierarchyResult>

Handle a subtypes request for an item from a previous prepare or walk.

Errors

See Self::handle_supertypes.

impl Translator

pub fn new() -> Self

Create a new translator.

Starts with an empty router: nothing is routable until Self::with_router installs one, which matches having no servers registered.

Also starts with no workspace roots, which makes every path-taking operation fail closed with Error::NoWorkspaceRoots – embedders MUST call Self::set_workspace_roots before serving any path-taking request.

pub fn set_workspace_roots(&mut self, roots: WorkspaceRoots)

Set the workspace roots for path validation.

Only called during single-owner setup, before the translator is shared, so this replaces the roots wholesale rather than locking.

Mandatory for any embedder that will serve path-taking requests: leaving roots empty (or never calling this) makes every such operation reject with Error::NoWorkspaceRoots instead of allowing unrestricted access.

pub fn with_notification_cache( self, cache: Arc<Mutex<NotificationCache>>, ) -> Self

Give the translator a handle to the shared diagnostics cache, so the respawn path can invalidate a respawned server’s stale entries.

Only called during single-owner setup (mirrors Self::with_router), before the translator is shared – serve_with passes the same Arc<Mutex<NotificationCache>> used by the notification pump tasks.

pub const fn with_indexing_ready_timeout( self, timeout: IndexingReadyTimeoutSecs, ) -> Self

Override the bound Self::wait_for_indexing_ready waits for a routed server to report indexing readiness, in place of the built-in navigation::INDEXING_READY_TIMEOUT default.

Only called during single-owner setup (mirrors Self::with_notification_cache), before the translator is shared. serve() wires this from workspace.indexing_ready_timeout_seconds, whose type already bounds it.

pub fn set_expected_servers(&self, servers: HashSet<ServerId>)

Mark the set of servers that are expected (configured + applicable) but may still be initializing in the background.

pub fn clear_expected_servers(&self)

Clear the expected-servers set (e.g. after background init failed).

pub fn with_router(self, router: ToolRouter) -> Self

Install the per-tool routing table built from the applicable configs.

Only called during single-owner setup, before the translator is shared, so this replaces the Arc-wrapped router wholesale.

pub fn rebind_router(&self, registered: &HashSet<ServerId>)

Rebind the routing table to the set of servers that actually registered, dropping or redirecting routes to every other server as if it had failed to spawn. See ToolRouter::rebind for the semantics.

pub fn is_diagnostics_route( &self, language_id: &LanguageId, id: &ServerId, ) -> bool

Whether id is the server the router currently resolves ToolKind::Diagnostics to for language_id.

Purpose-built for the startup settlement, which needs this to compute each pump’s diagnostics role and the diagnostics-route count, without exposing the router’s lock guard outside this module.

pub fn with_file_patterns( self, patterns: impl IntoIterator<Item = FilePattern>, ) -> Self

Configure the file_patterns reported by no-server-for-language errors.

Only called during single-owner setup, before the translator is shared.

pub fn with_extensions(self, language_map: impl Into<LanguageMap>) -> Self

Configure the file extension and name mappings.

This method sets the language map and updates the document tracker to use the same mappings for language detection. A plain extension-to-language HashMap is accepted too.

Only called during single-owner setup, before the translator is shared, so this replaces the Arc-wrapped fields wholesale.

pub fn with_resource_limits(self, limits: ResourceLimits) -> Self

Configure resource limits (max open documents, max file size) for the document tracker.

Only called during single-owner setup, before the translator is shared. This builder and Self::with_extensions may be called in either order – each rebuilds document_tracker from both of self.resource_limits/self.language_map’s current values, instead of one of them starting fresh from ResourceLimits::default()/an empty language map, which previously meant whichever builder ran last silently discarded the other’s effect.

pub fn register_server_complete(&self, server: LspServer)

Register a spawned server under its routing identity, in one step.

The routing identity and client are both derived from server itself, so they cannot be registered out of sync. The server also owns the config a respawn would use.

Examples

use mcpls_core::bridge::Translator;
use mcpls_core::lsp::LspServer;

fn register(translator: &Translator, server: LspServer) {
    translator.register_server_complete(server);
}

pub fn open_document_paths(&self) -> Vec<PathBuf>

Snapshot of currently open document paths, used for MCP resource listing.

pub fn is_document_open(&self, path: &Path) -> bool

Whether a document is currently tracked as open.

Trait Implementations

impl Debug for Translator

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Translator

fn default() -> Self

Same as Translator::new: no workspace roots configured, so every path-taking operation fails closed with Error::NoWorkspaceRoots until Translator::set_workspace_roots is called.