# tjx666/vscode-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/tjx666/vscode-mcp
- Repository: https://github.com/tjx666/vscode-mcp

## Overview

##### Project Type and Purpose
- This is a monorepo open-source tool (VSCode extension + accompanying server + IPC library) that “bridges” VSCode’s LSP and API into the MCP (Model Context Protocol) ecosystem for AI coding assistants.
- Its goal is to let external AI clients (Cursor, Copilot, Claude, etc.) call VSCode real-time services (diagnostics, hover, navigation, execute commands, AI agent calls) via a standard MCP protocol.

##### File Structure
- Top-level: project configuration (.github CI, eslint, pnpm workspace).
- packages/vscode-mcp-bridge: The VSCode Extension (TypeScript) that opens a Unix socket and exposes LSP & API calls to local clients.
- packages/vscode-mcp-ipc: A small TypeScript library defining events & dispatchers for type-safe JSON communication over the socket.
- packages/vscode-mcp-server: A CLI “MCP Server” (JSON-RPC stdio endpoint) that translates MCP calls into function calls to the IPC layer.

##### Key Architecture Details from README
- Three main modules:
a. MCP Client (external AI agent) speaks JSON-RPC over stdio.
b. MCP Server (Node CLI) uses the vscode-mcp-ipc library.
c. VSCode Extension (vscode-mcp-bridge) listens on a Unix socket, implements calls via VSCode API & LSP.
- Communication flows:
- JSON-RPC (stdio) ↔ MCP Server
- Function calls ↔ IPC Layer
- JSON over Unix socket ↔ VSCode Extension
- Extension ↔ VSCode API & LSP

##### Components
- External “MCP Client” (Cursor, GitHub Copilot, etc.)
- MCP Server
- JSON-RPC endpoint (stdio)
- Calls into vscode-mcp-ipc library
- IPC Layer
- Event definitions & dispatcher
- Unix socket transport
- VSCode Extension
- Socket listener
- VSCode API calls & LSP integration
- VSCode’s Language Server Protocol & Extension API

##### Architectural Patterns & Principles
- Modular layering: clear separation of concerns (client ↔ server ↔ IPC ↔ extension ↔ IDE)
- Protocol-adapter pattern: JSON-RPC ↔ internal calls ↔ socket transport ↔ VSCode API
- Type-safe event definitions in ipc package
- Per-workspace socket to isolate multi-window environments

##### Relevant Technologies & Frameworks
- Node.js + TypeScript
- VSCode Extension API
- Language Server Protocol (LSP) via VSCode
- JSON-RPC (protocol for MCP Server)
- Unix domain sockets for IPC
- pnpm monorepo

##### Final Checklist
- Components clearly named and grouped
- Call/response flows in correct order
- Notes on extensibility points for open-source contributors

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client" 
        direction TB
        MCPClient["MCP Client<br/><i>(Cursor, Copilot, etc.)</i>"]:::client
    end

    %% Server Layer
    subgraph "MCP Server" 
        direction TB
        JSONRPC["MCP Server: JSON-RPC StdIO"]:::server
        ServerTools["MCP Server Tools<br/>(MCP → IPC translation)"]:::server
    end

    %% IPC Layer
    subgraph "IPC Layer"
        direction TB
        IPCIndex["IPC Layer Index"]:::ipc
        IPCDispatch["IPC Dispatcher"]:::ipc
        IPCEvents["IPC Events"]:::ipc
    end

    %% Extension & LSP Layer
    subgraph "VSCode Extension & LSP"
        direction TB
        ExtensionEntry["Extension Activation"]:::ext
        SocketListener["Socket Listener"]:::ext
        BridgeServices["Bridge Services"]:::ext
        VSCodeAPI["VSCode API & LSP"]:::ext
    end

    %% Connections
    MCPClient -->|JSON-RPC over stdio| JSONRPC
    JSONRPC -->|TS function calls| ServerTools
    ServerTools -->|TS function calls| IPCIndex
    IPCIndex -->|uses dispatcher| IPCDispatch
    IPCIndex -->|loads events| IPCEvents
    IPCDispatch -->|JSON over Unix socket| SocketListener
    IPCEvents -->|defines protocols| SocketListener
    SocketListener -->|calls services| BridgeServices
    BridgeServices -->|uses VSCode API / LSP| VSCodeAPI
    ExtensionEntry -->|activates| SocketListener
    ExtensionEntry -->|activates| BridgeServices

    %% Click Events
    click JSONRPC "https://github.com/tjx666/vscode-mcp/blob/main/packages/vscode-mcp-server/src/index.ts"
    click JSONRPC "https://github.com/tjx666/vscode-mcp/blob/main/packages/vscode-mcp-server/src/server.ts"
    click ServerTools "https://github.com/tjx666/vscode-mcp/blob/main/packages/vscode-mcp-server/src/tools/index.ts"
    click IPCIndex "https://github.com/tjx666/vscode-mcp/blob/main/packages/vscode-mcp-ipc/src/index.ts"
    click IPCDispatch "https://github.com/tjx666/vscode-mcp/blob/main/packages/vscode-mcp-ipc/src/dispatch.ts"
    click IPCEvents "https://github.com/tjx666/vscode-mcp/blob/main/packages/vscode-mcp-ipc/src/events/index.ts"
    click ExtensionEntry "https://github.com/tjx666/vscode-mcp/blob/main/packages/vscode-mcp-bridge/src/extension.ts"
    click SocketListener "https://github.com/tjx666/vscode-mcp/blob/main/packages/vscode-mcp-bridge/src/socket-server.ts"
    click BridgeServices "https://github.com/tjx666/vscode-mcp/blob/main/packages/vscode-mcp-bridge/src/services/index.ts"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef server fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef ipc fill:#90EE90,stroke:#333,stroke-width:1px
    classDef ext fill:#FFDAB9,stroke:#333,stroke-width:1px
```
