# biegehydra/bifrostmcp architecture

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

- Interactive diagram: https://gitdiagram.com/biegehydra/bifrostmcp
- Repository: https://github.com/biegehydra/bifrostmcp

## Overview

##### Project type and purpose
- This is a VS Code extension (“Bifrost”) that embeds an HTTP/SSE MCP server into the VS Code Extension Host.
- Purpose: expose VS Code’s language-server–based features (find references, completions, code actions, etc.) over a Model Context Protocol (MCP) HTTP/SSE interface for AI assistants or other external clients.

##### Top-level file structure and architectural implications
- package.json, webpack.config.js, tsconfig.json – build and bundling for a Node/Extension Host target
- src/extension.ts – entry point that registers commands, spins up the HTTP/SSE server, reads bifrost.config.json
- src/config.ts – loads project-specific config (port, path, projectName) or falls back to defaults
- src/toolRunner.ts, src/tools.ts – dispatches incoming MCP requests to the correct VS Code API calls
- src/rosyln.ts, src/mcpresponses.ts – glue to map VS Code/LSP data to MCP response format
- src/debugPanel.ts, src/webview.ts – UI components (WebviewPanel) for debugging and manual testing
- src/helpers.ts, src/globals.ts – shared utilities and global state (current port, project path)
- src/test/extension.test.ts – end-to-end and unit tests against extension activation and HTTP endpoints

##### Key architectural patterns
- Single Node.js/Extension-Host process running inside VS Code’s Extension Host sandbox
- HTTP server exposing two endpoints:
- SSE stream at /sse for real-time notifications
- HTTP POST at /message for RPC-style requests
- MCP Router: maps incoming JSON payload (tool name + args) to a handler in toolRunner → calls VS Code API
- Optional external “supergateway” CLI wrapper that proxies SSE to AI assistants (via npx supergateway)
- Webview-based debug UI that connects to the same HTTP/SSE server to show available tools and sample payloads

##### Components and interactions
A. VS Code IDE shell
- Extension Host process
– Config Manager (reads bifrost.config.json or example.bifrost.config.json)
– MCP HTTP/SSE Server (port 8008 default or configured)
– MCP Router / Tool Runner
– Roslyn/LSP Adapter (src/rosyln.ts)
– Webview Debug Panel & Commands (src/debugPanel.ts, src/webview.ts)
B. VS Code Language Features
- Underlying language servers (provided by other installed VS Code extensions)
- VS Code API layer for symbol search, code actions, references, etc.
C. External Clients
- AI Assistant (MCP-compatible client) connecting over SSE and HTTP POST
- Optional Supergateway CLI bridging SSE to external AI assistant
D. Tests & Build
- Webpack bundling → packaged extension
- Unit/E2E tests hitting /sse and /message endpoints

##### Relationships and data flows
- On activation: extension.ts → reads config → starts HTTP/SSE server
- External client → opens SSE connection → receives server metadata/events
- External client → sends JSON RPC POST to /message with “name” = tool (e.g., get_completions) and arguments
- MCP Router → toolRunner → invokes appropriate VS Code API via language client or Roslyn adapter
- Handler returns result → formatted via mcpresponses → sent back over HTTP response or SSE update
- DebugPanel Webview uses the same endpoints to let a user manually fire MCP requests and view JSON responses

##### Important design principles and patterns
- Modular separation: config, routing, handlers, adapters, UI
- Single-process Node server for minimal overhead in Extension Host
- Use of SSE for streaming events and HTTP POST for request/response
- Webview for in-IDE debugging, without leaving VS Code
- Config-driven ports and paths for multi-project isolation

##### Capturing all essential elements
- Project-specific config flow → custom port & path → server instantiation
- Test harness hitting the MCP endpoints
- Build step (webpack) feeding into the packaged extension
- How the debug panel Webview and commands tie back into the same HTTP/SSE infrastructure

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% VS Code IDE Boundary
    subgraph "VS Code IDE" 
        direction TB
        subgraph "Extension Host"
            direction TB
            %% Entry Point & Config
            ExtensionActivation["Extension Activation & Server Startup"]:::server
            ConfigManager["Configuration Manager"]:::server
            ExampleConfig["example.bifrost.config.json"]:::server

            %% Global State & Utilities
            Globals["Global State"]:::server
            Helpers["Shared Helpers"]:::server

            %% MCP HTTP/SSE Server and Routing
            subgraph "MCP HTTP/SSE Server" 
                direction TB
                Router["MCP Router & Tool Runner"]:::server
                Tools["Tool Definitions"]:::server
                Adapter["Roslyn/LSP Adapter"]:::adapter
                Formatter["MCP Response Formatter"]:::adapter
            end

            %% Debug UI
            subgraph "Webview Debug Panel" 
                direction TB
                DebugPanel["Debug Panel UI"]:::ui
                WebviewContent["Webview Content/Controller"]:::ui
            end
        end
    end

    %% External Components
    ExternalAssistant["External AI Assistant"]:::external
    Supergateway["Supergateway CLI"]:::external
    LanguageAPI["VS Code Language Server API"]:::adapter

    %% Tests & Build
    subgraph "Build & Test"
        direction TB
        Webpack["webpack.config.js"]:::config
        TSConfig["tsconfig.json"]:::config
        PackageJSON["package.json"]:::config
        Tests["Extension Unit & E2E Tests"]:::test
    end

    %% Connections
    ExtensionActivation -->|reads config| ConfigManager
    ConfigManager -->|loads example config| ExampleConfig
    ExtensionActivation -->|starts server| Router
    Router -->|dispatches to| Tools
    Tools -->|calls VS Code API| LanguageAPI
    Tools -->|uses adapter| Adapter
    Adapter -->|formats with| Formatter
    ExternalAssistant -->|SSE connect /sse| Router
    ExternalAssistant -->|HTTP POST /message| Router
    Supergateway -->|proxies SSE| ExternalAssistant
    DebugPanel -->|uses endpoints| Router
    WebviewContent -->|uses endpoints| Router

    %% Build & Test Flows
    Webpack -->|bundles| ExtensionActivation
    TSConfig -->|types| ExtensionActivation
    PackageJSON -->|metadata| ExtensionActivation
    Tests -->|hits endpoints| Router

    %% Click Events
    click ExtensionActivation "https://github.com/biegehydra/bifrostmcp/blob/master/src/extension.ts"
    click ConfigManager "https://github.com/biegehydra/bifrostmcp/blob/master/src/config.ts"
    click ExampleConfig "https://github.com/biegehydra/bifrostmcp/blob/master/example.bifrost.config.json"
    click Globals "https://github.com/biegehydra/bifrostmcp/blob/master/src/globals.ts"
    click Helpers "https://github.com/biegehydra/bifrostmcp/blob/master/src/helpers.ts"
    click Router "https://github.com/biegehydra/bifrostmcp/blob/master/src/toolRunner.ts"
    click Tools "https://github.com/biegehydra/bifrostmcp/blob/master/src/tools.ts"
    click Adapter "https://github.com/biegehydra/bifrostmcp/blob/master/src/rosyln.ts"
    click Formatter "https://github.com/biegehydra/bifrostmcp/blob/master/src/mcpresponses.ts"
    click DebugPanel "https://github.com/biegehydra/bifrostmcp/blob/master/src/debugPanel.ts"
    click WebviewContent "https://github.com/biegehydra/bifrostmcp/blob/master/src/webview.ts"
    click Tests "https://github.com/biegehydra/bifrostmcp/blob/master/src/test/extension.test.ts"
    click Webpack "https://github.com/biegehydra/bifrostmcp/blob/master/webpack.config.js"
    click TSConfig "https://github.com/biegehydra/bifrostmcp/blob/master/tsconfig.json"
    click PackageJSON "https://github.com/biegehydra/bifrostmcp/blob/master/package.json"

    %% Styles
    classDef server fill:#E0F7FA,stroke:#006064,color:#006064
    classDef adapter fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef ui fill:#FFF3E0,stroke:#EF6C00,color:#EF6C00
    classDef external fill:#FFEBEE,stroke:#C62828,color:#C62828
    classDef config fill:#EDE7F6,stroke:#512DA8,color:#512DA8
    classDef test fill:#F3E5F5,stroke:#4A148C,color:#4A148C
```
