@homenshum/convex-mcp-nodebench 0.2.0 → 0.3.0

package/README.md

@@ -1,41 +1,59 @@
 # convex-mcp-nodebench
 
-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.
+Convex-specific MCP server applying NodeBench self-instruct diligence patterns to Convex development. Schema audit, function compliance, HTTP endpoint analysis, deployment gates, persistent gotcha DB, and methodology guidance.
 
 **Complements** Context7 (raw library docs) and the official Convex MCP (deployment introspection) with structured verification workflows and persistent Convex knowledge.
 
-## 11 Tools across 5 Categories
+## 17 Tools across 8 Categories
 
 ### Schema Tools
 | Tool | Description |
 |------|-------------|
-| `convex_audit_schema` | Scan schema.ts for anti-patterns: deprecated validators, reserved field names, missing indexes, naming violations |
+| `convex_audit_schema` | Scan schema.ts for anti-patterns: deprecated validators (`v.bigint()`), `v.any()` usage, reserved field names, missing indexes, naming conventions |
 | `convex_suggest_indexes` | Analyze query patterns across all functions and suggest missing indexes |
 | `convex_check_validator_coverage` | Check all exported functions have args + returns validators |
 
 ### Function Tools
 | Tool | Description |
 |------|-------------|
-| `convex_audit_functions` | Audit function registration, missing validators, public/internal misuse, action anti-patterns |
+| `convex_audit_functions` | Audit function registration, missing validators, public/internal misuse, action anti-patterns, **cross-call violations** (query calling runMutation/runAction) |
 | `convex_check_function_refs` | Validate api.x.y / internal.x.y references, detect direct function passing |
 
+### HTTP Tools
+| Tool | Description |
+|------|-------------|
+| `convex_analyze_http` | Analyze convex/http.ts for duplicate routes, missing CORS headers, missing OPTIONS preflight handlers, missing httpRouter/httpAction imports |
+
 ### Deployment Tools
 | Tool | Description |
 |------|-------------|
-| `convex_pre_deploy_gate` | Pre-deployment quality gate: schema, auth, validators, recent audit results |
-| `convex_check_env_vars` | Check env vars referenced in code exist in .env files |
+| `convex_pre_deploy_gate` | Pre-deployment quality gate: schema, auth, validators, recent audit results (only blocks on truly critical issues) |
+| `convex_check_env_vars` | Check Convex-specific env vars referenced in code exist in .env files (filters out NODE_ENV, PATH, etc.) |
 
 ### Learning Tools
 | Tool | Description |
 |------|-------------|
 | `convex_record_gotcha` | Persist a Convex gotcha/edge case for future reference |
-| `convex_search_gotchas` | Full-text search across known Convex gotchas |
+| `convex_search_gotchas` | Full-text search across known Convex gotchas (BM25 + FTS5) |
 
 ### Methodology Tools
 | Tool | Description |
 |------|-------------|
 | `convex_get_methodology` | Step-by-step guides: schema audit, function compliance, deploy verification, knowledge management |
-| `convex_discover_tools` | Search available tools by keyword, category, or task description |
+| `convex_discover_tools` | BM25-scored tool discovery with optional embedding-enhanced semantic search |
+
+### Integration Bridge Tools
+| Tool | Description |
+|------|-------------|
+| `convex_generate_rules_md` | Generate a Convex rules markdown file from gotcha DB, recent audits, and project stats |
+| `convex_snapshot_schema` | Capture schema snapshot for diffing (tracks tables, indexes per table, size). Auto-diffs against previous snapshot |
+| `convex_bootstrap_project` | Comprehensive project health scan: schema, auth, _generated, file count, improvement plan |
+
+### Infrastructure Tools
+| Tool | Description |
+|------|-------------|
+| `convex_check_crons` | Validate crons.ts: duplicate names, public handlers, interval issues |
+| `convex_analyze_components` | Parse convex.config.ts: active/conditional components, unused imports |
 
 ## Self-Instruct QuickRefs
 
@@ -53,20 +71,35 @@ Every tool response includes a `quickRef` block telling the agent what to do nex
 
 ## Pre-Seeded Gotcha Database
 
-Ships with 20 gotchas extracted from Convex best practices:
+Ships with 32 gotchas extracted from Convex best practices, auto-upserted on upgrade:
 
+### Critical
+- `pagination_cursor_null_first` -- First paginate() call must pass cursor: null
+- `query_no_side_effects` -- Queries CANNOT call runMutation or runAction (runtime error)
+- `use_node_for_external_api` -- Actions calling external APIs need `"use node"` directive
 - `validator_bigint_deprecated` -- Use v.int64() not v.bigint()
-- `undefined_not_valid` -- Use null, never undefined
-- `index_field_order` -- Query fields must match index definition order
-- `no_map_set_validators` -- Use v.record() instead
-- `returns_validator_required` -- Every function needs a returns validator
-- `action_from_action` -- Only cross-runtime, otherwise use helpers
-- And 14 more...
+
+### Warnings
+- `ctx_auth_returns_null` -- getUserIdentity() returns null when unauthenticated
+- `http_cors_manual` -- CORS headers must be added manually to HTTP endpoints
+- `http_route_no_wildcard` -- HTTP routes use exact path matching, no wildcards
+- `avoid_v_any` -- v.any() defeats the purpose of validators
+- `mutation_transaction_atomicity` -- Each mutation is a separate transaction
+- `db_get_returns_null` -- ctx.db.get() returns null if document missing
+- `storage_get_returns_null` -- ctx.storage.get() returns null if file missing
+- `convex_1mb_document_limit` -- Documents cannot exceed 1MB
+- `scheduled_function_must_be_internal` -- Scheduled functions should be internal
+- And 19 more covering index ordering, undefined handling, field naming, action patterns...
 
 ## Quick Start
 
 ### Install
 ```bash
+npm install @homenshum/convex-mcp-nodebench
+```
+
+Or from source:
+```bash
 cd packages/convex-mcp-nodebench
 npm install
 npm run build
@@ -74,7 +107,7 @@ npm run build
 
 ### Run (stdio)
 ```bash
-node dist/index.js
+npx convex-mcp-nodebench
 ```
 
 ### Dev mode
@@ -87,8 +120,8 @@ npx tsx src/index.ts
 {
   "mcpServers": {
     "convex-mcp-nodebench": {
-      "command": "node",
-      "args": ["/path/to/packages/convex-mcp-nodebench/dist/index.js"]
+      "command": "npx",
+      "args": ["@homenshum/convex-mcp-nodebench"]
     }
   }
 }
@@ -96,15 +129,15 @@ npx tsx src/index.ts
 
 ### First prompt
 ```
-Search convex gotchas for "validator" then audit the schema at /path/to/my-project
+Search convex gotchas for "pagination" then audit the schema at /path/to/my-project
 ```
 
 ## Data Storage
 
 Persistent SQLite database at `~/.convex-mcp-nodebench/convex.db`:
 
-- **convex_gotchas** -- Gotcha knowledge base with FTS5 search
-- **schema_snapshots** -- Schema history for diffing
+- **convex_gotchas** -- Gotcha knowledge base with FTS5 full-text search
+- **schema_snapshots** -- Schema history for table + index diffing
 - **deploy_checks** -- Deployment gate audit trail
 - **audit_results** -- Per-file analysis cache
 
@@ -114,24 +147,49 @@ Persistent SQLite database at `~/.convex-mcp-nodebench/convex.db`:
 npm test
 ```
 
-All 15 tests verify tools work against the real nodebench-ai codebase (3,138 Convex functions).
+30 tests verify all 17 tools work against the real nodebench-ai codebase (3,147 Convex functions, 323 tables, 82 crons, 8 HTTP routes).
 
 ## Architecture
 
 ```
 packages/convex-mcp-nodebench/
   src/
-    index.ts                 -- MCP server entry, tool assembly
-    db.ts                    -- SQLite schema + seed logic
-    types.ts                 -- Tool types, QuickRef interface
-    gotchaSeed.ts            -- 20 pre-seeded Convex gotchas
+    index.ts                    -- MCP server entry, tool assembly (17 tools)
+    db.ts                       -- SQLite schema + upsert seed logic
+    types.ts                    -- Tool types, QuickRef interface
+    gotchaSeed.ts               -- 32 pre-seeded Convex gotchas
     tools/
-      schemaTools.ts         -- Schema audit, index suggestions, validator coverage
-      functionTools.ts       -- Function audit, reference checking
-      deploymentTools.ts     -- Pre-deploy gate, env var checking
-      learningTools.ts       -- Gotcha recording + search
-      methodologyTools.ts    -- Methodology guides, tool discovery
-      toolRegistry.ts        -- Central catalog with quickRef metadata
+      schemaTools.ts            -- Schema audit, index suggestions, validator coverage
+      functionTools.ts          -- Function audit, cross-call detection, reference checking
+      httpTools.ts              -- HTTP endpoint analysis (routes, CORS, duplicates)
+      deploymentTools.ts        -- Pre-deploy gate, env var checking (Convex-filtered)
+      learningTools.ts          -- Gotcha recording + FTS5 search
+      methodologyTools.ts       -- Methodology guides, BM25 tool discovery
+      integrationBridgeTools.ts -- Rules generation, schema snapshots with index diffing, project bootstrap
+      cronTools.ts              -- Cron job validation
+      componentTools.ts         -- Component config analysis
+      toolRegistry.ts           -- Central catalog with quickRef metadata + BM25 scoring
+      embeddingProvider.ts      -- Optional semantic search (Google/OpenAI embeddings)
     __tests__/
-      tools.test.ts          -- 15 integration tests
+      tools.test.ts             -- 30 integration tests
 ```
+
+## Changelog
+
+### v0.3.0
+- **New tool**: `convex_analyze_http` -- HTTP endpoint analysis (duplicate routes, CORS, OPTIONS handlers)
+- **Cross-call detection**: queries calling `ctx.runMutation`/`ctx.runAction` flagged as critical
+- **12 new gotchas**: pagination, ctx.auth, scheduled functions, HTTP routes, CORS, v.any(), storage, transactions, document limits, "use node"
+- **Schema snapshot diffs** now track index additions/removals per table
+- **env_vars** filtered to Convex-specific patterns (excludes NODE_ENV, PATH, HOME, etc.)
+- **Gotcha seeding** upgraded to upsert -- existing users get new gotchas on upgrade
+- **Bug fixes**: fnv1aHash missing in embeddingProvider, collectTsFilesFlat ESM compat
+
+### v0.2.0
+- Schema audit noise reduced (836 -> 163 issues): index naming aggregated, v.any() detection added
+- Function audit severity corrected: missing returns downgraded from critical to warning
+- Deploy gate threshold: only blocks on >10 criticals
+- npm tarball reduced from 45.9kB to 31.5kB
+
+### v0.1.0
+- Initial release: 16 tools, 20 gotchas, BM25 discovery, embedding-enhanced search

package/dist/db.js

@@ -111,13 +111,19 @@ export function genId(prefix) {
 }
 export function seedGotchasIfEmpty(gotchas) {
     const db = getDb();
-    const count = db.prepare("SELECT COUNT(*) as c FROM convex_gotchas").get().c;
-    if (count > 0)
-        return;
-    const insert = db.prepare("INSERT OR IGNORE INTO convex_gotchas (key, content, category, severity, tags, source) VALUES (?, ?, ?, ?, ?, 'seed')");
+    // Upsert: insert new seed gotchas, skip user-created ones (source != 'seed')
+    const upsert = db.prepare(`INSERT INTO convex_gotchas (key, content, category, severity, tags, source)
+     VALUES (?, ?, ?, ?, ?, 'seed')
+     ON CONFLICT(key) DO UPDATE SET
+       content = excluded.content,
+       category = excluded.category,
+       severity = excluded.severity,
+       tags = excluded.tags,
+       updated_at = datetime('now')
+     WHERE source = 'seed'`);
     const tx = db.transaction(() => {
         for (const g of gotchas) {
-            insert.run(g.key, g.content, g.category, g.severity, g.tags);
+            upsert.run(g.key, g.content, g.category, g.severity, g.tags);
         }
     });
     tx();

package/dist/gotchaSeed.d.ts

@@ -122,5 +122,77 @@ export declare const CONVEX_GOTCHAS: readonly [{
     readonly category: "function";
     readonly severity: "warning";
     readonly tags: "action,query,mutation,transaction,race,condition";
+}, {
+    readonly key: "pagination_cursor_null_first";
+    readonly content: "When using .paginate(), the first call must pass cursor: null (not undefined). Subsequent calls use the continueCursor from the previous response. The paginationOpts validator is paginationOptsValidator from 'convex/server'.";
+    readonly category: "function";
+    readonly severity: "critical";
+    readonly tags: "pagination,cursor,null,paginate,paginationOpts";
+}, {
+    readonly key: "query_no_side_effects";
+    readonly content: "Queries (query/internalQuery) CANNOT call ctx.runMutation or ctx.runAction. They are read-only. Attempting to mutate from a query will throw a runtime error.";
+    readonly category: "function";
+    readonly severity: "critical";
+    readonly tags: "query,mutation,action,side-effect,read-only,runtime";
+}, {
+    readonly key: "ctx_auth_returns_null";
+    readonly content: "ctx.auth.getUserIdentity() returns null when the user is not authenticated. Always null-check before accessing identity fields. Do NOT assume it returns a value.";
+    readonly category: "function";
+    readonly severity: "warning";
+    readonly tags: "auth,identity,null,getUserIdentity,authentication";
+}, {
+    readonly key: "scheduled_function_must_be_internal";
+    readonly content: "Functions passed to ctx.scheduler.runAfter or ctx.scheduler.runAt should be internal functions (internalMutation/internalAction). Using public functions exposes them to the API.";
+    readonly category: "function";
+    readonly severity: "warning";
+    readonly tags: "scheduler,scheduled,runAfter,runAt,internal,cron";
+}, {
+    readonly key: "http_route_no_wildcard";
+    readonly content: "Convex HTTP routes use exact path matching, not prefix/wildcard matching. /api/users does NOT match /api/users/123. Register separate routes for each path.";
+    readonly category: "function";
+    readonly severity: "warning";
+    readonly tags: "http,route,wildcard,path,exact,matching";
+}, {
+    readonly key: "http_cors_manual";
+    readonly content: "Convex HTTP endpoints do not automatically handle CORS. You must manually add CORS headers (Access-Control-Allow-Origin, etc.) and handle OPTIONS preflight requests.";
+    readonly category: "function";
+    readonly severity: "warning";
+    readonly tags: "http,cors,headers,options,preflight,origin";
+}, {
+    readonly key: "avoid_v_any";
+    readonly content: "v.any() defeats the purpose of validators — it accepts any value and provides no type safety. Use specific validators (v.string(), v.object({...}), v.union(...)) instead.";
+    readonly category: "validator";
+    readonly severity: "warning";
+    readonly tags: "any,validator,type-safety,schema";
+}, {
+    readonly key: "storage_get_returns_null";
+    readonly content: "ctx.storage.get(storageId) returns null if the file doesn't exist. Always null-check the result before using it. Also, storage IDs are typed as Id<'_storage'>.";
+    readonly category: "function";
+    readonly severity: "warning";
+    readonly tags: "storage,get,null,file,upload,_storage";
+}, {
+    readonly key: "mutation_transaction_atomicity";
+    readonly content: "Each mutation runs as a single transaction. If you call ctx.runMutation multiple times from an action, each is a separate transaction — there's no cross-mutation atomicity. Design mutations to be self-contained.";
+    readonly category: "function";
+    readonly severity: "warning";
+    readonly tags: "mutation,transaction,atomicity,action,consistency";
+}, {
+    readonly key: "db_get_returns_null";
+    readonly content: "ctx.db.get(id) returns null if the document doesn't exist or was deleted. Always null-check before accessing fields. TypeScript won't catch this at compile time.";
+    readonly category: "function";
+    readonly severity: "warning";
+    readonly tags: "db,get,null,document,deleted";
+}, {
+    readonly key: "convex_1mb_document_limit";
+    readonly content: "Individual Convex documents cannot exceed 1MB. Large text, arrays of objects, or embedded binary data can exceed this. Split large data across multiple documents or use file storage.";
+    readonly category: "schema";
+    readonly severity: "warning";
+    readonly tags: "document,size,limit,1mb,split,storage";
+}, {
+    readonly key: "use_node_for_external_api";
+    readonly content: "Convex actions that call external APIs (fetch, HTTP clients) must use the Node.js runtime. Add 'use node' at the top of the file. V8 runtime does not support fetch to external URLs.";
+    readonly category: "function";
+    readonly severity: "critical";
+    readonly tags: "node,runtime,fetch,external,api,use-node";
 }];
 export type ConvexGotcha = typeof CONVEX_GOTCHAS[number];

package/dist/gotchaSeed.js

@@ -143,5 +143,89 @@ export const CONVEX_GOTCHAS = [
         severity: "warning",
         tags: "action,query,mutation,transaction,race,condition",
     },
+    {
+        key: "pagination_cursor_null_first",
+        content: "When using .paginate(), the first call must pass cursor: null (not undefined). Subsequent calls use the continueCursor from the previous response. The paginationOpts validator is paginationOptsValidator from 'convex/server'.",
+        category: "function",
+        severity: "critical",
+        tags: "pagination,cursor,null,paginate,paginationOpts",
+    },
+    {
+        key: "query_no_side_effects",
+        content: "Queries (query/internalQuery) CANNOT call ctx.runMutation or ctx.runAction. They are read-only. Attempting to mutate from a query will throw a runtime error.",
+        category: "function",
+        severity: "critical",
+        tags: "query,mutation,action,side-effect,read-only,runtime",
+    },
+    {
+        key: "ctx_auth_returns_null",
+        content: "ctx.auth.getUserIdentity() returns null when the user is not authenticated. Always null-check before accessing identity fields. Do NOT assume it returns a value.",
+        category: "function",
+        severity: "warning",
+        tags: "auth,identity,null,getUserIdentity,authentication",
+    },
+    {
+        key: "scheduled_function_must_be_internal",
+        content: "Functions passed to ctx.scheduler.runAfter or ctx.scheduler.runAt should be internal functions (internalMutation/internalAction). Using public functions exposes them to the API.",
+        category: "function",
+        severity: "warning",
+        tags: "scheduler,scheduled,runAfter,runAt,internal,cron",
+    },
+    {
+        key: "http_route_no_wildcard",
+        content: "Convex HTTP routes use exact path matching, not prefix/wildcard matching. /api/users does NOT match /api/users/123. Register separate routes for each path.",
+        category: "function",
+        severity: "warning",
+        tags: "http,route,wildcard,path,exact,matching",
+    },
+    {
+        key: "http_cors_manual",
+        content: "Convex HTTP endpoints do not automatically handle CORS. You must manually add CORS headers (Access-Control-Allow-Origin, etc.) and handle OPTIONS preflight requests.",
+        category: "function",
+        severity: "warning",
+        tags: "http,cors,headers,options,preflight,origin",
+    },
+    {
+        key: "avoid_v_any",
+        content: "v.any() defeats the purpose of validators — it accepts any value and provides no type safety. Use specific validators (v.string(), v.object({...}), v.union(...)) instead.",
+        category: "validator",
+        severity: "warning",
+        tags: "any,validator,type-safety,schema",
+    },
+    {
+        key: "storage_get_returns_null",
+        content: "ctx.storage.get(storageId) returns null if the file doesn't exist. Always null-check the result before using it. Also, storage IDs are typed as Id<'_storage'>.",
+        category: "function",
+        severity: "warning",
+        tags: "storage,get,null,file,upload,_storage",
+    },
+    {
+        key: "mutation_transaction_atomicity",
+        content: "Each mutation runs as a single transaction. If you call ctx.runMutation multiple times from an action, each is a separate transaction — there's no cross-mutation atomicity. Design mutations to be self-contained.",
+        category: "function",
+        severity: "warning",
+        tags: "mutation,transaction,atomicity,action,consistency",
+    },
+    {
+        key: "db_get_returns_null",
+        content: "ctx.db.get(id) returns null if the document doesn't exist or was deleted. Always null-check before accessing fields. TypeScript won't catch this at compile time.",
+        category: "function",
+        severity: "warning",
+        tags: "db,get,null,document,deleted",
+    },
+    {
+        key: "convex_1mb_document_limit",
+        content: "Individual Convex documents cannot exceed 1MB. Large text, arrays of objects, or embedded binary data can exceed this. Split large data across multiple documents or use file storage.",
+        category: "schema",
+        severity: "warning",
+        tags: "document,size,limit,1mb,split,storage",
+    },
+    {
+        key: "use_node_for_external_api",
+        content: "Convex actions that call external APIs (fetch, HTTP clients) must use the Node.js runtime. Add 'use node' at the top of the file. V8 runtime does not support fetch to external URLs.",
+        category: "function",
+        severity: "critical",
+        tags: "node,runtime,fetch,external,api,use-node",
+    },
 ];
 //# sourceMappingURL=gotchaSeed.js.map

package/dist/index.js

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

package/dist/tools/deploymentTools.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { getDb, genId } from "../db.js";
 import { getQuickRef } from "./toolRegistry.js";
@@ -126,7 +126,13 @@ function checkEnvVars(projectDir) {
             result.envVarsInEnvFile.push(...vars.map((v) => v.replace("=", "")));
         }
     }
-    // Scan convex/ for process.env references
+    // Scan convex/ for process.env references (filter out non-Convex vars)
+    const NON_CONVEX_VARS = new Set([
+        "NODE_ENV", "HOME", "PATH", "SHELL", "USER", "LANG", "TERM",
+        "HOSTNAME", "PWD", "TMPDIR", "TMP", "TEMP", "CI", "DEBUG",
+        "LOG_LEVEL", "VERBOSE", "PORT", "HOST", "NODE_PATH",
+        "npm_config_registry", "npm_lifecycle_event",
+    ]);
     const convexDir = findConvexDir(projectDir);
     if (convexDir) {
         const files = collectTsFilesFlat(convexDir);
@@ -136,7 +142,11 @@ function checkEnvVars(projectDir) {
             const content = readFileSync(filePath, "utf-8");
             let m;
             while ((m = envPattern.exec(content)) !== null) {
-                codeEnvVars.add(m[1]);
+                const varName = m[1];
+                // Skip common Node/OS vars that aren't Convex env vars
+                if (!NON_CONVEX_VARS.has(varName)) {
+                    codeEnvVars.add(varName);
+                }
             }
         }
         result.envVarsInCode = [...codeEnvVars];
@@ -157,7 +167,6 @@ function collectTsFilesFlat(dir) {
     const results = [];
     if (!existsSync(dir))
         return results;
-    const { readdirSync } = require("node:fs");
     const entries = readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
         const full = join(dir, entry.name);

package/dist/tools/embeddingProvider.js

@@ -14,6 +14,15 @@ let _provider = null;
 let _providerChecked = false;
 let _embeddingIndex = null;
 let _initPromise = null;
+// Simple FNV-1a hash for corpus change detection
+function fnv1aHash(str) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        hash = (hash * 0x01000193) >>> 0;
+    }
+    return hash.toString(36);
+}
 const CACHE_VERSION = 1;
 const CACHE_DIR = join(homedir(), ".convex-mcp-nodebench");
 const CACHE_FILE = join(CACHE_DIR, "embedding_cache.json");
@@ -99,12 +108,14 @@ async function _doInit(corpus) {
     const provider = await getEmbeddingProvider();
     if (!provider)
         return;
+    const hash = fnv1aHash(corpus.map((c) => c.text).join("\n"));
     const cached = loadCache();
     if (cached &&
         cached.providerName === provider.name &&
         cached.dimensions === provider.dimensions &&
         cached.version === CACHE_VERSION &&
         cached.toolCount === corpus.length &&
+        cached.corpusHash === hash &&
         corpus.every((c) => c.name in cached.entries)) {
         _embeddingIndex = corpus.map((c) => ({
             name: c.name,
@@ -124,6 +135,7 @@ async function _doInit(corpus) {
             dimensions: provider.dimensions,
             version: CACHE_VERSION,
             toolCount: corpus.length,
+            corpusHash: hash,
             entries: {},
         };
         for (let i = 0; i < corpus.length; i++) {

package/dist/tools/functionTools.js

@@ -146,6 +146,34 @@ function auditFunctions(convexDir) {
             });
         }
     }
+    // Check 4: Cross-call violations — queries CANNOT call runMutation or runAction
+    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");
+        if (/ctx\.runMutation/.test(chunk)) {
+            issues.push({
+                severity: "critical",
+                location: `${fn.relativePath}:${fn.line}`,
+                functionName: fn.name,
+                message: `${fn.type} "${fn.name}" calls ctx.runMutation — queries cannot mutate data. This will throw at runtime.`,
+                fix: "Move the mutation call to a mutation or action function",
+            });
+        }
+        if (/ctx\.runAction/.test(chunk)) {
+            issues.push({
+                severity: "critical",
+                location: `${fn.relativePath}:${fn.line}`,
+                functionName: fn.name,
+                message: `${fn.type} "${fn.name}" calls ctx.runAction — queries cannot call actions. This will throw at runtime.`,
+                fix: "Move the action call to an action function",
+            });
+        }
+    }
     return issues;
 }
 function checkFunctionRefs(convexDir) {

package/dist/tools/httpTools.d.ts

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

package/dist/tools/httpTools.js

@@ -0,0 +1,168 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+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 analyzeHttpEndpoints(convexDir) {
+    const httpPath = join(convexDir, "http.ts");
+    if (!existsSync(httpPath)) {
+        return { hasHttp: false, routes: [], issues: [], hasCors: false, hasOptionsHandler: false };
+    }
+    const content = readFileSync(httpPath, "utf-8");
+    const lines = content.split("\n");
+    const routes = [];
+    const issues = [];
+    // Extract routes: http.route({ path: "...", method: "...", handler: ... })
+    const routeBlockPattern = /http\.route\s*\(\s*\{/g;
+    let routeMatch;
+    while ((routeMatch = routeBlockPattern.exec(content)) !== null) {
+        const startIdx = routeMatch.index;
+        // Find the closing of this route block (rough — find next })
+        let depth = 0;
+        let endIdx = startIdx;
+        for (let i = startIdx; i < content.length; i++) {
+            if (content[i] === "{")
+                depth++;
+            if (content[i] === "}") {
+                depth--;
+                if (depth === 0) {
+                    endIdx = i;
+                    break;
+                }
+            }
+        }
+        const block = content.slice(startIdx, endIdx + 1);
+        const pathMatch = block.match(/path\s*:\s*["']([^"']+)["']/);
+        const methodMatch = block.match(/method\s*:\s*["']([^"']+)["']/);
+        const line = content.slice(0, startIdx).split("\n").length;
+        if (pathMatch && methodMatch) {
+            routes.push({
+                path: pathMatch[1],
+                method: methodMatch[1].toUpperCase(),
+                line,
+                handlerType: /handler\s*:\s*httpAction/.test(block) ? "inline" : "imported",
+            });
+        }
+    }
+    // Check for duplicate routes (same path + method)
+    const routeKeys = new Map();
+    for (const route of routes) {
+        const key = `${route.method} ${route.path}`;
+        const count = (routeKeys.get(key) || 0) + 1;
+        routeKeys.set(key, count);
+        if (count === 2) {
+            issues.push({
+                severity: "critical",
+                message: `Duplicate route: ${key} — only the last registration will be used`,
+                location: `http.ts:${route.line}`,
+            });
+        }
+    }
+    // Check for CORS handling
+    const hasCors = /Access-Control-Allow-Origin/i.test(content) ||
+        /cors/i.test(content);
+    const hasOptionsHandler = routes.some((r) => r.method === "OPTIONS");
+    if (!hasCors && routes.length > 0) {
+        issues.push({
+            severity: "warning",
+            message: "No CORS headers detected. Browser requests from different origins will fail. Add Access-Control-Allow-Origin headers.",
+        });
+    }
+    if (hasCors && !hasOptionsHandler) {
+        issues.push({
+            severity: "warning",
+            message: "CORS headers found but no OPTIONS handler registered. Preflight requests will fail. Add http.route({ path: '...', method: 'OPTIONS', handler: ... }).",
+        });
+    }
+    // Check for paths that look like they should be grouped
+    const pathPrefixes = new Map();
+    for (const route of routes) {
+        const parts = route.path.split("/").filter(Boolean);
+        if (parts.length >= 2) {
+            const prefix = `/${parts[0]}/${parts[1]}`;
+            pathPrefixes.set(prefix, (pathPrefixes.get(prefix) || 0) + 1);
+        }
+    }
+    // Check for missing httpRouter import
+    if (!/httpRouter/.test(content)) {
+        issues.push({
+            severity: "critical",
+            message: "Missing httpRouter import. HTTP endpoints require: import { httpRouter } from 'convex/server';",
+        });
+    }
+    // Check for export default
+    if (!/export\s+default\s+http/.test(content)) {
+        issues.push({
+            severity: "critical",
+            message: "Missing 'export default http'. The httpRouter must be exported as default.",
+        });
+    }
+    // Check for httpAction import
+    if (!/httpAction/.test(content) && routes.length > 0) {
+        issues.push({
+            severity: "warning",
+            message: "No httpAction usage found. HTTP route handlers should use httpAction().",
+        });
+    }
+    return { hasHttp: true, routes, issues, hasCors, hasOptionsHandler };
+}
+// ── Tool Definitions ────────────────────────────────────────────────
+export const httpTools = [
+    {
+        name: "convex_analyze_http",
+        description: "Analyze convex/http.ts for HTTP endpoint issues: duplicate routes, missing CORS headers, missing OPTIONS preflight handlers, missing httpRouter/httpAction imports, and missing default export. Returns route inventory with methods and paths.",
+        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 result = analyzeHttpEndpoints(convexDir);
+            if (!result.hasHttp) {
+                return {
+                    hasHttp: false,
+                    message: "No convex/http.ts found — project has no HTTP endpoints",
+                    quickRef: getQuickRef("convex_analyze_http"),
+                };
+            }
+            // Group routes by path prefix
+            const byMethod = {};
+            for (const r of result.routes) {
+                byMethod[r.method] = (byMethod[r.method] || 0) + 1;
+            }
+            return {
+                hasHttp: true,
+                totalRoutes: result.routes.length,
+                byMethod,
+                hasCors: result.hasCors,
+                hasOptionsHandler: result.hasOptionsHandler,
+                routes: result.routes,
+                issues: {
+                    total: result.issues.length,
+                    critical: result.issues.filter((i) => i.severity === "critical").length,
+                    warnings: result.issues.filter((i) => i.severity === "warning").length,
+                    details: result.issues,
+                },
+                quickRef: getQuickRef("convex_analyze_http"),
+            };
+        },
+    },
+];
+//# sourceMappingURL=httpTools.js.map

package/dist/tools/integrationBridgeTools.js

@@ -110,8 +110,27 @@ function captureSchemaSnapshot(projectDir) {
     while ((m = tablePattern.exec(schemaContent)) !== null) {
         tables.push(m[1]);
     }
+    // Extract indexes per table
+    const indexMap = {};
+    const indexPattern = /\.index\s*\(\s*["']([^"']+)["']\s*,\s*\[([^\]]*)\]\s*\)/g;
+    let currentTable = "";
+    const lines = schemaContent.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const tableDef = lines[i].match(/(\w+)\s*[:=]\s*defineTable\s*\(/);
+        if (tableDef)
+            currentTable = tableDef[1];
+        const idxMatch = lines[i].match(/\.index\s*\(\s*["']([^"']+)["']/);
+        if (idxMatch && currentTable) {
+            if (!indexMap[currentTable])
+                indexMap[currentTable] = [];
+            indexMap[currentTable].push(idxMatch[1]);
+        }
+    }
+    const totalIndexes = Object.values(indexMap).reduce((sum, arr) => sum + arr.length, 0);
     const schemaJson = JSON.stringify({
         tables,
+        indexes: indexMap,
+        totalIndexes,
         rawLength: schemaContent.length,
         capturedAt: new Date().toISOString(),
     });
@@ -188,10 +207,29 @@ export const integrationBridgeTools = [
                     const curr = JSON.parse(snapshot.schemaJson);
                     const addedTables = curr.tables.filter((t) => !prev.tables.includes(t));
                     const removedTables = prev.tables.filter((t) => !curr.tables.includes(t));
+                    // Index diff
+                    const prevIdx = prev.indexes || {};
+                    const currIdx = curr.indexes || {};
+                    const addedIndexes = [];
+                    const removedIndexes = [];
+                    const allTables = new Set([...Object.keys(prevIdx), ...Object.keys(currIdx)]);
+                    for (const table of allTables) {
+                        const pSet = new Set(prevIdx[table] || []);
+                        const cSet = new Set(currIdx[table] || []);
+                        for (const idx of cSet)
+                            if (!pSet.has(idx))
+                                addedIndexes.push(`${table}.${idx}`);
+                        for (const idx of pSet)
+                            if (!cSet.has(idx))
+                                removedIndexes.push(`${table}.${idx}`);
+                    }
                     diff = {
                         previousSnapshot: previous.snapshot_at,
                         addedTables,
                         removedTables,
+                        addedIndexes,
+                        removedIndexes,
+                        indexCountChange: (curr.totalIndexes || 0) - (prev.totalIndexes || 0),
                         sizeChange: curr.rawLength - prev.rawLength,
                     };
                 }

package/dist/tools/toolRegistry.js

@@ -231,6 +231,21 @@ export const REGISTRY = [
         phase: "audit",
         complexity: "low",
     },
+    // ── HTTP Tools ────────────
+    {
+        name: "convex_analyze_http",
+        category: "function",
+        tags: ["http", "endpoint", "route", "cors", "api", "rest", "options", "preflight"],
+        quickRef: {
+            nextAction: "Fix duplicate routes and add CORS headers before deploy",
+            nextTools: ["convex_pre_deploy_gate", "convex_audit_functions"],
+            methodology: "convex_deploy_verification",
+            relatedGotchas: ["http_exact_path", "http_route_no_wildcard", "http_cors_manual"],
+            confidence: "high",
+        },
+        phase: "audit",
+        complexity: "low",
+    },
 ];
 export function getQuickRef(toolName) {
     const entry = REGISTRY.find((e) => e.name === toolName);
@@ -323,15 +338,15 @@ export async function findToolsWithEmbedding(query) {
     // RRF fusion: combine BM25 rank with embedding rank
     const fusedScores = new Map();
     bm25Results.forEach((entry, i) => {
-        const bm25Rrf = 1000 / (60 + i + 1);
+        const bm25Rrf = 1000 / (20 + i + 1);
         const embRank = vecRanks.get(entry.name);
-        const embRrf = embRank ? 1000 / (60 + embRank) : 0;
+        const embRrf = embRank ? 1000 / (20 + embRank) : 0;
         fusedScores.set(entry.name, bm25Rrf + embRrf);
     });
     // Also include embedding-only hits not in BM25 results
     for (const [name, rank] of vecRanks) {
         if (!fusedScores.has(name)) {
-            const embRrf = 1000 / (60 + rank);
+            const embRrf = 1000 / (20 + rank);
             fusedScores.set(name, embRrf);
         }
     }

package/package.json

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