# bug-ops/mcpls architecture

> Architecture diagram of the GitHub repository bug-ops/mcpls, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bug-ops/mcpls
- Repository: https://github.com/bug-ops/mcpls

## Overview

mcpls is a command-line MCP-to-LSP bridge that gives AI coding assistants semantic code intelligence. The main workflow is an MCP client calling a tool, the MCP server dispatching it through the translator, and the translator routing an LSP request to a language server and returning translated results. Separate branches expose push diagnostics, workspace resources, and server monitoring. Source excerpts are partial, so uncertain internal wiring is omitted; additional tool capabilities are documented in the README.

Main entry points: [`crates/mcpls-core/src/bridge/translator/mod.rs`](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/mod.rs) (LSP translator), [`crates/mcpls-core/src/mcp/server.rs`](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/mcp/server.rs) (MCP server), [`crates/mcpls-core/src/bridge/translator/routing.rs`](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/routing.rs) (Tool routing), [`crates/mcpls-cli/src/main.rs`](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-cli/src/main.rs) (CLI startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Startup and transport"]
  node_cli["CLI startup<br/>[main.rs]"]
  node_config["Server configuration<br/>[server.rs]"]
  node_transport["MCP transport<br/>[transport.rs]"]
end

subgraph group_mcp["MCP interface"]
  node_mcpserver["MCP server<br/>[server.rs]"]
  node_handlers["Handler context<br/>[handlers.rs]"]
end

subgraph group_bridge["Translation and state"]
  node_translator["LSP translator<br/>[mod.rs]"]
  node_routing["Tool routing<br/>[routing.rs]"]
  node_toolroutes["Server selection<br/>[routing.rs]"]
  node_documents["Document state<br/>[state.rs]"]
  node_encoding["Protocol encoding<br/>[encoding.rs]"]
  node_navigation["Code navigation<br/>[navigation.rs]"]
  node_symbols["Symbol lookup<br/>[symbols.rs]"]
  node_diagnostics["Diagnostics tools<br/>[diagnostics.rs]"]
  node_refactoring["Edits and actions<br/>[edits.rs]"]
  node_analysis["Call hierarchy<br/>[call_hierarchy.rs]"]
  node_notifications[("Notification cache<br/>[notifications.rs]")]
  node_resources["Workspace resources<br/>[resources.rs]"]
end

subgraph group_lsp["Language servers"]
  node_lifecycle["Server lifecycle<br/>[lifecycle.rs]"]
  node_client["LSP client<br/>[client.rs]"]
end

node_assistant(("AI assistant"))
node_language_server["Language server"]

node_assistant -->|"sends MCP requests"| node_transport
node_cli -->|"loads settings"| node_config
node_cli -->|"starts service"| node_transport
node_transport -->|"dispatches requests"| node_mcpserver
node_mcpserver -->|"uses context"| node_handlers
node_mcpserver -->|"invokes tools"| node_translator
node_translator -->|"routes requests"| node_routing
node_routing -->|"selects server"| node_toolroutes
node_routing -->|"prepares documents"| node_documents
node_routing -->|"sends LSP calls"| node_client
node_translator -->|"handles navigation"| node_navigation
node_translator -->|"handles symbol queries"| node_symbols
node_translator -->|"handles diagnostics"| node_diagnostics
node_translator -->|"handles edits"| node_refactoring
node_translator -->|"handles call hierarchy"| node_analysis
node_client -->|"uses negotiated encoding"| node_encoding
node_lifecycle -->|"starts process"| node_language_server
node_client -->|"exchanges LSP messages"| node_language_server
node_cli -->|"initializes servers"| node_lifecycle
node_language_server -->|"publishes diagnostics"| node_notifications
node_mcpserver -->|"serves cached diagnostics"| node_notifications
node_mcpserver -->|"serves workspace resources"| node_resources

click node_cli "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-cli/src/main.rs"
click node_config "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/config/server.rs"
click node_transport "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/transport.rs"
click node_mcpserver "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/mcp/server.rs"
click node_handlers "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/mcp/handlers.rs"
click node_translator "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/mod.rs"
click node_routing "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/routing.rs"
click node_toolroutes "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/config/routing.rs"
click node_documents "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/state.rs"
click node_encoding "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/encoding.rs"
click node_navigation "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/navigation.rs"
click node_symbols "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/symbols.rs"
click node_diagnostics "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/diagnostics.rs"
click node_refactoring "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/edits.rs"
click node_analysis "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/call_hierarchy.rs"
click node_notifications "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/notifications.rs"
click node_resources "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/resources.rs"
click node_lifecycle "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/lsp/lifecycle.rs"
click node_client "https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/lsp/client.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config,node_transport toneBlue
class node_mcpserver,node_handlers toneAmber
class node_translator,node_routing,node_toolroutes,node_documents,node_encoding,node_navigation,node_symbols,node_diagnostics,node_refactoring,node_analysis,node_notifications,node_resources,node_language_server toneMint
class node_lifecycle,node_client toneRose
class node_assistant toneIndigo
```

## Components

### Startup and transport

- [CLI startup](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-cli/src/main.rs): `crates/mcpls-cli/src/main.rs`
- [Server configuration](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/config/server.rs): `crates/mcpls-core/src/config/server.rs`
- [MCP transport](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/transport.rs): `crates/mcpls-core/src/transport.rs`

### MCP interface

- [MCP server](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/mcp/server.rs): `crates/mcpls-core/src/mcp/server.rs`
- [Handler context](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/mcp/handlers.rs): `crates/mcpls-core/src/mcp/handlers.rs`

### Translation and state

- [LSP translator](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/mod.rs): `crates/mcpls-core/src/bridge/translator/mod.rs`
- [Tool routing](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/routing.rs): `crates/mcpls-core/src/bridge/translator/routing.rs`
- [Server selection](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/config/routing.rs): `crates/mcpls-core/src/config/routing.rs`
- [Document state](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/state.rs): `crates/mcpls-core/src/bridge/state.rs`
- [Protocol encoding](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/encoding.rs): `crates/mcpls-core/src/bridge/encoding.rs`
- [Code navigation](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/navigation.rs): `crates/mcpls-core/src/bridge/translator/navigation.rs`
- [Symbol lookup](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/symbols.rs): `crates/mcpls-core/src/bridge/translator/symbols.rs`
- [Diagnostics tools](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/diagnostics.rs): `crates/mcpls-core/src/bridge/translator/diagnostics.rs`
- [Edits and actions](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/edits.rs): `crates/mcpls-core/src/bridge/translator/edits.rs`
- [Call hierarchy](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/translator/call_hierarchy.rs): `crates/mcpls-core/src/bridge/translator/call_hierarchy.rs`
- [Notification cache](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/notifications.rs): `crates/mcpls-core/src/bridge/notifications.rs`
- [Workspace resources](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/bridge/resources.rs): `crates/mcpls-core/src/bridge/resources.rs`

### Language servers

- [Server lifecycle](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/lsp/lifecycle.rs): `crates/mcpls-core/src/lsp/lifecycle.rs`
- [LSP client](https://github.com/bug-ops/mcpls/blob/main/crates/mcpls-core/src/lsp/client.rs): `crates/mcpls-core/src/lsp/client.rs`

### Other components

- **AI assistant**
- **Language server**

## Connections

- AI assistant → MCP transport: sends MCP requests
- CLI startup → Server configuration: loads settings
- CLI startup → MCP transport: starts service
- MCP transport → MCP server: dispatches requests
- MCP server → Handler context: uses context
- MCP server → LSP translator: invokes tools
- LSP translator → Tool routing: routes requests
- Tool routing → Server selection: selects server
- Tool routing → Document state: prepares documents
- Tool routing → LSP client: sends LSP calls
- LSP translator → Code navigation: handles navigation
- LSP translator → Symbol lookup: handles symbol queries
- LSP translator → Diagnostics tools: handles diagnostics
- LSP translator → Edits and actions: handles edits
- LSP translator → Call hierarchy: handles call hierarchy
- LSP client → Protocol encoding: uses negotiated encoding
- Server lifecycle → Language server: starts process
- LSP client → Language server: exchanges LSP messages
- CLI startup → Server lifecycle: initializes servers
- Language server → Notification cache: publishes diagnostics
- MCP server → Notification cache: serves cached diagnostics
- MCP server → Workspace resources: serves workspace resources