# isaacphi/mcp-language-server architecture

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

- Interactive diagram: https://gitdiagram.com/isaacphi/mcp-language-server
- Repository: https://github.com/isaacphi/mcp-language-server

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Go Code"
        direction TB
        CLI["CLI Entrypoint\nmain.go"]:::runtime
        Parser["Argument Parser & Config\ntools.go"]:::runtime
        Watcher["File Watcher\ninternal/watcher/"]:::runtime
        MCP["MCP Protocol Server\n(mcp-go)"]:::runtime
        Tools["Tools Layer\ninternal/tools/"]:::runtime
        Adapter["LSP Client Adapter\ninternal/lsp/"]:::runtime
        Protocol["Protocol Types & Tables\ninternal/protocol/"]:::runtime
        Logging1["Logging Subsystem\ninternal/logging/logger.go"]:::runtime
        Logging2["Logging Utilities\ninternal/utilities/logging.go"]:::runtime
    end

    subgraph "External Processes"
        direction TB
        ExtLSP["External LSP Servers\n(gopls, rust-analyzer, ...)"]:::external
    end

    subgraph "Developer Tools"
        direction TB
        Codegen["Code Generation Subcommand\ncmd/generate/"]:::dev
    end

    subgraph "Tests"
        direction TB
        Test["Integration Test Harness\nintegrationtests/"]:::test
    end

    %% Runtime flow
    CLI -->|"parses flags"| Parser
    CLI -->|"initializes logger"| Logging1
    CLI --> Logging2
    CLI -->|"starts watcher"| Watcher
    CLI -->|"starts MCP server"| MCP

    Watcher -->|"file change events"| Tools
    MCP -->|"MCP JSON"| Tools
    Tools -->|"calls adapter"| Adapter
    Adapter -->|"LSP JSON-RPC"| ExtLSP
    ExtLSP -->|"responses"| Adapter
    Tools -->|"uses types"| Protocol
    Adapter --> Protocol

    %% Codegen flow
    CLI -.->|"codegen subcommand"| Codegen

    %% Test flow
    Test -->|"spins up"| ExtLSP
    Test -->|"uses fixtures"| Test

    %% Click Events
    click CLI "https://github.com/isaacphi/mcp-language-server/blob/main/main.go"
    click Parser "https://github.com/isaacphi/mcp-language-server/blob/main/tools.go"
    click Watcher "https://github.com/isaacphi/mcp-language-server/tree/main/internal/watcher/"
    click Adapter "https://github.com/isaacphi/mcp-language-server/tree/main/internal/lsp/"
    click Tools "https://github.com/isaacphi/mcp-language-server/tree/main/internal/tools/"
    click Protocol "https://github.com/isaacphi/mcp-language-server/tree/main/internal/protocol/"
    click Logging1 "https://github.com/isaacphi/mcp-language-server/blob/main/internal/logging/logger.go"
    click Logging2 "https://github.com/isaacphi/mcp-language-server/blob/main/internal/utilities/logging.go"
    click Codegen "https://github.com/isaacphi/mcp-language-server/tree/main/cmd/generate/"
    click Test "https://github.com/isaacphi/mcp-language-server/tree/main/integrationtests/"

    classDef runtime fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef external fill:#e5ffe5,stroke:#28a745,color:#28a745
    classDef dev fill:#fff5cc,stroke:#dbab09,color:#8a6d00
    classDef test fill:#eeeeee,stroke:#6c757d,color:#6c757d
```
