@sammorrowdrums/mcpi-ext 0.1.0

package/scripts/test-mcp-integration.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * Integration smoke test: connect to the test-echo-server via stdio,
+ * discover tools, call the echo tool, disconnect, exit 0.
+ */
+import { McpClientManager } from "../dist/mcp/client-manager.js";
+
+const manager = new McpClientManager();
+
+try {
+  await manager.connectAll(
+    {
+      mcpServers: {
+        "test-echo": {
+          type: "stdio",
+          command: "node",
+          args: ["scripts/test-echo-server.mjs"],
+        },
+      },
+    },
+    (msg) => console.log(msg),
+  );
+
+  const servers = manager.getConnectedServers();
+  if (servers.length !== 1) {
+    throw new Error(`Expected 1 server, got ${servers.length}`);
+  }
+
+  const tools = manager.getTools();
+  console.log(`Discovered ${tools.length} tool(s): ${tools.map((t) => t.name).join(", ")}`);
+
+  const echoTool = tools.find((t) => t.name === "echo");
+  if (!echoTool) {
+    throw new Error('Expected to find "echo" tool');
+  }
+
+  // Call the tool via the client
+  const client = manager.getClient("test-echo");
+  if (!client) throw new Error("No client for test-echo");
+
+  const result = await client.callTool({
+    name: "echo",
+    arguments: { message: "hello from integration test" },
+  });
+
+  const text = result.content?.[0]?.text;
+  if (text !== "hello from integration test") {
+    throw new Error(`Unexpected echo result: ${JSON.stringify(result)}`);
+  }
+  console.log(`Echo tool returned: "${text}"`);
+
+  await manager.disconnectAll();
+  console.log("Integration test passed ✓");
+  process.exit(0);
+} catch (err) {
+  console.error("Integration test failed:", err);
+  await manager.disconnectAll().catch(() => {});
+  process.exit(1);
+}

package/scripts/test-tool-cli-smoke.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Smoke test: start RPC server with the weather test server,
+ * exercise every tool-cli command, then shut down.
+ */
+import { McpClientManager } from "../dist/mcp/client-manager.js";
+import { ToolCliRpcServer } from "../dist/tool-cli/rpc-server.js";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const CLI = "dist/tool-cli/cli.js";
+const manager = new McpClientManager();
+let rpc;
+
+async function run(...args) {
+  const { stdout } = await execFileAsync("node", [CLI, ...args], {
+    encoding: "utf-8",
+    env: { ...process.env, TOOL_CLI_PORT: String(rpc.getPort()) },
+  });
+  console.log(`$ tool-cli ${args.join(" ")}`);
+  console.log(stdout);
+  return stdout;
+}
+
+try {
+  await manager.connectOne("weather", {
+    type: "stdio",
+    command: "node",
+    args: ["dist/test-servers/weather-stdio.js"],
+  });
+
+  rpc = new ToolCliRpcServer(manager, 0);
+  await rpc.start(console.log);
+
+  // --help: list servers
+  const help = await run("--help");
+  if (!help.includes("weather")) throw new Error("--help missing weather server");
+
+  // <server>: list tools
+  const tools = await run("weather");
+  if (!tools.includes("check_weather_for_city"))
+    throw new Error("tool list missing check_weather_for_city");
+
+  // <server> <tool>: describe
+  const desc = await run("weather", "check_weather_for_city");
+  if (!desc.includes("city")) throw new Error("describe missing city param");
+
+  // <server> <tool> <args>: call
+  const result = await run("weather", "check_weather_for_city", '{"city":"London"}');
+  if (!result.includes("London")) throw new Error("call result missing London");
+
+  await rpc.stop();
+  await manager.disconnectAll();
+  console.log("Smoke test passed ✓");
+  process.exit(0);
+} catch (err) {
+  console.error("Smoke test failed:", err);
+  await rpc?.stop().catch(() => {});
+  await manager.disconnectAll().catch(() => {});
+  process.exit(1);
+}

package/src/code-mode/code-mode-integration.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { McpClientManager } from "../mcp/client-manager.js";
+import { CodeModeManager } from "./index.js";
+
+/**
+ * Integration test: connect to the test weather server, verify code mode
+ * eligibility, type hint generation, and sandboxed execution with real
+ * MCP tool calls returning structuredContent.
+ */
+describe("code mode integration (weather server)", () => {
+  const manager = new McpClientManager();
+  const codeMode = new CodeModeManager();
+
+  beforeAll(async () => {
+    await manager.connectAll({
+      mcpServers: {
+        "test-weather": {
+          type: "stdio",
+          command: "node",
+          args: ["dist/test-servers/weather-stdio.js"],
+        },
+      },
+    });
+
+    codeMode.initialize(manager);
+  });
+
+  afterAll(async () => {
+    await manager.disconnectAll();
+  });
+
+  it("discovers eligible tools with readOnlyHint + outputSchema", () => {
+    const eligible = codeMode.getEligibleTools();
+    expect(eligible.length).toBeGreaterThanOrEqual(2);
+    const names = eligible.map((t) => t.name).sort();
+    expect(names).toContain("check_weather_for_city");
+    expect(names).toContain("check_weekly_forecast_for_city");
+    expect(names).toContain("echo");
+  });
+
+  it("generates type hints for eligible tools", () => {
+    const hints = codeMode.getTypeHints();
+    expect(hints).toContain("declare const codemode");
+    expect(hints).toContain("check_weather_for_city");
+    expect(hints).toContain("check_weekly_forecast_for_city");
+    expect(hints).toContain("echo");
+    expect(hints).toContain("listTools");
+  });
+
+  it("reports as active", () => {
+    expect(codeMode.isActive).toBe(true);
+  });
+
+  it("generates system prompt section", () => {
+    const section = codeMode.formatSystemPromptSection();
+    expect(section).toContain("<code_mode>");
+    expect(section).toContain("code_search");
+    expect(section).toContain("code_execute");
+    expect(section).toContain("declare const codemode");
+  });
+
+  it("executes code that calls a single tool", async () => {
+    const result = await codeMode.executeCode(`
+      const weather = await codemode.check_weather_for_city({ city: "Tokyo" });
+      return weather;
+    `);
+
+    expect(result.error).toBeUndefined();
+    expect(result.result).toHaveProperty("temperature", 26);
+    expect(result.result).toHaveProperty("conditions", "Sunny");
+    expect(result.result).toHaveProperty("humidity", 55);
+  });
+
+  it("executes code that chains multiple tool calls", async () => {
+    const result = await codeMode.executeCode(`
+      const cities = ["London", "Tokyo"];
+      const results = [];
+      for (const city of cities) {
+        const w = await codemode.check_weather_for_city({ city });
+        results.push({ city, temp: w.temperature });
+      }
+      return results;
+    `);
+
+    expect(result.error).toBeUndefined();
+    expect(result.result).toEqual([
+      { city: "London", temp: 14 },
+      { city: "Tokyo", temp: 26 },
+    ]);
+  });
+
+  it("executes code that uses listTools", async () => {
+    const result = await codeMode.executeCode(`
+      const tools = await codemode.listTools();
+      return tools.sort();
+    `);
+
+    expect(result.error).toBeUndefined();
+    const names = result.result as string[];
+    expect(names).toContain("check_weather_for_city");
+    expect(names).toContain("echo");
+  });
+
+  it("executes code that calls echo tool", async () => {
+    const result = await codeMode.executeCode(`
+      const r = await codemode.echo({ message: "hello code mode" });
+      return r;
+    `);
+
+    expect(result.error).toBeUndefined();
+    expect(result.result).toEqual({ echo: "hello code mode" });
+  });
+
+  it("handles tool errors gracefully", async () => {
+    const result = await codeMode.executeCode(`
+      const w = await codemode.check_weather_for_city({ city: "Atlantis" });
+      return w;
+    `);
+
+    // Atlantis isn't in the data — server returns text-only content (no structuredContent)
+    // The executor should still return something (parsed text or raw string)
+    expect(result.error).toBeUndefined();
+    expect(result.result).toBeDefined();
+  });
+
+  it("search mode works for tool discovery", async () => {
+    const result = await codeMode.searchTools(`
+      const tools = await codemode.listTools();
+      return tools;
+    `);
+
+    expect(result.error).toBeUndefined();
+    expect(Array.isArray(result.result)).toBe(true);
+  });
+});

package/src/code-mode/eligibility.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import type { McpTool } from "../mcp/index.js";
+import { isEligibleForCodeMode } from "./eligibility.js";
+
+function makeTool(overrides: Partial<McpTool> = {}): McpTool {
+  return {
+    name: "test_tool",
+    description: "A test tool",
+    inputSchema: { type: "object", properties: {} },
+    serverName: "test-server",
+    ...overrides,
+  };
+}
+
+describe("isEligibleForCodeMode", () => {
+  it("returns true when readOnlyHint is true and outputSchema is defined", () => {
+    const tool = makeTool({
+      annotations: { readOnlyHint: true },
+      outputSchema: { type: "object", properties: { result: { type: "string" } } },
+    });
+    expect(isEligibleForCodeMode(tool)).toBe(true);
+  });
+
+  it("returns false when readOnlyHint is false", () => {
+    const tool = makeTool({
+      annotations: { readOnlyHint: false },
+      outputSchema: { type: "object", properties: {} },
+    });
+    expect(isEligibleForCodeMode(tool)).toBe(false);
+  });
+
+  it("returns false when readOnlyHint is missing", () => {
+    const tool = makeTool({
+      annotations: {},
+      outputSchema: { type: "object", properties: {} },
+    });
+    expect(isEligibleForCodeMode(tool)).toBe(false);
+  });
+
+  it("returns false when annotations is undefined", () => {
+    const tool = makeTool({
+      annotations: undefined,
+      outputSchema: { type: "object", properties: {} },
+    });
+    expect(isEligibleForCodeMode(tool)).toBe(false);
+  });
+
+  it("returns false when outputSchema is missing", () => {
+    const tool = makeTool({
+      annotations: { readOnlyHint: true },
+      outputSchema: undefined,
+    });
+    expect(isEligibleForCodeMode(tool)).toBe(false);
+  });
+
+  it("returns false when both readOnlyHint and outputSchema are missing", () => {
+    const tool = makeTool();
+    expect(isEligibleForCodeMode(tool)).toBe(false);
+  });
+});

package/src/code-mode/eligibility.ts

@@ -0,0 +1,16 @@
+import type { McpClientManager, McpTool } from "../mcp/index.js";
+
+/**
+ * A tool is eligible for code mode when:
+ * 1. annotations.readOnlyHint === true — does not modify its environment
+ * 2. outputSchema is defined — results are typed and parseable
+ */
+export function isEligibleForCodeMode(tool: McpTool): boolean {
+  const annotations = tool.annotations as { readOnlyHint?: boolean } | undefined;
+  return annotations?.readOnlyHint === true && tool.outputSchema != null;
+}
+
+/** Get all tools eligible for code mode across all connected MCP servers. */
+export function getEligibleTools(mcpManager: McpClientManager): McpTool[] {
+  return mcpManager.getTools().filter(isEligibleForCodeMode);
+}

package/src/code-mode/executor.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from "vitest";
+import { executeInSandbox, normalizeCode } from "./executor.js";
+
+describe("normalizeCode", () => {
+  it("strips markdown code fences", () => {
+    expect(normalizeCode("```js\nconst x = 1;\n```")).toBe("const x = 1;");
+  });
+
+  it("strips typescript fences", () => {
+    expect(normalizeCode("```typescript\nconst x = 1;\n```")).toBe("const x = 1;");
+  });
+
+  it("wraps arrow function in invocation", () => {
+    expect(normalizeCode("async () => { return 42; }")).toBe(
+      "return (async () => { return 42; })();",
+    );
+  });
+
+  it("wraps function declaration in invocation", () => {
+    const code = "async function main() { return 42; }";
+    const result = normalizeCode(code);
+    expect(result).toContain("async function main()");
+    expect(result).toContain("return main();");
+  });
+
+  it("strips export default", () => {
+    const result = normalizeCode("export default async () => { return 42; }");
+    expect(result).toContain("return (async () => { return 42; })();");
+  });
+
+  it("leaves bare code as-is", () => {
+    expect(normalizeCode("const x = 1;\nreturn x;")).toBe("const x = 1;\nreturn x;");
+  });
+});
+
+describe("executeInSandbox", () => {
+  it("executes simple code and returns result", async () => {
+    const result = await executeInSandbox("return 2 + 2;", [], async () => ({}), {
+      timeoutMs: 5000,
+    });
+
+    expect(result.result).toBe(4);
+    expect(result.error).toBeUndefined();
+  });
+
+  it("captures console.log output", async () => {
+    const result = await executeInSandbox(
+      'console.log("hello", "world"); return 1;',
+      [],
+      async () => ({}),
+      { timeoutMs: 5000 },
+    );
+
+    expect(result.result).toBe(1);
+    expect(result.logs).toContain("hello world");
+  });
+
+  it("dispatches tool calls through the callback", async () => {
+    const dispatched: { name: string; args: Record<string, unknown> }[] = [];
+
+    const dispatch = async (name: string, args: Record<string, unknown>) => {
+      dispatched.push({ name, args });
+      return { results: ["doc1", "doc2"] };
+    };
+
+    const code = `
+      const result = await codemode.search_docs({ query: "test" });
+      return result;
+    `;
+
+    const result = await executeInSandbox(code, ["search_docs"], dispatch, { timeoutMs: 5000 });
+
+    expect(result.error).toBeUndefined();
+    expect(result.result).toEqual({ results: ["doc1", "doc2"] });
+    expect(dispatched).toHaveLength(1);
+    expect(dispatched[0].name).toBe("search_docs");
+    expect(dispatched[0].args).toEqual({ query: "test" });
+  });
+
+  it("handles tools with special characters in names", async () => {
+    const dispatched: string[] = [];
+
+    const dispatch = async (name: string) => {
+      dispatched.push(name);
+      return { ok: true };
+    };
+
+    const code = `
+      const result = await codemode.github_list_repos({});
+      return result;
+    `;
+
+    const result = await executeInSandbox(code, ["github.list-repos"], dispatch, {
+      timeoutMs: 5000,
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(dispatched).toContain("github.list-repos");
+  });
+
+  it("returns error for invalid code", async () => {
+    const result = await executeInSandbox("throw new Error('boom');", [], async () => ({}), {
+      timeoutMs: 5000,
+    });
+
+    expect(result.error).toContain("boom");
+    expect(result.result).toBeUndefined();
+  });
+
+  it("enforces timeout", async () => {
+    const result = await executeInSandbox("while(true) {}", [], async () => ({}), {
+      timeoutMs: 100,
+    });
+
+    expect(result.error).toBeDefined();
+    expect(result.result).toBeUndefined();
+  });
+
+  it("chains multiple tool calls", async () => {
+    const calls: string[] = [];
+
+    const dispatch = async (name: string, args: Record<string, unknown>) => {
+      calls.push(name);
+      if (name === "list_items") return { items: ["a", "b", "c"] };
+      if (name === "get_details") return { detail: `info for ${args.id}` };
+      return {};
+    };
+
+    const code = `
+      const { items } = await codemode.list_items({});
+      const details = [];
+      for (const id of items) {
+        const d = await codemode.get_details({ id });
+        details.push(d.detail);
+      }
+      return details;
+    `;
+
+    const result = await executeInSandbox(code, ["list_items", "get_details"], dispatch, {
+      timeoutMs: 5000,
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(result.result).toEqual(["info for a", "info for b", "info for c"]);
+    expect(calls).toEqual(["list_items", "get_details", "get_details", "get_details"]);
+  });
+
+  it("prevents imports", async () => {
+    const code = 'import("fs")';
+    const result = await executeInSandbox(code, [], async () => ({}), { timeoutMs: 5000 });
+
+    expect(result.error).toBeDefined();
+  });
+
+  it("listTools returns available tools", async () => {
+    const code = `
+      const tools = await codemode.listTools();
+      return tools;
+    `;
+
+    const result = await executeInSandbox(code, ["search", "execute"], async () => ({}), {
+      timeoutMs: 5000,
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(result.result).toEqual(["search", "execute"]);
+  });
+});

package/src/code-mode/executor.ts

@@ -0,0 +1,163 @@
+import ivm from "isolated-vm";
+import { sanitizeToolName } from "./type-hints.js";
+
+/** Result of code execution. */
+export interface ExecuteResult {
+  result: unknown;
+  error?: string;
+  logs: string[];
+}
+
+/** A function the sandbox can call to invoke an MCP tool. */
+export type ToolDispatchFn = (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
+
+export interface ExecutorOptions {
+  /** Memory limit in MB for the V8 isolate. Default: 128. */
+  memoryLimit?: number;
+  /** Execution timeout in milliseconds. Default: 30000. */
+  timeoutMs?: number;
+}
+
+const DEFAULT_MEMORY_LIMIT = 128;
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Execute model-generated JavaScript code in an isolated V8 sandbox.
+ *
+ * The code runs in a fresh `isolated-vm` isolate with:
+ * - Enforced memory limit (default 128MB)
+ * - Execution timeout (default 30s)
+ * - No access to Node.js APIs, filesystem, or network
+ * - Only access to provided tool dispatch functions via `codemode.*` proxy
+ *
+ * Tool calls are dispatched to the host via `Reference` callbacks —
+ * actual MCP tool execution happens outside the sandbox.
+ */
+export async function executeInSandbox(
+  code: string,
+  toolNames: string[],
+  dispatch: ToolDispatchFn,
+  options: ExecutorOptions = {},
+): Promise<ExecuteResult> {
+  const memoryLimit = options.memoryLimit ?? DEFAULT_MEMORY_LIMIT;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  const isolate = new ivm.Isolate({ memoryLimit });
+  try {
+    return await runInIsolate(isolate, code, toolNames, dispatch, timeoutMs);
+  } finally {
+    isolate.dispose();
+  }
+}
+
+async function runInIsolate(
+  isolate: ivm.Isolate,
+  code: string,
+  toolNames: string[],
+  dispatch: ToolDispatchFn,
+  timeoutMs: number,
+): Promise<ExecuteResult> {
+  const ctx = await isolate.createContext();
+  const jail = ctx.global;
+
+  const logs: string[] = [];
+
+  // Inject console.log that captures to logs array
+  const logCallback = new ivm.Callback((...args: unknown[]) => {
+    logs.push(args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" "));
+  });
+  await jail.set("__log", logCallback);
+
+  // Inject tool dispatcher Reference (async callback)
+  const dispatchRef = new ivm.Reference(async (toolName: string, argsJson: string) => {
+    const args = JSON.parse(argsJson) as Record<string, unknown>;
+    const result = await dispatch(toolName, args);
+    return JSON.stringify(result === undefined ? null : result);
+  });
+  await jail.set("__dispatch", dispatchRef);
+
+  // Build the tool call helper and codemode proxy as setup code
+  const toolProxyEntries = toolNames
+    .map((name) => {
+      const safe = sanitizeToolName(name);
+      return `    ${safe}: async (args) => __callTool(${JSON.stringify(name)}, args)`;
+    })
+    .join(",\n");
+
+  const normalized = normalizeCode(code);
+
+  // Use ctx.eval with { promise: true } instead of compileModule,
+  // because module.evaluate() can resolve prematurely with multiple
+  // sequential async Reference.apply calls.
+  const wrappedCode = `
+    (async () => {
+      const console = { log: (...args) => __log(args.map(a => typeof a === 'string' ? a : JSON.stringify(a)).join(' ')) };
+      const __callTool = async (name, args) => {
+        const r = await __dispatch.apply(undefined, [name, JSON.stringify(args ?? {})], { arguments: { copy: true }, result: { promise: true, copy: true } });
+        return JSON.parse(r);
+      };
+      const codemode = {
+        listTools: async () => ${JSON.stringify(toolNames)},
+        describeTools: async (names) => "Use the typed codemode.toolName(args) methods instead.",
+${toolProxyEntries}
+      };
+
+      const __userFn = async () => {
+        ${normalized}
+      };
+
+      return JSON.stringify({ value: await __userFn() });
+    })()
+  `;
+
+  try {
+    const rawResult = (await ctx.eval(wrappedCode, {
+      promise: true,
+      copy: true,
+      timeout: timeoutMs,
+    })) as string;
+
+    const parsed = JSON.parse(rawResult) as { value: unknown };
+    return { result: parsed.value, logs };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { result: undefined, error: message, logs };
+  }
+}
+
+/**
+ * Normalize model-generated code:
+ * - Strip markdown code fences
+ * - Handle arrow functions, function declarations, export default
+ * - Otherwise leave code as a statement block; callers must explicitly `return` a value
+ */
+export function normalizeCode(code: string): string {
+  let normalized = code.trim();
+
+  // Strip markdown code fences
+  normalized = normalized.replace(/^```(?:js|javascript|typescript|ts)?\s*\n?/i, "");
+  normalized = normalized.replace(/\n?```\s*$/i, "");
+  normalized = normalized.trim();
+
+  // If it's an arrow function or function expression, invoke it
+  if (/^(?:async\s+)?(?:\([^)]*\)|[a-zA-Z_$][a-zA-Z0-9_$]*)\s*=>/.test(normalized)) {
+    return `return (${normalized})();`;
+  }
+
+  // If it's a function declaration, invoke it
+  if (/^(?:async\s+)?function\s+/.test(normalized)) {
+    const match = normalized.match(/^(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/);
+    if (match) {
+      return `${normalized}\nreturn ${match[1]}();`;
+    }
+  }
+
+  // If it starts with export default, strip the export default
+  if (/^export\s+default\s+/.test(normalized)) {
+    normalized = normalized.replace(/^export\s+default\s+/, "");
+    return `return (${normalized})();`;
+  }
+
+  // Otherwise, treat as a code block — return the last expression
+  return normalized;
+}