@teddysc/mcp-codemode 1.0.0

package/src/cli.ts

@@ -0,0 +1,249 @@
+#!/usr/bin/env bun
+/**
+ * mcp-codemode CLI
+ *
+ * Wraps one or more stdio/HTTP MCP servers with two codemode tools:
+ *   search  – LLM writes JS to inspect upstream tool schemas
+ *   execute – LLM writes JS to orchestrate upstream tools
+ *
+ * Usage:
+ *   mcp-codemode [options] -- <cmd> [args...]
+ *   mcp-codemode [options] <url>
+ *   mcp-codemode [options] --config ./mcp-codemode.toml
+ *
+ * Examples:
+ *   mcp-codemode -- bunx @playwright/mcp@latest --extension
+ *   mcp-codemode --no-add-search -- npx @modelcontextprotocol/server-filesystem /tmp
+ *   mcp-codemode https://mcp.example.com/sse
+ */
+
+import cac from "cac";
+import { loadTomlConfig } from "./config.js";
+import { runServer, type UpstreamConfig } from "./server.js";
+
+const cli = cac("mcp-codemode");
+
+cli
+  .option("--add-search", "Always expose the search tool (default: auto when >= 10 upstream tools)")
+  .option("--timeout <ms>", "Execution timeout in milliseconds")
+  .option("--name <name>", "MCP server name")
+  .option("--header <name:value>", "HTTP header for URL upstream mode (repeatable)")
+  .option(
+    "--execute-tool-list",
+    "Include available tools in execute description (use --no-execute-tool-list to hide)",
+  )
+  .option(
+    "--config <path>",
+    "Path to a TOML config file with one or more upstream servers",
+  );
+
+cli.help();
+cli.version("1.0.0");
+
+const { options, args: positional } = cli.parse();
+
+if (options.help || options.version) {
+  process.exit(0);
+}
+
+// --no-add-search sets options.addSearch = false via cac's built-in negation.
+// --add-search    sets options.addSearch = true.
+// Neither flag    leaves options.addSearch = undefined → auto-detect.
+const addSearch: boolean | undefined = options.addSearch;
+const executeToolList: boolean | undefined = options.executeToolList;
+const configPath: string | undefined = options.config;
+const headerOption: unknown = options.header;
+
+// Everything after -- lands in options['--']; positional args are a fallback
+// for the URL-only form (mcp-codemode <url>).
+const rest: string[] = (options["--"] as string[] | undefined) ?? [];
+const upstreamArgs = rest.length > 0 ? rest : positional;
+
+const KNOWN_OPTION_KEYS = new Set([
+  "--",
+  "help",
+  "version",
+  "addSearch",
+  "timeout",
+  "name",
+  "header",
+  "executeToolList",
+  "config",
+]);
+
+function camelToKebab(input: string): string {
+  return input.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+function unknownOptionArgs(
+  parsedOptions: Record<string, unknown>,
+): string[] {
+  const forwarded: string[] = [];
+  for (const [key, value] of Object.entries(parsedOptions)) {
+    if (KNOWN_OPTION_KEYS.has(key)) continue;
+    const flag = `--${camelToKebab(key)}`;
+    if (typeof value === "boolean") {
+      if (value) forwarded.push(flag);
+      else forwarded.push(`--no-${camelToKebab(key)}`);
+      continue;
+    }
+    if (typeof value === "number" || typeof value === "string") {
+      forwarded.push(flag, String(value));
+      continue;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        forwarded.push(flag, String(item));
+      }
+    }
+  }
+  return forwarded;
+}
+
+function debugUpstreamSpawn(command: string, args: string[]): void {
+  if (!process.env.MCP_CODEMODE_DEBUG_UPSTREAM) return;
+  process.stderr.write(
+    `[mcp-codemode] upstream spawn: ${JSON.stringify({ command, args })}\n`,
+  );
+}
+
+if (configPath && upstreamArgs.length > 0) {
+  console.error(
+    "mcp-codemode: Cannot combine --config with positional/-- upstream args.\n" +
+    "Use one mode:\n" +
+    "  config: mcp-codemode [options] --config ./mcp-codemode.toml\n" +
+    "  stdio:  mcp-codemode [options] -- <cmd> [args...]\n" +
+    "  http:   mcp-codemode [options] <url>",
+  );
+  process.exit(1);
+}
+
+function isHttpUrl(value: string): boolean {
+  return value.startsWith("http://") || value.startsWith("https://");
+}
+
+function parseTimeoutMs(value: unknown, field: string): number | undefined {
+  if (value === undefined) return undefined;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${field} must be a number > 0.`);
+  }
+  return parsed;
+}
+
+function expandEnvPlaceholders(value: string, field: string): string {
+  return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name: string) => {
+    const envValue = process.env[name];
+    if (envValue === undefined) {
+      throw new Error(`${field} references \${${name}} but ${name} is not set.`);
+    }
+    return envValue;
+  });
+}
+
+function parseHeader(raw: string): [name: string, value: string] {
+  const separator = raw.indexOf(":");
+  if (separator <= 0) {
+    throw new Error(
+      `--header must use "Name: Value" format. Received: ${JSON.stringify(raw)}`,
+    );
+  }
+  const name = raw.slice(0, separator).trim();
+  const value = raw.slice(separator + 1).trim();
+  if (!name) {
+    throw new Error(`--header contains an empty header name.`);
+  }
+  return [name, expandEnvPlaceholders(value, `--header:${name}`)];
+}
+
+function parseCliHeaders(value: unknown): Record<string, string> | undefined {
+  if (value === undefined) return undefined;
+  const values = Array.isArray(value) ? value : [value];
+  const headers: Record<string, string> = {};
+
+  for (const entry of values) {
+    if (typeof entry !== "string") {
+      throw new Error(`--header values must be strings.`);
+    }
+    const [name, parsedValue] = parseHeader(entry);
+    headers[name] = parsedValue;
+  }
+
+  return headers;
+}
+
+const cliHttpHeaders = parseCliHeaders(headerOption);
+
+if (configPath && cliHttpHeaders) {
+  console.error(
+    "mcp-codemode: --header is only supported in URL upstream mode.\n" +
+      "Use per-server `headers` in your TOML file when using --config.",
+  );
+  process.exit(1);
+}
+
+let upstreams: UpstreamConfig[] = [];
+let timeoutMs: number | undefined;
+let serverName: string | undefined;
+let effectiveAddSearch: boolean | undefined = addSearch;
+let effectiveExecuteToolList = executeToolList ?? true;
+
+if (configPath) {
+  const fileConfig = await loadTomlConfig(String(configPath));
+  upstreams = fileConfig.upstreams;
+  timeoutMs =
+    parseTimeoutMs(options.timeout, "--timeout") ?? fileConfig.timeoutMs;
+  serverName = (options.name as string | undefined) ?? fileConfig.serverName;
+  effectiveAddSearch = addSearch ?? fileConfig.addSearch;
+  effectiveExecuteToolList =
+    executeToolList ?? fileConfig.includeExecuteToolList ?? true;
+  if (process.env.MCP_CODEMODE_DEBUG_UPSTREAM) {
+    for (const upstream of upstreams) {
+      if (upstream.type === "http") debugUpstreamSpawn(upstream.url, []);
+      else debugUpstreamSpawn(upstream.command, upstream.args);
+    }
+  }
+}
+
+if (!configPath) {
+  if (upstreamArgs.length === 0) {
+    console.error(
+      "mcp-codemode: No upstream MCP server specified.\n" +
+        "  config: mcp-codemode [options] --config ./mcp-codemode.toml\n" +
+        "  stdio:  mcp-codemode [options] -- <cmd> [args...]\n" +
+        "  http:   mcp-codemode [options] <url>",
+    );
+    process.exit(1);
+  }
+
+  const [command, ...cmdArgs] = upstreamArgs;
+  const recoveredUnknownArgs =
+    rest.length === 0 ? unknownOptionArgs(options as Record<string, unknown>) : [];
+  const mergedCmdArgs = [...cmdArgs, ...recoveredUnknownArgs];
+  if (isHttpUrl(command)) {
+    upstreams = [
+      { id: "upstream", type: "http", url: command, headers: cliHttpHeaders },
+    ];
+    debugUpstreamSpawn(command, []);
+  } else {
+    if (cliHttpHeaders) {
+      console.error(
+        "mcp-codemode: --header can only be used when the upstream is an http(s) URL.",
+      );
+      process.exit(1);
+    }
+    upstreams = [{ id: "upstream", type: "stdio", command, args: mergedCmdArgs }];
+    debugUpstreamSpawn(command, mergedCmdArgs);
+  }
+
+  timeoutMs = parseTimeoutMs(options.timeout, "--timeout");
+  serverName = options.name as string | undefined;
+}
+
+await runServer({
+  upstreams,
+  timeoutMs: timeoutMs ?? 60_000,
+  serverName: serverName ?? "mcp-codemode",
+  addSearch: effectiveAddSearch,
+  includeExecuteToolList: effectiveExecuteToolList,
+});

package/src/config.ts

@@ -0,0 +1,236 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { UpstreamConfig } from "./server.js";
+
+type ConfigRecord = Record<string, unknown>;
+
+export interface FileConfig {
+  serverName?: string;
+  timeoutMs?: number;
+  addSearch?: boolean;
+  includeExecuteToolList?: boolean;
+  upstreams: UpstreamConfig[];
+}
+
+type BunToml = {
+  parse: (input: string) => unknown;
+};
+
+type BunGlobal = {
+  Bun?: {
+    TOML?: BunToml;
+  };
+};
+
+function asRecord(value: unknown, context: string): ConfigRecord {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${context} must be a TOML table/object.`);
+  }
+  return value as ConfigRecord;
+}
+
+function asOptionalString(
+  value: unknown,
+  field: string,
+): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string") {
+    throw new Error(`${field} must be a string.`);
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error(`${field} must not be empty.`);
+  }
+  return trimmed;
+}
+
+function asOptionalNumber(
+  value: unknown,
+  field: string,
+): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${field} must be a finite number.`);
+  }
+  if (value <= 0) {
+    throw new Error(`${field} must be greater than 0.`);
+  }
+  return value;
+}
+
+function asOptionalBoolean(
+  value: unknown,
+  field: string,
+): boolean | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean") {
+    throw new Error(`${field} must be a boolean.`);
+  }
+  return value;
+}
+
+function parseAddSearch(value: unknown): boolean | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "auto") return undefined;
+    if (normalized === "always") return true;
+    if (normalized === "never") return false;
+  }
+  throw new Error(
+    `add_search must be one of: true, false, "auto", "always", "never".`,
+  );
+}
+
+function parseStringArray(value: unknown, field: string): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`${field} must be an array of strings.`);
+  }
+  return value.map((item, index) => {
+    if (typeof item !== "string") {
+      throw new Error(`${field}[${index}] must be a string.`);
+    }
+    return item;
+  });
+}
+
+function expandEnvPlaceholders(value: string, field: string): string {
+  return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name: string) => {
+    const envValue = process.env[name];
+    if (envValue === undefined) {
+      throw new Error(`${field} references \${${name}} but ${name} is not set.`);
+    }
+    return envValue;
+  });
+}
+
+function parseStringRecord(
+  value: unknown,
+  field: string,
+): Record<string, string> | undefined {
+  if (value === undefined) return undefined;
+  const table = asRecord(value, field);
+  const parsed: Record<string, string> = {};
+
+  for (const [key, raw] of Object.entries(table)) {
+    const name = key.trim();
+    if (name.length === 0) {
+      throw new Error(`${field} contains an empty header name.`);
+    }
+    if (typeof raw !== "string") {
+      throw new Error(`${field}.${name} must be a string.`);
+    }
+    parsed[name] = expandEnvPlaceholders(raw, `${field}.${name}`);
+  }
+
+  return parsed;
+}
+
+function parseUpstreams(value: unknown): UpstreamConfig[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(`servers must be a non-empty array of TOML tables.`);
+  }
+
+  const seenIds = new Set<string>();
+  const upstreams: UpstreamConfig[] = [];
+
+  value.forEach((entry, index) => {
+    const table = asRecord(entry, `servers[${index}]`);
+    const id =
+      asOptionalString(table["id"], `servers[${index}].id`) ??
+      `server${index + 1}`;
+    if (seenIds.has(id)) {
+      throw new Error(`Duplicate server id "${id}". Each server id must be unique.`);
+    }
+    seenIds.add(id);
+
+    const type = asOptionalString(table["type"], `servers[${index}].type`);
+    if (!type) {
+      throw new Error(`servers[${index}].type is required.`);
+    }
+
+    if (type === "stdio") {
+      const command = asOptionalString(
+        table["command"],
+        `servers[${index}].command`,
+      );
+      if (!command) {
+        throw new Error(`servers[${index}].command is required for stdio servers.`);
+      }
+      const args = parseStringArray(table["args"], `servers[${index}].args`);
+      upstreams.push({ id, type: "stdio", command, args });
+      return;
+    }
+
+    if (type === "http") {
+      const url = asOptionalString(table["url"], `servers[${index}].url`);
+      if (!url) {
+        throw new Error(`servers[${index}].url is required for http servers.`);
+      }
+      const headers = parseStringRecord(
+        table["headers"],
+        `servers[${index}].headers`,
+      );
+      let parsed: URL;
+      try {
+        parsed = new URL(url);
+      } catch {
+        throw new Error(`servers[${index}].url is not a valid URL.`);
+      }
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(
+          `servers[${index}].url must start with http:// or https://.`,
+        );
+      }
+      upstreams.push({
+        id,
+        type: "http",
+        url: parsed.toString(),
+        headers,
+      });
+      return;
+    }
+
+    throw new Error(
+      `servers[${index}].type must be "stdio" or "http", got "${type}".`,
+    );
+  });
+
+  return upstreams;
+}
+
+function parseToml(text: string, source: string): unknown {
+  const parser = (globalThis as BunGlobal).Bun?.TOML?.parse;
+  if (!parser) {
+    throw new Error(
+      `TOML parsing is unavailable (Bun.TOML.parse not found) while loading ${source}.`,
+    );
+  }
+  try {
+    return parser(text);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse TOML at ${source}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+export async function loadTomlConfig(configPath: string): Promise<FileConfig> {
+  const absolutePath = resolve(configPath);
+  const raw = await readFile(absolutePath, "utf8");
+  const parsed = parseToml(raw, absolutePath);
+  const root = asRecord(parsed, "config");
+
+  return {
+    serverName: asOptionalString(root["name"], "name"),
+    timeoutMs: asOptionalNumber(root["timeout_ms"], "timeout_ms"),
+    addSearch: parseAddSearch(root["add_search"]),
+    includeExecuteToolList: asOptionalBoolean(
+      root["include_execute_tool_list"],
+      "include_execute_tool_list",
+    ),
+    upstreams: parseUpstreams(root["servers"]),
+  };
+}

package/src/executor.ts

@@ -0,0 +1,116 @@
+/**
+ * Local in-process executor for codemode.
+ *
+ * Runs LLM-generated async arrow functions in Node's vm module with a
+ * captured `codemode` proxy that routes calls to the real tool functions.
+ *
+ * In production, DynamicWorkerExecutor (Cloudflare Workers) provides
+ * stronger isolation. For local use with Playwright MCP, vm is sufficient.
+ */
+
+import * as vm from "node:vm";
+
+export type ToolFns = Record<string, (...args: unknown[]) => Promise<unknown>>;
+
+export interface ExecuteResult {
+  result: unknown;
+  error?: string;
+  logs: string[];
+}
+
+export class LocalExecutor {
+  private timeoutMs: number;
+
+  constructor({ timeoutMs = 60_000 } = {}) {
+    // Playwright operations can be slow (page loads, etc.) — generous timeout
+    this.timeoutMs = timeoutMs;
+  }
+
+  async execute(code: string, fns: ToolFns): Promise<ExecuteResult> {
+    const logs: string[] = [];
+
+    const capturedConsole = {
+      log: (...args: unknown[]) => {
+        const msg = args.map(a =>
+          typeof a === "object" ? JSON.stringify(a) : String(a)
+        ).join(" ");
+        logs.push(msg);
+        process.stdout.write(`  [log] ${msg}\n`);
+      },
+      warn: (...args: unknown[]) => {
+        const msg = args.map(a => String(a)).join(" ");
+        logs.push(`[warn] ${msg}`);
+        process.stdout.write(`  [warn] ${msg}\n`);
+      },
+      error: (...args: unknown[]) => {
+        const msg = args.map(a => String(a)).join(" ");
+        logs.push(`[error] ${msg}`);
+        process.stdout.write(`  [error] ${msg}\n`);
+      },
+    };
+
+    // Build codemode proxy — calls the real tool fns directly
+    const codemode = new Proxy({} as Record<string, unknown>, {
+      get: (_target, prop: string) => {
+        const fn = fns[prop];
+        if (!fn) {
+          return () => Promise.reject(new Error(`Tool "${prop}" not found. Available: ${Object.keys(fns).join(", ")}`));
+        }
+        return fn;
+      },
+    });
+
+    const normalizedCode = normalizeCode(code);
+
+    // Use vm.createContext so we can pass in codemode + captured console
+    // without polluting global scope. We include fetch/setTimeout for helpers.
+    const g = globalThis as Record<string, unknown>;
+    const sandbox = {
+      codemode,
+      console: capturedConsole,
+      fetch: g["fetch"],
+      setTimeout: g["setTimeout"],
+      clearTimeout: g["clearTimeout"],
+      Promise: g["Promise"],
+      JSON: g["JSON"],
+      Math: g["Math"],
+      URL: g["URL"],
+      Error: g["Error"],
+    };
+
+    const context = vm.createContext(sandbox);
+
+    try {
+      // Script returns a Promise (the async arrow fn invocation).
+      // vm timeout only covers sync execution; we wrap in Promise.race for async.
+      const script = new vm.Script(`(${normalizedCode})()`, {
+        filename: "codemode-exec.js",
+      });
+      const timeoutPromise = new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error(`Execution timed out after ${this.timeoutMs}ms`)), this.timeoutMs)
+      );
+      const result = await Promise.race([script.runInContext(context), timeoutPromise]);
+      return { result, logs };
+    } catch (err) {
+      return {
+        result: undefined,
+        error: err instanceof Error ? err.message : String(err),
+        logs,
+      };
+    }
+  }
+}
+
+/**
+ * Ensures code is an async arrow function expression so we can call it.
+ * Mirrors codemode's normalizeCode behaviour (without the acorn dependency).
+ */
+function normalizeCode(code: string): string {
+  const trimmed = code.trim();
+
+  // Already an async arrow function
+  if (/^async\s*(\(|[a-zA-Z_$])/.test(trimmed)) return trimmed;
+
+  // Wrap bare body in async arrow function
+  return `async () => {\n${trimmed}\n}`;
+}