@homenshum/convex-mcp-nodebench 0.3.0 → 0.4.1

package/dist/index.js

@@ -25,6 +25,7 @@ import { integrationBridgeTools } from "./tools/integrationBridgeTools.js";
 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 { CONVEX_GOTCHAS } from "./gotchaSeed.js";
 import { REGISTRY } from "./tools/toolRegistry.js";
 import { initEmbeddingIndex } from "./tools/embeddingProvider.js";
@@ -39,6 +40,7 @@ const ALL_TOOLS = [
     ...cronTools,
     ...componentTools,
     ...httpTools,
+    ...critterTools,
 ];
 const toolMap = new Map();
 for (const tool of ALL_TOOLS) {

package/dist/tools/critterTools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Critter Tools — The accountability partner that wants to know everything.
+ *
+ * Convex-flavored version: "Why are you making this schema change? Who needs this function?"
+ * The friction is the feature — slowing down to think prevents Convex-specific pitfalls
+ * like unnecessary indexes, over-normalized schemas, and functions nobody calls.
+ *
+ * 1 tool:
+ * - convex_critter_check: Pre-action intentionality check for Convex work
+ */
+import type { McpTool } from "../types.js";
+export declare const critterTools: McpTool[];

package/dist/tools/critterTools.js

@@ -0,0 +1,204 @@
+/**
+ * Critter Tools — The accountability partner that wants to know everything.
+ *
+ * Convex-flavored version: "Why are you making this schema change? Who needs this function?"
+ * The friction is the feature — slowing down to think prevents Convex-specific pitfalls
+ * like unnecessary indexes, over-normalized schemas, and functions nobody calls.
+ *
+ * 1 tool:
+ * - convex_critter_check: Pre-action intentionality check for Convex work
+ */
+import { getDb } from "../db.js";
+// ── DB setup ────────────────────────────────────────────────────────────────
+function ensureCritterTable() {
+    const db = getDb();
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS critter_checks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      task TEXT NOT NULL,
+      why TEXT NOT NULL,
+      who TEXT NOT NULL,
+      success_looks_like TEXT,
+      score INTEGER NOT NULL,
+      verdict TEXT NOT NULL,
+      feedback TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+}
+function scoreCritterCheck(input) {
+    const feedback = [];
+    let score = 100;
+    const taskLower = input.task.toLowerCase().trim();
+    const whyLower = input.why.toLowerCase().trim();
+    const whoLower = input.who.toLowerCase().trim();
+    // Check 1: Circular reasoning (threshold 0.5)
+    const taskWords = new Set(taskLower.split(/\s+/).filter((w) => w.length > 3));
+    const whyWords = whyLower.split(/\s+/).filter((w) => w.length > 3);
+    const overlap = whyWords.filter((w) => taskWords.has(w));
+    if (whyWords.length > 0 && overlap.length / whyWords.length > 0.5) {
+        score -= 30;
+        feedback.push("Circular: your 'why' mostly restates the task. What user outcome does this enable?");
+    }
+    // Check 2: Vague audience
+    const vagueAudiences = ["users", "everyone", "people", "the team", "stakeholders", "clients", "customers", "developers"];
+    if (vagueAudiences.includes(whoLower)) {
+        score -= 20;
+        feedback.push(`"${input.who}" is too broad. Which user role or API consumer specifically?`);
+    }
+    // Check 3: Empty or too short
+    if (whyLower.length === 0) {
+        score -= 40;
+        feedback.push("Empty 'why': you haven't stated any purpose at all.");
+    }
+    else if (whyLower.length < 10) {
+        score -= 25;
+        feedback.push("The 'why' is too short. What problem does this solve?");
+    }
+    if (whoLower.length < 3) {
+        score -= 25;
+        feedback.push("The 'who' is too short. Specify who benefits.");
+    }
+    // Check 4: Deference over understanding
+    const deferPatterns = ["was told", "asked to", "ticket says", "was asked", "jira", "they said"];
+    if (deferPatterns.some((p) => whyLower.includes(p))) {
+        score -= 15;
+        feedback.push("Citing authority instead of understanding purpose. Why does this matter to the product?");
+    }
+    // Check 5: Non-answer patterns (count matches, -20 each, cap -40)
+    const nonAnswerPatterns = [
+        "just because", "don't know", "not sure", "why not", "might need it",
+        "no reason", "no idea", "whatever", "idk", "tbd",
+    ];
+    const nonAnswerHits = nonAnswerPatterns.filter((p) => whyLower.includes(p)).length;
+    if (nonAnswerHits > 0) {
+        const nonAnswerPenalty = Math.min(nonAnswerHits * 20, 40);
+        score -= nonAnswerPenalty;
+        feedback.push("Non-answer: your 'why' signals unclear purpose. What specific problem does this solve?");
+    }
+    // Check 6: Repetitive padding (why + who)
+    const whyAllWords = whyLower.split(/\s+/).filter((w) => w.length > 2);
+    if (whyAllWords.length >= 5) {
+        const whyUniqueWords = new Set(whyAllWords);
+        if (whyUniqueWords.size / whyAllWords.length < 0.4) {
+            score -= 25;
+            feedback.push("Repetitive: your 'why' repeats the same words. Articulate distinct reasoning.");
+        }
+    }
+    const whoAllWords = whoLower.split(/\s+/).filter((w) => w.length > 2);
+    if (whoAllWords.length >= 5) {
+        const whoUniqueWords = new Set(whoAllWords);
+        if (whoUniqueWords.size / whoAllWords.length < 0.4) {
+            score -= 25;
+            feedback.push("Repetitive: your 'who' repeats the same words. Name a real audience.");
+        }
+    }
+    // Check 7: Buzzword-heavy corporate-speak (scans why + who)
+    const buzzwords = [
+        "leverage", "synergies", "synergy", "paradigm", "holistic", "alignment",
+        "transformation", "innovative", "disruptive", "best practices",
+        "streamline", "ecosystem", "actionable", "circle back",
+    ];
+    const allText = `${whyLower} ${whoLower}`;
+    const buzzCount = buzzwords.filter((b) => allText.includes(b)).length;
+    if (buzzCount >= 4) {
+        score -= 35;
+        feedback.push("Buzzword-heavy: corporate-speak without concrete meaning. What specific problem does this solve?");
+    }
+    else if (buzzCount >= 3) {
+        score -= 30;
+        feedback.push("Buzzword-heavy: corporate-speak without concrete meaning. What specific problem does this solve?");
+    }
+    else if (buzzCount >= 2) {
+        score -= 20;
+        feedback.push("Buzzword-heavy: corporate-speak without concrete meaning. What specific problem does this solve?");
+    }
+    // Check 8: Hedging language
+    const hedgeWords = ["could", "potentially", "maybe", "possibly", "might", "perhaps", "hopefully"];
+    const hedgeCount = hedgeWords.filter((h) => {
+        const regex = new RegExp(`\\b${h}\\b`, "i");
+        return regex.test(whyLower);
+    }).length;
+    if (hedgeCount >= 2) {
+        score -= 15;
+        feedback.push("Hedging: too many 'could/maybe/potentially' signals uncertain value. Be definitive.");
+    }
+    // Check 9: Task-word echo — same word from task repeated 3+ times in why
+    for (const tw of taskWords) {
+        const twCount = whyWords.filter((w) => w === tw).length;
+        if (twCount >= 3) {
+            score -= 20;
+            feedback.push(`Echo: "${tw}" appears ${twCount} times in your 'why' — this is filler, not reasoning.`);
+            break;
+        }
+    }
+    // Bonus for specificity
+    if (input.success_looks_like && input.success_looks_like.length > 20) {
+        score += 10;
+        feedback.push("Good: success criteria defined — this makes the deploy gate concrete.");
+    }
+    score = Math.max(0, Math.min(100, score));
+    let verdict;
+    if (score >= 70) {
+        verdict = "proceed";
+        if (feedback.length === 0) {
+            feedback.push("Clear intent. Proceed with confidence.");
+        }
+    }
+    else if (score >= 40) {
+        verdict = "reconsider";
+        feedback.push("Pause. Sharpen your answers before writing Convex code.");
+    }
+    else {
+        verdict = "stop";
+        feedback.push("Stop: purpose unclear. Do not proceed.");
+    }
+    return { score, verdict, feedback };
+}
+// ── Tool definition ─────────────────────────────────────────────────────────
+export const critterTools = [
+    {
+        name: "convex_critter_check",
+        description: "The accountability partner that wants to know everything — answer 'Why are you doing this? Who is it for?' before starting Convex work. " +
+            "Scores for circular reasoning, vague audiences, and deference-over-understanding. " +
+            "The friction is the feature: slowing down prevents unnecessary schema changes, unneeded indexes, and functions nobody calls.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                task: {
+                    type: "string",
+                    description: "What you are about to do (e.g. 'Add a new table for user preferences')",
+                },
+                why: {
+                    type: "string",
+                    description: "Why are you doing this? What user problem does it solve?",
+                },
+                who: {
+                    type: "string",
+                    description: "Who is this for? Name a specific role, persona, or API consumer.",
+                },
+                success_looks_like: {
+                    type: "string",
+                    description: "Optional: What does success look like? How will you verify this worked?",
+                },
+            },
+            required: ["task", "why", "who"],
+        },
+        handler: async (args) => {
+            ensureCritterTable();
+            const result = scoreCritterCheck(args);
+            const db = getDb();
+            db.prepare(`INSERT INTO critter_checks (task, why, who, success_looks_like, score, verdict, feedback)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`).run(args.task, args.why, args.who, args.success_looks_like ?? null, result.score, result.verdict, JSON.stringify(result.feedback));
+            return {
+                score: result.score,
+                verdict: result.verdict,
+                feedback: result.feedback,
+                tip: result.verdict === "proceed"
+                    ? "Critter check passed. Proceed with clear intent."
+                    : "Sharpen your answers and re-run convex_critter_check.",
+            };
+        },
+    },
+];
+//# sourceMappingURL=critterTools.js.map

package/dist/tools/functionTools.js

@@ -147,14 +147,33 @@ function auditFunctions(convexDir) {
         }
     }
     // Check 4: Cross-call violations — queries CANNOT call runMutation or runAction
+    // Use brace-depth tracking to find exact function boundaries (avoids false positives)
     for (const fn of functions) {
         if (fn.type !== "query" && fn.type !== "internalQuery")
             continue;
         const content = readFileSync(fn.filePath, "utf-8");
         const lines = content.split("\n");
-        // Find the function body (rough: from export line to next export or end)
         const startLine = fn.line - 1;
-        const chunk = lines.slice(startLine, Math.min(startLine + 80, lines.length)).join("\n");
+        // Find the function body by tracking brace depth from the opening ({
+        // The pattern is: export const X = query({ ... });
+        let depth = 0;
+        let foundOpen = false;
+        let endLine = Math.min(startLine + 80, lines.length);
+        for (let i = startLine; i < lines.length; i++) {
+            for (const ch of lines[i]) {
+                if (ch === "{") {
+                    depth++;
+                    foundOpen = true;
+                }
+                if (ch === "}")
+                    depth--;
+            }
+            if (foundOpen && depth <= 0) {
+                endLine = i + 1;
+                break;
+            }
+        }
+        const chunk = lines.slice(startLine, endLine).join("\n");
         if (/ctx\.runMutation/.test(chunk)) {
             issues.push({
                 severity: "critical",

package/dist/tools/integrationBridgeTools.js

@@ -235,9 +235,13 @@ export const integrationBridgeTools = [
                 }
                 catch { /* ignore */ }
             }
+            const parsed = JSON.parse(snapshot.schemaJson);
             return {
                 snapshotId: id,
                 tableCount: snapshot.tableCount,
+                tables: parsed.tables,
+                totalIndexes: parsed.totalIndexes,
+                indexes: parsed.indexes,
                 diff,
                 quickRef: getQuickRef("convex_audit_schema"),
             };

package/dist/tools/methodologyTools.js

@@ -108,7 +108,13 @@ export const methodologyTools = [
             required: ["topic"],
         },
         handler: async (args) => {
-            const content = METHODOLOGY_CONTENT[args.topic];
+            // Default to overview when topic is missing
+            let topic = args.topic || "overview";
+            // Accept short names: "schema_audit" -> "convex_schema_audit"
+            if (!METHODOLOGY_CONTENT[topic] && METHODOLOGY_CONTENT[`convex_${topic}`]) {
+                topic = `convex_${topic}`;
+            }
+            const content = METHODOLOGY_CONTENT[topic];
             if (!content) {
                 return {
                     error: `Unknown topic: ${args.topic}`,
@@ -149,6 +155,7 @@ export const methodologyTools = [
                 matchingTools: results.length,
                 tools: results.map((r) => ({
                     name: r.name,
+                    score: Math.round(r._score * 100) / 100,
                     category: r.category,
                     phase: r.phase,
                     complexity: r.complexity,

package/dist/tools/schemaTools.js

@@ -120,20 +120,26 @@ function analyzeSchema(schemaContent, filePath) {
             gotchaKey: "index_name_include_fields",
         });
     }
-    // Check: v.any() usage (defeats validator purpose)
+    // Check: v.any() usage (defeats validator purpose) — aggregate
+    const vAnyLines = [];
     lines.forEach((line, i) => {
         if (line.trim().startsWith("//") || line.trim().startsWith("*"))
             return;
         if (/v\.any\s*\(\s*\)/.test(line)) {
-            issues.push({
-                severity: "warning",
-                location: `${filePath}:${i + 1}`,
-                message: "v.any() defeats the purpose of validators. Use a specific validator type.",
-                fix: "Replace v.any() with the appropriate validator (v.string(), v.object({...}), etc.)",
-                gotchaKey: "avoid_v_any",
-            });
+            vAnyLines.push(i + 1);
         }
     });
+    if (vAnyLines.length > 0) {
+        const examples = vAnyLines.slice(0, 5).map((l) => `line ${l}`).join(", ");
+        const more = vAnyLines.length > 5 ? ` (+${vAnyLines.length - 5} more)` : "";
+        issues.push({
+            severity: "warning",
+            location: filePath,
+            message: `${vAnyLines.length} uses of v.any() defeat the purpose of validators. Locations: ${examples}${more}`,
+            fix: "Replace v.any() with specific validators (v.string(), v.object({...}), v.union(...), etc.)",
+            gotchaKey: "avoid_v_any",
+        });
+    }
     // Check: _creationTime or _id in schema definition (system fields)
     lines.forEach((line, i) => {
         if (line.trim().startsWith("//") || line.trim().startsWith("*"))

package/dist/tools/toolRegistry.d.ts

@@ -2,9 +2,12 @@ import type { ConvexQuickRef, ToolRegistryEntry } from "../types.js";
 export declare const REGISTRY: ToolRegistryEntry[];
 export declare function getQuickRef(toolName: string): ConvexQuickRef | null;
 export declare function getToolsByCategory(category: string): ToolRegistryEntry[];
-export declare function findTools(query: string): ToolRegistryEntry[];
+export interface ScoredToolEntry extends ToolRegistryEntry {
+    _score: number;
+}
+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.
  */
-export declare function findToolsWithEmbedding(query: string): Promise<ToolRegistryEntry[]>;
+export declare function findToolsWithEmbedding(query: string): Promise<ScoredToolEntry[]>;

package/dist/tools/toolRegistry.js

@@ -246,6 +246,21 @@ export const REGISTRY = [
         phase: "audit",
         complexity: "low",
     },
+    // ── Critter Tools ──────────────────────────
+    {
+        name: "convex_critter_check",
+        category: "methodology",
+        tags: ["intentionality", "why", "who", "purpose", "audience", "reflection", "pre-action", "critter"],
+        quickRef: {
+            nextAction: "Critter check done. If verdict is 'proceed', start your Convex work. If 'reconsider', sharpen answers.",
+            nextTools: ["convex_audit_schema", "convex_audit_functions", "convex_search_gotchas"],
+            methodology: "convex_intentionality",
+            relatedGotchas: [],
+            confidence: "high",
+        },
+        phase: "meta",
+        complexity: "low",
+    },
 ];
 export function getQuickRef(toolName) {
     const entry = REGISTRY.find((e) => e.name === toolName);
@@ -314,12 +329,11 @@ export function findTools(query) {
             const termIdf = index.idf.get(qt) ?? 0;
             score += termIdf * (termTf * (k1 + 1)) / (termTf + k1 * (1 - b + b * (dl / index.avgDl)));
         }
-        return { entry, score };
+        return { ...entry, _score: score };
     });
     return scored
-        .filter((s) => s.score > 0)
-        .sort((a, b) => b.score - a.score)
-        .map((s) => s.entry);
+        .filter((s) => s._score > 0)
+        .sort((a, b) => b._score - a._score);
 }
 /**
  * Async wrapper around findTools that fuses BM25 results with embedding RRF
@@ -360,6 +374,7 @@ export async function findToolsWithEmbedding(query) {
     }
     return [...allEntries.values()]
         .filter((e) => fusedScores.has(e.name))
-        .sort((a, b) => (fusedScores.get(b.name) ?? 0) - (fusedScores.get(a.name) ?? 0));
+        .sort((a, b) => (fusedScores.get(b.name) ?? 0) - (fusedScores.get(a.name) ?? 0))
+        .map((e) => ({ ...e, _score: fusedScores.get(e.name) ?? 0 }));
 }
 //# sourceMappingURL=toolRegistry.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homenshum/convex-mcp-nodebench",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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": {