diff --git a/README.md b/README.md index 3e6ecb69..2c77f640 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,10 @@ Claude CLI (`claude`) it runs. Keep them in the same directory; a symlink to instead, set `CLAUDE_CODE_EXECUTABLE`. On Alpine, install `libgcc` and `libstdc++` first. +A CLI named with `CLAUDE_CODE_EXECUTABLE` gets a session's MCP servers on its +command line, where other users of the machine can read their `env` and +`headers`. The CLI that comes with the adapter gets them over stdin. + To build one for your machine (needs [Bun](https://bun.sh)) and check it: ```sh diff --git a/src/claude-cli.ts b/src/claude-cli.ts index 99990fac..d4fb2897 100644 --- a/src/claude-cli.ts +++ b/src/claude-cli.ts @@ -32,18 +32,26 @@ export async function claudeCliPath(): Promise { } /** - * How a session's MCP servers reach the Claude CLI unless the client's options - * name a `mcpServersDelivery`: in the `--mcp-config` flag, as before SDK - * 0.3.326. A server's `env` and `headers` are then on the CLI's command line. - * `'initialize'` sends them over stdin instead, but with a CLI that cannot - * read them there (e.g. 2.1.323 through `CLAUDE_CODE_EXECUTABLE`) the session - * fails at startup. + * How a session's MCP servers reach the CLI of {@link claudeCliPath}, unless + * the client's options name a `mcpServersDelivery`. + * + * - `'initialize'` for the CLI that the adapter ships: over stdin, in the + * SDK's initialize request. A server's `env` and `headers`, such as the + * bearer token of an MCP-over-ACP endpoint (see `McpOverAcp`), stay off the + * CLI's command line, which other users of the machine can read. Only a + * launch that the client's options give `--sdk-url` still gets them there. + * - `'argv'` for a CLI that `CLAUDE_CODE_EXECUTABLE` names: in the + * `--mcp-config` flag, so on its command line, as before SDK 0.3.326. Its + * version is not known, and the SDK ends the session at startup when the CLI + * cannot read the servers from the initialize request (e.g. 2.1.323). * * The adapter always sets the option. It names the CLI to start * (`pathToClaudeCodeExecutable`), and for such an app the SDK prints a * `DeprecationWarning` when a session has MCP servers and the option is unset. */ -export const MCP_SERVERS_DELIVERY: NonNullable = "argv"; +export function mcpServersDelivery(): NonNullable { + return process.env.CLAUDE_CODE_EXECUTABLE ? "argv" : "initialize"; +} function bundledClaudeCliPath(directory: string): string { const path = join(directory, CLI_FILE_NAME); diff --git a/src/tests/claude-cli.test.ts b/src/tests/claude-cli.test.ts index c34402d6..9f8cfccf 100644 --- a/src/tests/claude-cli.test.ts +++ b/src/tests/claude-cli.test.ts @@ -55,3 +55,25 @@ describe("claudeCliPath", () => { expect(await claudeCliPath()).toMatch(/@anthropic-ai\/claude-agent-sdk-[^/]+\/claude(\.exe)?$/); }); }); + +describe("mcpServersDelivery", () => { + afterEach(() => vi.unstubAllEnvs()); + + it.each([ + { + name: "is initialize for the CLI that it ships", + cli: "", + delivery: "initialize", + }, + { + name: "is argv for a CLAUDE_CODE_EXECUTABLE CLI", + cli: "/opt/claude", + delivery: "argv", + }, + ])("$name", async ({ cli, delivery }) => { + vi.stubEnv("CLAUDE_CODE_EXECUTABLE", cli); + const { mcpServersDelivery } = await load(); + + expect(mcpServersDelivery()).toBe(delivery); + }); +}); diff --git a/src/tests/v1/create-session-options.test.ts b/src/tests/v1/create-session-options.test.ts index 58f9950c..06f110ee 100644 --- a/src/tests/v1/create-session-options.test.ts +++ b/src/tests/v1/create-session-options.test.ts @@ -616,7 +616,7 @@ describe("createSession options merging", () => { }); it.each([ - { name: "sends MCP servers on the command line", delivery: undefined }, + { name: "sends MCP servers as the CLI takes them", delivery: undefined }, { name: "lets a caller choose the MCP delivery", delivery: "initialize" as const }, ])("$name", async ({ delivery }) => { await agent.newSession({ @@ -625,6 +625,7 @@ describe("createSession options merging", () => { ...(delivery && { _meta: { claudeCode: { options: { mcpServersDelivery: delivery } } } }), }); + // Unit runs name a CLI with CLAUDE_CODE_EXECUTABLE (see `vitest.config.ts`). expect(capturedOptions!.mcpServersDelivery).toBe(delivery ?? "argv"); }); diff --git a/src/tests/v2/v2-integration.test.ts b/src/tests/v2/v2-integration.test.ts index 76220866..6587fbed 100644 --- a/src/tests/v2/v2-integration.test.ts +++ b/src/tests/v2/v2-integration.test.ts @@ -159,6 +159,17 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("v2 core with Claude Code", // Claude Code asks for the server's MCP revision first, not with `initialize`. await until(() => served.includes("tools/list"), 30_000); expect(served[0]).toBe("server/discover"); + // The server's bearer token went to Claude Code over stdin: it is on no + // command line of the adapter's processes (`ps`, so not on Windows). A + // CLAUDE_CODE_EXECUTABLE CLI gets it on its command line. + if (process.platform !== "win32" && !process.env.CLAUDE_CODE_EXECUTABLE) { + const commandLines = spawnSync("ps", ["-axww", "-o", "ppid=,command="], { encoding: "utf8" }) + .stdout.split("\n") + .filter((line) => line.trim().startsWith(`${child.pid} `)); + // Claude Code's session process is one of them. + expect(commandLines.some((line) => line.includes("stream-json"))).toBe(true); + expect(commandLines.filter((line) => line.includes("Bearer "))).toEqual([]); + } }, 60_000); it("reports requires_action while a permission request waits", async () => { diff --git a/src/tests/v2/v2.test.ts b/src/tests/v2/v2.test.ts index 14ee173f..8eb16ce9 100644 --- a/src/tests/v2/v2.test.ts +++ b/src/tests/v2/v2.test.ts @@ -879,7 +879,7 @@ describe("ACP v2 core", () => { }); it.each([ - { name: "sends MCP servers on the command line", delivery: undefined }, + { name: "sends MCP servers as the CLI takes them", delivery: undefined }, { name: "lets the client choose the MCP delivery", delivery: "initialize" }, ])("$name", async ({ delivery }) => { const client = v2Client(); @@ -895,6 +895,7 @@ describe("ACP v2 core", () => { }); }); + // Unit runs name a CLI with CLAUDE_CODE_EXECUTABLE (see `vitest.config.ts`). expect(sdk.processes[0].options.mcpServersDelivery).toBe(delivery ?? "argv"); }); diff --git a/src/v1/acp-agent.ts b/src/v1/acp-agent.ts index e524d81e..fe306685 100644 --- a/src/v1/acp-agent.ts +++ b/src/v1/acp-agent.ts @@ -187,7 +187,7 @@ import { import { AuthStatusReporter, cliLogout } from "../auth-status-reporter.js"; import { terminalAuthMethods as authMethodsForTerminal } from "../auth-methods.js"; import { McpOverAcp, sdkMcpServers } from "../mcp-servers.js"; -import { claudeCliPath, MCP_SERVERS_DELIVERY } from "../claude-cli.js"; +import { claudeCliPath, mcpServersDelivery } from "../claude-cli.js"; import { ContentBlockParam } from "@anthropic-ai/sdk/resources"; import { randomUUID } from "node:crypto"; import type { Stats } from "node:fs"; @@ -10135,7 +10135,7 @@ export class ClaudeAcpAgent { // `promptSuggestions: false` keeps it off. promptSuggestions: true, // Before `userProvidedOptions`, so a client's own `mcpServersDelivery` wins. - mcpServersDelivery: MCP_SERVERS_DELIVERY, + mcpServersDelivery: mcpServersDelivery(), ...userProvidedOptions, // Claude Code uses the same checkpoint store for /rewind. Enable it only // for clients that negotiated per-turn file-change reports; this avoids diff --git a/src/v2/agent.ts b/src/v2/agent.ts index 8d210e46..d9fcb972 100644 --- a/src/v2/agent.ts +++ b/src/v2/agent.ts @@ -33,7 +33,7 @@ import packageJson from "../../package.json" with { type: "json" }; import { messageIdForGrouping } from "../sdk-to-acp.js"; import type { Logger } from "../logger.js"; import { customAgents } from "../session-config-options.js"; -import { claudeCliPath, MCP_SERVERS_DELIVERY } from "../claude-cli.js"; +import { claudeCliPath, mcpServersDelivery } from "../claude-cli.js"; import { clientSystemPrompt, sessionSystemPrompt } from "../client-system-prompt.js"; import type { ElicitationSupport } from "../elicitation.js"; import { forkSession } from "../fork-session.js"; @@ -1063,7 +1063,7 @@ class V2Agent implements AgentHandle, SessionConnection { // Before the client's options: `promptSuggestions: false` turns it off. ...(this.air.client ? { promptSuggestions: true } : {}), // Before the client's options: its own `mcpServersDelivery` wins. - mcpServersDelivery: MCP_SERVERS_DELIVERY, + mcpServersDelivery: mcpServersDelivery(), ...client, // The checkpoints that AIR's file-change reports read (see // `file-changes.ts`), only for a client that declared them, as on v1.