How jonrad/lsp-mcp works
Project type and purpose
• It’s an MCP (Model Context Protocol) server that wraps one or more Language Server Protocol (LSP) servers, exposing their capabilities over MCP.
• Purpose: Allow LLMs/AI agents (e.g. Claude Desktop, Cursor, CLI) to query language-aware context (symbols, diagnostics, completions) from a codebase.
File structure
Top-level:
• Dockerfile / .dockerignore / package.json – build & packaging
• src/ – core Node.js implementation
– app.ts (entrypoint)
– config.ts (loads MCP & LSP config via zod)
– lsp-manager.ts (manages lifecycle of LSP subprocesses)
– lsp.ts, lsp-methods.ts (wires LSP JSON-RPC to MCP methods)
– tool-manager.ts (plugin registry for MCP “tools”)
– resources/ (static JSON schema & metamodel)
• dev/ – development helpers & sample configs for Docker, npx, proxy
• poc/ – earlier Python proof-of-concept; not part of prod flow
README for additional insights
• Core stack: Node.js + FastMCP (low-level MCP SDK) + zod (validation)
• Patterns: dynamic generation of MCP methods from LSP JSON Schema, on-demand LSP startup, pluggable multi-language support.
• Deployment targets: Docker container, npx package, CLI client integration.
Main components & interactions
A. MCP Server (Node.js)
• Entrypoint: app.ts
• Configuration Loader: config.ts (reads dev/prod config JSON)
• Tool Manager: tool-manager.ts (registers “lsp” tool)
• LSP Manager: lsp-manager.ts (spawns language servers, mediates stdio JSON-RPC)
• LSP Method Handler: lsp-methods.ts (auto-generates MCP endpoints from schema)
• Logging: logger.ts
• Resources: generated.protocol.schema.json & metaModel.json
B. External LSP Servers (per language)
• typescript-language-server, python-language-server, etc.
• Started as child processes with stdio pipes
C. MCP Clients (consumers)
• Claude Desktop via Docker or npx
• Cursor (Docker command)
• mcp-cli (CLI client)
D. File System / Codebase
• Volume mount inside Docker or path on host
• LSP servers read and index files
Data flows:
MCP Client → MCP Server (stdin/stdout or TCP)
MCP Server → LSP Manager → Spawn LSP process
LSP process ↔ MCP Server (JSON-RPC over stdio)
MCP Server → MCP Client (responds with LSP data)
Architectural patterns & principles
• Plugin architecture – “tools” (only LSP right now) registered with ToolManager
• On-demand resource usage – LSP processes are lazy-started
• Dynamic schema-driven codegen – MCP methods generated at startup from LSP JSON Schema
• Separation of concerns – config loading, process management, protocol wiring, logging
Final checklist
– Components: MCP Client, MCP Server Core (split into modules), External LSP Servers, File System
– Data flows: client ↔ server ↔ language servers
– Config & resources loading paths