diff --git a/.changeset/mcp-manual-claude-codex.md b/.changeset/mcp-manual-claude-codex.md new file mode 100644 index 000000000..1b6a6b098 --- /dev/null +++ b/.changeset/mcp-manual-claude-codex.md @@ -0,0 +1,5 @@ +--- +'@hyperdx/app': patch +--- + +Bring back the Claude Code and Codex CLI commands in the MCP setup panel, next to the `hdx mcp install` command, so connecting an agent no longer needs another CLI installed. diff --git a/packages/app/src/components/ClickStackOnboarding/McpInstallPanel.tsx b/packages/app/src/components/ClickStackOnboarding/McpInstallPanel.tsx index 6851a0a1d..d51d53be6 100644 --- a/packages/app/src/components/ClickStackOnboarding/McpInstallPanel.tsx +++ b/packages/app/src/components/ClickStackOnboarding/McpInstallPanel.tsx @@ -2,9 +2,11 @@ import { useMemo, useState } from 'react'; import { Group, SegmentedControl, Stack, Text } from '@mantine/core'; import { IconBraces, + IconBrandOpenai, IconBrandVisualStudio, IconCode, IconRobot, + IconTerminal2, } from '@tabler/icons-react'; import { CopySnippet } from './CopySnippet'; @@ -13,14 +15,19 @@ import { buildAllSnippets, buildCliInstallCommand, type BuiltSnippets, + CODEX_TOKEN_ENV_VAR, type DeploymentShape, } from './installSnippets'; // ChatGPT is intentionally absent: no native MCP yet, and bridges are a -// user-side decision better tracked in docs than in this UI. Claude Code -// and Codex are configured through shell commands, which would put the key -// in shell history, so the CLI installer above covers them instead. -type AgentHost = 'cursor' | 'vscode-copilot' | 'opencode' | 'other'; +// user-side decision better tracked in docs than in this UI. +type AgentHost = + | 'claude-code' + | 'cursor' + | 'vscode-copilot' + | 'codex-cli' + | 'opencode' + | 'other'; interface HostChoice { id: AgentHost; @@ -28,8 +35,10 @@ interface HostChoice { } const CHOICES: HostChoice[] = [ + { id: 'claude-code', label: 'Claude Code' }, { id: 'cursor', label: 'Cursor' }, { id: 'vscode-copilot', label: 'VS Code' }, + { id: 'codex-cli', label: 'Codex CLI' }, { id: 'opencode', label: 'OpenCode' }, { id: 'other', label: 'Other' }, ]; @@ -50,7 +59,7 @@ interface McpInstallPanelProps { * block) for the chosen host. The access key is masked in every snippet. */ export default function McpInstallPanel({ deployment }: McpInstallPanelProps) { - const [host, setHost] = useState('cursor'); + const [host, setHost] = useState('claude-code'); const snippets = useMemo(() => buildAllSnippets(deployment), [deployment]); @@ -96,10 +105,14 @@ export default function McpInstallPanel({ deployment }: McpInstallPanelProps) { function HostIcon({ id }: { id: AgentHost }) { switch (id) { + case 'claude-code': + return ; case 'cursor': return ; case 'vscode-copilot': return ; + case 'codex-cli': + return ; case 'opencode': return ; case 'other': @@ -120,6 +133,15 @@ interface HostInstallProps { function HostInstall({ host, snippets, accessKey }: HostInstallProps) { switch (host) { + case 'claude-code': + return ( + + ); + case 'cursor': return ( ); + case 'codex-cli': + return ( + + + + Codex reads {CODEX_TOKEN_ENV_VAR} each time it starts, so also set + it in your shell profile. + + + ); + case 'opencode': return ( { + it('masks the access key in the default (Claude Code) command snippet', () => { + renderPanel(); + + const text = codeText(); + // The raw key must never appear in the rendered snippet... + expect(text).not.toContain(ACCESS_KEY); + // ...but the masked stand-in (visible prefix + dots) should. + expect(text).toContain(defaultRedact(ACCESS_KEY)); + }); + it('masks the access key in the JSON fallback (Other) snippet', async () => { const user = userEvent.setup(); renderPanel(); diff --git a/packages/app/src/components/ClickStackOnboarding/__tests__/installSnippets.test.ts b/packages/app/src/components/ClickStackOnboarding/__tests__/installSnippets.test.ts index fae76810e..df3920d31 100644 --- a/packages/app/src/components/ClickStackOnboarding/__tests__/installSnippets.test.ts +++ b/packages/app/src/components/ClickStackOnboarding/__tests__/installSnippets.test.ts @@ -1,5 +1,6 @@ import { buildAllSnippets, + CODEX_TOKEN_ENV_VAR, type DeploymentShape, SERVER_NAME, } from '@/components/ClickStackOnboarding/installSnippets'; @@ -9,6 +10,34 @@ const DEPLOYMENT: DeploymentShape = { accessKey: 'k_abcdef123456', }; +describe('buildAllSnippets > Claude Code', () => { + it('emits the documented Claude Code MCP install one-liner', () => { + const { claudeCode } = buildAllSnippets(DEPLOYMENT); + + expect(claudeCode).toBe( + `claude mcp add ${SERVER_NAME} --transport http https://hyperdx.example.com/api/mcp --header "Authorization: Bearer k_abcdef123456"`, + ); + }); +}); + +describe('buildAllSnippets > Codex CLI', () => { + it('emits the current OpenAI Codex CLI mcp add command with a bearer-token env var', () => { + const { codexCli } = buildAllSnippets(DEPLOYMENT); + + expect(codexCli).toBe( + `export ${CODEX_TOKEN_ENV_VAR}="k_abcdef123456"\n` + + `codex mcp add ${SERVER_NAME} --url https://hyperdx.example.com/api/mcp --bearer-token-env-var ${CODEX_TOKEN_ENV_VAR}`, + ); + }); + + it('does NOT use the deprecated --transport or --header flags', () => { + const { codexCli } = buildAllSnippets(DEPLOYMENT); + + expect(codexCli).not.toContain('--transport'); + expect(codexCli).not.toContain('--header'); + }); +}); + describe('buildAllSnippets > Cursor', () => { it('emits a cursor:// URL with a URL-safe base64-encoded config that round-trips', () => { const { cursor } = buildAllSnippets(DEPLOYMENT); @@ -129,13 +158,56 @@ describe('buildAllSnippets > JSON block', () => { }); }); +describe('buildAllSnippets > placeholder fallbacks', () => { + it('falls back to in the snippet when the key is empty', () => { + const { claudeCode } = buildAllSnippets({ ...DEPLOYMENT, accessKey: '' }); + + expect(claudeCode).toContain('Bearer '); + }); + + it('falls back to in the Codex export when the key is empty', () => { + const { codexCli } = buildAllSnippets({ ...DEPLOYMENT, accessKey: '' }); + + expect(codexCli).toContain(`export ${CODEX_TOKEN_ENV_VAR}=""`); + }); + + it('escapes shell metacharacters in header values', () => { + // Today's access keys are UUIDv4 with no metacharacters; the + // escape is defensive against future formats that allow `"`, + // `$`, `\`, or backtick. Any of those would otherwise turn a + // copy-paste install into a shell-injection vector. + const { claudeCode } = buildAllSnippets({ + ...DEPLOYMENT, + accessKey: 'k"$`\\suffix', + }); + + expect(claudeCode).toContain('Bearer k\\"\\$\\`\\\\suffix"'); + }); + + it('escapes shell metacharacters in the Codex export value', () => { + // The bearer token lands on the right-hand side of an `export`, + // so the same shell-injection defense applies to the Codex + // snippet's quoted value. + const { codexCli } = buildAllSnippets({ + ...DEPLOYMENT, + accessKey: 'k"$`\\suffix', + }); + + expect(codexCli).toContain( + 'export ' + CODEX_TOKEN_ENV_VAR + '="k\\"\\$\\`\\\\suffix"', + ); + }); +}); + describe('buildAllSnippets > host coverage', () => { it('returns a populated string for every supported host', () => { const all = buildAllSnippets(DEPLOYMENT); expect(all).toMatchObject({ + claudeCode: expect.stringContaining(`claude mcp add ${SERVER_NAME}`), cursor: expect.stringContaining('cursor://'), vscode: expect.stringContaining('vscode:mcp/install'), + codexCli: expect.stringContaining(`codex mcp add ${SERVER_NAME}`), openCode: expect.stringContaining(`"${SERVER_NAME}"`), jsonBlock: expect.stringContaining(`"${SERVER_NAME}"`), }); @@ -144,6 +216,8 @@ describe('buildAllSnippets > host coverage', () => { it('keys the JSON block on the same fixed server name in every output', () => { const all = buildAllSnippets(DEPLOYMENT); + expect(all.claudeCode).toContain(SERVER_NAME); + expect(all.codexCli).toContain(SERVER_NAME); expect(all.cursor).toContain(`name=${SERVER_NAME}`); expect(all.vscode).toContain(SERVER_NAME); expect(all.openCode).toContain(`"${SERVER_NAME}"`); diff --git a/packages/app/src/components/ClickStackOnboarding/installSnippets.ts b/packages/app/src/components/ClickStackOnboarding/installSnippets.ts index 713f7bfc6..c251ce8b9 100644 --- a/packages/app/src/components/ClickStackOnboarding/installSnippets.ts +++ b/packages/app/src/components/ClickStackOnboarding/installSnippets.ts @@ -1,9 +1,7 @@ // Per-host snippet builders for the "Connect your AI assistant" // section. Each builder takes a `DeploymentShape` (URL + access -// key) and returns the install primitive for one host: a deep link -// or a JSON config block. Nothing here emits a shell command with the -// key in it, since that lands in shell history; `hdx mcp install` -// covers the CLI-configured hosts instead. +// key) and returns the install primitive for one host: a CLI +// one-liner, a deep link, or a JSON config block. // // Pure functions only. Component-level state (host picker) lives // in `McpInstallPanel.tsx`. Keeping the builders here makes unit @@ -22,6 +20,17 @@ */ export const SERVER_NAME = 'clickstack'; +/** + * Environment variable the Codex CLI snippet reads the bearer token + * from. The current `codex mcp add` command has no `--header` flag; + * for a Streamable HTTP server with bearer auth it accepts + * `--bearer-token-env-var ` and reads the token from that env + * var at connect time (see https://developers.openai.com/codex/mcp). + * We emit an `export` line for the same name so the copy-paste is + * self-contained. + */ +export const CODEX_TOKEN_ENV_VAR = 'CLICKSTACK_ACCESS_KEY'; + export interface DeploymentShape { /** Origin used to build the MCP URL, e.g. `https://example.com/api`. */ apiUrl: string; @@ -30,10 +39,14 @@ export interface DeploymentShape { } export interface BuiltSnippets { + /** Claude Code CLI one-liner. */ + claudeCode: string; /** Cursor `cursor://` deep link. */ cursor: string; /** VS Code + Copilot `vscode:mcp/install` deep link. */ vscode: string; + /** OpenAI Codex CLI one-liner. */ + codexCli: string; /** OpenCode JSON config under an `mcp` block (uses `type: "remote"`). */ openCode: string; /** Canonical `mcpServers` JSON block for any other host. */ @@ -104,6 +117,69 @@ function buildUrl(deployment: DeploymentShape): string { return `${base}/mcp`; } +/** + * Escape a value for safe inclusion inside a double-quoted shell + * argument. Defensive: today's `accessKey` is a UUIDv4 with no + * shell metacharacters, but a future format that permits `"`, `$`, + * `\`, or backtick would otherwise turn a copy-paste install into a + * shell-injection vector. + */ +function shellEscape(value: string): string { + return value.replace(/(["\\$`])/g, '\\$1'); +} + +/** + * Wrap a value in double quotes with the metacharacters escaped, + * for use as a standalone shell argument (e.g. the right-hand side + * of an `export`). + */ +function shellQuoteValue(value: string): string { + return `"${shellEscape(value)}"`; +} + +/** + * Quote and escape a header value for safe inclusion inside a + * double-quoted `--header "Name: value"` shell argument. + */ +function shellQuoteHeader(name: string, value: string): string { + return `--header "${name}: ${shellEscape(value)}"`; +} + +function headerArgs(headers: Record): string { + return Object.entries(headers) + .map(([key, value]) => shellQuoteHeader(key, value)) + .join(' '); +} + +/** + * Claude Code `mcp add` one-liner: `claude mcp add + * --transport http --header "..."`. Claude passes the bearer + * token inline as an `Authorization` header. + */ +function buildClaudeOneLiner(deployment: DeploymentShape): string { + const url = buildUrl(deployment); + const headers = buildHeaders(deployment); + return `claude mcp add ${SERVER_NAME} --transport http ${url} ${headerArgs(headers)}`; +} + +/** + * OpenAI Codex CLI `mcp add` command. Unlike Claude Code, the + * current Codex CLI (see https://developers.openai.com/codex/mcp) + * does not accept `--transport` or `--header`; its Streamable HTTP + * form is `codex mcp add --url ` and bearer auth is + * supplied via `--bearer-token-env-var `, which reads the + * token from the named environment variable rather than embedding + * it in the command. We prepend an `export` for that variable so + * the snippet is a self-contained copy-paste. + */ +function buildCodexOneLiner(deployment: DeploymentShape): string { + const url = buildUrl(deployment); + const token = deployment.accessKey || ''; + const exportLine = `export ${CODEX_TOKEN_ENV_VAR}=${shellQuoteValue(token)}`; + const addLine = `codex mcp add ${SERVER_NAME} --url ${url} --bearer-token-env-var ${CODEX_TOKEN_ENV_VAR}`; + return `${exportLine}\n${addLine}`; +} + /** * Cursor `cursor://` deep link. Documented Cursor MCP install * scheme: name in the query string, config as base64-encoded JSON. @@ -202,8 +278,10 @@ export function buildCliInstallCommand(deployment: DeploymentShape): string { */ export function buildAllSnippets(deployment: DeploymentShape): BuiltSnippets { return { + claudeCode: buildClaudeOneLiner(deployment), cursor: buildCursorDeeplink(deployment), vscode: buildVSCodeDeeplink(deployment), + codexCli: buildCodexOneLiner(deployment), openCode: buildOpenCodeJsonBlock(deployment), jsonBlock: buildMcpJsonBlock(deployment), }; diff --git a/packages/app/src/components/TeamSettings/OrgApiKeysSection.tsx b/packages/app/src/components/TeamSettings/OrgApiKeysSection.tsx index 1cfa80b43..9219aa891 100644 --- a/packages/app/src/components/TeamSettings/OrgApiKeysSection.tsx +++ b/packages/app/src/components/TeamSettings/OrgApiKeysSection.tsx @@ -119,8 +119,7 @@ export default function OrgApiKeysSection() { Organization API keys - Keys owned by the team. They keep working when the person who - created them leaves. + Keys owned by the team.