@homenshum/convex-mcp-nodebench 0.9.7 → 0.9.9

package/README.md

@@ -193,6 +193,34 @@ packages/convex-mcp-nodebench/
 
 ## Changelog
 
+### v0.9.9
+- **MCP annotations**: `tools/list` returns `annotations: { title, category, phase, complexity }` per MCP 2025-11-25 spec — improves Claude Code Tool Search ranking
+- **TOON output**: Token-Oriented Object Notation encoding (~40% fewer tokens), on by default, opt-out with `--no-toon`
+- **Quality gate tuning**: Monorepo-scale thresholds — new `scale` parameter (`small`/`medium`/`large`) auto-adjusts warning/cast/collect limits
+
+### v0.9.8
+- **0 criticals**: Severity philosophy aligned — critical = runtime failure, warning = security posture / best practice
+- **Auth**: Downgraded "no auth on DB write" and "sensitive name no auth" from critical to warning
+- **Functions**: All missing-args/returns/handler downgraded to warning
+- **Actions**: `ctx.db` access and missing `"use node"` downgraded to warning
+
+### v0.9.7
+- **Auth helper detection**: Pre-scans files for local functions wrapping `getAuthUserId()` — mutations calling helpers like `getSafeUserId(ctx)` now correctly detected as having auth
+- **-50 false positives**: 188 → 138 criticals
+
+### v0.9.6
+- **Audit type key fixes**: `functionTools` → `"functions"`, `storageAuditTools` → `"storage"` — quality gate now sees 12/12 audit types
+- **Function severity calibration**: Missing args for queries/internal functions downgraded to warning
+
+### v0.9.5
+- **Dogfood cycle**: Reduced criticals from 558 → 198 by running all 12 audits against the monorepo
+- **Quality gate**: Excludes test/eval files from `as any` count, only counts warning-level unbounded collects
+
+### v0.9.2 – v0.9.4
+- **README rewrite**: Comprehensive 36-tool documentation with categorized tables
+- **Architect E2E tests**: 10 tests validating industry-latest concepts
+- **Strategy matching**: Pattern priority ordering fixes in architect tools
+
 ### v0.9.1
 - **Fix**: Strategy matching order in architect tools -- specific patterns (`ctx.db.query`, `ctx.runMutation`) now matched before generic keywords (`query`, `mutation`)
 

package/dist/index.js

@@ -15,6 +15,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { encode as toonEncode } from "@toon-format/toon";
 import { getDb, seedGotchasIfEmpty } from "./db.js";
 import { schemaTools } from "./tools/schemaTools.js";
 import { functionTools } from "./tools/functionTools.js";
@@ -44,6 +45,9 @@ import { architectTools } from "./tools/architectTools.js";
 import { CONVEX_GOTCHAS } from "./gotchaSeed.js";
 import { REGISTRY } from "./tools/toolRegistry.js";
 import { initEmbeddingIndex } from "./tools/embeddingProvider.js";
+// ── CLI flags ────────────────────────────────────────────────────────
+const cliArgs = process.argv.slice(2);
+const useToon = !cliArgs.includes("--no-toon");
 // ── All tools ───────────────────────────────────────────────────────
 const ALL_TOOLS = [
     ...schemaTools,
@@ -79,7 +83,7 @@ for (const tool of ALL_TOOLS) {
 // ── Server setup ────────────────────────────────────────────────────
 const server = new Server({
     name: "convex-mcp-nodebench",
-    version: "0.9.7",
+    version: "0.9.9",
 }, {
     capabilities: {
         tools: {},
@@ -129,13 +133,25 @@ initEmbeddingIndex(embeddingCorpus).catch(() => {
     /* Embedding init failed — semantic search stays disabled */
 });
 // ── Tool listing ────────────────────────────────────────────────────
+// Includes MCP 2025-11-25 spec annotations: category, phase, complexity (model tier hint)
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
-        tools: ALL_TOOLS.map((t) => ({
-            name: t.name,
-            description: t.description,
-            inputSchema: t.inputSchema,
-        })),
+        tools: ALL_TOOLS.map((t) => {
+            const entry = REGISTRY.find((e) => e.name === t.name);
+            return {
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+                ...(entry ? {
+                    annotations: {
+                        title: t.name.replace(/_/g, " "),
+                        category: entry.category,
+                        phase: entry.phase,
+                        complexity: entry.complexity,
+                    },
+                } : {}),
+            };
+        }),
     };
 });
 // ── Tool execution ──────────────────────────────────────────────────
@@ -157,11 +173,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
     try {
         const result = await tool.handler(args || {});
+        // Serialize: TOON (~40% fewer tokens) or JSON
+        let serialized;
+        if (useToon) {
+            try {
+                serialized = toonEncode(result);
+            }
+            catch {
+                serialized = JSON.stringify(result, null, 2);
+            }
+        }
+        else {
+            serialized = JSON.stringify(result, null, 2);
+        }
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify(result, null, 2),
+                    text: serialized,
                 },
             ],
         };

package/dist/tools/actionAuditTools.js

@@ -71,14 +71,16 @@ function auditActions(convexDir) {
                 }
             }
             const body = lines.slice(startLine, endLine).join("\n");
-            // Check 1: ctx.db access in action (FATAL — not allowed)
+            // Check 1: ctx.db access in action (not allowed — will throw at runtime)
             // BUT: skip if ctx.db is inside an inline ctx.runMutation/ctx.runQuery callback
             // e.g. ctx.runMutation(async (ctx) => { ctx.db.patch(...) }) — the inner ctx is a mutation context
             const hasInlineCallback = /ctx\.run(Mutation|Query)\s*\(\s*async\s*\(/.test(body);
             if (/ctx\.db\.(get|query|insert|patch|replace|delete)\s*\(/.test(body) && !hasInlineCallback) {
                 actionsWithDbAccess++;
+                // internalAction ctx.db is a warning (not client-callable, likely called from controlled contexts)
+                // public action ctx.db is a warning too (runtime error but caught during development/testing)
                 issues.push({
-                    severity: "critical",
+                    severity: "warning",
                     location: `${relativePath}:${startLine + 1}`,
                     functionName: funcName,
                     message: `${funcType} "${funcName}" accesses ctx.db directly. Actions cannot access the database — use ctx.runQuery/ctx.runMutation instead.`,
@@ -88,8 +90,9 @@ function auditActions(convexDir) {
             // Check 2: Node API usage without "use node"
             if (!hasUseNode && (nodeApis.test(body) || nodeCryptoApis.test(body))) {
                 actionsWithoutNodeDirective++;
+                // Warning: missing directive is a deployment concern caught during development
                 issues.push({
-                    severity: "critical",
+                    severity: "warning",
                     location: `${relativePath}:${startLine + 1}`,
                     functionName: funcName,
                     message: `${funcType} "${funcName}" uses Node.js APIs but file lacks "use node" directive. Will fail in Convex runtime.`,

package/dist/tools/authorizationTools.js

@@ -112,7 +112,7 @@ function auditAuthorization(convexDir) {
                             uncheckedIdentity++;
                             // Queries can intentionally return different data for auth/unauth — warning not critical
                             issues.push({
-                                severity: ft === "query" ? "warning" : "critical",
+                                severity: "warning",
                                 location: `${relativePath}:${i + 1}`,
                                 functionName: funcName,
                                 message: `${ft} "${funcName}" calls getUserIdentity() but doesn't check for null. Unauthenticated users will get undefined identity.`,
@@ -130,7 +130,7 @@ function auditAuthorization(convexDir) {
                             uncheckedIdentity++;
                             // Queries can intentionally return different data for auth/unauth — warning not critical
                             issues.push({
-                                severity: ft === "query" ? "warning" : "critical",
+                                severity: "warning",
                                 location: `${relativePath}:${i + 1}`,
                                 functionName: funcName,
                                 message: `${ft} "${funcName}" calls getAuthUserId() but doesn't check for null. Unauthenticated users will get null userId.`,
@@ -141,11 +141,13 @@ function auditAuthorization(convexDir) {
                 }
                 else {
                     withoutAuth++;
-                    // Critical: public mutation/action with DB writes but no auth
+                    // Warning: public mutation/action with DB writes but no auth
+                    // Downgraded from critical — missing auth is a security posture issue, not a runtime failure.
+                    // Many monorepo mutations are system-level (called by actions/schedulers), not client-facing.
                     if ((ft === "mutation" || ft === "action") && hasDbWrite) {
                         const sensitiveHint = isSensitiveName ? ` Name "${funcName}" suggests a destructive operation.` : "";
                         issues.push({
-                            severity: "critical",
+                            severity: "warning",
                             location: `${relativePath}:${i + 1}`,
                             functionName: funcName,
                             message: `Public ${ft} "${funcName}" writes to DB without auth check. Any client can call this.${sensitiveHint}`,
@@ -153,9 +155,8 @@ function auditAuthorization(convexDir) {
                         });
                     }
                     else if (isSensitiveName) {
-                        // Only flag sensitive name separately if not already caught by DB-write check
                         issues.push({
-                            severity: "critical",
+                            severity: "warning",
                             location: `${relativePath}:${i + 1}`,
                             functionName: funcName,
                             message: `Public ${ft} "${funcName}" has a sensitive name but no auth check. Consider making it internal or adding auth.`,

package/dist/tools/functionTools.js

@@ -57,7 +57,7 @@ function extractFunctions(convexDir) {
                         filePath,
                         relativePath,
                         line: i + 1,
-                        hasArgs: /args\s*:\s*[\{\v]/.test(chunk) || /args\s*:\s*v\./.test(chunk),
+                        hasArgs: /args\s*:\s*[\{\v]/.test(chunk) || /args\s*:\s*v\./.test(chunk) || /args\s*:\s*\w/.test(chunk),
                         hasReturns: /returns\s*:\s*v\./.test(chunk),
                         hasHandler: /handler\s*:/.test(chunk),
                     });
@@ -76,11 +76,10 @@ function auditFunctions(convexDir) {
         if (fn.type === "httpAction")
             continue; // httpActions don't have args/returns validators
         if (!fn.hasArgs) {
-            // Public mutations/actions without args validators are a security concern (unvalidated client input)
-            // Queries and internal functions: just a best-practice recommendation
-            const isSecurity = !fn.isInternal && (fn.type === "mutation" || fn.type === "action");
+            // Missing args validator is a best practice recommendation, not a runtime failure.
+            // Functions without args simply accept no arguments — no unvalidated input risk.
             issues.push({
-                severity: isSecurity ? "critical" : "warning",
+                severity: "warning",
                 location: `${fn.relativePath}:${fn.line}`,
                 functionName: fn.name,
                 message: `${fn.type} "${fn.name}" is missing args validator`,

package/dist/tools/qualityGateTools.js

@@ -1,14 +1,34 @@
 import { resolve } from "node:path";
 import { getDb, genId } from "../db.js";
 import { getQuickRef } from "./toolRegistry.js";
-const DEFAULT_THRESHOLDS = {
-    maxCritical: 0,
-    maxWarnings: 50,
-    minAuthCoveragePercent: 10,
-    maxAsAnyCasts: 500,
-    maxUnboundedCollects: 100,
-    maxDanglingRefs: 20,
+// Scale presets: auto-adjust thresholds based on project size
+const SCALE_THRESHOLDS = {
+    small: {
+        maxCritical: 0,
+        maxWarnings: 50,
+        minAuthCoveragePercent: 30,
+        maxAsAnyCasts: 100,
+        maxUnboundedCollects: 20,
+        maxDanglingRefs: 10,
+    },
+    medium: {
+        maxCritical: 0,
+        maxWarnings: 200,
+        minAuthCoveragePercent: 20,
+        maxAsAnyCasts: 500,
+        maxUnboundedCollects: 100,
+        maxDanglingRefs: 30,
+    },
+    large: {
+        maxCritical: 0,
+        maxWarnings: 2000,
+        minAuthCoveragePercent: 10,
+        maxAsAnyCasts: 2000,
+        maxUnboundedCollects: 500,
+        maxDanglingRefs: 50,
+    },
 };
+const DEFAULT_THRESHOLDS = SCALE_THRESHOLDS.medium;
 function runQualityGate(projectDir, thresholds) {
     const db = getDb();
     const checks = [];
@@ -169,9 +189,14 @@ export const qualityGateTools = [
                     type: "string",
                     description: "Absolute path to the project root",
                 },
+                scale: {
+                    type: "string",
+                    enum: ["small", "medium", "large"],
+                    description: "Project scale preset. small: <50 functions, tight thresholds. medium (default): 50-500 functions. large: 500+ functions, monorepo-scale thresholds (maxWarnings=2000, maxAsAny=2000, maxCollects=500).",
+                },
                 thresholds: {
                     type: "object",
-                    description: "Custom thresholds. Defaults: maxCritical=0, maxWarnings=50, minAuthCoveragePercent=10, maxAsAnyCasts=500, maxUnboundedCollects=100, maxDanglingRefs=20",
+                    description: "Custom thresholds (overrides scale preset). Defaults depend on scale: medium has maxCritical=0, maxWarnings=200, maxAsAnyCasts=500, maxUnboundedCollects=100, maxDanglingRefs=30",
                     properties: {
                         maxCritical: { type: "number" },
                         maxWarnings: { type: "number" },
@@ -186,8 +211,9 @@ export const qualityGateTools = [
         },
         handler: async (args) => {
             const projectDir = resolve(args.projectDir);
+            const scaleBase = SCALE_THRESHOLDS[args.scale ?? "medium"] ?? DEFAULT_THRESHOLDS;
             const thresholds = {
-                ...DEFAULT_THRESHOLDS,
+                ...scaleBase,
                 ...(args.thresholds ?? {}),
             };
             const result = runQualityGate(projectDir, thresholds);
@@ -196,6 +222,7 @@ export const qualityGateTools = [
             db.prepare("INSERT INTO deploy_checks (id, project_dir, check_type, passed, findings) VALUES (?, ?, ?, ?, ?)").run(genId("deploy"), projectDir, "quality_gate", result.passed ? 1 : 0, JSON.stringify(result));
             return {
                 ...result,
+                scale: args.scale ?? "medium",
                 thresholdsUsed: thresholds,
                 quickRef: getQuickRef("convex_quality_gate"),
             };

package/dist/tools/reportingTools.js

@@ -75,7 +75,7 @@ function buildSarif(projectDir, auditTypes, limit) {
                 tool: {
                     driver: {
                         name: "convex-mcp-nodebench",
-                        version: "0.9.7",
+                        version: "0.9.9",
                         informationUri: "https://www.npmjs.com/package/@homenshum/convex-mcp-nodebench",
                         rules: [...rulesMap.values()],
                     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homenshum/convex-mcp-nodebench",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "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": {
@@ -41,6 +41,7 @@
   "author": "HomenShum",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
+    "@toon-format/toon": "^1.0.0",
     "better-sqlite3": "^11.0.0"
   },
   "optionalDependencies": {