How isaacphi/mcp-language-server works
Project Type and Purpose
• This is an open-source CLI tool (written in Go) that implements an MCP (Model Context Protocol) server and sits in front of any LSP-compliant language server.
• It exposes semantic code navigation tools (definition, references, diagnostics, hover, rename, edit_file) via MCP to LLM-based clients.
• It also provides a subcommand cmd/generate to auto-generate LSP protocol types and helper methods from tables.
High-Level File Structure Analysis
• cmd/
• generate/ ← code-generation CLI (reads internal/protocol tables and emits Go code).
• main.go + tools.go + justfile ← entrypoint for the MCP language server binary.
• internal/
• lsp/ ← adapters & transport (wraps stdio to LSP server, marshals/unmarshals JSON-RPC)
• protocol/ ← generated LSP types & interfaces (borrowed from gopls)
• tools/ ← implementations of semantic operations (definition, references, diagnostics, etc.)
• utilities/ ← file editing helpers, logging utilities
• logging/ ← structured logging abstraction
• watcher/ ← file-watcher for workspace changes (optional)
• integrationtests/ ← snapshot tests + mock workspaces to verify tool correctness across Go, Rust, Python, TypeScript, C/C++
• go.mod, .github/, LICENSE, ATTRIBUTION, README.md
Key README Insights
• The server is invoked via CLI flags:
--workspace <path>
--lsp <path-to-lsp-server> [-- additional args]
• It shells out to a real LSP server over stdio, forwards MCP requests → LSP requests → MCP responses.
• Uses mcp-go for MCP wire protocol and gopls code for LSP wire protocol.
• Snapshot tests spin up a language server per language against small workspaces and compare outputs.
Main Components & Interactions
a. Components
1. CLI Entrypoint (main.go)
2. Argument Parser & Config (tools.go)
3. File Watcher (internal/watcher)
4. MCP-Protocol Server (mcp-go library)
5. LSP Client Adapter (internal/lsp)
6. LSP Server (external binary: gopls, rust-analyzer, pyright, clangd, …)
7. Tools Layer (internal/tools) implements each semantic operation by calling internal/lsp
8. Protocol Types (internal/protocol) shared between LSP adapter and tools
9. Logging Subsystem (internal/logging & utilities/logging)
10. Code Generation Subcommand (cmd/generate) – separate flow
11. Integration Test Harness (integrationtests/)
b. Data Flow & Relationships
• Startup: CLI parses flags → initializes logger → launches file watcher (optional)
• CLI starts MCP server endpoint over stdio or pipes → MCP client connects
• On MCP request (e.g., “definition”):
MCP Server ↔ internal/tools/definition.go ↔ internal/lsp ↔ external LSP process → response
internal/lsp receives JSON-RPC, decodes, returns typed Go struct (internal/protocol)
tools layer adapts to MCP response format, sends back to MCP client
• Logging intercepts all messages for debug.
• File watcher signals workspace change events into tools or triggers diagnostics automatically.
• cmd/generate: a standalone tool that reads internal/protocol/tables.go and outputs new Go files under internal/protocol.
Architectural Patterns & Principles
• Clearly layered architecture:
CLI → Protocol Layer → Transport Layer → External Process
• Adapter Pattern: internal/lsp wraps the LSP protocol and presents a uniform Go API.
• Separation of Concerns: tools implement high-level commands; protocol and transport are decoupled.
• Test Harness uses Golden Snapshot pattern to validate behavior end-to-end.
• Code generation as a build step: cmd/generate → internal/protocol.
Essential Details to Capture
• The dual role of the binary: runtime server vs. code-generation subcommand
• Use of mcp-go for MCP messaging and borrowed gopls code for LSP types
• Test harness coupling real LSP servers and workspace fixtures
• How the watcher integrates (optional file change events)
• Clear distinction between internal layers (protocol, transport, tools) and external dependencies