BlizDB MCP — VS Code Extension

Database explorer, SQL editor, data grid and MCP integration for BlizDB — a high-performance SQL database engine with multi-tenant support.

Architecture Overview

Database Engines

BlizDB supports two database engines — you choose which engine to use when creating a database:

Both engines are accessed through the same BlizDB connection. When using the PostgreSQL engine, BlizDB proxies all queries transparently — no separate connection is needed from the client or AI.

More external engines may be added in the future.

SQL Compatibility Highlights (native engine)

BlizDB's native engine speaks PostgreSQL-flavoured SQL, including:

• Joins: INNER / LEFT / RIGHT / FULL OUTER / CROSS — and LATERAL joins (, LATERAL (...), CROSS/LEFT JOIN LATERAL (...)) with correlated outer references
• Arrays: array types + functions, and containment/overlap operators @>, <@, &&
• JSONB: ->, ->>, #>, #>>, containment @>/<@, merge ||, GIN-accelerated
• CTEs (incl. WITH RECURSIVE), window functions, views, materialized views, triggers
• information_schema (+ size_bytes/size_pretty/table_rows extension columns), emulated read-only pg_catalog, and size functions (pg_size_pretty, pg_total_relation_size, pg_database_size, …)
• PostgreSQL wire protocol (port 5432) — psql, ODBC, JDBC, npgsql, psycopg connect directly

The engine serves an always-current capability page at https://<your-server>/compatibility (machine-readable summary at /llms.txt).

Multi-Tenant Hierarchy

BlizDB organises data in a strict hierarchy:

Portal → Domain → Database → Table

• Portal — top-level tenant (company or organisation)
• Domain — subdivision within a portal (department, environment, project)
• Database — belongs to a domain; uses either the native or PostgreSQL engine
• Table — standard table within a database

Features

Database Explorer

A full tree view in the VS Code sidebar showing your connection hierarchy:

• Connections — add, edit, remove and connect/disconnect servers
• Databases — browse all databases with active-database indicator (★), 24h insight tooltips, portal/domain info
• Tables — row counts, expandable columns (types, nullable, PK) and indices
• Portals & Domains — multi-tenant namespace management
• Users — view server users and roles
• Auto-refreshes on a configurable interval (default 30s)

SQL Editor & IntelliSense

• Open SQL files with Ctrl+N or run ad-hoc queries
• IntelliSense with ~130 SQL keywords, live table names, column completions (qualified and unqualified)
• Context-aware: columns from referenced tables are boosted in suggestions
• Run query: Ctrl+Enter (entire file) or Ctrl+Shift+Enter (selection only)
• Results shown as a styled table with row count, execution time, and copy to CSV/JSON

Interactive Data Grid

• Browse table data with pagination, sorting (click column headers) and filtering (SQL WHERE expressions)
• Inline editing — double-click any cell to edit, auto-commits via UPDATE
• Row deletion with confirmation dialog
• Configurable default row limit

Server Dashboard

Real-time server health panel showing:

• Hostname, OS, architecture, engine type
• CPU usage, memory (process + system), disk usage
• Database/table/row counts, connected clients, total queries
• PostgreSQL and HTTP port info, replication role
• Per-database 24h insights (reads, inserts, updates, deletes, avg query time)
• Auto-refreshes every 10 seconds

Server Status (Sidebar)

Compact status card in the sidebar with server metrics, CPU/disk progress bars, and connection info. Refreshes periodically with an in-flight guard so overlapping refreshes coalesce instead of stacking heavy metrics calls.

Server Log Viewer

Live-streaming log viewer with two tabs:

• SQL Queries — timestamp, query type, database (contextual path: Portal / Domain / DB), SQL preview, row count, duration, status
• Server Logs — real-time entries with level coloring (ERROR/WARN/INFO), user and database tags
• SSE live stream — connects to GET /api/events?topics=logs,activity for instant updates (no polling delay)
• Automatic fallback to 3s HTTP polling if SSE is unavailable
• Pause/resume, clear, manual refresh
• Auto-reconnect with exponential backoff on SSE disconnection

MCP Integration (GitHub Copilot)

When you connect to a BlizDB server, the extension automatically registers the server's MCP endpoint in VS Code so GitHub Copilot can discover and use all database tools — no manual configuration needed.

Simply open Copilot Chat and ask:

• "List all tables in my database"
• "Show me the first 10 rows from the users table"
• "Create a new table called sensors with columns id, name, value"
• "What's the server status?"

30+ MCP tools are available for AI-assisted database operations:

Database creation is Native by default. MCP clients should only set PostgreSQL/MySQL backend fields when the user explicitly requests external storage. For BlizDB.com API connections, use connection name BlizDB.com, URL/host blizdb.com, port 443, and SSL enabled. For BlizDB.com PG-wire client connections, use pg.blizdb.com:5432.

Tools are discovered dynamically from the server at connection time, with a hardcoded fallback list. Destructive tools require user confirmation before execution.

If Copilot reports that a BlizDB tool is unavailable even though the extension is connected, run BlizDB: Diagnose MCP/Copilot from the Command Palette. The report checks the MCP settings entry, the server tool list, direct Language Model tool registration, and active connections without printing bearer tokens. You can also run BlizDB: Refresh MCP/Copilot Registration to rewrite the MCP registration and re-register the direct tools; existing Copilot chats may still need a new chat because tool lists can be snapshotted per session.

Real-Time SSE Event Stream

The extension maintains a persistent SSE connection to the server for instant push updates:

Auto-reconnects with exponential backoff. Falls back gracefully if SSE is unavailable.

Query Execution Features

• Query cancellation — cancel long-running queries via server-side queryId
• Explain query — run EXPLAIN ANALYZE via Ctrl+Shift+E or the editor context menu
• Configurable timeout — per-query timeout with blizdb.queryTimeout
• Parameterized queries — data grid uses server-side parameterized queries for safe inline editing

Multi-Tenant Support

• Portals & Domains — create and manage tenant namespaces
• Context switching — switch between Global, Portal, and Domain contexts
• View Access / Roles — right-click portals, domains, databases, or users to inspect role assignments
• Assign/unassign databases to domains

Getting Started

Prerequisites

• VS Code v1.100.0 or later
• A running BlizDB server

Installation

Install from the VS Code Marketplace:

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "BlizDB MCP"
4. Click Install

Or install from the command line:

code --install-extension Traberg-Larsen.blizdb-mcp

Add a Connection

1. Open the BlizDB sidebar (click the BlizDB icon in the Activity Bar)
2. Click Add Connection or run BlizDB: Add Connection from the Command Palette
3. Enter a name, host, port, and optionally enable SSL or provide an API key
4. Connect by clicking the plug icon on the connection

Commands

All commands are available via the Command Palette (Ctrl+Shift+P) under the BlizDB category:

Keyboard Shortcuts

Settings

Configure via File > Preferences > Settings and search for "BlizDB":

Development

Setup

git clone https://github.com/antigravity/blizdb-vscode.git
cd blizdb-vscode
npm install

Build

npm run compile        # Development build
npm run watch          # Watch mode (rebuilds on save)
npm run package        # Production build (minified)

Debug

1. Open the project in VS Code
2. Press F5 to launch the Extension Development Host
3. The extension activates automatically when you open the BlizDB sidebar

Lint & Test

npm run lint           # ESLint
npm test               # Vitest

Publishing New Versions

Pushes to main automatically publish a new patch version to the VS Code Marketplace via GitHub Actions.

Manual Publishing

If you need to publish manually:

# Patch release: 0.1.0 → 0.1.1
npx vsce publish patch

# Minor release: 0.1.0 → 0.2.0
npx vsce publish minor

# Major release: 0.1.0 → 1.0.0
npx vsce publish major

CI/CD Setup

The GitHub Actions workflow (.github/workflows/publish.yml) requires a VSCE_PAT secret:

1. Go to your repo Settings → Secrets → Actions
2. Add VSCE_PAT with your Azure DevOps Personal Access Token (Scope: Marketplace > Manage)

Build Without Publishing

# Create a .vsix file for local testing
npx vsce package

# Install locally
code --install-extension blizdb-mcp-0.1.0.vsix

Updating Your PAT

If your Personal Access Token expires:

1. Go to https://dev.azure.com → User Settings → Personal Access Tokens
2. Create a new token (Organization: All accessible, Scope: Marketplace > Manage)
3. Update the VSCE_PAT secret in GitHub and/or run npx vsce login Traberg-Larsen locally

License

MIT