VS Code MCP Supergateway

A centralized, multi-client Model Context Protocol (MCP) gateway that aggregates, routes, and offloads context between IDE clients, local LLM workers, and backend MCP services.

💡 Overview & Value Proposition

As MCP usage grows, managing multiple disjointed MCP servers across different clients (VS Code/Copilot, LM Studio, etc.) becomes cumbersome. VS Code MCP Supergateway acts as a unified hub:

1. Multiplexing & Routing: Connect multiple clients to a single, orchestrated MCP endpoint.

2. Context & Token Savings: Keep expensive Frontier Model context clean by delegating repetitive context-structuring tasks to local worker models.

3. LM Studio Loopback Pattern: Turn LM Studio into both an MCP consumer and a high-speed local MCP tool/worker for tasks like documentation linting, diff summarization, and task management.

Related MCP server: mcp-llm-bridge

🏗 Architecture

Everything except your IDE and LM Studio runs inside Docker — the containers bring their own Node.js, Python, and the current set of six upstream MCP servers.

graph LR
    subgraph Host["🖥 Host machine"]
        Copilot["VS Code / Copilot Chat"]

        subgraph LMStudio["LM Studio"]
          LMStudioServer["Local API server :1234"]
          LMStudioUI["Client UI"]
          LocalAgents@{ shape: subproc, label: "local agents" }
        end

        subgraph Docker["🐳 Docker Compose"]
            Supergateway["SuperGateway MCP Server"]

            Proxy@{ shape: subproc, label: "MSP Stack MCP Aggregate<br/>(admin UI :3100)" }
            SemanticBridge["Semantic Bridge MCP<br/>call chain resolver for<br/>C# / TS / JS / Py / MD / ..." ]
            SupergatewayRpc["Supergateway RPC<br/>local tool endpoint<br/>(LM Studio + SiYuan)" ]
            MCP@{ shape: processes, label: "Access Controlled Tools &amp;<br/> Task Mgmt for Local Agents<br/>(MCP :8080)" }

            GitLab["GitLab MCP"]
            SiYuanNote["SiYuan Note MCP<br/>(Markdown Vault UI :6806)"]
            CodebaseMemory["Codebase Memory MCP<br>(graph routed through dashboard :3100)"]
            MarkItDown["MarkItDown MCP<br/>(docs/Office/PDF to Markdown)"]
        end
    end

    Supergateway --> |forward proxy| Proxy
    SemanticBridge -. provide semantic edges .-> CodebaseMemory
    SupergatewayRpc -. exposes local tools .-> Proxy
    SupergatewayRpc --> |LM Studio / tool calls| LMStudioServer
    SiYuanNote --> |updates task docs| SupergatewayRpc
    Supergateway -->|provider| MCP

    MCP --> Copilot
    MCP --> LMStudioServer

    LMStudioServer --> |openweight model provider| LocalAgents
    LocalAgents --> Copilot
    LocalAgents --> LMStudioUI
    LMStudioServer --> |tool results / completions| SupergatewayRpc

    Proxy --> CodebaseMemory
    Proxy --> GitLab
    Proxy --> MarkItDown
    Proxy --> SiYuanNote
    Proxy --> SemanticBridge

    click Supergateway "blob/main/src/gateway.ts" "Entry point: src/gateway.ts (main())"
    click SemanticBridge "blob/main/src/semanticBridgeMcp.ts" "Entry point: src/semanticBridgeMcp.ts (semantic API bridge)"
    click SupergatewayRpc "blob/main/src/supergatewayRpcMcp.ts" "Entry point: src/supergatewayRpcMcp.ts (supergateway-rpc)"
    click Proxy href "https://www.npmjs.com/package/@mspstack/mcp-gateway" "npm: @mspstack/mcp-gateway" _blank
    click MCP href "https://www.npmjs.com/package/@mspstack/mcp-gateway" "npm: @mspstack/mcp-gateway (RBAC & tool access)" _blank
    click SiYuanNote href "https://www.npmjs.com/package/siyuan-mcp" "npm: siyuan-mcp" _blank
    click CodebaseMemory href "https://www.npmjs.com/package/codebase-memory-mcp" "npm: codebase-memory-mcp" _blank
    click GitLab href "https://www.npmjs.com/package/@zereight/mcp-gitlab" "npm: @zereight/mcp-gitlab" _blank
    click MarkItDown href "https://pypi.org/project/markitdown-mcp/" "PyPI: markitdown-mcp" _blank
    click LMStudioServer href "https://lmstudio.ai/docs/app/api" "LM Studio local server docs" _blank
    click LMStudioUI href "https://lmstudio.ai/" "LM Studio" _blank

    classDef entryPoint fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px,color:#1e3a8a;
    classDef thirdParty fill:#fef3c7,stroke:#b45309,stroke-width:2px,color:#78350f;
    classDef hostApp fill:#e5e7eb,stroke:#4b5563,stroke-width:1px,color:#111827;

    class Supergateway,SemanticBridge,SupergatewayRpc entryPoint;
    class Proxy,MCP,SiYuanNote,CodebaseMemory,GitLab,MarkItDown thirdParty;
    class Copilot,LMStudioServer,LMStudioUI,LocalAgents hostApp;

    style Host fill:#f8fafc,stroke:#64748b,stroke-width:1px
    style LMStudio fill:#f1f5f9,stroke:#94a3b8,stroke-width:1px,stroke-dasharray: 3 3
    style Docker fill:#ecfeff,stroke:#0e7490,stroke-width:2px

Legend: 🟦 blue = this repo's code entry points (click to open the source file) · 🟨 amber = third-party MCP servers/packages (click for npm/PyPI page) · ⬜ grey = host-side applications you already run (VS Code, LM Studio). Subgraph backgrounds: outer host boundary in slate, the LM Studio group dashed, the Docker Compose boundary in cyan.

🧭 Canonical project policy

This README is the canonical project-facing reference for users and developers. It describes the supported runtime, environment files, dependency policy, and operational conventions for this repository.

The local agent instructions file in this repo is a reminder layer for AI tools and contributors. It exists to keep agents aligned with the project rules, but it is not a second source of truth. When a task touches project policy, dependency pinning, environment setup, or operational conventions, the agent must re-read the relevant README section and use it as the authoritative source.

For reproducibility, direct dependency versions in package.json must be pinned to exact versions instead of ranges, and paired packages such as ws and @types/ws must stay in sync in the same change. This prevents silent drift between developer machines, CI, and the runtime image.

🚀 Quick Start

1. Prerequisites

• Docker — Docker Desktop on Windows/macOS. This is the only requirement. Node.js, Python, and every upstream MCP server are bundled inside the image; nothing is installed on your host.

• VS Code with GitHub Copilot — the client that will consume the gateway.

• LM Studio — optional, only for local model offloading & the loopback tools.

2. Clone and configure

git clone https://github.com/Flexi23/vscode-mcp-supergateway.git
cd vscode-mcp-supergateway
cp .env.example .env

Then edit .env:

3. Start

docker compose up -d --build

The first build takes a while and produces a ~2.9 GB image — see 🐳 Operations for why.

4. Connect VS Code

Point your MCP client config at the gateway's public port:

{
  "servers": {
    "central-mcp-gateway": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

Verify it came up:

curl http://localhost:8080/ping     # -> ok
docker compose logs gateway         # -> [upstream:*] connected (stdio) x6

The local dashboard lives at http://localhost:3100/ and exposes the Codebase Memory overview and project indexing/status. The graph UI itself is served on the upstream default internal port 9749, and routed at /cbm/graph without wrapping the dashboard shell. The public MCP endpoint remains on port 8080; the dashboard stays on port 3100, and legacy browser routes are no longer exposed.

The Codebase Memory progress stream sends a structured websocket payload for each update: type, repoPath, and the current job state. In addition to the percent, the payload includes fileName, processedCount, and totalCount, so the dashboard can show both the live file being processed and the absolute position within the total work queue.

Port numbers are a strict .env concern: every published and internal port must be declared in .env and consumed in docker-compose.yml as ${VAR}. No numeric port literals are used as a second source of truth.

📦 Services & Ports

gateway.ts and server.ts run as a single Node process in a single container (vscode-mcp-supergateway-backend:local), started via node dist/gateway.js (see docker-compose.yml). gateway.ts imports and starts server.ts's Express app directly instead of spawning a second container.

The LM Studio loopback's lmstudio_update_siyuan_task tool reads/writes SiYuan documents directly via SiyuanClient (src/services/siyuanClient.ts), the same backend the siyuan-note upstream talks to (see Configured Upstreams).

What is @mspstack/mcp-gateway?

@mspstack/mcp-gateway ("MSPStack Gateway", MIT-licensed, by Eugene Samotija) is a third-party, self-hosted MCP aggregator: it federates any number of MCP servers (stdio or HTTP) behind one endpoint with namespaced tools, and normally adds OAuth 2.1 / static-token auth, role-based tool access, and secret-store integration (OpenBao, Azure Key Vault) on top — built for MSPs running many client-facing MCP servers.

src/gateway.ts spawns it via npx -y @mspstack/mcp-gateway --port <admin-port> --config <admin-config> --db-path <db> and sets DEV_ALLOW_UNAUTHENTICATED=true, which puts it in its documented localhost-only, no-auth mode — we use its core aggregation feature to expose one MCP endpoint for our six stdio upstreams, without the OAuth/RBAC/secret-store machinery. DEV_ALLOW_UNAUTHENTICATED=true must never be used on anything but 127.0.0.1/localhost; the package itself refuses to start without it or a real auth method configured. Requires Node ≥24 (uses the built-in node:sqlite, no native dependencies) — see the Node version note below.

🔌 Configured Upstreams

All six upstreams run inside the gateway container; the runtime column only says which language runtime the image provides for them.

Upstream wiring lives in docker/gateway.config.json. The siyuan service itself (image b3log/siyuan) is defined in docker-compose.yml and also publishes its own web UI at http://localhost:6806. If you want the SiYuan lock screen enabled, set the current compose variables SIYUAN_ACCESS_AUTH_CODE and SIYUAN_ACCESS_AUTH_CODE_BYPASS in .env accordingly.

Semantic Dependency Resolver

The semantic edge resolution strategy dispatcher lives in src/services/semanticEdgeResolutionStrategyDispatcher.ts. It is the bridge that turns a repository into graph edges for Codebase Memory instead of leaving each project as an isolated node.

Important: the Roslyn-based resolver tests in resolver.test.mjs are intentionally designed to run only inside the project container. They assume the Linux runtime layout used by the gateway image (DOTNET_ROOT=/usr/share/dotnet, the container-side .NET SDK, and the bind-mounted workspace root), not a host machine installation. A host-side ENOENT for /usr/share/dotnet/dotnet is therefore not a valid signal for a container-runtime bug; the test is meant to validate the container execution path only.

It does three things in sequence:

1. Discover semantic source files under a project root.

2. Resolve cross-file references for .NET sources through the Roslyn-based dependency resolver and parse the remaining non-.NET imports directly from the filesystem.

3. Convert the resulting graph into a trace payload and ingest it with codebase-memory-mcp cli ingest_traces.

On large repositories, the gateway writes the trace payload to a temp JSON args file instead of embedding the entire JSON in a single CLI argument. That avoids the OS-level E2BIG/argv-length failure while preserving the same project + traces payload contract for Codebase Memory.

The current implementation is intentionally language-aware but not C#-only:

• C# / .cs and Razor .razor files are resolved through the Roslyn worker that runs inside the gateway container, so the dependency graph is built without depending on a host VS Code session.

• TypeScript / JavaScript imports are parsed from .ts, .tsx, .js, and .jsx files using import/require patterns.

• Python call chains are resolved by src/services/pythonCallChainResolver.ts: it spawns the container's python3 running an embedded script built on the stdlib ast module (the real Python parser), resolves intra-project imports, then walks each file's call expressions and resolves callees against per-file import bindings and a project-wide (unambiguous) symbol table — so the graph reflects actual function/method call relationships, not just imports.

• Markdown links and component references are also recognized, so docs and frontend component trees can contribute graph edges.

• Non-.NET source types rely on direct file parsing (or, for Python, the stdlib ast parser) for relative imports, local references, and call resolution; no host-side editor API is required.

The runtime integration is in src/gateway.ts: after index_repository succeeds, enrichRepositorySemanticEdges() calls the resolver, writes the generated edge list to a local JSON artifact, and then triggers ingest_traces against the project name in Codebase Memory.

This means the flow is:

index_repository -> extractEdges -> writeLinksFile -> ingest_traces

The MCP-facing entry point is src/semanticBridgeMcp.ts, which exposes C#, TypeScript, and Python workspace tools over stdio for the gateway to aggregate like any other upstream. That keeps the semantic logic behind a typed MCP tool surface instead of reaching directly into the host editor from the container runtime.

⚡ Key Features & Concepts

• Unified Control Plane: Connect Copilot and LM Studio simultaneously to your underlying toolchain (GitLab, Codebase Memory, SiYuan Note, MarkItDown).

• Sub-Agent Loopback: Offload context aggregation, diff generation, and documentation updates to fast local models running in LM Studio without consuming cloud tokens.

• Semantic Edge Resolver: Resolve cross-file dependencies from the active IDE semantics (C#, TypeScript/JavaScript, and Python call chains first, with file-based fallbacks for the same code graph) and emit graph links for the codebase-memory indexer, so the 3D graph contains structural edges instead of only isolated file nodes.

• Pattern: container-local semantic capabilities as MCP upstreams: the gateway does not reach into a host editor directly. Instead, each source-analysis capability is wrapped in its own MCP stdio bridge (for example src/semanticBridgeMcp.ts), which exposes a narrow, typed tool surface (csharp_list_workspace_files, csharp_extract_dependency_graph, typescript_extract_dependency_graph, python_extract_call_chain_graph, and friends). The gateway then aggregates that bridge like any other upstream. This keeps the routing layer uniform while making repository analysis available to all clients through the same MCP interface.

• SiYuan Note Integration: Read and edit notebooks, documents, content blocks, and native databases in a running SiYuan instance through the siyuan-note upstream.

• Document Conversion: MarkItDown upstream exposes convert_to_markdown(uri), turning PDFs, Office documents, images, and other files into Markdown for downstream agent consumption.

🐳 Operations

docker compose up -d --build   # start (rebuilds if needed)
docker compose logs -f gateway # follow gateway logs
docker compose down            # stop and remove

Notes:

• Data persistence: the gateway DB lives in the gateway-data named volume (not a bind mount) — inspect with docker compose exec gateway sh. The SiYuan workspace is a host bind mount from SIYUAN_WORKSPACE_DIR (see .env.example), so it's directly inspectable/backupable on the host.

• Node ≥24 required: @mspstack/mcp-gateway declares it in its engines field, so Dockerfile uses node:24-alpine (builder) / node:24-bookworm-slim (runtime). Do not downgrade to node:20.

• Image size (~2.9 GB): caused by Python's markitdown[all] (onnxruntime, pandas, azure SDKs, ...) plus ~330 Node packages. Accepted trade-off for having zero host-level dependencies.

🛠 Developing on this repo

Only relevant if you change the TypeScript sources. The image compiles src/ itself during docker compose build, so you never need a host-side build to run anything — a local install is purely for editor IntelliSense and fast type-check feedback:

For reproducibility, keep all direct dependency versions pinned to exact values in package.json; avoid caret ranges for runtime and transport packages because they can silently drift across machines and CI jobs. When a package ships a companion type package (ws + @types/ws), update the pair together and keep the exact version set in sync.

npm install          # type definitions for your editor
npx tsc --noEmit     # type-check without producing dist/

Then rebuild the image to pick up your changes:

docker compose up -d --build

For the repo-local MCP help and markdown vault conventions, start at the vault policy in vault/meta/vault-policy.md. It defines the canonical directory semantics, the MARKDOWN_VAULT_ROOT expectation, and the distinction between tracked project help and generated local cache files.

🗺 Roadmap & Future Plan

Current status: live gateway + semantic bridge

• Basic stdio / SSE transport routing.

• Multi-backend server orchestration for Codebase Memory, semantic bridge, GitLab, SiYuan Note, and MarkItDown.

• IDE-native semantic bridge exposing C#, TypeScript, and Python dependency/call-chain graph tools via a dedicated MCP upstream.

• Automatic stale-state reset for gateway and Codebase Memory runtime data before startup.

• Per-upstream startup log grouping and runtime tool discovery with the final tool catalog only emitted after the admin UI appears.

Next improvements

• Harden the semantic bridge for larger workspaces and more file types with finer-grained indexing and caching.

• Expand graph normalization and trace ingestion across docs, code, and UI/component references.

• Add stronger permission checks around destructive SiYuan and repository-index operations.

• Build more specialized LM Studio loopback tools for ADR generation, PR summarization, and agent task orchestration.

Phase 3: Unified Semantic Layer (Roslyn + Razor + JS + Docs)

• Treat the IDE semantic stack as a single capability family: C#, Razor, JavaScript/TypeScript, and Markdown reference-aware analysis.

• Build shared graph normalization so each semantic domain emits the same edges and metadata shape (source, target, kind, uri, range, symbol, referenceType).

• Preserve language-specific nuance: Roslyn for C#, Razor symbol resolution for .razor, TypeScript language service for JS/TS, and markdown link/reference parsing for docs.

• Feed the unified semantic graph into the same codebase-memory pipeline so the knowledge graph can reason across code and documentation, not only raw file names.

• Add cross-domain queries such as “what docs mention this component?” or “which C# symbol owns this Razor binding?”

Phase 4: LM Studio Loopback & Context Worker

• Implement local LM Studio MCP tool wrapper (summarize_diff, generate_adr, and the SiYuan task update flow).

• Add async tool handling for local inference without blocking gateway startup.

• Graceful fallback & timeout management when local GPUs are under heavy load.

Phase 5: SiYuan Note & Task Management Enhancements

• Structured task/ADR documents in SiYuan, driven by the siyuan-note upstream and lmstudio_update_siyuan_task.

• Define and maintain the repo-local vault policy and directory structure (meta/, help/, notes/, templates/, ops/, archive/) so local MCP tooling has a stable, Git-visible, project-scoped knowledge base and entry point.

• Agent scope security layer (permission checks around destructive SiYuan operations).

• Automated context bundle generator for Copilot prompts.

Design note: container-local semantic provider

The semantic graph in this project is intentionally treated as a container-local capability, not a host-side one: the Roslyn C# resolver, the TypeScript compiler-API resolver, and the Python ast-based call-chain resolver all run inside the gateway container itself (spawning dotnet/using the bundled TypeScript package/spawning python3 respectively), so none of them depend on a host VS Code session or its installed language services. The gateway remains the centralized routing layer, and each source-analysis capability is exposed as its own MCP upstream (semantic-bridge). This keeps the architecture consistent: “feature provider” and “routing aggregator” are separate responsibilities, but both live in the same container so the whole gateway stays self-contained. Markdown references are not a separate ecosystem; they are a semantic layer that links code and docs explicitly, so the graph can answer questions across implementation, UX, and documentation.

📄 License

MIT License. Feel free to contribute or adapt!

🧪 Disclaimer

Parts of this repository were deliberately generated with small local LLMs rather than a single frontier model — quality and style vary accordingly between commits. This includes the preserved original prototype created by Gemma 4 12B, which was saved on its own branch before the Docker refactor and later merged back into main for provenance. See individual commit messages for which model produced each change.