Vega MCP Server

A standalone Model Context Protocol server that exposes Vega design system documentation as structured tools for AI assistants such as GitHub Copilot, Cursor, and Claude. The project is scaffolded with Nx as a monorepo.

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                           AI Assistant                                  │
│                  (GitHub Copilot / Cursor / Claude)                     │
└──────────────────────────┬──────────────────────────────────────────────┘
                           │  MCP Protocol
                           ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         MCP Server (index.ts)                           │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      Transport Layer                             │   │
│  │  ┌─────────────────┐          ┌────────────────────────────┐    │   │
│  │  │   stdio (CLI)   │          │   HTTP (Streamable HTTP)   │    │   │
│  │  │  Single session  │          │  Multi-session + Swagger   │    │   │
│  │  └─────────────────┘          └────────────────────────────┘    │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                              │                                          │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      Tool Registry (7 tools)                     │   │
│  │  list_components │ get_component_api │ get_component_examples    │   │
│  │  list_types │ get_type_definition │ search_docs │ get_doc        │   │
│  └──────────────────────────┬───────────────────────────────────────┘   │
│                              │                                          │
│  ┌──────────────────────────┴───────────────────────────────────────┐   │
│  │                      ContentLoader                               │   │
│  │  In-memory index: component docs, type docs, examples, guides    │   │
│  │  ┌──────────────┐                                                │   │
│  │  │  SearchEngine │  Full-text search with TF scoring             │   │
│  │  └──────────────┘                                                │   │
│  └──────────────────────────┬───────────────────────────────────────┘   │
│                              │  reads .md files from                    │
└──────────────────────────────┼──────────────────────────────────────────┘
                               ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                       ContentFetcher                                     │
│                                                                          │
│  ┌──────────────────┐       ┌─────────────────────────────────────────┐  │
│  │  BlobDownloader   │       │         ContentCache                    │  │
│  │                   │       │                                         │  │
│  │  Azure Blob Store │       │  OS-standard cache dir:                 │  │
│  │  - listBlobs()    │       │    Linux:   ~/.cache/vega-mcp/          │  │
│  │  - downloadBlob() │       │    macOS:   ~/Library/Caches/vega-mcp/  │  │
│  │  - Retry w/ backoff│      │    Windows: %LOCALAPPDATA%\vega-mcp\    │  │
│  │  - 10 concurrent  │       │                                         │  │
│  └────────┬─────────┘       │  - TTL validation (.fetched-at marker)   │  │
│           │                  │  - Atomic writes (temp → rename)         │  │
│           │  downloads to    │  - LRU eviction (max 3 versions)        │  │
│           └─────────────────►│  - Age-based purge (> 30 days)          │  │
│                              └─────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────┘

Data Flow

Startup
  │
  ├─ parseConfig()          CLI flags + env vars → ServerConfig
  │
  ├─ resolveContentDir()    Content override? → use local dir
  │     │                   Otherwise → ContentFetcher:
  │     │                     cache hit?  → return cached path
  │     │                     cache miss? → download from Azure → cache → return path
  │     ▼
  ├─ ContentLoader          Reads all .md files into in-memory Maps
  │     │
  ├─ registerTools()        Binds 7 MCP tools to the loader
  │     │
  └─ startTransport()       stdio or HTTP based on --http flag
        │
        ▼
  Serving MCP requests ← AI assistant queries tools

Prerequisites

• Node.js 20 or newer
• npm 10 or newer

Quick Start

1. Install dependencies

npm install

2. Build and run

npx nx build http-server
npx nx build stdio-server
npx nx serve stdio-server             # stdio mode (default)
npx nx serve http-server              # HTTP mode on port 3000

Documentation content is automatically fetched from Azure Blob Storage on first run and cached locally at ~/.cache/vega-mcp/{version}/. Use --vega-version to pin a specific version, or set VEGA_MCP_CONTENT_DIR to point to a local content directory.

MCP Tools

| Tool | Parameters | Description | | ------------------------ | ----------------------------- | ---------------------------------------------------------------- | | list_components | None | List all Vega UI components with available API docs and examples | | get_component_api | componentName | Return the full API documentation for a component | | get_component_examples | componentName, framework? | Return framework-specific code examples | | list_types | None | List all Vega TypeScript type definitions | | get_type_definition | typeName | Return the full type definition content | | search_docs | query, maxResults? | Search across all loaded documentation with preview snippets | | get_doc | name | Return the full content of a document by exact name/path |

VS Code / Cursor Configuration

Local build reference

{
  "servers": {
    "vega": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/vega-mcp/dist/index.js"]
    }
  }
}

npx usage

{
  "servers": {
    "vega": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@heartlandone/vega-mcp"]
    }
  }
}

Team-shared content directory

{
  "servers": {
    "vega": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/vega-mcp/dist/index.js"],
      "env": {
        "VEGA_MCP_CONTENT_DIR": "/shared/vega-content"
      }
    }
  }
}

Development Commands

npx nx serve stdio-server              # Run in stdio mode (dev, with tsx)
npx nx serve http-server               # Run in HTTP mode on port 3000
npx nx build http-server               # Bundle into dist/apps/http-server/index.js
npx nx build stdio-server              # Bundle into dist/apps/stdio-server/index.js
npx nx lint http-server                # Run ESLint
npx nx test http-server                # Run Vitest unit tests
npx nx type-check http-server          # Type check with tsc --noEmit
npm run format                         # Format files with Prettier
npm run format:check                   # Check formatting

Environment Variables

| Variable | Default | Description | | ---------------------- | -------- | ----------------------------------------------------- | | VEGA_MCP_CONTENT_DIR | — | Override the content directory path (skip auto-fetch) | | VEGA_VERSION | latest | Content version to fetch from blob storage | | AZURE_BLOB_SAS_TOKEN | — | SAS token for authenticated blob storage access | | PORT | 3000 | HTTP server listen port (HTTP mode only) |

CI/CD

GitHub Actions workflows are included for:

• CI: lint, type-check, test, and build on pushes and pull requests
• Publish: npm publish to GitHub Packages on version tags

Release Vega MCP HTTP Service

Use this process when you need to publish a new vega-mcp HTTP service version.

1. Build and push Docker image to ACR

# Build the Linux image used by the HTTP deployment
npx nx run http-server:image:dev

# Optional: authenticate to Azure and ACR if needed
az login
az acr login --name vegaassistantacrdev

# Tag and push both commit-based and latest tags to ACR
npx nx run http-server:deploy-image:dev

2. Trigger the deploy pipeline in vega-assistant

Go to the vega-assistant repository and run the pipeline that deploys the vega-mcp pod.

Recommended checks before running the pipeline:

• Confirm the new image tag is available in vegaassistantacrdev.azurecr.io/vega-mcp-dev
• Confirm the pipeline is configured to pull the expected image tag

3. Verify deployment result on Vega website

After the pipeline finishes:

• Open Vega website and run MCP-related user flows
• Confirm the HTTP service responds as expected
• Check logs and error rate to ensure there is no regression