@homenshum/convex-mcp-nodebench 0.4.0 → 0.7.0

package/dist/tools/dataModelingTools.js

@@ -0,0 +1,168 @@
+import { readFileSync, existsSync } 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 auditDataModeling(convexDir) {
+    const schemaPath = join(convexDir, "schema.ts");
+    const issues = [];
+    let totalTables = 0;
+    let tablesWithArrays = 0;
+    let tablesWithDeepNesting = 0;
+    let danglingIdRefs = 0;
+    let vAnyCount = 0;
+    if (!existsSync(schemaPath)) {
+        return {
+            issues: [{ severity: "critical", location: "schema.ts", message: "No schema.ts found", fix: "Create convex/schema.ts" }],
+            stats: { totalTables: 0, tablesWithArrays: 0, tablesWithDeepNesting: 0, danglingIdRefs: 0, vAnyCount: 0 },
+        };
+    }
+    const content = readFileSync(schemaPath, "utf-8");
+    const lines = content.split("\n");
+    // Parse all table names
+    const tableNames = new Set();
+    const tableDefPattern = /(\w+)\s*[:=]\s*defineTable\s*\(/g;
+    let m;
+    while ((m = tableDefPattern.exec(content)) !== null) {
+        tableNames.add(m[1]);
+        totalTables++;
+    }
+    // Per-table analysis
+    let currentTable = "";
+    let tableStartLine = 0;
+    let tableNestDepth = 0;
+    let maxNestInTable = 0;
+    let tableHasArray = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Track current table
+        const tableDef = line.match(/(\w+)\s*[:=]\s*defineTable\s*\(/);
+        if (tableDef) {
+            // Check previous table
+            if (currentTable && maxNestInTable > 3) {
+                tablesWithDeepNesting++;
+                issues.push({
+                    severity: "warning",
+                    location: `schema.ts:${tableStartLine + 1}`,
+                    table: currentTable,
+                    message: `Table "${currentTable}" has ${maxNestInTable} levels of nesting. Deep nesting increases document size and query complexity.`,
+                    fix: "Consider normalizing deeply nested data into separate tables with Id references",
+                });
+            }
+            if (currentTable && tableHasArray)
+                tablesWithArrays++;
+            currentTable = tableDef[1];
+            tableStartLine = i;
+            maxNestInTable = 0;
+            tableHasArray = false;
+        }
+        if (line.trim().startsWith("//") || line.trim().startsWith("*"))
+            continue;
+        // Track nesting depth within a table
+        if (currentTable) {
+            const opens = (line.match(/v\.object\s*\(/g) || []).length;
+            tableNestDepth += opens;
+            if (tableNestDepth > maxNestInTable)
+                maxNestInTable = tableNestDepth;
+            const closes = (line.match(/\)/g) || []).length;
+            tableNestDepth = Math.max(0, tableNestDepth - closes);
+        }
+        // Check: v.array() usage (potential size limit issue)
+        if (/v\.array\s*\(/.test(line) && currentTable) {
+            tableHasArray = true;
+        }
+        // Check: v.any() usage
+        if (/v\.any\s*\(\s*\)/.test(line)) {
+            vAnyCount++;
+        }
+        // Check: v.id("tableName") references — verify the table exists
+        const idRefPattern = /v\.id\s*\(\s*["'](\w+)["']\s*\)/g;
+        let idMatch;
+        while ((idMatch = idRefPattern.exec(line)) !== null) {
+            const refTable = idMatch[1];
+            if (refTable !== "_storage" && !tableNames.has(refTable)) {
+                danglingIdRefs++;
+                issues.push({
+                    severity: "critical",
+                    location: `schema.ts:${i + 1}`,
+                    table: currentTable,
+                    message: `v.id("${refTable}") references table "${refTable}" which is not defined in the schema. This will cause type errors.`,
+                    fix: `Either add the "${refTable}" table to the schema or fix the reference`,
+                });
+            }
+        }
+    }
+    // Check last table
+    if (currentTable && maxNestInTable > 3) {
+        tablesWithDeepNesting++;
+        issues.push({
+            severity: "warning",
+            location: `schema.ts:${tableStartLine + 1}`,
+            table: currentTable,
+            message: `Table "${currentTable}" has ${maxNestInTable} levels of nesting.`,
+            fix: "Consider normalizing deeply nested data into separate tables",
+        });
+    }
+    if (currentTable && tableHasArray)
+        tablesWithArrays++;
+    // Check: tables with many fields (approaching limits)
+    const fieldCountPattern = /defineTable\s*\(\s*v\.object\s*\(\s*\{([\s\S]*?)\}\s*\)/g;
+    let fcm;
+    while ((fcm = fieldCountPattern.exec(content)) !== null) {
+        const fieldBlock = fcm[1];
+        const fieldCount = (fieldBlock.match(/\w+\s*:/g) || []).length;
+        if (fieldCount > 50) {
+            issues.push({
+                severity: "warning",
+                location: "schema.ts",
+                message: `A table has ${fieldCount} fields. Consider splitting into related tables if this grows further (Convex max: 1024 fields).`,
+                fix: "Split large tables into related tables with Id references",
+            });
+        }
+    }
+    return {
+        issues,
+        stats: { totalTables, tablesWithArrays, tablesWithDeepNesting, danglingIdRefs, vAnyCount },
+    };
+}
+// ── Tool Definition ─────────────────────────────────────────────────
+export const dataModelingTools = [
+    {
+        name: "convex_audit_data_modeling",
+        description: "Audit Convex schema for data modeling issues: deeply nested objects (flatten into tables), dangling v.id() references to non-existent tables, tables approaching field count limits, v.any() overuse, and array fields that may hit size limits.",
+        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 } = auditDataModeling(convexDir);
+            const db = getDb();
+            db.prepare("INSERT INTO audit_results (id, project_dir, audit_type, issues_json, issue_count) VALUES (?, ?, ?, ?, ?)").run(genId("audit"), projectDir, "data_modeling", JSON.stringify(issues), issues.length);
+            return {
+                summary: { ...stats, totalIssues: issues.length },
+                issues,
+                quickRef: getQuickRef("convex_audit_data_modeling"),
+            };
+        },
+    },
+];
+//# sourceMappingURL=dataModelingTools.js.map

package/dist/tools/deploymentTools.js

@@ -20,7 +20,12 @@ function runPreDeployChecks(projectDir) {
     if (!convexDir) {
         checks.push({ name: "convex_dir_exists", passed: false, message: "No convex/ directory found" });
         blockers.push("No convex/ directory found");
-        return { passed: false, checks, blockers };
+        return {
+            passed: false,
+            checks,
+            blockers: blockers.map((b, i) => ({ priority: i + 1, blocker: b, fixFirst: i === 0 })),
+            fixOrder: "Fix #1: Create a convex/ directory. Then re-run convex_pre_deploy_gate.",
+        };
     }
     checks.push({ name: "convex_dir_exists", passed: true, message: `Found at ${convexDir}` });
     // Check 2: schema.ts exists
@@ -101,10 +106,19 @@ function runPreDeployChecks(projectDir) {
         checks.push({ name: "generated_dir_exists", passed: false, message: "_generated/ not found - run 'npx convex dev' first" });
         blockers.push("Run 'npx convex dev' to initialize the project before deploying");
     }
+    // Add priority ordering to blockers
+    const prioritizedBlockers = blockers.map((b, i) => ({
+        priority: i + 1,
+        blocker: b,
+        fixFirst: i === 0,
+    }));
     return {
         passed: blockers.length === 0,
         checks,
-        blockers,
+        blockers: prioritizedBlockers,
+        fixOrder: blockers.length > 0
+            ? `Fix ${blockers.length} blocker(s) in order: ${blockers.map((_, i) => `#${i + 1}`).join(" → ")}. Then re-run convex_pre_deploy_gate.`
+            : "All checks passed. Safe to deploy.",
     };
 }
 function checkEnvVars(projectDir) {
@@ -222,8 +236,34 @@ export const deploymentTools = [
         handler: async (args) => {
             const projectDir = resolve(args.projectDir);
             const result = checkEnvVars(projectDir);
+            // Group missing vars by service for actionable output
+            const serviceGroups = {};
+            for (const v of result.missingInEnvFile) {
+                const vUp = v.toUpperCase();
+                const svc = vUp.includes("OPENAI") ? "OpenAI" :
+                    vUp.includes("GEMINI") || vUp.includes("GOOGLE") ? "Google" :
+                        vUp.includes("OPENBB") ? "OpenBB" :
+                            vUp.includes("TWILIO") ? "Twilio" :
+                                vUp.includes("LINKEDIN") ? "LinkedIn" :
+                                    vUp.includes("GITHUB") ? "GitHub" :
+                                        vUp.includes("STRIPE") ? "Stripe" :
+                                            vUp.includes("OPENROUTER") ? "OpenRouter" :
+                                                vUp.includes("RESEARCH") ? "Research MCP" :
+                                                    vUp.includes("MCP") ? "MCP" :
+                                                        vUp.includes("NTFY") ? "Ntfy" :
+                                                            vUp.includes("XAI") ? "xAI" :
+                                                                vUp.includes("CLERK") ? "Clerk" :
+                                                                    vUp.includes("CONVEX") ? "Convex" :
+                                                                        "Other";
+                if (!serviceGroups[svc])
+                    serviceGroups[svc] = [];
+                serviceGroups[svc].push(v);
+            }
             return {
                 ...result,
+                missingByService: Object.entries(serviceGroups)
+                    .sort(([, a], [, b]) => b.length - a.length)
+                    .map(([service, vars]) => ({ service, count: vars.length, vars })),
                 quickRef: getQuickRef("convex_check_env_vars"),
             };
         },

package/dist/tools/devSetupTools.d.ts

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

package/dist/tools/devSetupTools.js

@@ -0,0 +1,170 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getDb, genId } from "../db.js";
+import { getQuickRef } from "./toolRegistry.js";
+function auditDevSetup(projectDir) {
+    const issues = [];
+    const checks = [];
+    // Check 1: .gitignore includes _generated/
+    const gitignorePath = join(projectDir, ".gitignore");
+    if (existsSync(gitignorePath)) {
+        const gitignore = readFileSync(gitignorePath, "utf-8");
+        if (gitignore.includes("_generated") || gitignore.includes("convex/_generated")) {
+            checks.push({ area: "gitignore", status: "pass", detail: "_generated/ is in .gitignore" });
+        }
+        else {
+            checks.push({ area: "gitignore", status: "warn", detail: "_generated/ not in .gitignore — generated files may be committed" });
+            issues.push({
+                severity: "warning",
+                area: "gitignore",
+                message: "_generated/ directory is not in .gitignore. These files are auto-generated and should not be committed.",
+                fix: "Add `convex/_generated/` to .gitignore",
+            });
+        }
+    }
+    else {
+        checks.push({ area: "gitignore", status: "fail", detail: "No .gitignore file found" });
+        issues.push({
+            severity: "warning",
+            area: "gitignore",
+            message: "No .gitignore file found. Generated and environment files may be committed.",
+            fix: "Create a .gitignore with at least: node_modules/, convex/_generated/, .env.local",
+        });
+    }
+    // Check 2: .env.example exists
+    const envExamplePath = join(projectDir, ".env.example");
+    if (existsSync(envExamplePath)) {
+        checks.push({ area: "env_example", status: "pass", detail: ".env.example exists for onboarding" });
+    }
+    else {
+        // Check if there are env vars in use
+        const envLocalPath = join(projectDir, ".env.local");
+        const envPath = join(projectDir, ".env");
+        if (existsSync(envLocalPath) || existsSync(envPath)) {
+            checks.push({ area: "env_example", status: "warn", detail: ".env files exist but no .env.example for new developers" });
+            issues.push({
+                severity: "info",
+                area: "env_example",
+                message: "No .env.example file. New developers won't know which env vars to set.",
+                fix: "Create .env.example with placeholder values for all required environment variables",
+            });
+        }
+    }
+    // Check 3: convex.json exists and points to valid deployment
+    const convexJsonPath = join(projectDir, "convex.json");
+    if (existsSync(convexJsonPath)) {
+        try {
+            const convexJson = JSON.parse(readFileSync(convexJsonPath, "utf-8"));
+            if (convexJson.project) {
+                checks.push({ area: "convex_json", status: "pass", detail: `convex.json configured for project: ${convexJson.project}` });
+            }
+            else {
+                checks.push({ area: "convex_json", status: "warn", detail: "convex.json exists but no project configured" });
+            }
+        }
+        catch {
+            checks.push({ area: "convex_json", status: "fail", detail: "convex.json exists but is invalid JSON" });
+            issues.push({
+                severity: "critical",
+                area: "convex_json",
+                message: "convex.json is invalid JSON. Convex CLI won't work.",
+                fix: "Fix the JSON syntax in convex.json or delete and run `npx convex dev` to regenerate",
+            });
+        }
+    }
+    // Check 4: package.json has convex as dependency
+    const pkgJsonPath = join(projectDir, "package.json");
+    if (existsSync(pkgJsonPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            if (deps.convex) {
+                checks.push({ area: "convex_dep", status: "pass", detail: `convex@${deps.convex} installed` });
+            }
+            else {
+                checks.push({ area: "convex_dep", status: "fail", detail: "convex not in dependencies" });
+                issues.push({
+                    severity: "critical",
+                    area: "convex_dep",
+                    message: "convex package is not in dependencies. Install it first.",
+                    fix: "Run: npm install convex",
+                });
+            }
+        }
+        catch { /* ignore parse errors */ }
+    }
+    // Check 5: tsconfig.json configured for Convex
+    const tsconfigPath = join(projectDir, "tsconfig.json");
+    if (existsSync(tsconfigPath)) {
+        const tsconfig = readFileSync(tsconfigPath, "utf-8");
+        if (/\"strict\"\s*:\s*true/.test(tsconfig)) {
+            checks.push({ area: "tsconfig", status: "pass", detail: "TypeScript strict mode enabled" });
+        }
+        else {
+            checks.push({ area: "tsconfig", status: "info", detail: "TypeScript strict mode not enabled — recommended for Convex" });
+        }
+    }
+    // Check 6: _generated/ directory exists (project initialized)
+    const convexDir = join(projectDir, "convex");
+    const generatedDir = join(convexDir, "_generated");
+    if (existsSync(generatedDir)) {
+        checks.push({ area: "initialization", status: "pass", detail: "_generated/ exists — project is initialized" });
+    }
+    else if (existsSync(convexDir)) {
+        checks.push({ area: "initialization", status: "warn", detail: "_generated/ not found — run `npx convex dev` to initialize" });
+        issues.push({
+            severity: "warning",
+            area: "initialization",
+            message: "Convex project not initialized — _generated/ directory is missing.",
+            fix: "Run `npx convex dev` to generate types and initialize the project",
+        });
+    }
+    // Check 7: Node modules installed
+    const nodeModulesPath = join(projectDir, "node_modules", "convex");
+    if (existsSync(nodeModulesPath)) {
+        checks.push({ area: "node_modules", status: "pass", detail: "convex package installed in node_modules" });
+    }
+    else if (existsSync(pkgJsonPath)) {
+        checks.push({ area: "node_modules", status: "warn", detail: "convex not in node_modules — run npm install" });
+    }
+    return { issues, checks };
+}
+// ── Tool Definition ─────────────────────────────────────────────────
+export const devSetupTools = [
+    {
+        name: "convex_audit_dev_setup",
+        description: "Audit Convex project development setup: .gitignore includes _generated/, .env.example exists, convex.json is valid, convex is in dependencies, TypeScript strict mode, project initialization status.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectDir: {
+                    type: "string",
+                    description: "Absolute path to the project root",
+                },
+            },
+            required: ["projectDir"],
+        },
+        handler: async (args) => {
+            const projectDir = resolve(args.projectDir);
+            const { issues, checks } = auditDevSetup(projectDir);
+            const db = getDb();
+            db.prepare("INSERT INTO audit_results (id, project_dir, audit_type, issues_json, issue_count) VALUES (?, ?, ?, ?, ?)").run(genId("audit"), projectDir, "dev_setup", JSON.stringify(issues), issues.length);
+            const passed = checks.filter((c) => c.status === "pass").length;
+            const warned = checks.filter((c) => c.status === "warn").length;
+            const failed = checks.filter((c) => c.status === "fail").length;
+            return {
+                summary: {
+                    totalChecks: checks.length,
+                    passed,
+                    warned,
+                    failed,
+                    totalIssues: issues.length,
+                },
+                checks,
+                issues,
+                quickRef: getQuickRef("convex_audit_dev_setup"),
+            };
+        },
+    },
+];
+//# sourceMappingURL=devSetupTools.js.map

package/dist/tools/embeddingProvider.d.ts

@@ -11,19 +11,25 @@ export interface EmbeddingProvider {
     dimensions: number;
     embed(texts: string[]): Promise<Float32Array[]>;
 }
+/** Node type in the bipartite graph: tool nodes vs domain (agent) nodes */
+export type GraphNodeType = "tool" | "domain";
 interface EmbeddingIndexEntry {
     name: string;
     vector: Float32Array;
+    /** Node type for Agent-as-a-Graph bipartite scoring */
+    nodeType: GraphNodeType;
 }
 export declare function getEmbeddingProvider(): Promise<EmbeddingProvider | null>;
 export declare function initEmbeddingIndex(corpus: Array<{
     name: string;
     text: string;
+    nodeType?: GraphNodeType;
 }>): Promise<void>;
 export declare function embedQuery(text: string): Promise<Float32Array | null>;
 export declare function embeddingSearch(queryVec: Float32Array, limit?: number): Array<{
     name: string;
     similarity: number;
+    nodeType: GraphNodeType;
 }>;
 export declare function isEmbeddingReady(): boolean;
 export declare function getProviderName(): string | null;

package/dist/tools/embeddingProvider.js

@@ -120,6 +120,7 @@ async function _doInit(corpus) {
         _embeddingIndex = corpus.map((c) => ({
             name: c.name,
             vector: new Float32Array(cached.entries[c.name]),
+            nodeType: c.nodeType ?? "tool",
         }));
         return;
     }
@@ -129,6 +130,7 @@ async function _doInit(corpus) {
         _embeddingIndex = corpus.map((c, i) => ({
             name: c.name,
             vector: vectors[i],
+            nodeType: c.nodeType ?? "tool",
         }));
         const cacheData = {
             providerName: provider.name,
@@ -165,6 +167,7 @@ export function embeddingSearch(queryVec, limit = 30) {
     const scored = _embeddingIndex.map((entry) => ({
         name: entry.name,
         similarity: cosineSim(queryVec, entry.vector),
+        nodeType: entry.nodeType,
     }));
     scored.sort((a, b) => b.similarity - a.similarity);
     return scored.slice(0, limit);

package/dist/tools/functionTools.js

@@ -287,6 +287,22 @@ export const functionTools = [
             db.prepare("INSERT INTO audit_results (id, project_dir, audit_type, issues_json, issue_count) VALUES (?, ?, ?, ?, ?)").run(genId("audit"), projectDir, "function_audit", JSON.stringify(issues), issues.length);
             const critical = issues.filter((i) => i.severity === "critical");
             const warnings = issues.filter((i) => i.severity === "warning");
+            // Aggregate issues by category for cleaner output
+            const categories = {};
+            for (const issue of issues) {
+                const cat = issue.message.includes("missing args") ? "missing_args_validator" :
+                    issue.message.includes("missing returns") ? "missing_returns_validator" :
+                        issue.message.includes("missing handler") ? "missing_handler_old_syntax" :
+                            issue.message.includes("sensitive") ? "sensitive_function_public" :
+                                issue.message.includes("queries cannot") ? "query_cross_call_violation" :
+                                    issue.message.includes("multiple actions") ? "action_from_action" :
+                                        "other";
+                if (!categories[cat])
+                    categories[cat] = { severity: issue.severity, count: 0, examples: [] };
+                categories[cat].count++;
+                if (categories[cat].examples.length < 5)
+                    categories[cat].examples.push(issue);
+            }
             return {
                 summary: {
                     totalFunctions: functions.length,
@@ -296,7 +312,14 @@ export const functionTools = [
                     critical: critical.length,
                     warnings: warnings.length,
                 },
-                issues,
+                issuesByCategory: Object.entries(categories)
+                    .sort(([, a], [, b]) => (b.severity === "critical" ? 1 : 0) - (a.severity === "critical" ? 1 : 0) || b.count - a.count)
+                    .map(([cat, data]) => ({
+                    category: cat,
+                    severity: data.severity,
+                    count: data.count,
+                    examples: data.examples,
+                })),
                 quickRef: getQuickRef("convex_audit_functions"),
             };
         },