convex-mcp-visual 1.0.0

package/dist/tools/schema-browser.js

@@ -0,0 +1,260 @@
+/**
+ * Schema Browser Tool
+ *
+ * MCP tool that displays database schema in terminal AND
+ * opens an interactive schema browser UI in the browser.
+ */
+import { launchUIApp } from '../ui-server.js';
+export const schemaBrowserTool = {
+    name: 'schema_browser',
+    description: `Opens an interactive Schema Browser for exploring your Convex database.
+
+Features:
+- Browse all tables with document counts
+- View declared vs inferred schemas side-by-side
+- Paginate through documents
+- Build and run read-only queries
+
+The Schema Browser renders as an interactive UI panel where you can click through tables,
+inspect field types, and explore your data visually.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            deployment: {
+                type: 'string',
+                description: 'Deployment selector (from status tool). If not provided, uses the default deployment.',
+            },
+            table: {
+                type: 'string',
+                description: 'Pre-select a specific table to view',
+            },
+            showInferred: {
+                type: 'boolean',
+                description: 'Show inferred schemas alongside declared schemas (default: true)',
+                default: true,
+            },
+            pageSize: {
+                type: 'number',
+                description: 'Number of documents per page (default: 50)',
+                default: 50,
+            },
+        },
+        required: [],
+    },
+};
+export async function handleSchemaBrowser(client, args = {}) {
+    const { table, showInferred = true, pageSize = 50 } = args;
+    // Check if client is connected
+    if (!client.isConnected()) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `## Schema Browser
+
+**Connection Error**: No Convex deployment configured.
+
+To connect:
+1. Run \`npx convex login\` to authenticate
+2. Or set \`CONVEX_URL\` and \`CONVEX_DEPLOY_KEY\` environment variables
+
+Once connected, the Schema Browser will display your tables and schemas.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    try {
+        // Get table list and document counts
+        const tables = await client.listTables();
+        // Get all documents for schema inference
+        const allDocuments = await client.getAllDocuments();
+        // Build table info with schema data
+        const tableInfos = tables.map((t) => {
+            const docs = allDocuments[t.name] || [];
+            const inferredFields = inferSchemaFromDocuments(docs);
+            return {
+                name: t.name,
+                documentCount: docs.length || t.documentCount,
+                hasIndexes: t.indexes.length > 0,
+                indexes: t.indexes,
+                documents: docs.slice(0, pageSize),
+                inferredFields,
+            };
+        });
+        // Get schema for selected table if specified
+        let selectedTableInfo = null;
+        if (table) {
+            selectedTableInfo = tableInfos.find((t) => t.name === table);
+        }
+        // Build config for UI app
+        const config = {
+            deploymentUrl: client.getDeploymentUrl(),
+            selectedTable: table || null,
+            showInferred,
+            pageSize,
+            tables: tableInfos,
+            selectedSchema: selectedTableInfo
+                ? {
+                    tableName: selectedTableInfo.name,
+                    declaredFields: [], // Would come from schema.ts if defined
+                    inferredFields: selectedTableInfo.inferredFields,
+                    indexes: selectedTableInfo.indexes,
+                }
+                : null,
+            allDocuments,
+        };
+        // Launch the interactive UI in browser
+        let uiUrl = '';
+        try {
+            const uiServer = await launchUIApp({
+                appName: 'schema-browser',
+                config,
+                port: 3456,
+                autoClose: 30 * 60 * 1000, // Auto-close after 30 minutes
+            });
+            uiUrl = uiServer.url;
+        }
+        catch (error) {
+            console.error('Failed to launch UI:', error);
+        }
+        // Build terminal output (markdown tables)
+        const terminalOutput = buildTerminalOutput(tableInfos, table, client.getDeploymentUrl(), uiUrl);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: terminalOutput,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `## Schema Browser
+
+**Error**: ${error instanceof Error ? error.message : String(error)}
+
+Please check:
+1. Your Convex credentials are valid
+2. You have access to this deployment
+3. The deployment URL is correct`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * Infer schema from document samples
+ */
+function inferSchemaFromDocuments(documents) {
+    if (documents.length === 0)
+        return [];
+    const fieldStats = new Map();
+    const totalDocs = documents.length;
+    for (const doc of documents) {
+        for (const [key, value] of Object.entries(doc)) {
+            const stats = fieldStats.get(key) || { types: new Set(), count: 0 };
+            stats.types.add(getValueType(value));
+            stats.count++;
+            fieldStats.set(key, stats);
+        }
+    }
+    return Array.from(fieldStats.entries())
+        .map(([name, stats]) => ({
+        name,
+        type: Array.from(stats.types).join(' | '),
+        optional: stats.count < totalDocs,
+    }))
+        .sort((a, b) => {
+        // Sort system fields first
+        const aIsSystem = a.name.startsWith('_');
+        const bIsSystem = b.name.startsWith('_');
+        if (aIsSystem && !bIsSystem)
+            return -1;
+        if (!aIsSystem && bIsSystem)
+            return 1;
+        return a.name.localeCompare(b.name);
+    });
+}
+/**
+ * Get the type of a value for schema inference
+ */
+function getValueType(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (Array.isArray(value))
+        return 'array';
+    if (typeof value === 'object')
+        return 'object';
+    return typeof value;
+}
+/**
+ * Build terminal-friendly markdown output
+ */
+function buildTerminalOutput(tables, selectedTable, deploymentUrl, uiUrl) {
+    const lines = [];
+    lines.push('## Schema Browser');
+    lines.push('');
+    if (uiUrl) {
+        lines.push(`**Interactive UI**: ${uiUrl}`);
+        lines.push('');
+    }
+    lines.push(`Connected to: \`${deploymentUrl}\``);
+    lines.push('');
+    if (tables.length === 0) {
+        lines.push('*No tables found in this deployment.*');
+        return lines.join('\n');
+    }
+    // If a specific table is selected, show detailed view
+    if (selectedTable) {
+        const tableInfo = tables.find((t) => t.name === selectedTable);
+        if (tableInfo) {
+            lines.push(`### ${selectedTable} (${tableInfo.documentCount} documents)`);
+            lines.push('');
+            lines.push('**Schema:**');
+            lines.push('');
+            lines.push('| Field | Type | Required |');
+            lines.push('|-------|------|----------|');
+            for (const field of tableInfo.inferredFields) {
+                lines.push(`| ${field.name} | ${field.type} | ${field.optional ? 'No' : 'Yes'} |`);
+            }
+            lines.push('');
+            if (tableInfo.documents.length > 0) {
+                lines.push('**Sample Documents:**');
+                lines.push('');
+                lines.push('```json');
+                lines.push(JSON.stringify(tableInfo.documents.slice(0, 3), null, 2));
+                lines.push('```');
+            }
+            return lines.join('\n');
+        }
+    }
+    // Show all tables overview
+    lines.push(`Here's your complete database schema:`);
+    lines.push('');
+    for (const table of tables) {
+        lines.push('---');
+        lines.push(`${table.name} (${table.documentCount} documents)`);
+        lines.push('');
+        lines.push('| Field | Type | Required |');
+        lines.push('|-------|------|----------|');
+        if (table.inferredFields.length === 0) {
+            lines.push('| *(empty table)* | - | - |');
+        }
+        else {
+            for (const field of table.inferredFields) {
+                lines.push(`| ${field.name} | ${field.type} | ${field.optional ? 'No' : 'Yes'} |`);
+            }
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=schema-browser.js.map

package/dist/tools/schema-browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-browser.js","sourceRoot":"","sources":["../../src/tools/schema-browser.ts"],"names":[],"mappings":"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"}

package/dist/ui-server.d.ts

@@ -0,0 +1,26 @@
+/**
+ * UI Server
+ *
+ * Starts a local HTTP server to serve interactive UI apps
+ * and opens them in the user's default browser.
+ */
+export interface UIServerConfig {
+    appName: 'schema-browser' | 'realtime-dashboard';
+    config: Record<string, unknown>;
+    port?: number;
+    autoClose?: number;
+}
+export interface UIServerResult {
+    url: string;
+    port: number;
+    close: () => void;
+}
+/**
+ * Start a local server for a UI app and open it in the browser
+ */
+export declare function launchUIApp(options: UIServerConfig): Promise<UIServerResult>;
+/**
+ * Close all active UI servers
+ */
+export declare function closeAllUIServers(): void;
+//# sourceMappingURL=ui-server.d.ts.map

package/dist/ui-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-server.d.ts","sourceRoot":"","sources":["../src/ui-server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkFH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,gBAAgB,GAAG,oBAAoB,CAAC;IACjD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAiIlF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAKxC"}

package/dist/ui-server.js

@@ -0,0 +1,202 @@
+/**
+ * UI Server
+ *
+ * Starts a local HTTP server to serve interactive UI apps
+ * and opens them in the user's default browser.
+ */
+import { createServer } from 'http';
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname, extname } from 'path';
+import { fileURLToPath } from 'url';
+import { exec } from 'child_process';
+import { platform } from 'os';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Track active servers to avoid port conflicts
+const activeServers = new Map();
+// MIME types for serving static files
+const MIME_TYPES = {
+    '.html': 'text/html',
+    '.js': 'application/javascript',
+    '.css': 'text/css',
+    '.json': 'application/json',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.svg': 'image/svg+xml',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+};
+// Find an available port starting from the base
+async function findAvailablePort(basePort) {
+    let port = basePort;
+    while (activeServers.has(port)) {
+        port++;
+    }
+    return port;
+}
+// Open URL in default browser (cross-platform)
+function openBrowser(url) {
+    const cmd = platform() === 'darwin'
+        ? 'open'
+        : platform() === 'win32'
+            ? 'start'
+            : 'xdg-open';
+    exec(`${cmd} "${url}"`, (error) => {
+        if (error) {
+            console.error(`Failed to open browser: ${error.message}`);
+        }
+    });
+}
+// Get the base path for built apps
+function getDistAppsPath() {
+    return join(__dirname, '..', 'dist', 'apps');
+}
+// Get the path to an app's index.html
+function getAppHtmlPath(appName) {
+    const basePath = getDistAppsPath();
+    // Try Vite's nested output: dist/apps/apps/{appName}/index.html
+    const nestedPath = join(basePath, 'apps', appName, 'index.html');
+    if (existsSync(nestedPath)) {
+        return nestedPath;
+    }
+    // Try flat structure: dist/apps/{appName}/index.html
+    const flatPath = join(basePath, appName, 'index.html');
+    if (existsSync(flatPath)) {
+        return flatPath;
+    }
+    // Try source: apps/{appName}/index.html
+    const srcPath = join(__dirname, '..', 'apps', appName, 'index.html');
+    if (existsSync(srcPath)) {
+        return srcPath;
+    }
+    throw new Error(`App not found: ${appName}`);
+}
+/**
+ * Start a local server for a UI app and open it in the browser
+ */
+export async function launchUIApp(options) {
+    const { appName, config, port: preferredPort = 3456, autoClose = 0 } = options;
+    const port = await findAvailablePort(preferredPort);
+    const configJson = JSON.stringify(config);
+    const distAppsPath = getDistAppsPath();
+    // Read and modify the HTML with injected config
+    let indexHtml;
+    try {
+        const appHtmlPath = getAppHtmlPath(appName);
+        indexHtml = readFileSync(appHtmlPath, 'utf-8');
+        // Inject the config into the HTML
+        const configScript = `
+    <script>
+      window.__CONVEX_CONFIG__ = ${configJson};
+    </script>
+    `;
+        indexHtml = indexHtml.replace('<head>', `<head>\n${configScript}`);
+    }
+    catch (error) {
+        // If app HTML not found, serve an error page
+        indexHtml = `
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Error - ${appName}</title>
+  <style>
+    body { font-family: system-ui; background: #1a1a2e; color: #eee; padding: 40px; }
+    h1 { color: #e94560; }
+    pre { background: #16213e; padding: 20px; border-radius: 8px; overflow-x: auto; }
+  </style>
+</head>
+<body>
+  <h1>UI App Not Found</h1>
+  <p>The ${appName} UI could not be loaded. Make sure to build the project first:</p>
+  <pre>npm run build</pre>
+  <p>Error: ${error instanceof Error ? error.message : String(error)}</p>
+  <h2>Config received:</h2>
+  <pre>${JSON.stringify(config, null, 2)}</pre>
+</body>
+</html>
+    `;
+    }
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            const url = req.url || '/';
+            // Serve index.html for root
+            if (url === '/' || url === '/index.html') {
+                res.writeHead(200, {
+                    'Content-Type': 'text/html',
+                    'Cache-Control': 'no-cache',
+                });
+                res.end(indexHtml);
+                return;
+            }
+            // Serve static assets from dist/apps/assets/
+            if (url.startsWith('/assets/') || url.includes('/assets/')) {
+                const assetPath = url.replace(/^.*\/assets\//, 'assets/');
+                const filePath = join(distAppsPath, assetPath);
+                if (existsSync(filePath)) {
+                    const ext = extname(filePath);
+                    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+                    try {
+                        const content = readFileSync(filePath);
+                        res.writeHead(200, {
+                            'Content-Type': contentType,
+                            'Cache-Control': 'public, max-age=31536000',
+                        });
+                        res.end(content);
+                        return;
+                    }
+                    catch {
+                        // Fall through to 404
+                    }
+                }
+            }
+            // 404 for everything else
+            res.writeHead(404, { 'Content-Type': 'text/plain' });
+            res.end('Not found');
+        });
+        server.on('error', (error) => {
+            if (error.code === 'EADDRINUSE') {
+                // Port in use, try next
+                launchUIApp({ ...options, port: port + 1 })
+                    .then(resolve)
+                    .catch(reject);
+            }
+            else {
+                reject(error);
+            }
+        });
+        server.listen(port, '127.0.0.1', () => {
+            activeServers.set(port, server);
+            const url = `http://127.0.0.1:${port}`;
+            // Open browser
+            openBrowser(url);
+            // Set up auto-close timer if requested
+            let closeTimer = null;
+            if (autoClose > 0) {
+                closeTimer = setTimeout(() => {
+                    close();
+                }, autoClose);
+            }
+            const close = () => {
+                if (closeTimer) {
+                    clearTimeout(closeTimer);
+                }
+                server.close();
+                activeServers.delete(port);
+            };
+            resolve({
+                url,
+                port,
+                close,
+            });
+        });
+    });
+}
+/**
+ * Close all active UI servers
+ */
+export function closeAllUIServers() {
+    for (const [port, server] of activeServers) {
+        server.close();
+        activeServers.delete(port);
+    }
+}
+//# sourceMappingURL=ui-server.js.map

package/dist/ui-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-server.js","sourceRoot":"","sources":["../src/ui-server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "convex-mcp-visual",
+  "version": "1.0.0",
+  "description": "Visual MCP tools for exploring Convex databases - graph view, schema browser, and dashboards",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "convex-mcp-visual": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm run build:server && npm run build:apps",
+    "build:server": "tsc -p tsconfig.server.json",
+    "build:apps": "vite build",
+    "dev": "tsc -p tsconfig.server.json --watch",
+    "start": "node dist/index.js --stdio",
+    "start:http": "node dist/index.js --http --port 3001",
+    "test": "node dist/index.js --test",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "convex": "^1.17.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vite": "^6.4.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "convex",
+    "mcp",
+    "model-context-protocol",
+    "schema-browser",
+    "database",
+    "visualization",
+    "graph",
+    "dashboard",
+    "claude",
+    "claude-code"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/convex-mcp-visual"
+  },
+  "author": "",
+  "homepage": "https://github.com/anthropics/convex-mcp-visual#readme"
+}