@homenshum/convex-mcp-nodebench 0.3.0 → 0.4.0

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,133 @@
+/**
+ * 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
+    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.7) {
+        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"];
+    if (vagueAudiences.includes(whoLower)) {
+        score -= 20;
+        feedback.push(`"${input.who}" is too broad. Which user role or API consumer specifically?`);
+    }
+    // Check 3: Too short
+    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?");
+    }
+    // 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/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.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);

package/package.json

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