# jonrad/lsp-mcp architecture

> Architecture diagram of the GitHub repository jonrad/lsp-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jonrad/lsp-mcp
- Repository: https://github.com/jonrad/lsp-mcp

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TD
    %% MCP Clients
    subgraph "MCP Clients"
        Claude["Claude Desktop"]:::client
        Cursor["Cursor"]:::client
        mcpCLI["mcp-cli"]:::client
    end

    %% MCP Server Core
    subgraph "MCP Server Core"
        Entrypoint["app.ts"]:::server
        ConfigLoader["config.ts"]:::server
        ToolManager["tool-manager.ts"]:::server
        LSPManager["lsp-manager.ts"]:::server
        LSPProtocol["lsp.ts"]:::server
        LSPMethods["lsp-methods.ts"]:::server
        MCPInit["mcp.ts"]:::server
        Logger["logger.ts"]:::server
        IndexStartup["index.ts"]:::server
    end

    %% Resources
    subgraph "Static Resources"
        Schema["generated.protocol.schema.json"]:::storage
        Meta["metaModel.json"]:::storage
        ThirdParty["3rdparty/metaModel.ts"]:::storage
    end

    %% Development Configs
    subgraph "Dev Configurations"
        DevJSON1["dev/dev.config.json"]:::config
        DevJSON2["dev/prod.config.json"]:::config
        ProxyJS["dev/proxy.js"]:::config
        MCPCLI1["dev/mcp-cli/npx.json"]:::config
        MCPCLI2["dev/mcp-cli/simple.json"]:::config
        MCPCLI3["dev/mcp-cli/with-config.json"]:::config
        MCPCLI4["dev/mcp-cli/with-docker.json"]:::config
    end

    %% External LSP Servers
    subgraph "External LSP Servers"
        TSLS["TypeScript Language Server"]:::external
        PyLS["Python Language Server"]:::external
    end

    %% File System / Codebase
    Codebase["Codebase (files)"]:::storage

    %% Docker and packaging
    Dockerfile["Dockerfile"]:::config
    DockerIgnore[".dockerignore"]:::config
    PackageJSON["package.json"]:::config

    %% Flows
    Claude -->|"MCP over stdin/stdout or TCP"| Entrypoint
    Cursor -->|"MCP over stdin/stdout or TCP"| Entrypoint
    mcpCLI -->|"MCP over stdin/stdout or TCP"| Entrypoint

    Entrypoint -->|"calls"| MCPInit
    Entrypoint -->|"loads"| ConfigLoader
    Entrypoint -->|"initializes"| Logger
    Entrypoint -->|"bootstraps"| IndexStartup

    ConfigLoader -->|"validate config via zod"| ToolManager
    ConfigLoader -.->|"load dev/prod config"| DevJSON1
    ConfigLoader -.->|"load dev/prod config"| DevJSON2
    ConfigLoader -.->|"load proxy settings"| ProxyJS
    ConfigLoader -.->|"load CLI configs"| MCPCLI1
    ConfigLoader -.->|"load CLI configs"| MCPCLI2
    ConfigLoader -.->|"load CLI configs"| MCPCLI3
    ConfigLoader -.->|"load CLI configs"| MCPCLI4
    Entrypoint -.->|"build context"| Dockerfile
    Entrypoint -.->|".dockerignore"| DockerIgnore
    Entrypoint -.->|"package info"| PackageJSON

    ToolManager -->|"register LSP tool"| LSPManager

    LSPManager -->|"spawn LSP on demand"| TSLS
    LSPManager -->|"spawn LSP on demand"| PyLS

    TSLS -->|"reads files"| Codebase
    PyLS -->|"reads files"| Codebase

    LSPProtocol <-->|"JSON-RPC over stdio"| TSLS
    LSPProtocol <-->|"JSON-RPC over stdio"| PyLS

    LSPMethods -->|"generate MCP endpoints from schema"| Entrypoint
    Schema -.->|"input to codegen"| LSPMethods
    Meta -.->|"input to codegen"| LSPMethods
    ThirdParty -.->|"input to codegen"| LSPMethods

    Entrypoint -->|"expose MCP methods"| Claude
    Entrypoint -->|"expose MCP methods"| Cursor
    Entrypoint -->|"expose MCP methods"| mcpCLI

    %% Click Events
    click Entrypoint "https://github.com/jonrad/lsp-mcp/blob/main/src/app.ts"
    click ConfigLoader "https://github.com/jonrad/lsp-mcp/blob/main/src/config.ts"
    click ToolManager "https://github.com/jonrad/lsp-mcp/blob/main/src/tool-manager.ts"
    click LSPManager "https://github.com/jonrad/lsp-mcp/blob/main/src/lsp-manager.ts"
    click LSPProtocol "https://github.com/jonrad/lsp-mcp/blob/main/src/lsp.ts"
    click LSPMethods "https://github.com/jonrad/lsp-mcp/blob/main/src/lsp-methods.ts"
    click MCPInit "https://github.com/jonrad/lsp-mcp/blob/main/src/mcp.ts"
    click Logger "https://github.com/jonrad/lsp-mcp/blob/main/src/logger.ts"
    click IndexStartup "https://github.com/jonrad/lsp-mcp/blob/main/src/index.ts"
    click Schema "https://github.com/jonrad/lsp-mcp/blob/main/src/resources/generated.protocol.schema.json"
    click Meta "https://github.com/jonrad/lsp-mcp/blob/main/src/resources/metaModel.json"
    click ThirdParty "https://github.com/jonrad/lsp-mcp/blob/main/src/3rdparty/metaModel.ts"
    click Dockerfile "https://github.com/jonrad/lsp-mcp/tree/main/Dockerfile"
    click DockerIgnore "https://github.com/jonrad/lsp-mcp/blob/main/.dockerignore"
    click DevJSON1 "https://github.com/jonrad/lsp-mcp/blob/main/dev/dev.config.json"
    click DevJSON2 "https://github.com/jonrad/lsp-mcp/blob/main/dev/prod.config.json"
    click ProxyJS "https://github.com/jonrad/lsp-mcp/blob/main/dev/proxy.js"
    click MCPCLI1 "https://github.com/jonrad/lsp-mcp/blob/main/dev/mcp-cli/npx.json"
    click MCPCLI2 "https://github.com/jonrad/lsp-mcp/blob/main/dev/mcp-cli/simple.json"
    click MCPCLI3 "https://github.com/jonrad/lsp-mcp/blob/main/dev/mcp-cli/with-config.json"
    click MCPCLI4 "https://github.com/jonrad/lsp-mcp/blob/main/dev/mcp-cli/with-docker.json"
    click PackageJSON "https://github.com/jonrad/lsp-mcp/blob/main/package.json"

    %% Styles
    classDef client fill:#B3DDF2,stroke:#333,stroke-width:1px;
    classDef server fill:#AED6F1,stroke:#333,stroke-width:1px;
    classDef external fill:#F9E79F,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef storage fill:#ABEBC6,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2;
    classDef config fill:#F5CBA7,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2;
```
