@homenshum/convex-mcp-nodebench 0.4.1 → 0.8.0

package/dist/index.js

@@ -14,7 +14,7 @@
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { getDb, seedGotchasIfEmpty } from "./db.js";
 import { schemaTools } from "./tools/schemaTools.js";
 import { functionTools } from "./tools/functionTools.js";
@@ -26,6 +26,20 @@ import { cronTools } from "./tools/cronTools.js";
 import { componentTools } from "./tools/componentTools.js";
 import { httpTools } from "./tools/httpTools.js";
 import { critterTools } from "./tools/critterTools.js";
+import { authorizationTools } from "./tools/authorizationTools.js";
+import { queryEfficiencyTools } from "./tools/queryEfficiencyTools.js";
+import { actionAuditTools } from "./tools/actionAuditTools.js";
+import { typeSafetyTools } from "./tools/typeSafetyTools.js";
+import { transactionSafetyTools } from "./tools/transactionSafetyTools.js";
+import { storageAuditTools } from "./tools/storageAuditTools.js";
+import { paginationTools } from "./tools/paginationTools.js";
+import { dataModelingTools } from "./tools/dataModelingTools.js";
+import { devSetupTools } from "./tools/devSetupTools.js";
+import { migrationTools } from "./tools/migrationTools.js";
+import { reportingTools } from "./tools/reportingTools.js";
+import { vectorSearchTools } from "./tools/vectorSearchTools.js";
+import { schedulerTools } from "./tools/schedulerTools.js";
+import { qualityGateTools } from "./tools/qualityGateTools.js";
 import { CONVEX_GOTCHAS } from "./gotchaSeed.js";
 import { REGISTRY } from "./tools/toolRegistry.js";
 import { initEmbeddingIndex } from "./tools/embeddingProvider.js";
@@ -41,6 +55,20 @@ const ALL_TOOLS = [
     ...componentTools,
     ...httpTools,
     ...critterTools,
+    ...authorizationTools,
+    ...queryEfficiencyTools,
+    ...actionAuditTools,
+    ...typeSafetyTools,
+    ...transactionSafetyTools,
+    ...storageAuditTools,
+    ...paginationTools,
+    ...dataModelingTools,
+    ...devSetupTools,
+    ...migrationTools,
+    ...reportingTools,
+    ...vectorSearchTools,
+    ...schedulerTools,
+    ...qualityGateTools,
 ];
 const toolMap = new Map();
 for (const tool of ALL_TOOLS) {
@@ -49,20 +77,52 @@ for (const tool of ALL_TOOLS) {
 // ── Server setup ────────────────────────────────────────────────────
 const server = new Server({
     name: "convex-mcp-nodebench",
-    version: "0.1.0",
+    version: "0.8.0",
 }, {
     capabilities: {
         tools: {},
+        resources: {},
+        prompts: {},
     },
 });
 // ── Initialize DB + seed gotchas ────────────────────────────────────
 getDb();
 seedGotchasIfEmpty(CONVEX_GOTCHAS);
 // ── Background: initialize embedding index for semantic search ───────
-const embeddingCorpus = REGISTRY.map((entry) => ({
+// Uses Agent-as-a-Graph bipartite corpus: tool nodes + domain nodes for graph-aware retrieval
+const descMap = new Map(ALL_TOOLS.map((t) => [t.name, t.description]));
+// Tool nodes: individual tools with full metadata text
+const toolCorpus = REGISTRY.map((entry) => ({
     name: entry.name,
-    text: `${entry.name} ${entry.tags.join(" ")} ${entry.category} ${entry.phase}`,
+    text: `${entry.name} ${entry.tags.join(" ")} ${entry.category} ${entry.phase} ${descMap.get(entry.name) ?? ""}`,
+    nodeType: "tool",
 }));
+// Domain nodes: aggregate category descriptions for upward traversal
+// When a domain matches, all tools in that domain get a sibling boost
+const categoryTools = new Map();
+for (const entry of REGISTRY) {
+    const list = categoryTools.get(entry.category) ?? [];
+    list.push(entry.name);
+    categoryTools.set(entry.category, list);
+}
+const domainCorpus = [...categoryTools.entries()].map(([category, toolNames]) => {
+    const allTags = new Set();
+    const descs = [];
+    for (const tn of toolNames) {
+        const e = REGISTRY.find((r) => r.name === tn);
+        if (e)
+            e.tags.forEach((t) => allTags.add(t));
+        const d = descMap.get(tn);
+        if (d)
+            descs.push(d);
+    }
+    return {
+        name: `domain:${category}`,
+        text: `${category} domain: ${toolNames.join(" ")} ${[...allTags].join(" ")} ${descs.map(d => d.slice(0, 80)).join(" ")}`,
+        nodeType: "domain",
+    };
+});
+const embeddingCorpus = [...toolCorpus, ...domainCorpus];
 initEmbeddingIndex(embeddingCorpus).catch(() => {
     /* Embedding init failed — semantic search stays disabled */
 });
@@ -119,6 +179,235 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
     }
 });
+// ── MCP Resources ───────────────────────────────────────────────────
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return {
+        resources: [
+            {
+                uri: "convex://project-health",
+                name: "Project Health Summary",
+                description: "Latest quality gate score, audit coverage, and issue counts across all audit types",
+                mimeType: "application/json",
+            },
+            {
+                uri: "convex://recent-audits",
+                name: "Recent Audit Results",
+                description: "Summary of the 10 most recent audit runs with issue counts and timestamps",
+                mimeType: "application/json",
+            },
+            {
+                uri: "convex://gotcha-db",
+                name: "Gotcha Knowledge Base",
+                description: "All stored Convex gotchas (seeded + user-recorded) with categories and severity",
+                mimeType: "application/json",
+            },
+        ],
+    };
+});
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    const db = getDb();
+    if (uri === "convex://project-health") {
+        // Aggregate across all projects
+        const audits = db.prepare("SELECT audit_type, issue_count, audited_at FROM audit_results ORDER BY audited_at DESC LIMIT 50").all();
+        const byType = {};
+        for (const a of audits) {
+            if (!byType[a.audit_type]) {
+                byType[a.audit_type] = { count: a.issue_count, latest: a.audited_at };
+            }
+        }
+        const totalIssues = Object.values(byType).reduce((s, v) => s + v.count, 0);
+        const auditTypes = Object.keys(byType).length;
+        const latestGate = db.prepare("SELECT findings FROM deploy_checks WHERE check_type = 'quality_gate' ORDER BY checked_at DESC LIMIT 1").get();
+        let gateResult = null;
+        if (latestGate?.findings) {
+            try {
+                gateResult = JSON.parse(latestGate.findings);
+            }
+            catch { /* skip */ }
+        }
+        return {
+            contents: [{
+                    uri,
+                    mimeType: "application/json",
+                    text: JSON.stringify({
+                        totalIssues,
+                        auditTypesRun: auditTypes,
+                        issuesByType: byType,
+                        latestQualityGate: gateResult ? { score: gateResult.score, grade: gateResult.grade, passed: gateResult.passed } : null,
+                        toolCount: ALL_TOOLS.length,
+                    }, null, 2),
+                }],
+        };
+    }
+    if (uri === "convex://recent-audits") {
+        const audits = db.prepare("SELECT id, project_dir, audit_type, issue_count, audited_at FROM audit_results ORDER BY audited_at DESC LIMIT 10").all();
+        return {
+            contents: [{
+                    uri,
+                    mimeType: "application/json",
+                    text: JSON.stringify({ audits }, null, 2),
+                }],
+        };
+    }
+    if (uri === "convex://gotcha-db") {
+        const gotchas = db.prepare("SELECT key, category, severity, tags, source, updated_at FROM convex_gotchas ORDER BY updated_at DESC").all();
+        return {
+            contents: [{
+                    uri,
+                    mimeType: "application/json",
+                    text: JSON.stringify({
+                        totalGotchas: gotchas.length,
+                        bySource: {
+                            seed: gotchas.filter(g => g.source === "seed").length,
+                            user: gotchas.filter(g => g.source === "user").length,
+                        },
+                        gotchas,
+                    }, null, 2),
+                }],
+        };
+    }
+    return {
+        contents: [{
+                uri,
+                mimeType: "text/plain",
+                text: `Unknown resource: ${uri}`,
+            }],
+    };
+});
+// ── MCP Prompts ─────────────────────────────────────────────────────
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return {
+        prompts: [
+            {
+                name: "full-audit",
+                description: "Run a complete Convex project audit: schema, functions, auth, queries, actions, type safety, transactions, storage, pagination, data modeling, dev setup, vectors, schedulers — then quality gate",
+                arguments: [
+                    {
+                        name: "projectDir",
+                        description: "Absolute path to the project root",
+                        required: true,
+                    },
+                ],
+            },
+            {
+                name: "pre-deploy-checklist",
+                description: "Step-by-step pre-deployment verification: audit critical issues, check env vars, review migration plan, run quality gate",
+                arguments: [
+                    {
+                        name: "projectDir",
+                        description: "Absolute path to the project root",
+                        required: true,
+                    },
+                ],
+            },
+            {
+                name: "security-review",
+                description: "Security-focused audit: authorization coverage, type safety, action safety, storage permissions",
+                arguments: [
+                    {
+                        name: "projectDir",
+                        description: "Absolute path to the project root",
+                        required: true,
+                    },
+                ],
+            },
+        ],
+    };
+});
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const { name, arguments: promptArgs } = request.params;
+    const projectDir = promptArgs?.projectDir ?? ".";
+    if (name === "full-audit") {
+        return {
+            description: "Complete Convex project audit sequence",
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Run a complete audit of the Convex project at "${projectDir}". Execute these tools in order:
+
+1. convex_audit_schema — Check schema.ts for anti-patterns
+2. convex_audit_functions — Audit function registration and compliance
+3. convex_audit_authorization — Check auth coverage on public endpoints
+4. convex_audit_query_efficiency — Find unbounded queries and missing indexes
+5. convex_audit_actions — Validate action safety (no ctx.db, error handling)
+6. convex_check_type_safety — Find as-any casts and type issues
+7. convex_audit_transaction_safety — Detect race conditions
+8. convex_audit_storage_usage — Check file storage patterns
+9. convex_audit_pagination — Validate pagination implementations
+10. convex_audit_data_modeling — Check schema design quality
+11. convex_audit_vector_search — Validate vector search setup
+12. convex_audit_schedulers — Check scheduled function safety
+13. convex_audit_dev_setup — Verify project setup
+14. convex_quality_gate — Run configurable quality gate across all results
+
+After running all audits, summarize:
+- Total issues by severity (critical/warning/info)
+- Top 5 most impactful issues to fix first
+- Quality gate score and grade
+- Trend direction if previous audits exist (use convex_audit_diff)`,
+                    },
+                },
+            ],
+        };
+    }
+    if (name === "pre-deploy-checklist") {
+        return {
+            description: "Pre-deployment verification sequence",
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Run pre-deployment checks for the Convex project at "${projectDir}":
+
+1. convex_pre_deploy_gate — Structural checks (schema, auth config, initialization)
+2. convex_check_env_vars — Verify all required env vars are set
+3. convex_audit_authorization — Ensure auth coverage is adequate
+4. convex_audit_actions — No ctx.db access in actions
+5. convex_snapshot_schema — Capture current schema state
+6. convex_schema_migration_plan — Compare against previous snapshot for breaking changes
+7. convex_quality_gate — Final quality check with thresholds
+
+Report: DEPLOY or DO NOT DEPLOY with specific blockers to fix.`,
+                    },
+                },
+            ],
+        };
+    }
+    if (name === "security-review") {
+        return {
+            description: "Security-focused audit sequence",
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Run a security review of the Convex project at "${projectDir}":
+
+1. convex_audit_authorization — Auth coverage on all public endpoints
+2. convex_check_type_safety — Type safety bypasses (as any)
+3. convex_audit_actions — Action safety (ctx.db, error handling, "use node")
+4. convex_audit_storage_usage — Storage permission patterns
+5. convex_audit_pagination — Unbounded numItems (DoS risk)
+6. convex_audit_transaction_safety — Race condition risks
+
+Focus on: unauthorized data access, unvalidated inputs, missing error boundaries, and potential data corruption vectors.`,
+                    },
+                },
+            ],
+        };
+    }
+    return {
+        description: "Unknown prompt",
+        messages: [{
+                role: "user",
+                content: { type: "text", text: `Unknown prompt: ${name}` },
+            }],
+    };
+});
 // ── Start server ────────────────────────────────────────────────────
 async function main() {
     const transport = new StdioServerTransport();

package/dist/tools/actionAuditTools.d.ts

@@ -0,0 +1,2 @@
+import type { McpTool } from "../types.js";
+export declare const actionAuditTools: McpTool[];

package/dist/tools/actionAuditTools.js

@@ -0,0 +1,180 @@
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getDb, genId } from "../db.js";
+import { getQuickRef } from "./toolRegistry.js";
+// ── Helpers ──────────────────────────────────────────────────────────
+function findConvexDir(projectDir) {
+    const candidates = [join(projectDir, "convex"), join(projectDir, "src", "convex")];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    return null;
+}
+function collectTsFiles(dir) {
+    const results = [];
+    if (!existsSync(dir))
+        return results;
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory() && entry.name !== "node_modules" && entry.name !== "_generated") {
+            results.push(...collectTsFiles(full));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".ts")) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function auditActions(convexDir) {
+    const files = collectTsFiles(convexDir);
+    const issues = [];
+    let totalActions = 0;
+    let actionsWithDbAccess = 0;
+    let actionsWithoutNodeDirective = 0;
+    let actionsWithoutErrorHandling = 0;
+    let actionCallingAction = 0;
+    // Node APIs that require "use node" directive
+    const nodeApis = /\b(require|__dirname|__filename|Buffer\.|process\.env|fs\.|path\.|crypto\.|child_process|net\.|http\.|https\.)\b/;
+    for (const filePath of files) {
+        const content = readFileSync(filePath, "utf-8");
+        const relativePath = filePath.replace(convexDir, "").replace(/^[\\/]/, "");
+        const lines = content.split("\n");
+        const hasUseNode = /["']use node["']/.test(content);
+        const actionPattern = /export\s+(?:const\s+(\w+)\s*=|default)\s+(action|internalAction)\s*\(/g;
+        let m;
+        while ((m = actionPattern.exec(content)) !== null) {
+            const funcName = m[1] || "default";
+            const funcType = m[2];
+            totalActions++;
+            const startLine = content.slice(0, m.index).split("\n").length - 1;
+            // Extract body using brace tracking
+            let depth = 0;
+            let foundOpen = false;
+            let endLine = Math.min(startLine + 100, lines.length);
+            for (let j = startLine; j < lines.length; j++) {
+                for (const ch of lines[j]) {
+                    if (ch === "{") {
+                        depth++;
+                        foundOpen = true;
+                    }
+                    if (ch === "}")
+                        depth--;
+                }
+                if (foundOpen && depth <= 0) {
+                    endLine = j + 1;
+                    break;
+                }
+            }
+            const body = lines.slice(startLine, endLine).join("\n");
+            // Check 1: ctx.db access in action (FATAL — not allowed)
+            if (/ctx\.db\.(get|query|insert|patch|replace|delete)\s*\(/.test(body)) {
+                actionsWithDbAccess++;
+                issues.push({
+                    severity: "critical",
+                    location: `${relativePath}:${startLine + 1}`,
+                    functionName: funcName,
+                    message: `${funcType} "${funcName}" accesses ctx.db directly. Actions cannot access the database — use ctx.runQuery/ctx.runMutation instead.`,
+                    fix: "Move DB operations into a query or mutation, then call via ctx.runQuery(internal.file.func, args) or ctx.runMutation(...)",
+                });
+            }
+            // Check 2: Node API usage without "use node"
+            if (!hasUseNode && nodeApis.test(body)) {
+                actionsWithoutNodeDirective++;
+                issues.push({
+                    severity: "critical",
+                    location: `${relativePath}:${startLine + 1}`,
+                    functionName: funcName,
+                    message: `${funcType} "${funcName}" uses Node.js APIs but file lacks "use node" directive. Will fail in Convex runtime.`,
+                    fix: `Add "use node"; at the top of ${relativePath}`,
+                });
+            }
+            // Check 3: External API calls without try/catch
+            const hasFetch = /\bfetch\s*\(/.test(body);
+            const hasAxios = /\baxios\b/.test(body);
+            const hasExternalCall = hasFetch || hasAxios;
+            const hasTryCatch = /try\s*\{/.test(body);
+            if (hasExternalCall && !hasTryCatch) {
+                actionsWithoutErrorHandling++;
+                issues.push({
+                    severity: "warning",
+                    location: `${relativePath}:${startLine + 1}`,
+                    functionName: funcName,
+                    message: `${funcType} "${funcName}" makes external API calls without try/catch. Network failures will crash the action.`,
+                    fix: "Wrap fetch/axios calls in try/catch and handle errors gracefully",
+                });
+            }
+            // Check 4: Action calling another action
+            if (/ctx\.runAction\s*\(/.test(body)) {
+                actionCallingAction++;
+                issues.push({
+                    severity: "warning",
+                    location: `${relativePath}:${startLine + 1}`,
+                    functionName: funcName,
+                    message: `${funcType} "${funcName}" calls ctx.runAction(). Only call action from action when crossing runtimes (V8 ↔ Node). Otherwise extract shared logic into a helper function.`,
+                    fix: "Extract shared logic into an async helper, or use ctx.runMutation/ctx.runQuery as intermediary",
+                });
+            }
+            // Check 5: Very long action body (likely doing too much)
+            const bodyLines = endLine - startLine;
+            if (bodyLines > 80) {
+                issues.push({
+                    severity: "info",
+                    location: `${relativePath}:${startLine + 1}`,
+                    functionName: funcName,
+                    message: `${funcType} "${funcName}" is ${bodyLines} lines long. Consider splitting into smaller actions or extracting helpers.`,
+                    fix: "Break large actions into smaller, focused functions",
+                });
+            }
+        }
+    }
+    return {
+        issues,
+        stats: {
+            totalActions,
+            actionsWithDbAccess,
+            actionsWithoutNodeDirective,
+            actionsWithoutErrorHandling,
+            actionCallingAction,
+        },
+    };
+}
+// ── Tool Definition ─────────────────────────────────────────────────
+export const actionAuditTools = [
+    {
+        name: "convex_audit_actions",
+        description: 'Audit Convex actions for: ctx.db access (fatal — actions cannot access DB directly), missing "use node" directive for Node APIs, external API calls without error handling, and action-calling-action anti-patterns.',
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectDir: {
+                    type: "string",
+                    description: "Absolute path to the project root containing a convex/ directory",
+                },
+            },
+            required: ["projectDir"],
+        },
+        handler: async (args) => {
+            const projectDir = resolve(args.projectDir);
+            const convexDir = findConvexDir(projectDir);
+            if (!convexDir) {
+                return { error: "No convex/ directory found" };
+            }
+            const { issues, stats } = auditActions(convexDir);
+            const db = getDb();
+            db.prepare("INSERT INTO audit_results (id, project_dir, audit_type, issues_json, issue_count) VALUES (?, ?, ?, ?, ?)").run(genId("audit"), projectDir, "action_audit", JSON.stringify(issues), issues.length);
+            return {
+                summary: {
+                    ...stats,
+                    totalIssues: issues.length,
+                    critical: issues.filter((i) => i.severity === "critical").length,
+                    warnings: issues.filter((i) => i.severity === "warning").length,
+                },
+                issues: issues.slice(0, 30),
+                quickRef: getQuickRef("convex_audit_actions"),
+            };
+        },
+    },
+];
+//# sourceMappingURL=actionAuditTools.js.map

package/dist/tools/authorizationTools.d.ts

@@ -0,0 +1,2 @@
+import type { McpTool } from "../types.js";
+export declare const authorizationTools: McpTool[];