@homenshum/convex-mcp-nodebench 0.7.0 → 0.9.0

package/dist/tools/toolRegistry.js

@@ -411,6 +411,123 @@ export const REGISTRY = [
         phase: "deploy",
         complexity: "medium",
     },
+    // ── Reporting Tools ─────────────────────
+    {
+        name: "convex_export_sarif",
+        category: "integration",
+        tags: ["sarif", "export", "report", "github", "code-scanning", "ci", "static-analysis"],
+        quickRef: {
+            nextAction: "Upload the SARIF file to GitHub Code Scanning or open in VS Code SARIF Viewer",
+            nextTools: ["convex_audit_diff", "convex_quality_gate"],
+            methodology: "convex_deploy_verification",
+            relatedGotchas: [],
+            confidence: "high",
+        },
+        phase: "deploy",
+        complexity: "low",
+    },
+    {
+        name: "convex_audit_diff",
+        category: "deployment",
+        tags: ["diff", "baseline", "trend", "new-issues", "fixed", "improving", "degrading", "comparison"],
+        quickRef: {
+            nextAction: "Focus on fixing new issues first, then tackle existing ones",
+            nextTools: ["convex_export_sarif", "convex_quality_gate"],
+            methodology: "convex_deploy_verification",
+            relatedGotchas: [],
+            confidence: "high",
+        },
+        phase: "deploy",
+        complexity: "medium",
+    },
+    // ── Vector Search Tools ─────────────────
+    {
+        name: "convex_audit_vector_search",
+        category: "schema",
+        tags: ["vector", "search", "embedding", "dimension", "similarity", "vectorIndex", "float64", "AI", "RAG"],
+        quickRef: {
+            nextAction: "Fix dimension mismatches and add filterFields to vector indexes for better performance",
+            nextTools: ["convex_audit_schema", "convex_suggest_indexes"],
+            methodology: "convex_schema_audit",
+            relatedGotchas: [],
+            confidence: "high",
+        },
+        phase: "audit",
+        complexity: "medium",
+    },
+    // ── Scheduler Tools ─────────────────────
+    {
+        name: "convex_audit_schedulers",
+        category: "function",
+        tags: ["scheduler", "runAfter", "runAt", "schedule", "cron", "infinite-loop", "backoff", "retry", "delayed"],
+        quickRef: {
+            nextAction: "Fix self-scheduling loops (add termination conditions) and implement exponential backoff",
+            nextTools: ["convex_check_crons", "convex_audit_actions"],
+            methodology: "convex_function_compliance",
+            relatedGotchas: [],
+            confidence: "high",
+        },
+        phase: "audit",
+        complexity: "medium",
+    },
+    // ── Quality Gate Tools ──────────────────
+    {
+        name: "convex_quality_gate",
+        category: "deployment",
+        tags: ["quality", "gate", "score", "grade", "threshold", "sonarqube", "metrics", "pass-fail", "A-F"],
+        quickRef: {
+            nextAction: "Fix blockers to raise your grade, then run again to verify improvement",
+            nextTools: ["convex_audit_diff", "convex_export_sarif", "convex_pre_deploy_gate"],
+            methodology: "convex_deploy_verification",
+            relatedGotchas: [],
+            confidence: "high",
+        },
+        phase: "deploy",
+        complexity: "high",
+    },
+    // ── Architect Tools ──────────────────────
+    {
+        name: "convex_scan_capabilities",
+        category: "architect",
+        tags: ["scan", "capabilities", "structure", "patterns", "analysis", "functions", "schema", "data-access", "regex"],
+        quickRef: {
+            nextAction: "Use the capability report to identify what patterns exist before implementing new features",
+            nextTools: ["convex_verify_concept", "convex_generate_plan"],
+            methodology: "convex_schema_audit",
+            relatedGotchas: [],
+            confidence: "high",
+        },
+        phase: "audit",
+        complexity: "low",
+    },
+    {
+        name: "convex_verify_concept",
+        category: "architect",
+        tags: ["verify", "concept", "signatures", "gap-analysis", "implementation", "check", "progress", "regex"],
+        quickRef: {
+            nextAction: "Pass missing signatures to convex_generate_plan to get Convex-specific implementation steps",
+            nextTools: ["convex_generate_plan", "convex_scan_capabilities"],
+            methodology: "convex_schema_audit",
+            relatedGotchas: [],
+            confidence: "high",
+        },
+        phase: "audit",
+        complexity: "low",
+    },
+    {
+        name: "convex_generate_plan",
+        category: "architect",
+        tags: ["plan", "implementation", "strategy", "missing", "signatures", "steps", "inject", "convex-specific"],
+        quickRef: {
+            nextAction: "Implement each step in order, then re-verify with convex_verify_concept to track progress",
+            nextTools: ["convex_verify_concept", "convex_quality_gate"],
+            methodology: "convex_function_compliance",
+            relatedGotchas: [],
+            confidence: "high",
+        },
+        phase: "implement",
+        complexity: "low",
+    },
 ];
 export function getQuickRef(toolName) {
     const entry = REGISTRY.find((e) => e.name === toolName);

package/dist/tools/vectorSearchTools.d.ts

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

package/dist/tools/vectorSearchTools.js

@@ -0,0 +1,192 @@
+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;
+}
+// Common embedding model dimensions
+const KNOWN_DIMENSIONS = {
+    384: "all-MiniLM-L6-v2",
+    512: "e5-small",
+    768: "text-embedding-004 / all-mpnet-base-v2",
+    1024: "e5-large / cohere-embed-v3",
+    1536: "text-embedding-3-small / text-embedding-ada-002",
+    3072: "text-embedding-3-large",
+};
+function auditVectorSearch(convexDir) {
+    const issues = [];
+    const schemaPath = join(convexDir, "schema.ts");
+    // Parse schema for vectorIndex definitions
+    const vectorIndexes = [];
+    if (existsSync(schemaPath)) {
+        const schema = readFileSync(schemaPath, "utf-8");
+        const lines = schema.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            // Match .vectorIndex("name", { ... })
+            const viMatch = lines[i].match(/\.vectorIndex\s*\(\s*["']([^"']+)["']/);
+            if (viMatch) {
+                // Look ahead for dimensions and filterFields
+                const chunk = lines.slice(i, Math.min(i + 10, lines.length)).join("\n");
+                const dimMatch = chunk.match(/dimensions\s*:\s*(\d+)/);
+                const filterMatch = chunk.match(/filterFields\s*:\s*\[([^\]]*)\]/);
+                const dims = dimMatch ? parseInt(dimMatch[1], 10) : 0;
+                const filters = filterMatch
+                    ? filterMatch[1].match(/["']([^"']+)["']/g)?.map(s => s.replace(/["']/g, "")) ?? []
+                    : [];
+                vectorIndexes.push({ table: viMatch[1], dimensions: dims, filterFields: filters, line: i + 1 });
+                // Check: uncommon dimension size
+                if (dims > 0 && !KNOWN_DIMENSIONS[dims]) {
+                    const nearest = Object.keys(KNOWN_DIMENSIONS)
+                        .map(Number)
+                        .sort((a, b) => Math.abs(a - dims) - Math.abs(b - dims))[0];
+                    issues.push({
+                        severity: "warning",
+                        location: `schema.ts:${i + 1}`,
+                        message: `Vector index "${viMatch[1]}" has ${dims} dimensions — not a standard embedding size. Did you mean ${nearest} (${KNOWN_DIMENSIONS[nearest]})?`,
+                        fix: `Verify your embedding model output size matches ${dims} dimensions`,
+                    });
+                }
+                // Check: no filter fields
+                if (filters.length === 0) {
+                    issues.push({
+                        severity: "info",
+                        location: `schema.ts:${i + 1}`,
+                        message: `Vector index "${viMatch[1]}" has no filterFields. Vector searches will scan all vectors — add filters for better performance.`,
+                        fix: 'Add filterFields: ["field1", "field2"] to narrow vector search scope',
+                    });
+                }
+            }
+            // Check: vector field declared as v.array(v.number()) instead of v.array(v.float64())
+            if (/v\.array\s*\(\s*v\.number\s*\(\s*\)\s*\)/.test(lines[i]) &&
+                /embed|vector|embedding/i.test(lines.slice(Math.max(0, i - 3), i + 1).join("\n"))) {
+                issues.push({
+                    severity: "warning",
+                    location: `schema.ts:${i + 1}`,
+                    message: "Vector field uses v.array(v.number()) — Convex vector search requires v.array(v.float64()) for proper storage.",
+                    fix: "Change to v.array(v.float64()) for vector fields",
+                });
+            }
+        }
+    }
+    // Scan code files for .vectorSearch() usage
+    const files = collectTsFiles(convexDir);
+    let vectorSearchCallCount = 0;
+    for (const filePath of files) {
+        const content = readFileSync(filePath, "utf-8");
+        const relativePath = filePath.replace(convexDir, "").replace(/^[\\/]/, "");
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const vsMatch = lines[i].match(/\.vectorSearch\s*\(\s*["']([^"']+)["']/);
+            if (vsMatch) {
+                vectorSearchCallCount++;
+                const indexName = vsMatch[1];
+                // Check if the referenced index exists
+                const matchingIdx = vectorIndexes.find(vi => vi.table === indexName);
+                if (!matchingIdx && vectorIndexes.length > 0) {
+                    issues.push({
+                        severity: "critical",
+                        location: `${relativePath}:${i + 1}`,
+                        message: `vectorSearch references index "${indexName}" which is not defined in schema.ts.`,
+                        fix: `Add a .vectorIndex("${indexName}", { ... }) to the appropriate table in schema.ts`,
+                    });
+                }
+                // Check: no filter parameter when filterFields exist
+                const chunk = lines.slice(i, Math.min(i + 5, lines.length)).join("\n");
+                if (matchingIdx && matchingIdx.filterFields.length > 0 && !/filter\s*:/.test(chunk)) {
+                    issues.push({
+                        severity: "info",
+                        location: `${relativePath}:${i + 1}`,
+                        message: `vectorSearch on "${indexName}" doesn't use filter — available filterFields: ${matchingIdx.filterFields.join(", ")}`,
+                        fix: "Add filter parameter to narrow results and improve performance",
+                    });
+                }
+                // Check: hardcoded vector dimensions in code (should match schema)
+                const vecLiteralMatch = chunk.match(/new\s+Float64Array\s*\(\s*(\d+)\s*\)|Array\s*\(\s*(\d+)\s*\)\.fill/);
+                if (vecLiteralMatch && matchingIdx) {
+                    const codeDims = parseInt(vecLiteralMatch[1] || vecLiteralMatch[2], 10);
+                    if (codeDims !== matchingIdx.dimensions && matchingIdx.dimensions > 0) {
+                        issues.push({
+                            severity: "critical",
+                            location: `${relativePath}:${i + 1}`,
+                            message: `Vector dimensions mismatch: code uses ${codeDims} but schema defines ${matchingIdx.dimensions} for index "${indexName}".`,
+                            fix: `Ensure embedding model output (${codeDims}) matches schema dimensions (${matchingIdx.dimensions})`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    const tablesWithVectors = [...new Set(vectorIndexes.map(vi => vi.table))];
+    const dimensions = [...new Set(vectorIndexes.map(vi => vi.dimensions).filter(d => d > 0))];
+    return {
+        issues,
+        stats: {
+            vectorIndexCount: vectorIndexes.length,
+            vectorSearchCallCount,
+            tablesWithVectors,
+            dimensions,
+        },
+    };
+}
+// ── Tool Definition ─────────────────────────────────────────────────
+export const vectorSearchTools = [
+    {
+        name: "convex_audit_vector_search",
+        description: "Audit Convex vector search implementation: validates vectorIndex dimensions against known embedding models, checks for missing filterFields, v.array(v.float64()) usage, dimension mismatches between schema and code, and undefined index references.",
+        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 } = auditVectorSearch(convexDir);
+            const db = getDb();
+            db.prepare("INSERT INTO audit_results (id, project_dir, audit_type, issues_json, issue_count) VALUES (?, ?, ?, ?, ?)").run(genId("audit"), projectDir, "vector_search", 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,
+                    knownDimensions: KNOWN_DIMENSIONS,
+                },
+                issues: issues.slice(0, 30),
+                quickRef: getQuickRef("convex_audit_vector_search"),
+            };
+        },
+    },
+];
+//# sourceMappingURL=vectorSearchTools.js.map

package/dist/types.d.ts

@@ -13,7 +13,7 @@ export interface ConvexQuickRef {
 }
 export interface ToolRegistryEntry {
     name: string;
-    category: "schema" | "function" | "deployment" | "learning" | "methodology" | "integration";
+    category: "schema" | "function" | "deployment" | "learning" | "methodology" | "integration" | "architect";
     tags: string[];
     quickRef: ConvexQuickRef;
     phase: "audit" | "implement" | "test" | "deploy" | "learn" | "meta";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homenshum/convex-mcp-nodebench",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Convex-specific MCP server applying NodeBench self-instruct diligence patterns to Convex development. Schema audit, function compliance, deployment gates, persistent gotcha DB, and methodology guidance. Complements Context7 (raw docs) and official Convex MCP (deployment introspection) with structured verification workflows.",
   "type": "module",
   "bin": {