@homenshum/convex-mcp-nodebench

convex-mcp-nodebench

Convex-specific MCP server that audits, verifies, and guides Convex development. 36 tools across schema audit, function compliance, security, performance, deployment gates, SARIF reporting, persistent gotcha DB, and adaptive architecture planning.

Complements Context7 (raw library docs) and the official Convex MCP (deployment introspection) with structured verification workflows and persistent Convex knowledge.

36 Tools

Core Audit (10 tools)

Tool	What it does
convex_audit_schema	Scan schema.ts for anti-patterns: deprecated validators, v.any(), reserved fields, missing indexes
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
convex_audit_functions	Audit function registration, validators, public/internal misuse, cross-call violations
convex_check_function_refs	Validate api.x.y / internal.x.y references, detect direct function passing
convex_check_type_safety	Find as any casts, undefined returns, loose ID types across all files
convex_audit_authorization	Audit auth guard coverage: which public functions check getUserIdentity()
convex_audit_actions	Audit actions for direct DB access, missing error handling, external API patterns
convex_audit_transaction_safety	Find read-modify-write races, multiple runMutation in single functions
convex_audit_query_efficiency	Detect unbounded .collect(), .filter() without index, mutation-as-read

Infrastructure Audit (9 tools)

Tool	What it does
convex_analyze_http	Analyze http.ts: duplicate routes, missing CORS, OPTIONS preflight handlers
convex_check_crons	Validate crons.ts: duplicate names, public handlers, interval issues
convex_analyze_components	Parse convex.config.ts: active/conditional components, unused imports
convex_audit_storage_usage	Audit storage: stores, deletes, missing null checks on getUrl()
convex_audit_pagination	Find paginate calls missing validators or without proper cursor handling
convex_audit_vector_search	Audit vector indexes, search calls, dimension mismatches
convex_audit_schedulers	Find runAfter/runAt usage, self-scheduling loops, missing termination
convex_audit_data_modeling	Audit tables: deep nesting, dangling refs, v.any(), arrays-of-arrays
convex_audit_dev_setup	Check project hygiene: _generated dir, tsconfig, package deps, env files

Deployment & Quality Gate (4 tools)

Tool	What it does
convex_pre_deploy_gate	Pre-deployment gate: schema, auth, validators, recent audits (blocks on critical)
convex_check_env_vars	Check env vars referenced in code exist in .env files (Convex-filtered)
convex_quality_gate	Composite quality score (A-F grade) with configurable thresholds
convex_schema_migration_plan	Diff schema snapshots and generate migration steps with risk assessment

Reporting (2 tools)

Tool	What it does
convex_export_sarif	Export all audit results as SARIF 2.1.0 (GitHub Code Scanning compatible)
convex_audit_diff	Compare current audit against baseline: new issues, fixed issues, trend

Adaptive Architect (3 tools)

Tool	What it does
convex_scan_capabilities	Regex scan of project structure: function types, data access, auth, storage, schema patterns
convex_verify_concept	Verify if a concept (e.g. "Vector Search RAG") is implemented via regex signatures
convex_generate_plan	Generate Convex-specific implementation steps for missing signatures

Self-discovery loop: scan_capabilities → verify_concept → generate_plan → implement → re-verify

Knowledge & Discovery (5 tools)

Tool	What it does
convex_record_gotcha	Persist a Convex gotcha/edge case for future reference
convex_search_gotchas	Full-text search across known Convex gotchas (BM25 + FTS5)
convex_get_methodology	Step-by-step guides: schema audit, function compliance, deploy verification
convex_discover_tools	BM25 + optional embedding-enhanced semantic tool discovery
convex_critter_check	Accountability check: scores task intent (why/who/what) before starting work

Integration Bridge (3 tools)

Tool	What it does
convex_generate_rules_md	Generate Convex rules markdown from gotcha DB, recent audits, project stats
convex_snapshot_schema	Capture schema snapshot for diffing (tables, indexes, size). Auto-diffs against previous
convex_bootstrap_project	Comprehensive project health scan with improvement plan

Quick Start

Install

npm install @homenshum/convex-mcp-nodebench

Add to MCP config (Claude Code, Cursor, Windsurf)

{
  "mcpServers": {
    "convex-mcp-nodebench": {
      "command": "npx",
      "args": ["@homenshum/convex-mcp-nodebench"]
    }
  }
}

First prompt

Audit the schema at /path/to/my-project, then run the quality gate

Optional: Enable semantic search

Set GOOGLE_API_KEY or OPENAI_API_KEY env var. The convex_discover_tools tool will automatically use embedding-enhanced search when available (Google text-embedding-004 or OpenAI text-embedding-3-small).

Self-Instruct QuickRefs

Every tool response includes a quickRef block guiding the agent to the next step:

{
  "nextAction": "Run convex_check_validator_coverage to ensure all functions have validators",
  "nextTools": ["convex_check_validator_coverage", "convex_audit_functions"],
  "methodology": "convex_schema_audit",
  "relatedGotchas": ["returns_validator_required", "new_function_syntax"],
  "confidence": "high"
}

Pre-Seeded Gotcha Database

Ships with 32 gotchas extracted from Convex best practices, auto-upserted on upgrade:

Critical: pagination_cursor_null_first, query_no_side_effects, use_node_for_external_api, validator_bigint_deprecated

Warnings: ctx_auth_returns_null, http_cors_manual, http_route_no_wildcard, avoid_v_any, mutation_transaction_atomicity, db_get_returns_null, storage_get_returns_null, convex_1mb_document_limit, scheduled_function_must_be_internal, and 19 more covering index ordering, undefined handling, field naming, action patterns...

Data Storage

Persistent SQLite at ~/.convex-mcp-nodebench/convex.db:

Table	Purpose
convex_gotchas	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
concept_verifications	Architect concept verification history
critter_checks	Task accountability records

Testing

npm test

63 tests (53 unit + 10 E2E) verify all 36 tools against the real nodebench-ai codebase (3,158 Convex functions, 328 tables, 82 crons, 44 HTTP routes).

Architecture

packages/convex-mcp-nodebench/
  src/
    index.ts                    -- MCP server, tool assembly (36 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, cross-call detection, ref checking
      httpTools.ts              -- HTTP endpoint analysis
      deploymentTools.ts        -- Pre-deploy gate, env var checking
      learningTools.ts          -- Gotcha recording + FTS5 search
      methodologyTools.ts       -- Methodology guides, BM25 tool discovery
      integrationBridgeTools.ts -- Rules generation, schema snapshots, project bootstrap
      cronTools.ts              -- Cron job validation
      componentTools.ts         -- Component config analysis
      critterTools.ts           -- Task accountability checking
      authorizationTools.ts     -- Auth guard audit
      queryEfficiencyTools.ts   -- Query performance audit
      actionAuditTools.ts       -- Action anti-pattern detection
      typeSafetyTools.ts        -- Type safety audit
      transactionSafetyTools.ts -- Transaction race detection
      storageAuditTools.ts      -- Storage usage audit
      paginationTools.ts        -- Pagination pattern audit
      dataModelingTools.ts      -- Data modeling audit
      devSetupTools.ts          -- Dev environment audit
      migrationTools.ts         -- Schema migration planning
      reportingTools.ts         -- SARIF export, baseline diff
      vectorSearchTools.ts      -- Vector search audit
      schedulerTools.ts         -- Scheduler audit
      qualityGateTools.ts       -- Composite quality gate
      architectTools.ts         -- Capability scan, concept verify, plan generation
      toolRegistry.ts           -- Central catalog with quickRef + BM25 scoring
      embeddingProvider.ts      -- Optional semantic search (Google/OpenAI embeddings)
    __tests__/
      tools.test.ts             -- 53 unit/integration tests
      architectE2E.test.ts      -- 10 E2E tests (industry-latest concept verification)

Changelog

v0.9.1

• Fix: Strategy matching order in architect tools -- specific patterns (ctx.db.query, ctx.runMutation) now matched before generic keywords (query, mutation)

v0.9.0

• 3 new tools: convex_scan_capabilities, convex_verify_concept, convex_generate_plan -- adaptive architect with Convex-specific regex patterns, strategies, and file hints
• Self-discovery loop: scan → verify → plan → implement → re-verify
• 7 Convex pattern categories: function types, schema, data access, auth, storage, client-side, cross-function calls
• ~40 Convex-specific strategies in inferConvexStrategy() with correct priority ordering
• 10 new E2E tests validating architect tools against industry-latest concepts (Vector Search RAG, Real-Time Collaboration, File Upload Pipeline, Scheduled Retry Queue, Row-Level Security)

v0.8.0

• 14 new tools: authorization audit, query efficiency, action audit, type safety, transaction safety, storage audit, pagination audit, data modeling audit, dev setup audit, schema migration planning, SARIF 2.1.0 export, baseline diff, vector search audit, scheduler audit
• Quality gate: Composite A-F scoring with configurable thresholds
• SARIF 2.1.0: GitHub Code Scanning compatible export aggregating all audit types
• Baseline diff: Track audit trends (improving/stable/degrading) over time
• MCP Resources: project-health, recent-audits, gotcha-db
• MCP Prompts: full-audit, pre-deploy-checklist, security-review

v0.4.0

• New tool: convex_critter_check -- task accountability with 10 calibrated checks
• Cross-call fix: improved detection of query→mutation violations
• v.any() aggregation: grouped by table for cleaner output

v0.3.0

• New tool: convex_analyze_http -- HTTP endpoint analysis
• Cross-call detection: queries calling ctx.runMutation/ctx.runAction flagged as critical
• 12 new gotchas: pagination, ctx.auth, scheduled functions, HTTP routes, CORS, storage, transactions
• Schema snapshot diffs track index additions/removals per table
• Gotcha seeding upgraded to upsert

v0.2.0

• Schema audit noise reduced (836 -> 163 issues)
• Function audit severity corrected
• 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