@goke/mcp 0.0.8 → 0.0.10

package/dist/cli-to-mcp.js

@@ -5,8 +5,19 @@
  * or a high-level McpServer by mounting tools/list + tools/call handlers.
  */
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
-import { coerceBySchema, extractJsonSchema } from "goke";
+import { coerceBySchema, extractJsonSchema, GokeProcessExit, } from "goke";
 const CLI_TO_MCP_STATE = Symbol.for("@goke/mcp/cli-to-mcp-state");
+function createTextCaptureStream() {
+    const chunks = [];
+    return {
+        get text() {
+            return chunks.join("");
+        },
+        write(data) {
+            chunks.push(data);
+        },
+    };
+}
 function isMountableCommand(command, commandFilter) {
     if (!command.commandAction) {
         return false;
@@ -167,6 +178,90 @@ function isToolNotFoundResult(result, toolName) {
     const text = String(textBlock?.text ?? "").toLowerCase();
     return text.includes("tool") && text.includes("not found") && text.includes(toolName.toLowerCase());
 }
+/**
+ * Build the same `GokeExecutionContext` an action would receive from
+ * `cli.parse()`, but with capture streams for stdout/stderr and an
+ * `exit` that throws `GokeProcessExit` instead of killing the host
+ * process.
+ *
+ * Capturing is required for the stdio MCP transport because the host
+ * `process.stdout` is the JSON-RPC channel — any write to it would
+ * corrupt the protocol. Capturing is also what lets us surface
+ * `ctx.console.log` output in the `CallToolResult.content`.
+ */
+function createCallToolExecutionContext(cli) {
+    const stdout = createTextCaptureStream();
+    const stderr = createTextCaptureStream();
+    const ctx = cli.createExecutionContext({
+        stdout,
+        stderr,
+        // Swallow the user-level exit: the outer createExecutionContext
+        // wrapper will still throw `GokeProcessExit` after this returns,
+        // which `runCliTool` catches and turns into a `CallToolResult`.
+        exit: () => { },
+    });
+    return { ctx, stdout, stderr };
+}
+/**
+ * Build a `CallToolResult` from an action's return value plus any
+ * text that was captured from the injected `ctx.console` /
+ * `ctx.process.stdout` / `ctx.process.stderr` streams.
+ *
+ * Precedence rules:
+ *   1. If the action returned a ready-made `CallToolResult` (object
+ *      with a `content` key), honor it as-is. Captured output is
+ *      ignored to give authors a fully manual escape hatch.
+ *   2. If anything was captured on stdout or stderr, emit one text
+ *      block per non-empty stream (stdout first, then stderr) and
+ *      append the stringified return value as a trailing block when
+ *      it is non-empty. This keeps warnings written via
+ *      `ctx.console.error` / `ctx.process.stderr.write` from being
+ *      silently dropped when the action also returns a value.
+ *   3. Otherwise fall back to the legacy behavior (stringify the
+ *      return value, empty string when `undefined`).
+ */
+function buildCallToolResult(returnValue, capturedStdout, capturedStderr) {
+    if (returnValue && typeof returnValue === "object" && "content" in returnValue) {
+        return returnValue;
+    }
+    if (capturedStdout || capturedStderr) {
+        const blocks = [];
+        if (capturedStdout) {
+            blocks.push({ type: "text", text: capturedStdout });
+        }
+        if (capturedStderr) {
+            blocks.push({ type: "text", text: capturedStderr });
+        }
+        const valueText = formatTextResult(returnValue);
+        if (valueText) {
+            blocks.push({ type: "text", text: valueText });
+        }
+        return { content: blocks };
+    }
+    return toCallToolResult(returnValue);
+}
+/**
+ * Build an error `CallToolResult` from captured output + the process
+ * exit code thrown by `ctx.process.exit(code)`. Mirrors the
+ * `{ stdout, stderr, exitCode }` shape just-bash produces, but in the
+ * MCP content-block format.
+ */
+function buildProcessExitResult(exitCode, capturedStdout, capturedStderr) {
+    const content = [];
+    if (capturedStdout) {
+        content.push({ type: "text", text: capturedStdout });
+    }
+    if (capturedStderr) {
+        content.push({ type: "text", text: capturedStderr });
+    }
+    if (content.length === 0) {
+        content.push({ type: "text", text: `Process exited with code ${exitCode}` });
+    }
+    return {
+        isError: exitCode !== 0,
+        content,
+    };
+}
 async function runCliTool(binding, argumentsObject) {
     for (const requiredName of binding.requiredNames) {
         if (getToolCallArguments(argumentsObject, requiredName) === undefined) {
@@ -212,19 +307,35 @@ async function runCliTool(binding, argumentsObject) {
     if (!action) {
         throw new McpError(ErrorCode.InvalidParams, `Command ${binding.command.name} has no action`);
     }
+    // Build the same execution context an action would see when invoked
+    // from the command line, but with capture streams + a no-op `exit`
+    // so tool calls can't corrupt the MCP transport or kill the host.
+    const { ctx, stdout, stderr } = createCallToolExecutionContext(binding.cli);
     try {
-        const result = await Promise.resolve(action(...positionalValues, optionsObject));
-        return toCallToolResult(result);
+        // Match `Goke#runMatchedCommand` by calling the action with the
+        // owning cli as `this`. Keeps behavior parity for JS authors who
+        // reference `this.name` / `this.options` from inside an action.
+        const result = await Promise.resolve(action.apply(binding.cli, [...positionalValues, optionsObject, ctx]));
+        return buildCallToolResult(result, stdout.text, stderr.text);
     }
     catch (error) {
+        if (error instanceof GokeProcessExit) {
+            return buildProcessExitResult(error.code, stdout.text, stderr.text);
+        }
         const message = error instanceof Error ? error.message : String(error);
+        const content = [
+            { type: "text", text: message },
+        ];
+        if (stderr.text) {
+            content.push({ type: "text", text: stderr.text });
+        }
         return {
             isError: true,
-            content: [{ type: "text", text: message }],
+            content,
         };
     }
 }
-function createBinding(command, toolName) {
+function createBinding(cli, command, toolName) {
     const positionalArgs = command.args;
     const options = command.options;
     const properties = {};
@@ -272,6 +383,7 @@ function createBinding(command, toolName) {
             inputSchema,
         },
         command,
+        cli,
         positionalArgs,
         options: optionBindings,
         requiredNames: Array.from(new Set(requiredNames)),
@@ -342,6 +454,50 @@ function getOrInstallState(server) {
     });
     return state;
 }
+/**
+ * Create a goke action callback that starts an MCP server over stdio.
+ *
+ * Exposes all CLI commands as MCP tools, automatically excluding the
+ * command this action is attached to.
+ *
+ * @example
+ * ```ts
+ * cli.command('mcp', 'Start MCP server over stdio')
+ *   .action(createMcpAction({ cli }))
+ * ```
+ */
+export function createMcpAction(options) {
+    const { cli, commandFilter: userFilter, sanitizeToolName, serverName, serverVersion, createTransport } = options;
+    return async () => {
+        // At call time, goke has already matched the command and set matchedCommandName.
+        // We use it to auto-exclude the MCP command itself from the tool list.
+        const mcpCommandName = cli.matchedCommandName;
+        const { Server: ServerClass } = await import("@modelcontextprotocol/sdk/server/index.js");
+        const server = new ServerClass({
+            name: serverName || cli.name || "cli-mcp-server",
+            version: serverVersion || "1.0.0",
+        }, { capabilities: {} });
+        addCliToolsToMcp({
+            cli,
+            server,
+            commandFilter: (name) => {
+                if (mcpCommandName && name === mcpCommandName)
+                    return false;
+                return userFilter ? userFilter(name) : true;
+            },
+            sanitizeToolName,
+        });
+        let transport;
+        if (createTransport) {
+            transport = await createTransport();
+        }
+        else {
+            const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+            transport = new StdioServerTransport();
+        }
+        await server.connect(transport);
+    };
+}
 export function addCliToolsToMcp(options) {
     const { cli, commandFilter, sanitizeToolName = defaultSanitizeToolName } = options;
     const server = resolveServer(options.server);
@@ -373,7 +529,7 @@ export function addCliToolsToMcp(options) {
         const baseToolName = defaultSanitizeToolName(sanitizeToolName(command.name));
         const toolName = uniqueToolName(baseToolName, usedNames);
         usedNames.add(toolName);
-        const binding = createBinding(command, toolName);
+        const binding = createBinding(cli, command, toolName);
         state.toolsByName.set(toolName, binding);
         state.commandToToolName.set(command.name, toolName);
     }

package/dist/index.d.ts

@@ -42,8 +42,8 @@
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { Goke } from "goke";
 import type { McpOAuthConfig } from "./types.js";
-export { addCliToolsToMcp } from "./cli-to-mcp.js";
-export type { AddCliToolsToMcpOptions } from "./cli-to-mcp.js";
+export { addCliToolsToMcp, createMcpAction } from "./cli-to-mcp.js";
+export type { AddCliToolsToMcpOptions, CreateMcpActionOptions } from "./cli-to-mcp.js";
 export type { Transport };
 export type { McpOAuthConfig, McpOAuthState } from "./types.js";
 export interface CachedMcpTools {

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAC/E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAKjC,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAG/D,YAAY,EAAE,SAAS,EAAE,CAAC;AAC1B,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,CAAC,CAAC;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,IAAI,CAAC;IACV;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAErC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEvF;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,cAAc,GAAG,SAAS,CAAC;IAE5C;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,KAAK,IAAI,CAAC;CACxD;AAmID;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyMlF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAC/E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAKjC,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAGvF,YAAY,EAAE,SAAS,EAAE,CAAC;AAC1B,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,CAAC,CAAC;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,IAAI,CAAC;IACV;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAErC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEvF;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,cAAc,GAAG,SAAS,CAAC;IAE5C;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,KAAK,IAAI,CAAC;CACxD;AAmID;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyMlF"}

package/dist/index.js

@@ -45,7 +45,7 @@ import { wrapJsonSchema } from "goke";
 import yaml from "js-yaml";
 import { FileOAuthProvider } from "./oauth-provider.js";
 import { startOAuthFlow, isAuthRequiredError } from "./auth.js";
-export { addCliToolsToMcp } from "./cli-to-mcp.js";
+export { addCliToolsToMcp, createMcpAction } from "./cli-to-mcp.js";
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 /**
  * Check if a schema represents a complex type (object/array) for help text display.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goke/mcp",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "type": "module",
   "description": "Dynamically generate CLI commands from MCP server tools",
   "repository": {
@@ -51,7 +51,7 @@
     "@types/node": "^22.19.7",
     "vitest": "^3.1.0",
     "zod": "^4.3.6",
-    "goke": "^6.2.3"
+    "goke": "^6.8.0"
   },
   "scripts": {
     "clean": "rm -rf dist",

package/src/__test__/add-cli-tools-to-mcp.test.ts

@@ -7,7 +7,7 @@ import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
-import { goke, wrapJsonSchema } from "goke";
+import { goke, wrapJsonSchema, type Goke } from "goke";
 import { z } from "zod";
 import { describe, expect, it } from "vitest";
 import { addCliToolsToMcp } from "../cli-to-mcp.js";
@@ -19,11 +19,13 @@ function createCli() {
     .command("say hi", "Say hello")
     .option("--name <name>", z.string().describe("Person to greet"))
     .option("--caps", z.boolean().default(false).describe("Uppercase output"))
-    .action((options: { name: string; caps: boolean }) => {
+    .action((options) => {
       const message = `Hello ${options.name}!`;
       return options.caps ? message.toUpperCase() : message;
     });
 
+  // sum-values uses wrapJsonSchema whose output is `unknown`, so values are
+  // cast with Number() inside the action.
   cli
     .command("sum-values", "Add two numbers")
     .option(
@@ -40,8 +42,8 @@ function createCli() {
         description: "Right operand",
       }),
     )
-    .action((options: { left: number; right: number }) => ({
-      sum: options.left + options.right,
+    .action((options) => ({
+      sum: Number(options.left) + Number(options.right),
     }));
 
   cli
@@ -54,8 +56,8 @@ function createCli() {
         description: "Repeat count",
       }),
     )
-    .action((message: string, options: { repeat: number }) => {
-      return message.repeat(options.repeat);
+    .action((message, options) => {
+      return message.repeat(Number(options.repeat));
     });
 
   cli
@@ -63,7 +65,7 @@ function createCli() {
     .option("--title <title>", "Required title")
     .option("--tag [tag]", "Optional tag")
     .option("--dry-run", "Dry run flag")
-    .action((options: { title: string; tag?: string; dryRun?: boolean }) => {
+    .action((options) => {
       return options;
     });
 
@@ -457,3 +459,300 @@ describe("addCliToolsToMcp", () => {
     }
   });
 });
+
+/**
+ * Spin up a live MCP client/server pair wired to a single cli.
+ *
+ * Used by the execution-context tests below to keep the boilerplate
+ * out of each test body.
+ */
+async function withMcpClient<T>(
+  cli: Goke,
+  fn: (client: Client) => Promise<T>,
+): Promise<T> {
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const server = new Server({ name: "test-server", version: "1.0.0" }, { capabilities: {} });
+  addCliToolsToMcp({ cli, server });
+
+  const client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities: {} });
+  try {
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+    return await fn(client);
+  } finally {
+    await client.close();
+    await server.close();
+  }
+}
+
+function textBlocks(result: Awaited<ReturnType<Client["callTool"]>>): string[] {
+  const content = "content" in result ? (result as { content: Array<{ type: string; text?: string }> }).content : [];
+  return content.filter((entry) => entry.type === "text").map((entry) => entry.text ?? "");
+}
+
+describe("addCliToolsToMcp execution context", () => {
+  it("passes an execution context as the third argument to the action", async () => {
+    const cli = goke("ctx-cli", {
+      cwd: "/workspace",
+      env: { TOKEN: "abc", USER: "tommy" },
+      stdin: "hello from stdin",
+    });
+
+    cli.command("inspect-ctx", "Return the injected execution context").action((_options, ctx) => {
+      return {
+        hasCtx: ctx != null,
+        hasConsole: typeof ctx?.console?.log === "function",
+        hasFs: typeof ctx?.fs?.readFile === "function",
+        cwd: ctx?.process?.cwd,
+        token: ctx?.process?.env?.TOKEN,
+        user: ctx?.process?.env?.USER,
+        stdin: ctx?.process?.stdin,
+      };
+    });
+
+    const result = await withMcpClient(cli, (client) =>
+      client.callTool({ name: "inspect-ctx", arguments: {} }),
+    );
+
+    expect(firstTextContent(result)).toMatchInlineSnapshot(`
+      "{
+        "hasCtx": true,
+        "hasConsole": true,
+        "hasFs": true,
+        "cwd": "/workspace",
+        "token": "abc",
+        "user": "tommy",
+        "stdin": "hello from stdin"
+      }"
+    `);
+  });
+
+  it("captures ctx.console.log output into the tool result content", async () => {
+    const cli = goke("logs-cli");
+
+    cli.command("noisy", "Write to ctx.console and return nothing").action((_options, ctx) => {
+      ctx.console.log("line one");
+      ctx.console.log("line", "two");
+    });
+
+    const result = await withMcpClient(cli, (client) =>
+      client.callTool({ name: "noisy", arguments: {} }),
+    );
+
+    expect(textBlocks(result)).toMatchInlineSnapshot(`
+      [
+        "line one
+      line two
+      ",
+      ]
+    `);
+  });
+
+  it("captures ctx.console.log output and still uses the action's return value", async () => {
+    const cli = goke("logs-plus-return-cli");
+
+    cli.command("both", "Log and return").action((_options, ctx) => {
+      ctx.console.log("before");
+      return "the-return-value";
+    });
+
+    const result = await withMcpClient(cli, (client) =>
+      client.callTool({ name: "both", arguments: {} }),
+    );
+
+    // Captured stdout first, then the stringified return value, as
+    // separate content blocks. Authors who want a single block can
+    // return a `{ content }` object to bypass this merging.
+    expect(textBlocks(result)).toMatchInlineSnapshot(`
+      [
+        "before
+      ",
+        "the-return-value",
+      ]
+    `);
+  });
+
+  it("treats ctx.process.exit(0) as a success result with captured content", async () => {
+    const cli = goke("exit-ok-cli");
+
+    cli.command("exit-ok", "Exit cleanly").action((_options, ctx) => {
+      ctx.console.log("all good");
+      ctx.process.exit(0);
+    });
+
+    const result = await withMcpClient(cli, (client) =>
+      client.callTool({ name: "exit-ok", arguments: {} }),
+    );
+
+    expect(result.isError).toBeFalsy();
+    expect(textBlocks(result)).toMatchInlineSnapshot(`
+      [
+        "all good
+      ",
+      ]
+    `);
+  });
+
+  it("treats ctx.process.exit(1) as an isError result with captured stderr", async () => {
+    const cli = goke("exit-fail-cli");
+
+    cli.command("exit-fail", "Exit with error").action((_options, ctx) => {
+      ctx.console.error("boom");
+      ctx.process.exit(1);
+    });
+
+    const result = await withMcpClient(cli, (client) =>
+      client.callTool({ name: "exit-fail", arguments: {} }),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(textBlocks(result)).toMatchInlineSnapshot(`
+      [
+        "boom
+      ",
+      ]
+    `);
+  });
+
+  it("does not corrupt the MCP transport when the action writes to ctx.process.stdout directly", async () => {
+    const cli = goke("stdout-cli");
+
+    cli.command("write-stdout", "Write through ctx.process.stdout").action((_options, ctx) => {
+      ctx.process.stdout.write("from-process-stdout\n");
+    });
+
+    const result = await withMcpClient(cli, (client) =>
+      client.callTool({ name: "write-stdout", arguments: {} }),
+    );
+
+    expect(firstTextContent(result)).toBe("from-process-stdout\n");
+  });
+
+  it("keeps the server alive after a tool action calls ctx.process.exit", async () => {
+    const cli = goke("survive-cli");
+
+    cli.command("boom", "Exit with non-zero code").action((_options, ctx) => {
+      ctx.process.exit(2);
+    });
+
+    cli.command("ping", "Return a value").action(() => "pong");
+
+    await withMcpClient(cli, async (client) => {
+      const boomResult = await client.callTool({ name: "boom", arguments: {} });
+      expect(boomResult.isError).toBe(true);
+
+      // Server must still be able to serve subsequent tool calls.
+      const pingResult = await client.callTool({ name: "ping", arguments: {} });
+      expect(firstTextContent(pingResult)).toBe("pong");
+    });
+  });
+
+  it("does not include captured content when the action returns a ready-made CallToolResult", async () => {
+    const cli = goke("raw-cli");
+
+    cli.command("raw", "Return a raw CallToolResult").action((_options, ctx) => {
+      // This write should be ignored — returning a {content} object is
+      // the explicit escape hatch for authors who want full control.
+      ctx.console.log("ignored-capture");
+      return {
+        content: [
+          { type: "text" as const, text: "authoritative" },
+        ],
+      };
+    });
+
+    const result = await withMcpClient(cli, (client) =>
+      client.callTool({ name: "raw", arguments: {} }),
+    );
+
+    expect(textBlocks(result)).toEqual(["authoritative"]);
+  });
+
+  it("captures ctx.console.error output on the success path", async () => {
+    const cli = goke("success-stderr-cli");
+
+    cli.command("warn-and-return", "Emit a warning and return a value").action((_options, ctx) => {
+      ctx.console.error("something suspicious");
+      return { ok: true };
+    });
+
+    const result = await withMcpClient(cli, (client) =>
+      client.callTool({ name: "warn-and-return", arguments: {} }),
+    );
+
+    // Captured stderr lands in its own text block so authors can spot
+    // the warning even though the action returned successfully. The
+    // stringified return value is appended after it.
+    expect(result.isError).toBeFalsy();
+    expect(textBlocks(result)).toMatchInlineSnapshot(`
+      [
+        "something suspicious
+      ",
+        "{
+        "ok": true
+      }",
+      ]
+    `);
+  });
+
+  it("captures ctx.process.stderr.write output on the success path", async () => {
+    const cli = goke("success-stderr-write-cli");
+
+    cli.command("warn-only", "Write to stderr and return undefined").action((_options, ctx) => {
+      ctx.process.stderr.write("low-level-warning\n");
+    });
+
+    const result = await withMcpClient(cli, (client) =>
+      client.callTool({ name: "warn-only", arguments: {} }),
+    );
+
+    expect(result.isError).toBeFalsy();
+    expect(textBlocks(result)).toEqual(["low-level-warning\n"]);
+  });
+
+  it("does not leak tool output into the cli's configured stdout/stderr", async () => {
+    const sentinelStdout: string[] = [];
+    const sentinelStderr: string[] = [];
+    const cli = goke("sentinel-cli", {
+      stdout: { write: (data) => { sentinelStdout.push(data); } },
+      stderr: { write: (data) => { sentinelStderr.push(data); } },
+    });
+
+    cli.command("noisy", "Write to both streams").action((_options, ctx) => {
+      ctx.console.log("stdout-chatter");
+      ctx.console.error("stderr-chatter");
+      ctx.process.stdout.write("direct-stdout\n");
+      ctx.process.stderr.write("direct-stderr\n");
+      return "value";
+    });
+
+    const result = await withMcpClient(cli, (client) =>
+      client.callTool({ name: "noisy", arguments: {} }),
+    );
+
+    // Everything lands in the CallToolResult — the cli's configured
+    // host streams must not receive a single byte during a tool call.
+    expect(sentinelStdout.join("")).toBe("");
+    expect(sentinelStderr.join("")).toBe("");
+    expect(textBlocks(result).join("|")).toBe(
+      "stdout-chatter\ndirect-stdout\n|stderr-chatter\ndirect-stderr\n|value",
+    );
+  });
+
+  it("invokes command actions with the owning cli as `this`", async () => {
+    const cli = goke("this-binding-cli");
+
+    let seenThis: unknown;
+    cli.command("whoami", "Report this-binding").action(function (this: unknown, _options, _ctx) {
+      seenThis = this;
+      return "ok";
+    });
+
+    await withMcpClient(cli, (client) =>
+      client.callTool({ name: "whoami", arguments: {} }),
+    );
+
+    // Same binding Goke#runMatchedCommand uses for parse-path actions.
+    expect(seenThis).toBe(cli);
+  });
+});