@homenshum/convex-mcp-nodebench 0.4.1 → 0.8.0

package/dist/tools/schedulerTools.js

@@ -0,0 +1,197 @@
+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 auditSchedulers(convexDir) {
+    const files = collectTsFiles(convexDir);
+    const issues = [];
+    let totalSchedulerCalls = 0;
+    let runAfterCalls = 0;
+    let runAtCalls = 0;
+    let selfSchedulingFunctions = 0;
+    const filesWithSchedulers = new Set();
+    for (const filePath of files) {
+        const content = readFileSync(filePath, "utf-8");
+        const relativePath = filePath.replace(convexDir, "").replace(/^[\\/]/, "");
+        const lines = content.split("\n");
+        // Find all exported functions (mutation/action) and their bodies
+        const funcPattern = /export\s+(?:const\s+(\w+)\s*=|default)\s+(mutation|internalMutation|action|internalAction)\s*\(/g;
+        let m;
+        while ((m = funcPattern.exec(content)) !== null) {
+            const funcName = m[1] || "default";
+            const funcType = m[2];
+            const startLine = content.slice(0, m.index).split("\n").length - 1;
+            // Extract body
+            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 scheduler calls in body
+            const runAfterMatches = [...body.matchAll(/ctx\.scheduler\.runAfter\s*\(/g)];
+            const runAtMatches = [...body.matchAll(/ctx\.scheduler\.runAt\s*\(/g)];
+            const allSchedulerCalls = runAfterMatches.length + runAtMatches.length;
+            if (allSchedulerCalls === 0)
+                continue;
+            filesWithSchedulers.add(relativePath);
+            totalSchedulerCalls += allSchedulerCalls;
+            runAfterCalls += runAfterMatches.length;
+            runAtCalls += runAtMatches.length;
+            // Check 1: Self-scheduling (infinite loop risk)
+            // Detect: function schedules itself by name
+            const selfRefPattern = new RegExp(`ctx\\.scheduler\\.run(?:After|At)\\s*\\([^,]*,\\s*(?:internal|api)\\.[^,]*\\.${funcName}\\b`);
+            if (selfRefPattern.test(body)) {
+                selfSchedulingFunctions++;
+                // Check if there's a termination condition
+                const hasTermination = /if\s*\(|return\s+(?:null|undefined|void)|\.length\s*(?:===?|<=?)\s*0/.test(body);
+                issues.push({
+                    severity: hasTermination ? "warning" : "critical",
+                    location: `${relativePath}:${startLine + 1}`,
+                    functionName: funcName,
+                    message: `${funcType} "${funcName}" schedules itself${hasTermination ? " (has conditional guard)" : " without clear termination — infinite loop risk"}.`,
+                    fix: hasTermination
+                        ? "Verify the termination condition covers all edge cases"
+                        : "Add a termination condition (max retries, empty queue check) before self-scheduling",
+                });
+            }
+            // Check 2: Very short delay (< 1 second) — may indicate missing backoff
+            for (const match of runAfterMatches) {
+                const callIdx = content.indexOf(match[0], m.index);
+                const callLine = content.slice(0, callIdx).split("\n").length;
+                const afterCall = content.slice(callIdx, callIdx + 100);
+                const delayMatch = afterCall.match(/runAfter\s*\(\s*(\d+(?:\.\d+)?)\s*[,)]/);
+                if (delayMatch) {
+                    const delay = parseFloat(delayMatch[1]);
+                    if (delay < 1) {
+                        issues.push({
+                            severity: "warning",
+                            location: `${relativePath}:${callLine}`,
+                            functionName: funcName,
+                            message: `scheduler.runAfter(${delay}, ...) uses sub-second delay. In retry/loop patterns this can overwhelm the scheduler.`,
+                            fix: "Use at least 1-second delay. For retries, implement exponential backoff (e.g., delay * 2^attempt)",
+                        });
+                    }
+                }
+            }
+            // Check 3: Scheduler in action without try/catch
+            if ((funcType === "action" || funcType === "internalAction") && allSchedulerCalls > 0) {
+                // Check if the scheduler call is wrapped in try/catch
+                if (!/try\s*\{/.test(body)) {
+                    issues.push({
+                        severity: "info",
+                        location: `${relativePath}:${startLine + 1}`,
+                        functionName: funcName,
+                        message: `${funcType} "${funcName}" uses scheduler without try/catch. If the action fails before scheduling, work may be lost.`,
+                        fix: "Wrap scheduler calls in try/catch or move scheduling to a mutation for transactional guarantees",
+                    });
+                }
+            }
+            // Check 4: Multiple scheduler calls in same function (fan-out)
+            if (allSchedulerCalls > 3) {
+                issues.push({
+                    severity: "info",
+                    location: `${relativePath}:${startLine + 1}`,
+                    functionName: funcName,
+                    message: `${funcType} "${funcName}" makes ${allSchedulerCalls} scheduler calls. Consider if a single orchestrator action would be cleaner.`,
+                    fix: "Group related work into fewer scheduled calls or use a queue-based pattern",
+                });
+            }
+            // Check 5: Scheduling from a query (not possible — queries are read-only)
+            if (funcType.includes("Query") || funcType === "query" || funcType === "internalQuery") {
+                issues.push({
+                    severity: "critical",
+                    location: `${relativePath}:${startLine + 1}`,
+                    functionName: funcName,
+                    message: `Query "${funcName}" tries to use ctx.scheduler — queries are read-only and cannot schedule functions.`,
+                    fix: "Move scheduler calls to a mutation or action",
+                });
+            }
+        }
+    }
+    return {
+        issues,
+        stats: {
+            totalSchedulerCalls,
+            runAfterCalls,
+            runAtCalls,
+            selfSchedulingFunctions,
+            filesWithSchedulers: filesWithSchedulers.size,
+        },
+    };
+}
+// ── Tool Definition ─────────────────────────────────────────────────
+export const schedulerTools = [
+    {
+        name: "convex_audit_schedulers",
+        description: "Audit Convex scheduled function usage (ctx.scheduler.runAfter/runAt): detects infinite self-scheduling loops, sub-second delays without backoff, scheduler calls in queries (impossible), unprotected scheduler calls in actions, and excessive fan-out 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 } = auditSchedulers(convexDir);
+            const db = getDb();
+            db.prepare("INSERT INTO audit_results (id, project_dir, audit_type, issues_json, issue_count) VALUES (?, ?, ?, ?, ?)").run(genId("audit"), projectDir, "scheduler_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_schedulers"),
+            };
+        },
+    },
+];
+//# sourceMappingURL=schedulerTools.js.map

package/dist/tools/schemaTools.js

@@ -156,6 +156,55 @@ function analyzeSchema(schemaContent, filePath) {
     });
     return issues;
 }
+function analyzeAdvancedIndexes(schemaContent) {
+    const searchIndexes = [];
+    const vectorIndexes = [];
+    const lines = schemaContent.split("\n");
+    let currentTable = "";
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Track current table context
+        const tableDef = line.match(/(\w+)\s*[:=]\s*defineTable\s*\(/);
+        if (tableDef)
+            currentTable = tableDef[1];
+        // Detect .searchIndex("name", { ... })
+        const searchMatch = line.match(/\.searchIndex\s*\(\s*["']([^"']+)["']/);
+        if (searchMatch && currentTable) {
+            // Look ahead for searchField and filterFields
+            const chunk = lines.slice(i, Math.min(i + 10, lines.length)).join("\n");
+            const searchFieldMatch = chunk.match(/searchField\s*:\s*["']([^"']+)["']/);
+            const filterFieldsMatch = chunk.match(/filterFields\s*:\s*\[([^\]]*)\]/);
+            const filterFields = filterFieldsMatch
+                ? (filterFieldsMatch[1].match(/["']([^"']+)["']/g) || []).map(f => f.replace(/["']/g, ""))
+                : [];
+            searchIndexes.push({
+                table: currentTable,
+                name: searchMatch[1],
+                searchField: searchFieldMatch?.[1] || "unknown",
+                filterFields,
+                line: i + 1,
+            });
+        }
+        // Detect .vectorIndex("name", { ... })
+        const vectorMatch = line.match(/\.vectorIndex\s*\(\s*["']([^"']+)["']/);
+        if (vectorMatch && currentTable) {
+            const chunk = lines.slice(i, Math.min(i + 10, lines.length)).join("\n");
+            const dimMatch = chunk.match(/dimensions\s*:\s*(\d+)/);
+            const filterFieldsMatch = chunk.match(/filterFields\s*:\s*\[([^\]]*)\]/);
+            const filterFields = filterFieldsMatch
+                ? (filterFieldsMatch[1].match(/["']([^"']+)["']/g) || []).map(f => f.replace(/["']/g, ""))
+                : [];
+            vectorIndexes.push({
+                table: currentTable,
+                name: vectorMatch[1],
+                dimensions: dimMatch ? parseInt(dimMatch[1]) : undefined,
+                filterFields,
+                line: i + 1,
+            });
+        }
+    }
+    return { searchIndexes, vectorIndexes };
+}
 function analyzeValidatorCoverage(convexDir) {
     const files = collectTsFiles(convexDir);
     const result = {
@@ -283,12 +332,16 @@ export const schemaTools = [
             }
             const schemaPath = join(convexDir, "schema.ts");
             const issues = analyzeSchema(schemaContent, schemaPath);
+            const advancedIndexes = analyzeAdvancedIndexes(schemaContent);
             // Store audit result
             const db = getDb();
             db.prepare("INSERT INTO audit_results (id, project_dir, audit_type, file_path, issues_json, issue_count) VALUES (?, ?, ?, ?, ?, ?)").run(genId("audit"), projectDir, "schema", schemaPath, JSON.stringify(issues), issues.length);
             const critical = issues.filter((i) => i.severity === "critical");
             const warnings = issues.filter((i) => i.severity === "warning");
             const info = issues.filter((i) => i.severity === "info");
+            // Count tables and regular indexes
+            const tableCount = (schemaContent.match(/defineTable\s*\(/g) || []).length;
+            const regularIndexCount = (schemaContent.match(/\.index\s*\(/g) || []).length;
             return {
                 summary: {
                     totalIssues: issues.length,
@@ -296,8 +349,18 @@ export const schemaTools = [
                     warnings: warnings.length,
                     info: info.length,
                     schemaFile: schemaPath,
+                    tables: tableCount,
+                    regularIndexes: regularIndexCount,
+                    searchIndexes: advancedIndexes.searchIndexes.length,
+                    vectorIndexes: advancedIndexes.vectorIndexes.length,
                 },
                 issues,
+                searchIndexes: advancedIndexes.searchIndexes.length > 0
+                    ? advancedIndexes.searchIndexes
+                    : undefined,
+                vectorIndexes: advancedIndexes.vectorIndexes.length > 0
+                    ? advancedIndexes.vectorIndexes
+                    : undefined,
                 quickRef: getQuickRef("convex_audit_schema"),
             };
         },
@@ -322,9 +385,40 @@ export const schemaTools = [
                 return { error: "No convex/ directory found" };
             }
             const suggestions = suggestIndexes(convexDir);
+            // Add existing index context per table mentioned in suggestions
+            const schemaContent = readSchemaFile(convexDir);
+            const existingByTable = {};
+            if (schemaContent) {
+                let currentTable = "";
+                for (const line of schemaContent.split("\n")) {
+                    const tableDef = line.match(/(\w+)\s*[:=]\s*defineTable\s*\(/);
+                    if (tableDef)
+                        currentTable = tableDef[1];
+                    const idxMatch = line.match(/\.index\s*\(\s*["']([^"']+)["']/);
+                    if (idxMatch && currentTable) {
+                        if (!existingByTable[currentTable])
+                            existingByTable[currentTable] = [];
+                        existingByTable[currentTable].push(idxMatch[1]);
+                    }
+                }
+            }
+            // Group suggestions by table for cleaner output
+            const byTable = {};
+            for (const s of suggestions) {
+                if (!byTable[s.table])
+                    byTable[s.table] = [];
+                byTable[s.table].push(s);
+            }
             return {
                 totalSuggestions: suggestions.length,
-                suggestions,
+                tablesNeedingIndexes: Object.keys(byTable).length,
+                suggestionsByTable: Object.entries(byTable)
+                    .sort(([, a], [, b]) => b.length - a.length)
+                    .map(([table, sugs]) => ({
+                    table,
+                    existingIndexes: existingByTable[table] || [],
+                    suggestions: sugs,
+                })),
                 quickRef: getQuickRef("convex_suggest_indexes"),
             };
         },

package/dist/tools/storageAuditTools.d.ts

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

package/dist/tools/storageAuditTools.js

@@ -0,0 +1,148 @@
+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 auditStorageUsage(convexDir) {
+    const files = collectTsFiles(convexDir);
+    const issues = [];
+    let filesUsingStorage = 0;
+    let storageGetCalls = 0;
+    let storageGetUrlCalls = 0;
+    let storageStoreCalls = 0;
+    let storageDeleteCalls = 0;
+    let missingNullChecks = 0;
+    for (const filePath of files) {
+        const content = readFileSync(filePath, "utf-8");
+        const relativePath = filePath.replace(convexDir, "").replace(/^[\\/]/, "");
+        const lines = content.split("\n");
+        const usesStorage = /ctx\.storage\./.test(content);
+        if (!usesStorage)
+            continue;
+        filesUsingStorage++;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            // Count storage operations
+            if (/ctx\.storage\.get\s*\(/.test(line))
+                storageGetCalls++;
+            if (/ctx\.storage\.getUrl\s*\(/.test(line))
+                storageGetUrlCalls++;
+            if (/ctx\.storage\.store\s*\(/.test(line))
+                storageStoreCalls++;
+            if (/ctx\.storage\.delete\s*\(/.test(line))
+                storageDeleteCalls++;
+            // Check 1: ctx.storage.get() or getUrl() without null check
+            const getMatch = line.match(/(?:const|let)\s+(\w+)\s*=\s*await\s+ctx\.storage\.(get|getUrl)\s*\(/);
+            if (getMatch) {
+                const varName = getMatch[1];
+                const method = getMatch[2];
+                // Look ahead 5 lines for null check
+                const lookahead = lines.slice(i, Math.min(i + 6, lines.length)).join("\n");
+                const hasNullCheck = new RegExp(`if\\s*\\(\\s*!${varName}\\b|if\\s*\\(\\s*${varName}\\s*===?\\s*null|${varName}\\s*\\?\\.|${varName}\\s*!\\s*\\.`).test(lookahead);
+                if (!hasNullCheck) {
+                    missingNullChecks++;
+                    issues.push({
+                        severity: "warning",
+                        location: `${relativePath}:${i + 1}`,
+                        message: `ctx.storage.${method}() result "${varName}" not null-checked. Returns null if file doesn't exist.`,
+                        fix: `Add: if (!${varName}) { throw new Error("File not found"); }`,
+                    });
+                }
+            }
+        }
+        // Check 2: Storage ID stored as string instead of Id<'_storage'>
+        // Look for v.string() in schema fields that likely hold storage IDs
+        const storageIdFields = content.match(/(\w*(?:storage|file|image|avatar|thumbnail|attachment|media|upload|blob|asset)\w*)\s*:\s*v\.string\s*\(\s*\)/gi);
+        if (storageIdFields) {
+            for (const fieldMatch of storageIdFields) {
+                const fieldName = fieldMatch.split(":")[0].trim();
+                issues.push({
+                    severity: "info",
+                    location: relativePath,
+                    message: `Field "${fieldName}" uses v.string() but appears to be a storage ID. Use v.id("_storage") for type safety.`,
+                    fix: `Change ${fieldName}: v.string() to ${fieldName}: v.id("_storage")`,
+                });
+            }
+        }
+    }
+    // Check 3: Orphan risk — stores without corresponding deletes
+    if (storageStoreCalls > 0 && storageDeleteCalls === 0) {
+        issues.push({
+            severity: "info",
+            location: "project-wide",
+            message: `${storageStoreCalls} storage.store() calls but 0 storage.delete() calls. Stored files may become orphaned when records are deleted.`,
+            fix: "Add ctx.storage.delete(storageId) when deleting records that reference stored files",
+        });
+    }
+    return {
+        issues,
+        stats: {
+            filesUsingStorage,
+            storageGetCalls,
+            storageGetUrlCalls,
+            storageStoreCalls,
+            storageDeleteCalls,
+            missingNullChecks,
+        },
+    };
+}
+// ── Tool Definition ─────────────────────────────────────────────────
+export const storageAuditTools = [
+    {
+        name: "convex_audit_storage_usage",
+        description: "Audit Convex file storage usage: missing null checks on ctx.storage.get()/getUrl(), storage IDs stored as v.string() instead of v.id('_storage'), and orphaned file risk (store calls without corresponding deletes).",
+        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 } = auditStorageUsage(convexDir);
+            const db = getDb();
+            db.prepare("INSERT INTO audit_results (id, project_dir, audit_type, issues_json, issue_count) VALUES (?, ?, ?, ?, ?)").run(genId("audit"), projectDir, "storage_usage", JSON.stringify(issues), issues.length);
+            return {
+                summary: {
+                    ...stats,
+                    totalIssues: issues.length,
+                },
+                issues: issues.slice(0, 30),
+                quickRef: getQuickRef("convex_audit_storage_usage"),
+            };
+        },
+    },
+];
+//# sourceMappingURL=storageAuditTools.js.map

package/dist/tools/toolRegistry.d.ts

@@ -9,5 +9,9 @@ export declare function findTools(query: string): ScoredToolEntry[];
 /**
  * Async wrapper around findTools that fuses BM25 results with embedding RRF
  * when a neural embedding provider is available. Falls back to plain findTools otherwise.
+ *
+ * Uses Agent-as-a-Graph bipartite RRF (arxiv:2511.18194):
+ * - Tool nodes get direct wRRF with α_T = 1.0
+ * - Domain nodes get stronger wRRF with α_D = 1.5 (paper-optimal, lifts sibling tools in that category)
  */
 export declare function findToolsWithEmbedding(query: string): Promise<ScoredToolEntry[]>;