vibesql-mcp 1.0.0

package/README.md

@@ -0,0 +1,62 @@
+# @vibesql/mcp
+
+MCP server that connects your AI coding tool to a [VibeSQL](https://vibesql.online) PostgreSQL database. One command, 9 tools, zero config.
+
+## Quick Start
+
+```bash
+npx vibesql-micro       # start database on :5173
+npx @vibesql/mcp        # start MCP server
+```
+
+## Claude Code Setup
+
+Add to `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "vibesql": {
+      "command": "npx",
+      "args": ["@vibesql/mcp"]
+    }
+  }
+}
+```
+
+Custom URL:
+
+```json
+{
+  "mcpServers": {
+    "vibesql": {
+      "command": "npx",
+      "args": ["@vibesql/mcp", "--url", "http://10.0.0.5:5173"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `query` | Execute any SQL query (DDL + DML) |
+| `list_tables` | List all tables in the database |
+| `describe_table` | Get column schema for a table |
+| `table_data` | Browse rows with pagination |
+| `create_table` | Create a table (validated, no semicolons) |
+| `insert_row` | Insert a row from JSON column-value pairs |
+| `help` | Help on a VibeSQL topic |
+| `help_products` | Product family overview |
+| `help_architecture` | Architecture patterns |
+
+The `query` tool is intentionally unrestricted -- it can execute any valid SQL including DROP, DELETE, and TRUNCATE. This is a local development tool.
+
+## Environment
+
+Set `VIBESQL_URL` to override the default `http://localhost:5173`. The `--url` CLI flag takes precedence over the env var.
+
+## License
+
+Apache-2.0

package/bin/vibesql-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/index.js');

package/dist/client.d.ts

@@ -0,0 +1,18 @@
+export interface QueryResult {
+    columns: string[];
+    rows: unknown[][];
+    time: number;
+}
+export declare class VibeClient {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    health(): Promise<{
+        status: string;
+    }>;
+    query(sql: string, params?: unknown[]): Promise<QueryResult>;
+    listTables(): Promise<QueryResult>;
+    describeTable(table: string): Promise<QueryResult>;
+    tableData(table: string, limit: number, offset: number): Promise<QueryResult>;
+    insertRow(table: string, data: Record<string, unknown>): Promise<QueryResult>;
+    createTable(sql: string): Promise<QueryResult>;
+}

package/dist/client.js

@@ -0,0 +1,69 @@
+const TABLE_NAME_RE = /^[A-Za-z0-9_]+$/;
+export class VibeClient {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+    }
+    async health() {
+        const res = await fetch(`${this.baseUrl}/v1/health`);
+        if (!res.ok) {
+            throw new Error(`Health check failed: ${res.status} ${res.statusText}`);
+        }
+        return res.json();
+    }
+    async query(sql, params) {
+        const body = { sql };
+        if (params && params.length > 0) {
+            body.params = params;
+        }
+        const res = await fetch(`${this.baseUrl}/v1/query`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`Query failed: ${res.status} ${res.statusText}${text ? ` — ${text}` : ''}`);
+        }
+        return res.json();
+    }
+    async listTables() {
+        return this.query(`SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' ORDER BY table_name`);
+    }
+    async describeTable(table) {
+        validateName(table, 'table');
+        return this.query(`SELECT column_name, data_type, is_nullable, column_default FROM information_schema.columns WHERE table_schema = 'public' AND table_name = $1 ORDER BY ordinal_position`, [table]);
+    }
+    async tableData(table, limit, offset) {
+        validateName(table, 'table');
+        return this.query(`SELECT * FROM "${table}" LIMIT $1 OFFSET $2`, [limit, offset]);
+    }
+    async insertRow(table, data) {
+        validateName(table, 'table');
+        const entries = Object.entries(data);
+        if (entries.length === 0) {
+            throw new Error('insert_row: data object must have at least one column');
+        }
+        for (const [col] of entries) {
+            validateName(col, 'column');
+        }
+        const columns = entries.map(([col]) => `"${col}"`).join(', ');
+        const placeholders = entries.map((_, i) => `$${i + 1}`).join(', ');
+        const values = entries.map(([, val]) => val);
+        return this.query(`INSERT INTO "${table}" (${columns}) VALUES (${placeholders}) RETURNING *`, values);
+    }
+    async createTable(sql) {
+        if (!/^CREATE\s+TABLE\b/i.test(sql)) {
+            throw new Error('create_table: SQL must start with CREATE TABLE');
+        }
+        if (sql.includes(';')) {
+            throw new Error('create_table: semicolons are not allowed (prevents multi-statement injection)');
+        }
+        return this.query(sql);
+    }
+}
+function validateName(name, kind) {
+    if (!TABLE_NAME_RE.test(name)) {
+        throw new Error(`Invalid ${kind} name "${name}" — only alphanumeric characters and underscores are allowed`);
+    }
+}

package/dist/help.d.ts

@@ -0,0 +1,2 @@
+export declare const HELP_TOPICS: Record<string, string>;
+export declare function getHelp(topic: string): string;

package/dist/help.js

@@ -0,0 +1,195 @@
+export const HELP_TOPICS = {
+    architecture: `# Architecture
+
+This page describes the cross-cutting patterns shared across the VibeSQL product family.
+
+## Envelope Encryption Pattern
+
+vsql-vault, vsql-backup, and vsql-sync all use **envelope encryption**. The pattern separates the key that encrypts data (DEK) from the key that protects the DEK (KEK).
+
+\`\`\`
+plaintext
+   |
+   v  AES-256-GCM (DEK)
+ciphertext  -->  stored
+
+DEK  -->  RSA wrap (KEK)  -->  wrapped DEK stored alongside ciphertext
+\`\`\`
+
+**Why envelope encryption?**
+- The DEK can be rotated or revoked by replacing only the wrapped DEK — no re-encryption of data required.
+- The KEK never touches the data storage layer; it lives in CryptAply.
+- Compromising one DEK affects only the data it encrypted, not the KEK or other DEKs.
+
+| Product | DEK scope | KEK source |
+|---------|-----------|------------|
+| vsql-vault | Per blob | CryptAply (RSA) |
+| vsql-backup | Per backup set | CryptAply (RSA) |
+| vsql-sync | Per session/batch | CryptAply (RSA) |
+
+## Hash Chains
+
+vsql-sync uses a **hash chain** to guarantee audit trail integrity. Each audit entry includes the hash of the previous entry. Any modification to a historical entry breaks the chain from that point forward, making tampering immediately detectable during verification.
+
+## Merkle Trees (Backup Manifest Verification)
+
+vsql-backup organizes its SHA-256 segment hashes into a **Merkle tree**. Each leaf is the hash of one backup segment. Parent nodes are hashes of their children. The root hash represents the entire backup set. To verify any single segment, you only need the segment's sibling hashes along the path to the root.
+
+## Ed25519 Signing (Sync Audit Entries)
+
+vsql-sync signs each audit trail entry with an **Ed25519** private key held by CryptAply. 64-byte signatures, fast verification, no key material on sync nodes.
+
+## Dev vs Prod Mode
+
+| Feature | Dev mode | Prod mode |
+|---------|----------|-----------|
+| TLS | Optional (HTTP allowed) | Required (HTTPS only) |
+| KEK source | Local key file | CryptAply (remote) |
+| Audit trail signing | Disabled or local key | Ed25519 via CryptAply |
+| Access log retention | Short (debugging) | Configured per policy |
+| PITR window | Hours | Days to weeks |
+
+## How All Products Connect
+
+\`\`\`
+vibesql-micro (PostgreSQL HTTP server)
+      |  query
+      v
+  application layer
+      |  store blobs          |  replicate changes
+      v                       v
+  vsql-vault             vsql-sync
+      |  backup               |  audit signing
+      v                       |
+  vsql-backup                 |
+      |                       |
+      +---------------------->|
+                         CryptAply
+                    (KEK management, key lifecycle,
+                     directive enforcement, compliance)
+\`\`\`
+
+CryptAply is the trust anchor. All encrypted services depend on it for KEK operations.`,
+    products: `# VibeSQL Product Family
+
+VibeSQL is a family of seven products delivering a compliant, governed, globally synchronized database ecosystem. Each product can be used independently or together as an integrated stack.
+
+## Products at a Glance
+
+| Product | Role | Port |
+|---------|------|------|
+| vibesql-micro | PostgreSQL-over-HTTP database server | 5173 |
+| vsql-vault | Encrypted blob storage | 8443 |
+| vsql-backup | Governed backup with pgBackRest engine | 8445 |
+| vsql-sync | Governed data movement — PCI-scoped replication | 8444 |
+| vsql-cryptaply | Key governance and compliance engine | — |
+| vibesql-admin | Unified admin hub + MCP server | 5174 |
+| vibesql (core) | Core database library | — |
+
+## vibesql-micro
+
+Lightweight PostgreSQL-over-HTTP database server with embedded PostgreSQL 16.1. Ships as a single binary with zero configuration required.
+
+Key endpoints:
+- POST /v1/query — Execute SQL statements
+- GET /v1/health — Service health check
+
+Designed for edge deployments, local-first applications, and embedded use cases.
+
+## vsql-vault
+
+Encrypted blob storage with envelope encryption. All data is encrypted at rest using AES-256-GCM. RSA key wrapping protects the data encryption keys. Features: access logging, configurable retention policies.
+
+## vsql-backup
+
+Rust binary wrapping pgBackRest (MIT, C) as the backup engine. Envelope encryption per backup set, manifest verification, PITR mechanics. CryptAply provides key governance authority.
+
+## vsql-sync
+
+Governed data movement layer. Encrypted replication payloads with envelope encryption. CRDT-based conflict resolution (LWW), Ed25519-signed audit trail with hash chaining, publication-based selective replication with column exclusion for PCI scope reduction.
+
+## vsql-cryptaply (CryptAply)
+
+Key governance and compliance engine. Directive-based policies over encryption keys used by vault, backup, and sync. Full key lifecycle management.
+
+## vibesql-admin
+
+Unified administration hub. One web UI for humans, one MCP server for AI agents, one help system for everyone.
+
+## How the Products Work Together
+
+\`\`\`
+vibesql-micro  -->  vsql-vault   -->  vsql-backup (Rust + pgBackRest)
+                        |                  |
+                    vsql-sync              |
+                    (governed wire)         |
+                        |                  |
+                    CryptAply <------------+
+                (KEK management, key lifecycle,
+                 directive enforcement, compliance)
+                        |
+                  vibesql-admin
+              (unified hub + MCP server)
+\`\`\``,
+    glossary: `# Glossary
+
+Reference definitions for terms used across VibeSQL documentation.
+
+## AES-256-GCM
+Advanced Encryption Standard with a 256-bit key in Galois/Counter Mode. Provides both confidentiality and authenticated integrity. Used by vsql-vault, vsql-backup, and vsql-sync for data encryption.
+
+## Blob
+An opaque binary object stored in vsql-vault. A blob has an ID, metadata, and an encrypted payload.
+
+## CDE (Cardholder Data Environment)
+The systems and processes that store, process, or transmit cardholder data. PCI DSS controls apply to everything in scope of the CDE.
+
+## CRDT (Conflict-free Replicated Data Type)
+A data structure designed so that concurrent updates on different nodes can always be merged without coordination. vsql-sync uses CRDTs for conflict resolution.
+
+## DEK (Data Encryption Key)
+The symmetric key that directly encrypts data. An AES-256-GCM key. Generated per blob (vault), per backup set (backup), or per session (sync). Always stored wrapped by a KEK.
+
+## Directive
+A policy document in CryptAply that governs a key or key family. Specifies algorithm, rotation schedule, allowed consumers, and expiry behavior.
+
+## Ed25519
+An elliptic-curve digital signature algorithm using Curve25519. Produces 64-byte signatures with fast verification. Used by vsql-sync for audit trail signing.
+
+## Envelope Encryption
+A two-layer encryption pattern: a DEK encrypts the data; a KEK encrypts (wraps) the DEK. Only the wrapped DEK is stored alongside the ciphertext.
+
+## Hash Chain
+A sequence of records where each record contains the hash of the previous record. Modification of any historical record invalidates all subsequent hashes.
+
+## KEK (Key Encryption Key)
+The key that wraps (encrypts) a DEK. Managed by CryptAply and never exposed to the storage layer. In VibeSQL, KEKs are RSA keys.
+
+## LWW (Last Writer Wins)
+A CRDT conflict resolution strategy. The update with the higher logical timestamp is kept. Used by vsql-sync.
+
+## Merkle Tree
+A binary tree of hashes for efficient partial verification of backup segments.
+
+## PCI DSS
+Payment Card Industry Data Security Standard. Relevant VibeSQL features: envelope encryption (Req 3), access logging (Req 10), column exclusion (scope reduction).
+
+## PITR (Point-in-Time Recovery)
+The ability to restore a database to any recorded moment in time, not just the most recent backup.
+
+## Publication
+A named configuration in vsql-sync defining which tables and columns replicate to which subscriber nodes.
+
+## RSA
+Asymmetric encryption algorithm used as the KEK algorithm for wrapping DEKs.
+
+## SHA-256
+Secure Hash Algorithm 2 with 256-bit output. Used for segment integrity hashes and hash chain linking.`,
+};
+export function getHelp(topic) {
+    const key = topic.toLowerCase().trim();
+    const content = HELP_TOPICS[key];
+    if (content)
+        return content;
+    return `Unknown topic "${topic}". Available topics: ${Object.keys(HELP_TOPICS).join(', ')}`;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,167 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { VibeClient } from './client.js';
+import { getHelp, HELP_TOPICS } from './help.js';
+// --- CLI args ---
+function parseArgs() {
+    const args = process.argv.slice(2);
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--url' && args[i + 1]) {
+            return args[++i];
+        }
+    }
+    return process.env['VIBESQL_URL'] || 'http://localhost:5173';
+}
+const baseUrl = parseArgs();
+const client = new VibeClient(baseUrl);
+// --- Health check ---
+try {
+    await client.health();
+}
+catch {
+    process.stderr.write(`\nCould not connect to VibeSQL at ${baseUrl}\n\n`);
+    process.stderr.write(`Start it with:   npx vibesql-micro\n`);
+    process.stderr.write(`Or specify URL:  npx @vibesql/mcp --url http://your-host:5173\n\n`);
+    process.exit(1);
+}
+// --- MCP Server ---
+const server = new McpServer({
+    name: '@vibesql/mcp',
+    version: '1.0.0',
+});
+// ---------------------------------------------------------------------------
+// Database tools
+// ---------------------------------------------------------------------------
+server.tool('query', 'Execute a SQL query against the VibeSQL database. This tool is unrestricted — it can execute any valid SQL including DDL (CREATE, ALTER, DROP) and DML (INSERT, UPDATE, DELETE). This is intentional for a local development tool.', {
+    sql: z.string().describe('SQL statement to execute'),
+    params: z.string().optional().describe('JSON array of query parameters'),
+}, async ({ sql, params }) => {
+    try {
+        const parsedParams = params ? JSON.parse(params) : undefined;
+        const result = await client.query(sql, parsedParams);
+        const header = result.columns.join('\t');
+        const rows = result.rows.map((row) => row.join('\t')).join('\n');
+        const text = [header, rows].filter(Boolean).join('\n');
+        return {
+            content: [{ type: 'text', text: text || '(no rows returned)' }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+server.tool('list_tables', 'List all tables in the database', async () => {
+    try {
+        const result = await client.listTables();
+        const tables = result.rows.map((row) => row[0]);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(tables, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+server.tool('describe_table', 'Get column schema for a table (column name, data type, nullable, default)', {
+    table: z.string().describe('Table name to describe'),
+}, async ({ table }) => {
+    try {
+        const result = await client.describeTable(table);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+server.tool('table_data', 'Browse rows from a table with pagination', {
+    table: z.string().describe('Table name to query'),
+    limit: z.number().int().positive().optional().describe('Maximum rows to return (default 50)'),
+    offset: z.number().int().nonnegative().optional().describe('Rows to skip (default 0)'),
+}, async ({ table, limit, offset }) => {
+    try {
+        const result = await client.tableData(table, limit ?? 50, offset ?? 0);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+server.tool('create_table', 'Create a new table. SQL must start with CREATE TABLE and must not contain semicolons.', {
+    sql: z.string().describe('CREATE TABLE DDL statement'),
+}, async ({ sql }) => {
+    try {
+        await client.createTable(sql);
+        const nameMatch = sql.match(/CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["']?(\w+)["']?/i);
+        const tableName = nameMatch ? nameMatch[1] : 'unknown';
+        return {
+            content: [{ type: 'text', text: `Table "${tableName}" created successfully.` }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+server.tool('insert_row', 'Insert a row into a table. Data is a JSON object of column-value pairs. Supported value types: string, number, boolean, null.', {
+    table: z.string().describe('Table name'),
+    data: z.string().describe('JSON object of column→value pairs, e.g. {"name":"Alice","age":30}'),
+}, async ({ table, data }) => {
+    try {
+        const parsed = JSON.parse(data);
+        const result = await client.insertRow(table, parsed);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// Help tools
+// ---------------------------------------------------------------------------
+server.tool('help', 'Get help on a VibeSQL topic. Available topics: architecture, products, glossary', {
+    topic: z.string().describe('Topic name (architecture, products, or glossary)'),
+}, async ({ topic }) => {
+    const text = getHelp(topic);
+    return {
+        content: [{ type: 'text', text }],
+    };
+});
+server.tool('help_products', 'VibeSQL product family overview — all 7 products and how they connect', async () => {
+    return {
+        content: [{ type: 'text', text: HELP_TOPICS['products'] }],
+    };
+});
+server.tool('help_architecture', 'VibeSQL architecture patterns — envelope encryption, hash chains, Merkle trees', async () => {
+    return {
+        content: [{ type: 'text', text: HELP_TOPICS['architecture'] }],
+    };
+});
+// ---------------------------------------------------------------------------
+// Start server
+// ---------------------------------------------------------------------------
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "vibesql-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for VibeSQL — connect your AI coding tool to a PostgreSQL database",
+  "type": "module",
+  "bin": {
+    "vibesql-mcp": "./bin/vibesql-mcp.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "keywords": ["vibesql", "mcp", "postgresql", "database", "ai", "claude"],
+  "author": "PayEz <opensource@payez.net>",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23"
+  },
+  "devDependencies": {
+    "typescript": "^5.7",
+    "@types/node": "^22.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,96 @@
+export interface QueryResult {
+  columns: string[];
+  rows: unknown[][];
+  time: number;
+}
+
+const TABLE_NAME_RE = /^[A-Za-z0-9_]+$/;
+
+export class VibeClient {
+  private readonly baseUrl: string;
+
+  constructor(baseUrl: string) {
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+  }
+
+  async health(): Promise<{ status: string }> {
+    const res = await fetch(`${this.baseUrl}/v1/health`);
+    if (!res.ok) {
+      throw new Error(`Health check failed: ${res.status} ${res.statusText}`);
+    }
+    return res.json() as Promise<{ status: string }>;
+  }
+
+  async query(sql: string, params?: unknown[]): Promise<QueryResult> {
+    const body: Record<string, unknown> = { sql };
+    if (params && params.length > 0) {
+      body.params = params;
+    }
+    const res = await fetch(`${this.baseUrl}/v1/query`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(`Query failed: ${res.status} ${res.statusText}${text ? ` — ${text}` : ''}`);
+    }
+    return res.json() as Promise<QueryResult>;
+  }
+
+  async listTables(): Promise<QueryResult> {
+    return this.query(
+      `SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' ORDER BY table_name`
+    );
+  }
+
+  async describeTable(table: string): Promise<QueryResult> {
+    validateName(table, 'table');
+    return this.query(
+      `SELECT column_name, data_type, is_nullable, column_default FROM information_schema.columns WHERE table_schema = 'public' AND table_name = $1 ORDER BY ordinal_position`,
+      [table]
+    );
+  }
+
+  async tableData(table: string, limit: number, offset: number): Promise<QueryResult> {
+    validateName(table, 'table');
+    return this.query(
+      `SELECT * FROM "${table}" LIMIT $1 OFFSET $2`,
+      [limit, offset]
+    );
+  }
+
+  async insertRow(table: string, data: Record<string, unknown>): Promise<QueryResult> {
+    validateName(table, 'table');
+    const entries = Object.entries(data);
+    if (entries.length === 0) {
+      throw new Error('insert_row: data object must have at least one column');
+    }
+    for (const [col] of entries) {
+      validateName(col, 'column');
+    }
+    const columns = entries.map(([col]) => `"${col}"`).join(', ');
+    const placeholders = entries.map((_, i) => `$${i + 1}`).join(', ');
+    const values = entries.map(([, val]) => val);
+    return this.query(
+      `INSERT INTO "${table}" (${columns}) VALUES (${placeholders}) RETURNING *`,
+      values
+    );
+  }
+
+  async createTable(sql: string): Promise<QueryResult> {
+    if (!/^CREATE\s+TABLE\b/i.test(sql)) {
+      throw new Error('create_table: SQL must start with CREATE TABLE');
+    }
+    if (sql.includes(';')) {
+      throw new Error('create_table: semicolons are not allowed (prevents multi-statement injection)');
+    }
+    return this.query(sql);
+  }
+}
+
+function validateName(name: string, kind: string): void {
+  if (!TABLE_NAME_RE.test(name)) {
+    throw new Error(`Invalid ${kind} name "${name}" — only alphanumeric characters and underscores are allowed`);
+  }
+}

package/src/help.ts

@@ -0,0 +1,199 @@
+export const HELP_TOPICS: Record<string, string> = {
+
+architecture: `# Architecture
+
+This page describes the cross-cutting patterns shared across the VibeSQL product family.
+
+## Envelope Encryption Pattern
+
+vsql-vault, vsql-backup, and vsql-sync all use **envelope encryption**. The pattern separates the key that encrypts data (DEK) from the key that protects the DEK (KEK).
+
+\`\`\`
+plaintext
+   |
+   v  AES-256-GCM (DEK)
+ciphertext  -->  stored
+
+DEK  -->  RSA wrap (KEK)  -->  wrapped DEK stored alongside ciphertext
+\`\`\`
+
+**Why envelope encryption?**
+- The DEK can be rotated or revoked by replacing only the wrapped DEK — no re-encryption of data required.
+- The KEK never touches the data storage layer; it lives in CryptAply.
+- Compromising one DEK affects only the data it encrypted, not the KEK or other DEKs.
+
+| Product | DEK scope | KEK source |
+|---------|-----------|------------|
+| vsql-vault | Per blob | CryptAply (RSA) |
+| vsql-backup | Per backup set | CryptAply (RSA) |
+| vsql-sync | Per session/batch | CryptAply (RSA) |
+
+## Hash Chains
+
+vsql-sync uses a **hash chain** to guarantee audit trail integrity. Each audit entry includes the hash of the previous entry. Any modification to a historical entry breaks the chain from that point forward, making tampering immediately detectable during verification.
+
+## Merkle Trees (Backup Manifest Verification)
+
+vsql-backup organizes its SHA-256 segment hashes into a **Merkle tree**. Each leaf is the hash of one backup segment. Parent nodes are hashes of their children. The root hash represents the entire backup set. To verify any single segment, you only need the segment's sibling hashes along the path to the root.
+
+## Ed25519 Signing (Sync Audit Entries)
+
+vsql-sync signs each audit trail entry with an **Ed25519** private key held by CryptAply. 64-byte signatures, fast verification, no key material on sync nodes.
+
+## Dev vs Prod Mode
+
+| Feature | Dev mode | Prod mode |
+|---------|----------|-----------|
+| TLS | Optional (HTTP allowed) | Required (HTTPS only) |
+| KEK source | Local key file | CryptAply (remote) |
+| Audit trail signing | Disabled or local key | Ed25519 via CryptAply |
+| Access log retention | Short (debugging) | Configured per policy |
+| PITR window | Hours | Days to weeks |
+
+## How All Products Connect
+
+\`\`\`
+vibesql-micro (PostgreSQL HTTP server)
+      |  query
+      v
+  application layer
+      |  store blobs          |  replicate changes
+      v                       v
+  vsql-vault             vsql-sync
+      |  backup               |  audit signing
+      v                       |
+  vsql-backup                 |
+      |                       |
+      +---------------------->|
+                         CryptAply
+                    (KEK management, key lifecycle,
+                     directive enforcement, compliance)
+\`\`\`
+
+CryptAply is the trust anchor. All encrypted services depend on it for KEK operations.`,
+
+products: `# VibeSQL Product Family
+
+VibeSQL is a family of seven products delivering a compliant, governed, globally synchronized database ecosystem. Each product can be used independently or together as an integrated stack.
+
+## Products at a Glance
+
+| Product | Role | Port |
+|---------|------|------|
+| vibesql-micro | PostgreSQL-over-HTTP database server | 5173 |
+| vsql-vault | Encrypted blob storage | 8443 |
+| vsql-backup | Governed backup with pgBackRest engine | 8445 |
+| vsql-sync | Governed data movement — PCI-scoped replication | 8444 |
+| vsql-cryptaply | Key governance and compliance engine | — |
+| vibesql-admin | Unified admin hub + MCP server | 5174 |
+| vibesql (core) | Core database library | — |
+
+## vibesql-micro
+
+Lightweight PostgreSQL-over-HTTP database server with embedded PostgreSQL 16.1. Ships as a single binary with zero configuration required.
+
+Key endpoints:
+- POST /v1/query — Execute SQL statements
+- GET /v1/health — Service health check
+
+Designed for edge deployments, local-first applications, and embedded use cases.
+
+## vsql-vault
+
+Encrypted blob storage with envelope encryption. All data is encrypted at rest using AES-256-GCM. RSA key wrapping protects the data encryption keys. Features: access logging, configurable retention policies.
+
+## vsql-backup
+
+Rust binary wrapping pgBackRest (MIT, C) as the backup engine. Envelope encryption per backup set, manifest verification, PITR mechanics. CryptAply provides key governance authority.
+
+## vsql-sync
+
+Governed data movement layer. Encrypted replication payloads with envelope encryption. CRDT-based conflict resolution (LWW), Ed25519-signed audit trail with hash chaining, publication-based selective replication with column exclusion for PCI scope reduction.
+
+## vsql-cryptaply (CryptAply)
+
+Key governance and compliance engine. Directive-based policies over encryption keys used by vault, backup, and sync. Full key lifecycle management.
+
+## vibesql-admin
+
+Unified administration hub. One web UI for humans, one MCP server for AI agents, one help system for everyone.
+
+## How the Products Work Together
+
+\`\`\`
+vibesql-micro  -->  vsql-vault   -->  vsql-backup (Rust + pgBackRest)
+                        |                  |
+                    vsql-sync              |
+                    (governed wire)         |
+                        |                  |
+                    CryptAply <------------+
+                (KEK management, key lifecycle,
+                 directive enforcement, compliance)
+                        |
+                  vibesql-admin
+              (unified hub + MCP server)
+\`\`\``,
+
+glossary: `# Glossary
+
+Reference definitions for terms used across VibeSQL documentation.
+
+## AES-256-GCM
+Advanced Encryption Standard with a 256-bit key in Galois/Counter Mode. Provides both confidentiality and authenticated integrity. Used by vsql-vault, vsql-backup, and vsql-sync for data encryption.
+
+## Blob
+An opaque binary object stored in vsql-vault. A blob has an ID, metadata, and an encrypted payload.
+
+## CDE (Cardholder Data Environment)
+The systems and processes that store, process, or transmit cardholder data. PCI DSS controls apply to everything in scope of the CDE.
+
+## CRDT (Conflict-free Replicated Data Type)
+A data structure designed so that concurrent updates on different nodes can always be merged without coordination. vsql-sync uses CRDTs for conflict resolution.
+
+## DEK (Data Encryption Key)
+The symmetric key that directly encrypts data. An AES-256-GCM key. Generated per blob (vault), per backup set (backup), or per session (sync). Always stored wrapped by a KEK.
+
+## Directive
+A policy document in CryptAply that governs a key or key family. Specifies algorithm, rotation schedule, allowed consumers, and expiry behavior.
+
+## Ed25519
+An elliptic-curve digital signature algorithm using Curve25519. Produces 64-byte signatures with fast verification. Used by vsql-sync for audit trail signing.
+
+## Envelope Encryption
+A two-layer encryption pattern: a DEK encrypts the data; a KEK encrypts (wraps) the DEK. Only the wrapped DEK is stored alongside the ciphertext.
+
+## Hash Chain
+A sequence of records where each record contains the hash of the previous record. Modification of any historical record invalidates all subsequent hashes.
+
+## KEK (Key Encryption Key)
+The key that wraps (encrypts) a DEK. Managed by CryptAply and never exposed to the storage layer. In VibeSQL, KEKs are RSA keys.
+
+## LWW (Last Writer Wins)
+A CRDT conflict resolution strategy. The update with the higher logical timestamp is kept. Used by vsql-sync.
+
+## Merkle Tree
+A binary tree of hashes for efficient partial verification of backup segments.
+
+## PCI DSS
+Payment Card Industry Data Security Standard. Relevant VibeSQL features: envelope encryption (Req 3), access logging (Req 10), column exclusion (scope reduction).
+
+## PITR (Point-in-Time Recovery)
+The ability to restore a database to any recorded moment in time, not just the most recent backup.
+
+## Publication
+A named configuration in vsql-sync defining which tables and columns replicate to which subscriber nodes.
+
+## RSA
+Asymmetric encryption algorithm used as the KEK algorithm for wrapping DEKs.
+
+## SHA-256
+Secure Hash Algorithm 2 with 256-bit output. Used for segment integrity hashes and hash chain linking.`,
+
+};
+
+export function getHelp(topic: string): string {
+  const key = topic.toLowerCase().trim();
+  const content = HELP_TOPICS[key];
+  if (content) return content;
+  return `Unknown topic "${topic}". Available topics: ${Object.keys(HELP_TOPICS).join(', ')}`;
+}

package/src/index.ts

@@ -0,0 +1,215 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { VibeClient } from './client.js';
+import { getHelp, HELP_TOPICS } from './help.js';
+
+// --- CLI args ---
+
+function parseArgs(): string {
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--url' && args[i + 1]) {
+      return args[++i]!;
+    }
+  }
+  return process.env['VIBESQL_URL'] || 'http://localhost:5173';
+}
+
+const baseUrl = parseArgs();
+const client = new VibeClient(baseUrl);
+
+// No startup health check — MCP starts regardless.
+// If vibesql-micro isn't running yet, individual tool calls return errors.
+// This allows Claude to start vibesql-micro via bash, then use MCP tools.
+
+// --- MCP Server ---
+
+const server = new McpServer({
+  name: '@vibesql/mcp',
+  version: '1.0.0',
+});
+
+// ---------------------------------------------------------------------------
+// Database tools
+// ---------------------------------------------------------------------------
+
+server.tool(
+  'query',
+  'Execute a SQL query against the VibeSQL database. This tool is unrestricted — it can execute any valid SQL including DDL (CREATE, ALTER, DROP) and DML (INSERT, UPDATE, DELETE). This is intentional for a local development tool.',
+  {
+    sql: z.string().describe('SQL statement to execute'),
+    params: z.string().optional().describe('JSON array of query parameters'),
+  },
+  async ({ sql, params }) => {
+    try {
+      const parsedParams = params ? (JSON.parse(params) as unknown[]) : undefined;
+      const result = await client.query(sql, parsedParams);
+      const header = result.columns.join('\t');
+      const rows = result.rows.map((row) => (row as unknown[]).join('\t')).join('\n');
+      const text = [header, rows].filter(Boolean).join('\n');
+      return {
+        content: [{ type: 'text' as const, text: text || '(no rows returned)' }],
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text' as const, text: `Error: ${(error as Error).message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+server.tool(
+  'list_tables',
+  'List all tables in the database',
+  async () => {
+    try {
+      const result = await client.listTables();
+      const tables = result.rows.map((row) => (row as unknown[])[0]);
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(tables, null, 2) }],
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text' as const, text: `Error: ${(error as Error).message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+server.tool(
+  'describe_table',
+  'Get column schema for a table (column name, data type, nullable, default)',
+  {
+    table: z.string().describe('Table name to describe'),
+  },
+  async ({ table }) => {
+    try {
+      const result = await client.describeTable(table);
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text' as const, text: `Error: ${(error as Error).message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+server.tool(
+  'table_data',
+  'Browse rows from a table with pagination',
+  {
+    table: z.string().describe('Table name to query'),
+    limit: z.number().int().positive().optional().describe('Maximum rows to return (default 50)'),
+    offset: z.number().int().nonnegative().optional().describe('Rows to skip (default 0)'),
+  },
+  async ({ table, limit, offset }) => {
+    try {
+      const result = await client.tableData(table, limit ?? 50, offset ?? 0);
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text' as const, text: `Error: ${(error as Error).message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+server.tool(
+  'create_table',
+  'Create a new table. SQL must start with CREATE TABLE and must not contain semicolons.',
+  {
+    sql: z.string().describe('CREATE TABLE DDL statement'),
+  },
+  async ({ sql }) => {
+    try {
+      await client.createTable(sql);
+      const nameMatch = sql.match(/CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["']?(\w+)["']?/i);
+      const tableName = nameMatch ? nameMatch[1] : 'unknown';
+      return {
+        content: [{ type: 'text' as const, text: `Table "${tableName}" created successfully.` }],
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text' as const, text: `Error: ${(error as Error).message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+server.tool(
+  'insert_row',
+  'Insert a row into a table. Data is a JSON object of column-value pairs. Supported value types: string, number, boolean, null.',
+  {
+    table: z.string().describe('Table name'),
+    data: z.string().describe('JSON object of column→value pairs, e.g. {"name":"Alice","age":30}'),
+  },
+  async ({ table, data }) => {
+    try {
+      const parsed = JSON.parse(data) as Record<string, unknown>;
+      const result = await client.insertRow(table, parsed);
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text' as const, text: `Error: ${(error as Error).message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// ---------------------------------------------------------------------------
+// Help tools
+// ---------------------------------------------------------------------------
+
+server.tool(
+  'help',
+  'Get help on a VibeSQL topic. Available topics: architecture, products, glossary',
+  {
+    topic: z.string().describe('Topic name (architecture, products, or glossary)'),
+  },
+  async ({ topic }) => {
+    const text = getHelp(topic);
+    return {
+      content: [{ type: 'text' as const, text }],
+    };
+  }
+);
+
+server.tool(
+  'help_products',
+  'VibeSQL product family overview — all 7 products and how they connect',
+  async () => {
+    return {
+      content: [{ type: 'text' as const, text: HELP_TOPICS['products']! }],
+    };
+  }
+);
+
+server.tool(
+  'help_architecture',
+  'VibeSQL architecture patterns — envelope encryption, hash chains, Merkle trees',
+  async () => {
+    return {
+      content: [{ type: 'text' as const, text: HELP_TOPICS['architecture']! }],
+    };
+  }
+);
+
+// ---------------------------------------------------------------------------
+// Start server
+// ---------------------------------------------------------------------------
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "sourceMap": false
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}