@arizeai/phoenix-cli 1.9.1 → 1.10.1

package/build/setup/mcp/agents.js

@@ -0,0 +1,265 @@
+/**
+ * The coding agents `px setup mcp` can register the Phoenix remote MCP server
+ * with, and how each one is configured per scope.
+ *
+ * Separate from the launch-focused instrumentation registry in
+ * `../agents/registry.ts`: MCP configuration has no launch, two scopes, and six
+ * agents (including VS Code and Gemini), so it gets its own registry rather than
+ * adding unused fields to that one.
+ *
+ * Each agent declares a per-scope {@link McpInstallAction}: `cli` runs the
+ * agent's own `mcp add` (so the format can't drift from the agent's schema);
+ * `file` merges into a config file. The file shapes mirror
+ * `docs/phoenix/integrations/remote-mcp.mdx`.
+ */
+import * as path from "node:path";
+/** The name the Phoenix MCP server is registered under in every agent config. */
+export const PHOENIX_MCP_SERVER_NAME = "phoenix";
+// ---------------------------------------------------------------------------
+// Header helpers
+// ---------------------------------------------------------------------------
+/** `--header "Name: value"` pairs, for agents whose CLI takes raw headers. */
+function headerFlags(headers) {
+    return headers.flatMap((header) => [
+        "--header",
+        `${header.name}: ${header.value}`,
+    ]);
+}
+/**
+ * A spreadable `{ headers }` fragment — present only when there are headers, so
+ * a URL-only (OAuth) config carries no empty `headers` key. Spread it into a
+ * server entry: `{ url, ...headersField(headers) }`.
+ */
+function headersField(headers) {
+    if (headers.length === 0) {
+        return {};
+    }
+    return {
+        headers: Object.fromEntries(headers.map((header) => [header.name, header.value])),
+    };
+}
+/** An `Authorization` value that is exactly `Bearer $VAR` or `Bearer ${VAR}`. */
+const BEARER_ENV_VAR_PATTERN = /^Bearer\s+(?:\$([A-Za-z_][A-Za-z0-9_]*)|\$\{([A-Za-z_][A-Za-z0-9_]*)\})$/;
+/**
+ * The one header Codex's `mcp add` can persist — the first `Authorization`
+ * header whose value is env-var-shaped — and the env-var name it references.
+ * Codex stores only `--bearer-token-env-var`; a literal token has no
+ * translation, so it is never honored.
+ */
+function honoredBearerHeader(headers) {
+    for (const header of headers) {
+        if (header.name.toLowerCase() !== "authorization") {
+            continue;
+        }
+        const match = header.value.match(BEARER_ENV_VAR_PATTERN);
+        const envVar = match?.[1] ?? match?.[2];
+        if (envVar) {
+            return { header, envVar };
+        }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Per-agent install builders
+// ---------------------------------------------------------------------------
+/**
+ * Claude Code and Gemini share one `mcp add` shape — both take
+ * `--scope user|project` and raw `--header`s; only the scope flag differs.
+ */
+function httpCliAdd(binary, scopeFlag, { verify }) {
+    return {
+        kind: "cli",
+        binary,
+        addArgs: (url, headers) => [
+            "mcp",
+            "add",
+            "--scope",
+            scopeFlag,
+            "--transport",
+            "http",
+            ...headerFlags(headers),
+            PHOENIX_MCP_SERVER_NAME,
+            url,
+        ],
+        removeArgs: [
+            "mcp",
+            "remove",
+            "--scope",
+            scopeFlag,
+            PHOENIX_MCP_SERVER_NAME,
+        ],
+        ...(verify ? { verifyArgs: ["mcp", "get", PHOENIX_MCP_SERVER_NAME] } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// File-config fragments
+// ---------------------------------------------------------------------------
+const OPENCODE_DEFAULTS = { $schema: "https://opencode.ai/config.json" };
+function cursorPatch(url, headers) {
+    return {
+        mcpServers: {
+            [PHOENIX_MCP_SERVER_NAME]: {
+                url,
+                ...headersField(headers),
+            },
+        },
+    };
+}
+function opencodePatch(url, headers) {
+    return {
+        mcp: {
+            [PHOENIX_MCP_SERVER_NAME]: {
+                type: "remote",
+                url,
+                enabled: true,
+                ...headersField(headers),
+            },
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+export const MCP_AGENTS = [
+    {
+        id: "claude",
+        label: "Claude Code",
+        binary: "claude",
+        install: {
+            // `--scope user` is user-wide; `--scope project` writes the shared
+            // `.mcp.json` at the repo root (the "repo" scope a --local install means).
+            global: httpCliAdd("claude", "user", { verify: true }),
+            local: httpCliAdd("claude", "project", { verify: true }),
+        },
+    },
+    {
+        id: "codex",
+        label: "Codex",
+        binary: "codex",
+        install: {
+            // Codex reads one global `~/.codex/config.toml`; there is no repo-scoped
+            // config, so only `global` is offered. `codex mcp add` writes the TOML
+            // itself, so we never format TOML by hand.
+            global: {
+                kind: "cli",
+                binary: "codex",
+                addArgs: (url, headers) => {
+                    const envVar = honoredBearerHeader(headers)?.envVar;
+                    return [
+                        "mcp",
+                        "add",
+                        PHOENIX_MCP_SERVER_NAME,
+                        "--url",
+                        url,
+                        ...(envVar ? ["--bearer-token-env-var", envVar] : []),
+                    ];
+                },
+                removeArgs: ["mcp", "remove", PHOENIX_MCP_SERVER_NAME],
+                verifyArgs: ["mcp", "get", PHOENIX_MCP_SERVER_NAME],
+                droppedHeaders: (headers) => {
+                    // Codex persists only the bearer env var derived from the honored
+                    // Authorization header; every other header — including a second
+                    // Authorization header, or one whose value isn't `Bearer ${VAR}` —
+                    // is discarded by `codex mcp add`, so report those as un-storable.
+                    const honored = honoredBearerHeader(headers)?.header;
+                    return headers.filter((header) => header !== honored);
+                },
+            },
+        },
+    },
+    {
+        id: "gemini",
+        label: "Gemini CLI",
+        binary: "gemini",
+        install: {
+            // Gemini's `mcp add` mirrors Claude's flags but ships no `get`, so there
+            // is no read-back — the add's exit code is trusted.
+            global: httpCliAdd("gemini", "user", { verify: false }),
+            local: httpCliAdd("gemini", "project", { verify: false }),
+        },
+    },
+    {
+        id: "cursor",
+        label: "Cursor",
+        binary: "cursor-agent",
+        install: {
+            global: {
+                kind: "file",
+                path: (ctx) => path.join(ctx.home, ".cursor", "mcp.json"),
+                displayPath: () => "~/.cursor/mcp.json",
+                patch: cursorPatch,
+            },
+            local: {
+                kind: "file",
+                path: (ctx) => path.join(ctx.cwd, ".cursor", "mcp.json"),
+                displayPath: () => ".cursor/mcp.json",
+                patch: cursorPatch,
+            },
+        },
+    },
+    {
+        id: "opencode",
+        label: "OpenCode",
+        binary: "opencode",
+        install: {
+            global: {
+                kind: "file",
+                path: (ctx) => path.join(ctx.home, ".config", "opencode", "opencode.json"),
+                displayPath: () => "~/.config/opencode/opencode.json",
+                createDefaults: OPENCODE_DEFAULTS,
+                patch: opencodePatch,
+            },
+            local: {
+                kind: "file",
+                path: (ctx) => path.join(ctx.cwd, "opencode.json"),
+                displayPath: () => "opencode.json",
+                createDefaults: OPENCODE_DEFAULTS,
+                patch: opencodePatch,
+            },
+        },
+    },
+    {
+        id: "vscode",
+        label: "VS Code",
+        binary: "code",
+        install: {
+            // Global: the user-profile `mcp.json` path is platform-specific, so we
+            // let the `code` CLI write it rather than guessing the location.
+            global: {
+                kind: "cli",
+                binary: "code",
+                addArgs: (url, headers) => [
+                    "--add-mcp",
+                    JSON.stringify({
+                        name: PHOENIX_MCP_SERVER_NAME,
+                        type: "http",
+                        url,
+                        ...headersField(headers),
+                    }),
+                ],
+            },
+            // Local: the documented workspace file.
+            local: {
+                kind: "file",
+                path: (ctx) => path.join(ctx.cwd, ".vscode", "mcp.json"),
+                displayPath: () => ".vscode/mcp.json",
+                patch: (url, headers) => ({
+                    servers: {
+                        [PHOENIX_MCP_SERVER_NAME]: {
+                            type: "http",
+                            url,
+                            ...headersField(headers),
+                        },
+                    },
+                }),
+            },
+        },
+    },
+];
+/** The agent with this id, or undefined when the id is unknown. */
+export function getMcpAgent(id) {
+    return MCP_AGENTS.find((agent) => agent.id === id);
+}
+/** Every id `--agent` accepts, for help text and error messages. */
+export const MCP_AGENT_IDS = MCP_AGENTS.map((agent) => agent.id);
+//# sourceMappingURL=agents.js.map

package/build/setup/mcp/agents.js.map

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

package/build/setup/mcp/install.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Execute one MCP install action — run the agent's `mcp add`, or merge the
+ * server entry into its config file.
+ *
+ * The CLI path adds first, and only remove-then-retries when the add is refused
+ * *and* the agent's own listing already shows an entry under our name — removing
+ * before the add is known to work could destroy a registration a failed retry
+ * can't restore. The `verifyArgs` read-back guards against drift: an add whose
+ * flags changed meaning while still exiting 0 shows up as a missing entry.
+ *
+ * Never throws when an install simply didn't take — returns a `failed` result
+ * with a reason for the caller to handle.
+ */
+import type { SetupDeps } from "../deps/index.js";
+import type { McpHeader, McpInstallAction, McpInstallContext } from "./agents.js";
+export type McpInstallOutcome = "configured" | "failed";
+export interface McpInstallResult {
+    outcome: McpInstallOutcome;
+    /** The config file written (repo-relative or `~/…`), for file-based installs. */
+    file?: string;
+    /** Why the install failed, when it did. */
+    reason?: string;
+}
+export interface RunMcpInstallArgs {
+    action: McpInstallAction;
+    /** The Phoenix MCP URL (endpoint + `/mcp`). */
+    url: string;
+    /** Headers for the API-key bearer fallback; empty for OAuth. */
+    headers: McpHeader[];
+    /** Home and repo-root the file paths resolve against. */
+    installContext: McpInstallContext;
+}
+export declare function runMcpInstall(deps: Pick<SetupDeps, "processes">, { action, url, headers, installContext }: RunMcpInstallArgs): Promise<McpInstallResult>;
+//# sourceMappingURL=install.d.ts.map

package/build/setup/mcp/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/setup/mcp/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE/E,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,QAAQ,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,gBAAgB,CAAC;IACzB,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,yDAAyD;IACzD,cAAc,EAAE,iBAAiB,CAAC;CACnC;AAED,wBAAsB,aAAa,CACjC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,EAClC,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,iBAAiB,GAC1D,OAAO,CAAC,gBAAgB,CAAC,CAW3B"}

package/build/setup/mcp/install.js

@@ -0,0 +1,76 @@
+/**
+ * Execute one MCP install action — run the agent's `mcp add`, or merge the
+ * server entry into its config file.
+ *
+ * The CLI path adds first, and only remove-then-retries when the add is refused
+ * *and* the agent's own listing already shows an entry under our name — removing
+ * before the add is known to work could destroy a registration a failed retry
+ * can't restore. The `verifyArgs` read-back guards against drift: an add whose
+ * flags changed meaning while still exiting 0 shows up as a missing entry.
+ *
+ * Never throws when an install simply didn't take — returns a `failed` result
+ * with a reason for the caller to handle.
+ */
+import { writeMcpConfig } from "../util/mcpConfig.js";
+/** Registering a server is one config write; a slow CLI start is still fine. */
+const CLI_INSTALL_TIMEOUT_MS = 30_000;
+export async function runMcpInstall(deps, { action, url, headers, installContext }) {
+    try {
+        return action.kind === "cli"
+            ? await runCliInstall(deps, action, { url, headers, installContext })
+            : runFileInstall(action, { url, headers, installContext });
+    }
+    catch (error) {
+        return {
+            outcome: "failed",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function runCliInstall(deps, action, { url, headers, installContext, }) {
+    // Every exec runs in the install context's cwd — the repo root for a local
+    // install, so a `--scope project` add lands the config in this repo, not
+    // wherever px happened to be launched from.
+    const exec = (args) => deps.processes.exec({
+        command: action.binary,
+        args,
+        cwd: installContext.cwd,
+        timeoutMs: CLI_INSTALL_TIMEOUT_MS,
+    });
+    const fail = (reason) => ({
+        outcome: "failed",
+        reason,
+    });
+    let added = await exec(action.addArgs(url, headers));
+    // Retry through remove only when we can both confirm an entry exists and
+    // remove it — otherwise a refused add is just reported.
+    if (added.exitCode !== 0 &&
+        action.removeArgs &&
+        action.verifyArgs &&
+        (await exec(action.verifyArgs)).exitCode === 0) {
+        await exec(action.removeArgs);
+        added = await exec(action.addArgs(url, headers));
+    }
+    if (added.exitCode !== 0) {
+        return fail(added.stderr.trim() || `exit code ${added.exitCode}`);
+    }
+    // Trust the add's exit code only when the agent has no listing to read back
+    // from; otherwise confirm the entry actually registered.
+    if (action.verifyArgs) {
+        const verified = await exec(action.verifyArgs);
+        if (verified.exitCode !== 0) {
+            return fail("the server did not show up in the agent's MCP list");
+        }
+    }
+    return { outcome: "configured" };
+}
+function runFileInstall(action, { url, headers, installContext, }) {
+    writeMcpConfig({
+        filePath: action.path(installContext),
+        displayPath: action.displayPath(installContext),
+        patch: action.patch(url, headers),
+        ...(action.createDefaults ? { createDefaults: action.createDefaults } : {}),
+    });
+    return { outcome: "configured", file: action.displayPath(installContext) };
+}
+//# sourceMappingURL=install.js.map

package/build/setup/mcp/install.js.map

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

package/build/setup/mcp/runSetupMcp.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `px setup mcp` — register the Phoenix remote MCP server (`<base-url>/mcp`)
+ * with a coding agent's config. This module receives the already-resolved
+ * endpoint from the command layer.
+ *
+ * Auth defaults to OAuth (URL-only config; the agent handles browser login on
+ * first use). `--header` adds an API-key bearer fallback for headless clients,
+ * applied per agent (see {@link ./agents}).
+ *
+ * Without `--agent` the command prompts for scope then agent, after confirming
+ * the endpoint. A headless run requires `--agent` and defaults to global scope.
+ */
+import type { SetupDeps } from "../deps/index.js";
+import { type McpAgentId, type McpHeader, type McpScope } from "./agents.js";
+/** What a run did, in the shape the summary and `--format json` print. */
+export interface McpSetupReport {
+    /** The Phoenix base URL the server was pointed at (no trailing `/mcp`). */
+    endpoint: string;
+    /** The full MCP URL written into the agent config. */
+    url: string;
+    serverName: string;
+    agent: McpAgentId;
+    scope: McpScope;
+    /** `oauth` when URL-only; `header` when a bearer/custom header was written. */
+    auth: "oauth" | "header";
+    /** The config file written, for file-based agents (repo-relative or `~/…`). */
+    file?: string;
+}
+export interface McpSetupInputs {
+    /** Resolved Phoenix base URL (normalized, no trailing slash). */
+    endpoint: string;
+    /** True when `--endpoint` pinned it — skips the interactive confirm prompt. */
+    endpointExplicit: boolean;
+    /** Pinned agent, or undefined to detect + prompt. */
+    agent?: McpAgentId;
+    /** Pinned scope, or undefined (interactive prompts; headless defaults global). */
+    scope?: McpScope;
+    /** Headers for the bearer fallback; empty means OAuth (URL only). */
+    headers: McpHeader[];
+    headless: boolean;
+}
+export declare const COPY: {
+    readonly endpointPrompt: "Phoenix endpoint";
+    readonly endpointInvalid: "Enter a full http:// or https:// URL (e.g. http://localhost:6006).";
+    readonly endpointUnusable: (value: string) => string;
+    readonly usingEndpoint: (url: string) => string;
+    readonly scopePrompt: "Where should the MCP server be configured?";
+    readonly scopeGlobalLabel: "Global";
+    readonly scopeGlobalHint: "available across all your projects";
+    readonly scopeLocalLabel: "This repo";
+    readonly scopeLocalHint: "written into this project's config, checked in with it";
+    readonly agentPrompt: "Which coding agent?";
+    readonly detectedHint: "detected";
+    readonly headlessNeedsAgent: `--agent is required with --no-input. Pass one of: ${string}.`;
+    readonly localNeedsRepo: "--local must run inside a git repository. Re-run from your project, or use --global.";
+    readonly globalOnly: (agentLabel: string) => string;
+    readonly globalOnlyHeadless: (agentLabel: string) => string;
+    readonly homeUnknown: (agentLabel: string) => string;
+    readonly scopeUnsupported: (agentLabel: string, scope: McpScope) => string;
+    readonly headersUnsupported: (agentLabel: string, dropped: McpHeader[]) => string;
+    readonly configuredCli: (agentLabel: string) => string;
+    readonly configuredFile: (agentLabel: string, file: string) => string;
+    readonly installFailed: (agentLabel: string, reason: string) => string;
+    readonly nextStepOAuth: (agentLabel: string) => string;
+    readonly nextStepHeader: "The server is configured with your bearer header — no browser login needed.";
+};
+export declare function runSetupMcp(deps: Pick<SetupDeps, "context" | "prompter" | "processes">, inputs: McpSetupInputs): Promise<McpSetupReport>;
+//# sourceMappingURL=runSetupMcp.d.ts.map

package/build/setup/mcp/runSetupMcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runSetupMcp.d.ts","sourceRoot":"","sources":["../../../src/setup/mcp/runSetupMcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,EAML,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,QAAQ,EACd,MAAM,UAAU,CAAC;AAGlB,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;IAChB,+EAA+E;IAC/E,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IACzB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,gBAAgB,EAAE,OAAO,CAAC;IAC1B,qDAAqD;IACrD,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,kFAAkF;IAClF,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,qEAAqE;IACrE,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,eAAO,MAAM,IAAI;aACf,cAAc,EAAE,kBAAkB;aAClC,eAAe,EACb,oEAAoE;aACtE,gBAAgB,UAAU,MAAM;aAGhC,aAAa,QAAQ,MAAM;aAE3B,WAAW,EAAE,4CAA4C;aACzD,gBAAgB,EAAE,QAAQ;aAC1B,eAAe,EAAE,oCAAoC;aACrD,eAAe,EAAE,WAAW;aAC5B,cAAc,EAAE,wDAAwD;aACxE,WAAW,EAAE,qBAAqB;aAClC,YAAY,EAAE,UAAU;aACxB,kBAAkB;aAClB,cAAc,EACZ,sFAAsF;aACxF,UAAU,eAAe,MAAM;aAE/B,kBAAkB,eAAe,MAAM;aAEvC,WAAW,eAAe,MAAM;aAGhC,gBAAgB,eAAe,MAAM,SAAS,QAAQ;aAEtD,kBAAkB,eAAe,MAAM,WAAW,SAAS,EAAE;aAK7D,aAAa,eAAe,MAAM;aAElC,cAAc,eAAe,MAAM,QAAQ,MAAM;aAEjD,aAAa,eAAe,MAAM,UAAU,MAAM;aAElD,aAAa,eAAe,MAAM;aAElC,cAAc,EACZ,6EAA6E;CACvE,CAAC;AAMX,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC,EAC3D,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,cAAc,CAAC,CA8EzB"}