@homenshum/convex-mcp-nodebench 0.1.0

package/dist/gotchaSeed.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Pre-seeded Convex gotchas extracted from convexRules.md and common patterns.
+ * These are loaded into the DB on first run.
+ */
+export declare const CONVEX_GOTCHAS: readonly [{
+    readonly key: "validator_bigint_deprecated";
+    readonly content: "v.bigint() is deprecated for representing signed 64-bit integers. Use v.int64() instead.";
+    readonly category: "validator";
+    readonly severity: "critical";
+    readonly tags: "bigint,int64,deprecated,validator";
+}, {
+    readonly key: "undefined_not_valid";
+    readonly content: "JavaScript's undefined is not a valid Convex value. Functions that return undefined or do not return will return null when called from a client. Use null instead of undefined.";
+    readonly category: "validator";
+    readonly severity: "critical";
+    readonly tags: "undefined,null,return,value";
+}, {
+    readonly key: "system_fields_auto";
+    readonly content: "_creationTime (v.number()) and _id (v.id(tableName)) are automatically added to all documents as system fields. Do not include them in your schema definition.";
+    readonly category: "schema";
+    readonly severity: "warning";
+    readonly tags: "_creationTime,_id,system,fields,schema";
+}, {
+    readonly key: "index_field_order";
+    readonly content: "Index fields must be queried in the same order they are defined. If you want to query by field1 then field2 AND by field2 then field1, you must create separate indexes.";
+    readonly category: "schema";
+    readonly severity: "critical";
+    readonly tags: "index,order,query,field";
+}, {
+    readonly key: "no_map_set_validators";
+    readonly content: "v.map() and v.set() are not supported. Use v.record(keys, values) for defining record types instead.";
+    readonly category: "validator";
+    readonly severity: "critical";
+    readonly tags: "map,set,record,validator,unsupported";
+}, {
+    readonly key: "action_from_action";
+    readonly content: "Only call an action from another action if you need to cross runtimes (e.g. from V8 to Node). Otherwise, extract the shared code into a helper async function and call that directly.";
+    readonly category: "function";
+    readonly severity: "warning";
+    readonly tags: "action,runtime,v8,node,helper";
+}, {
+    readonly key: "function_ref_not_direct";
+    readonly content: "Use api.x.y or internal.x.y function references when calling ctx.runQuery/runMutation/runAction. Do NOT try to pass the callee function directly.";
+    readonly category: "function";
+    readonly severity: "critical";
+    readonly tags: "function,reference,api,internal,runQuery";
+}, {
+    readonly key: "new_function_syntax";
+    readonly content: "Always use the new function syntax: query({ args: {}, returns: v.null(), handler: async (ctx, args) => { } }). The old style without args/returns objects is deprecated.";
+    readonly category: "function";
+    readonly severity: "critical";
+    readonly tags: "syntax,query,mutation,action,args,returns";
+}, {
+    readonly key: "internal_for_private";
+    readonly content: "Use internalQuery, internalMutation, and internalAction to register internal functions. These are private and not part of the app's public API. Use query/mutation/action only for functions that should be exposed publicly.";
+    readonly category: "function";
+    readonly severity: "warning";
+    readonly tags: "internal,private,public,security,api";
+}, {
+    readonly key: "returns_validator_required";
+    readonly content: "Always include argument and return validators for ALL Convex functions (query, internalQuery, mutation, internalMutation, action, internalAction). If a function doesn't return anything, use returns: v.null().";
+    readonly category: "function";
+    readonly severity: "critical";
+    readonly tags: "returns,validator,null,args,required";
+}, {
+    readonly key: "no_register_via_api";
+    readonly content: "You CANNOT register a function through the api or internal objects. These are only for referencing already-registered functions.";
+    readonly category: "function";
+    readonly severity: "critical";
+    readonly tags: "register,api,internal,function";
+}, {
+    readonly key: "circular_type_annotation";
+    readonly content: "When using ctx.runQuery, ctx.runMutation, or ctx.runAction to call a function in the same file, specify a type annotation on the return value to work around TypeScript circularity limitations.";
+    readonly category: "function";
+    readonly severity: "warning";
+    readonly tags: "circular,type,annotation,typescript,same-file";
+}, {
+    readonly key: "array_max_8192";
+    readonly content: "Arrays can have at most 8192 values in Convex.";
+    readonly category: "validator";
+    readonly severity: "warning";
+    readonly tags: "array,limit,8192,size";
+}, {
+    readonly key: "object_max_1024";
+    readonly content: "Objects can have at most 1024 entries in Convex.";
+    readonly category: "validator";
+    readonly severity: "warning";
+    readonly tags: "object,limit,1024,entries";
+}, {
+    readonly key: "field_no_dollar_underscore";
+    readonly content: "Field names must be nonempty and not start with '$' or '_'. These prefixes are reserved for system use.";
+    readonly category: "schema";
+    readonly severity: "critical";
+    readonly tags: "field,name,dollar,underscore,reserved";
+}, {
+    readonly key: "index_name_include_fields";
+    readonly content: "Always include all index fields in the index name. For example, if an index is defined as ['field1', 'field2'], the index name should be 'by_field1_and_field2'.";
+    readonly category: "schema";
+    readonly severity: "info";
+    readonly tags: "index,name,convention,fields";
+}, {
+    readonly key: "http_exact_path";
+    readonly content: "HTTP endpoints are always registered at the exact path you specify. For example, /api/someRoute registers at /api/someRoute, not as a prefix match.";
+    readonly category: "function";
+    readonly severity: "info";
+    readonly tags: "http,path,route,endpoint,exact";
+}, {
+    readonly key: "record_key_restrictions";
+    readonly content: "Record keys must be only ASCII characters, nonempty, and not start with '$' or '_'.";
+    readonly category: "validator";
+    readonly severity: "warning";
+    readonly tags: "record,key,ascii,restriction";
+}, {
+    readonly key: "string_utf8_1mb";
+    readonly content: "Strings are stored as UTF-8 and must be valid Unicode sequences. Strings must be smaller than the 1MB total size limit when encoded as UTF-8.";
+    readonly category: "validator";
+    readonly severity: "info";
+    readonly tags: "string,utf8,size,limit,1mb";
+}, {
+    readonly key: "minimize_action_to_query_calls";
+    readonly content: "Try to use as few calls from actions to queries and mutations as possible. Queries and mutations are transactions, so splitting logic into multiple calls introduces race condition risk.";
+    readonly category: "function";
+    readonly severity: "warning";
+    readonly tags: "action,query,mutation,transaction,race,condition";
+}];
+export type ConvexGotcha = typeof CONVEX_GOTCHAS[number];

package/dist/gotchaSeed.js

@@ -0,0 +1,147 @@
+/**
+ * Pre-seeded Convex gotchas extracted from convexRules.md and common patterns.
+ * These are loaded into the DB on first run.
+ */
+export const CONVEX_GOTCHAS = [
+    {
+        key: "validator_bigint_deprecated",
+        content: "v.bigint() is deprecated for representing signed 64-bit integers. Use v.int64() instead.",
+        category: "validator",
+        severity: "critical",
+        tags: "bigint,int64,deprecated,validator",
+    },
+    {
+        key: "undefined_not_valid",
+        content: "JavaScript's undefined is not a valid Convex value. Functions that return undefined or do not return will return null when called from a client. Use null instead of undefined.",
+        category: "validator",
+        severity: "critical",
+        tags: "undefined,null,return,value",
+    },
+    {
+        key: "system_fields_auto",
+        content: "_creationTime (v.number()) and _id (v.id(tableName)) are automatically added to all documents as system fields. Do not include them in your schema definition.",
+        category: "schema",
+        severity: "warning",
+        tags: "_creationTime,_id,system,fields,schema",
+    },
+    {
+        key: "index_field_order",
+        content: "Index fields must be queried in the same order they are defined. If you want to query by field1 then field2 AND by field2 then field1, you must create separate indexes.",
+        category: "schema",
+        severity: "critical",
+        tags: "index,order,query,field",
+    },
+    {
+        key: "no_map_set_validators",
+        content: "v.map() and v.set() are not supported. Use v.record(keys, values) for defining record types instead.",
+        category: "validator",
+        severity: "critical",
+        tags: "map,set,record,validator,unsupported",
+    },
+    {
+        key: "action_from_action",
+        content: "Only call an action from another action if you need to cross runtimes (e.g. from V8 to Node). Otherwise, extract the shared code into a helper async function and call that directly.",
+        category: "function",
+        severity: "warning",
+        tags: "action,runtime,v8,node,helper",
+    },
+    {
+        key: "function_ref_not_direct",
+        content: "Use api.x.y or internal.x.y function references when calling ctx.runQuery/runMutation/runAction. Do NOT try to pass the callee function directly.",
+        category: "function",
+        severity: "critical",
+        tags: "function,reference,api,internal,runQuery",
+    },
+    {
+        key: "new_function_syntax",
+        content: "Always use the new function syntax: query({ args: {}, returns: v.null(), handler: async (ctx, args) => { } }). The old style without args/returns objects is deprecated.",
+        category: "function",
+        severity: "critical",
+        tags: "syntax,query,mutation,action,args,returns",
+    },
+    {
+        key: "internal_for_private",
+        content: "Use internalQuery, internalMutation, and internalAction to register internal functions. These are private and not part of the app's public API. Use query/mutation/action only for functions that should be exposed publicly.",
+        category: "function",
+        severity: "warning",
+        tags: "internal,private,public,security,api",
+    },
+    {
+        key: "returns_validator_required",
+        content: "Always include argument and return validators for ALL Convex functions (query, internalQuery, mutation, internalMutation, action, internalAction). If a function doesn't return anything, use returns: v.null().",
+        category: "function",
+        severity: "critical",
+        tags: "returns,validator,null,args,required",
+    },
+    {
+        key: "no_register_via_api",
+        content: "You CANNOT register a function through the api or internal objects. These are only for referencing already-registered functions.",
+        category: "function",
+        severity: "critical",
+        tags: "register,api,internal,function",
+    },
+    {
+        key: "circular_type_annotation",
+        content: "When using ctx.runQuery, ctx.runMutation, or ctx.runAction to call a function in the same file, specify a type annotation on the return value to work around TypeScript circularity limitations.",
+        category: "function",
+        severity: "warning",
+        tags: "circular,type,annotation,typescript,same-file",
+    },
+    {
+        key: "array_max_8192",
+        content: "Arrays can have at most 8192 values in Convex.",
+        category: "validator",
+        severity: "warning",
+        tags: "array,limit,8192,size",
+    },
+    {
+        key: "object_max_1024",
+        content: "Objects can have at most 1024 entries in Convex.",
+        category: "validator",
+        severity: "warning",
+        tags: "object,limit,1024,entries",
+    },
+    {
+        key: "field_no_dollar_underscore",
+        content: "Field names must be nonempty and not start with '$' or '_'. These prefixes are reserved for system use.",
+        category: "schema",
+        severity: "critical",
+        tags: "field,name,dollar,underscore,reserved",
+    },
+    {
+        key: "index_name_include_fields",
+        content: "Always include all index fields in the index name. For example, if an index is defined as ['field1', 'field2'], the index name should be 'by_field1_and_field2'.",
+        category: "schema",
+        severity: "info",
+        tags: "index,name,convention,fields",
+    },
+    {
+        key: "http_exact_path",
+        content: "HTTP endpoints are always registered at the exact path you specify. For example, /api/someRoute registers at /api/someRoute, not as a prefix match.",
+        category: "function",
+        severity: "info",
+        tags: "http,path,route,endpoint,exact",
+    },
+    {
+        key: "record_key_restrictions",
+        content: "Record keys must be only ASCII characters, nonempty, and not start with '$' or '_'.",
+        category: "validator",
+        severity: "warning",
+        tags: "record,key,ascii,restriction",
+    },
+    {
+        key: "string_utf8_1mb",
+        content: "Strings are stored as UTF-8 and must be valid Unicode sequences. Strings must be smaller than the 1MB total size limit when encoded as UTF-8.",
+        category: "validator",
+        severity: "info",
+        tags: "string,utf8,size,limit,1mb",
+    },
+    {
+        key: "minimize_action_to_query_calls",
+        content: "Try to use as few calls from actions to queries and mutations as possible. Queries and mutations are transactions, so splitting logic into multiple calls introduces race condition risk.",
+        category: "function",
+        severity: "warning",
+        tags: "action,query,mutation,transaction,race,condition",
+    },
+];
+//# sourceMappingURL=gotchaSeed.js.map

package/dist/gotchaSeed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gotchaSeed.js","sourceRoot":"","sources":["../src/gotchaSeed.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * convex-mcp-nodebench — Convex-Specific MCP Server
+ *
+ * Applies NodeBench self-instruct diligence patterns to Convex development.
+ * Schema audit, function compliance, deployment gates, persistent gotcha DB,
+ * and methodology guidance.
+ *
+ * Data stored in ~/.convex-mcp-nodebench/convex.db
+ *
+ * Usage:
+ *   npx convex-mcp-nodebench          (stdio transport)
+ *   npx tsx src/index.ts              (dev mode)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * convex-mcp-nodebench — Convex-Specific MCP Server
+ *
+ * Applies NodeBench self-instruct diligence patterns to Convex development.
+ * Schema audit, function compliance, deployment gates, persistent gotcha DB,
+ * and methodology guidance.
+ *
+ * Data stored in ~/.convex-mcp-nodebench/convex.db
+ *
+ * Usage:
+ *   npx convex-mcp-nodebench          (stdio transport)
+ *   npx tsx src/index.ts              (dev mode)
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { getDb, seedGotchasIfEmpty } from "./db.js";
+import { schemaTools } from "./tools/schemaTools.js";
+import { functionTools } from "./tools/functionTools.js";
+import { deploymentTools } from "./tools/deploymentTools.js";
+import { learningTools } from "./tools/learningTools.js";
+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 { CONVEX_GOTCHAS } from "./gotchaSeed.js";
+// ── All tools ───────────────────────────────────────────────────────
+const ALL_TOOLS = [
+    ...schemaTools,
+    ...functionTools,
+    ...deploymentTools,
+    ...learningTools,
+    ...methodologyTools,
+    ...integrationBridgeTools,
+    ...cronTools,
+    ...componentTools,
+];
+const toolMap = new Map();
+for (const tool of ALL_TOOLS) {
+    toolMap.set(tool.name, tool);
+}
+// ── Server setup ────────────────────────────────────────────────────
+const server = new Server({
+    name: "convex-mcp-nodebench",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// ── Initialize DB + seed gotchas ────────────────────────────────────
+getDb();
+seedGotchasIfEmpty(CONVEX_GOTCHAS);
+// ── Tool listing ────────────────────────────────────────────────────
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: ALL_TOOLS.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        })),
+    };
+});
+// ── Tool execution ──────────────────────────────────────────────────
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const tool = toolMap.get(name);
+    if (!tool) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: `Unknown tool: ${name}`,
+                        availableTools: ALL_TOOLS.map((t) => t.name),
+                    }),
+                },
+            ],
+        };
+    }
+    try {
+        const result = await tool.handler(args || {});
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: error.message || String(error),
+                        tool: name,
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ── Start server ────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Server is now running on stdio
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/componentTools.d.ts

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

package/dist/tools/componentTools.js

@@ -0,0 +1,131 @@
+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 parseConvexConfig(content) {
+    const components = [];
+    const issues = [];
+    const lines = content.split("\n");
+    // Find all import lines for convex.config
+    const importPattern = /import\s+(\w+)\s+from\s+["'](@[\w/-]+)\/convex\.config["']/g;
+    let match;
+    while ((match = importPattern.exec(content)) !== null) {
+        const importName = match[1];
+        const packageName = match[2];
+        const lineNumber = content.substring(0, match.index).split("\n").length;
+        // Check if this component is used (app.use(...))
+        const usePattern = new RegExp(`app\\.use\\(${importName}\\)`, "g");
+        const isUsed = usePattern.test(content);
+        // Check if conditional
+        const conditionalPattern = new RegExp(`if\\s*\\([^)]*\\)\\s*\\{[^}]*app\\.use\\(${importName}\\)`, "s");
+        const isConditional = conditionalPattern.test(content);
+        components.push({
+            importName,
+            packageName,
+            configPath: `${packageName}/convex.config`,
+            isUsed,
+            isConditional,
+            line: lineNumber,
+        });
+    }
+    // Check for unused imports
+    for (const comp of components) {
+        if (!comp.isUsed) {
+            issues.push(`WARNING: Component "${comp.importName}" (${comp.packageName}) is imported but never used with app.use()`);
+        }
+    }
+    // Check for defineApp
+    if (!content.includes("defineApp")) {
+        issues.push("CRITICAL: Missing defineApp() — convex.config.ts must call defineApp()");
+    }
+    // Check for default export
+    if (!content.includes("export default")) {
+        issues.push("CRITICAL: Missing default export — convex.config.ts must export the app");
+    }
+    // Check for process.env usage (allowed but noteworthy)
+    const envUsages = content.match(/process\.env\.\w+/g) || [];
+    if (envUsages.length > 0) {
+        issues.push(`INFO: ${envUsages.length} environment variable(s) used for conditional component loading: ${envUsages.join(", ")}`);
+    }
+    return { components, issues };
+}
+// ── Tool Definitions ────────────────────────────────────────────────
+export const componentTools = [
+    {
+        name: "convex_analyze_components",
+        description: "Analyze Convex component imports in convex.config.ts. Lists all installed Convex components (agent, workflow, rag, etc.), checks for unused imports, conditional loading, and configuration issues. Essential before adding new components to avoid conflicts.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectDir: {
+                    type: "string",
+                    description: "Absolute path to the project root",
+                },
+            },
+            required: ["projectDir"],
+        },
+        handler: async (args) => {
+            const projectDir = resolve(args.projectDir);
+            const convexDir = findConvexDir(projectDir);
+            if (!convexDir)
+                return { error: "No convex/ directory found" };
+            const configPath = join(convexDir, "convex.config.ts");
+            if (!existsSync(configPath)) {
+                return {
+                    hasConfig: false,
+                    message: "No convex.config.ts found — project uses no Convex components",
+                    quickRef: getQuickRef("convex_get_methodology"),
+                };
+            }
+            const content = readFileSync(configPath, "utf-8");
+            const { components, issues } = parseConvexConfig(content);
+            // Check package.json for component versions
+            const pkgPath = join(projectDir, "package.json");
+            let componentVersions = {};
+            if (existsSync(pkgPath)) {
+                try {
+                    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+                    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+                    for (const comp of components) {
+                        if (allDeps[comp.packageName]) {
+                            componentVersions[comp.packageName] = allDeps[comp.packageName];
+                        }
+                    }
+                }
+                catch { /* ignore */ }
+            }
+            const criticalCount = issues.filter((i) => i.startsWith("CRITICAL")).length;
+            const warningCount = issues.filter((i) => i.startsWith("WARNING")).length;
+            return {
+                hasConfig: true,
+                totalComponents: components.length,
+                activeComponents: components.filter((c) => c.isUsed).length,
+                conditionalComponents: components.filter((c) => c.isConditional).length,
+                components: components.map((c) => ({
+                    name: c.importName,
+                    package: c.packageName,
+                    version: componentVersions[c.packageName] || "unknown",
+                    isUsed: c.isUsed,
+                    isConditional: c.isConditional,
+                    line: c.line,
+                })),
+                issues: {
+                    total: issues.length,
+                    critical: criticalCount,
+                    warnings: warningCount,
+                    details: issues,
+                },
+                quickRef: getQuickRef("convex_pre_deploy_gate"),
+            };
+        },
+    },
+];
+//# sourceMappingURL=componentTools.js.map

package/dist/tools/componentTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"componentTools.js","sourceRoot":"","sources":["../../src/tools/componentTools.ts"],"names":[],"mappings":"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"}

package/dist/tools/cronTools.d.ts

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