Skip to content

Commit a25e945

Browse files
feat(cli): name, team and agent choices for hdx mcp install (#3670)
1 parent 0096a35 commit a25e945

8 files changed

Lines changed: 655 additions & 65 deletions

File tree

‎.changeset/mcp-install-name.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'@hyperdx/cli': patch
3+
---
4+
5+
feat(cli): `hdx mcp install` can keep several ClickStack servers side by side
6+
7+
`--name <server-name>` adds the MCP server under a name you choose, so a second
8+
ClickStack instance no longer overwrites the first. When the key belongs to more
9+
than one team, the installer asks which teams to add a server for and adds one
10+
entry per team. When it finds more than one agent it asks which to set up.

‎MCP.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,9 @@ The key stays out of your shell history and agent chats.
4848
npx @hyperdx/cli mcp install --app-url <your-hyperdx-url>
4949
```
5050

51+
The entry is named `clickstack`, and running the command again replaces it. Pass
52+
`--name <server-name>` to add a second instance under its own name instead.
53+
5154
### Claude Code
5255

5356
`read -rs` waits for you to paste the key and press Enter, without echoing it,

‎packages/cli/README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,13 +222,25 @@ Codex, Cursor, and VS Code. It asks for a personal access key or an
222222
organization API key with hidden input and checks it before changing any
223223
config, so the key stays out of shell history and agent chats.
224224

225+
If the key belongs to more than one team, it asks which teams to add a server
226+
for (Enter keeps the default team). Picking several adds one entry per team,
227+
named `<name>-<team>`. If it finds more than one agent, it asks which
228+
to set up (Enter keeps all of them).
229+
225230
```bash
226231
npx @hyperdx/cli mcp install -a https://your-hyperdx.example
227232
```
228233

229234
The key is stored in plain text in each agent's user config, which the
230235
command lists when it finishes. Running it again replaces the existing entry.
231236

237+
The entry is named `clickstack`. To keep more than one ClickStack instance side
238+
by side, give each its own name:
239+
240+
```bash
241+
npx @hyperdx/cli mcp install -a https://staging.example --name clickstack-staging
242+
```
243+
232244
### `hdx upload-sourcemaps` — Source maps
233245

234246
Upload JavaScript source maps to HyperDX for stack trace de-obfuscation. Run it

‎packages/cli/src/__tests__/mcpInstall.test.ts‎

Lines changed: 261 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,22 @@ import * as os from 'node:os';
1111
import * as path from 'node:path';
1212

1313
import {
14+
installAll,
15+
isValidServerName,
16+
listTeams,
17+
mcpClients,
1418
mcpUrl,
19+
teamServers,
1520
upsertCodexServer,
1621
upsertJsonServer,
1722
verifyKey,
1823
} from '@/mcp/install';
1924

20-
const server = { url: 'https://example.com/api/mcp', key: 'hdx_org_abc' };
25+
const server = {
26+
name: 'clickstack',
27+
url: 'https://example.com/api/mcp',
28+
key: 'hdx_org_abc',
29+
};
2130

2231
let dir: string;
2332
beforeEach(() => {
@@ -40,38 +49,48 @@ describe('upsertJsonServer', () => {
4049
file,
4150
JSON.stringify({ theme: 'dark', mcpServers: { other: { url: 'x' } } }),
4251
);
43-
upsertJsonServer(file, 'mcpServers', { url: server.url });
52+
upsertJsonServer(file, 'mcpServers', 'clickstack', { url: server.url });
4453
expect(JSON.parse(fs.readFileSync(file, 'utf-8'))).toEqual({
4554
theme: 'dark',
4655
mcpServers: { other: { url: 'x' }, clickstack: { url: server.url } },
4756
});
4857
});
4958

59+
it('keeps an entry installed under another name', () => {
60+
const file = path.join(dir, 'mcp.json');
61+
upsertJsonServer(file, 'mcpServers', 'clickstack', { url: 'a' });
62+
upsertJsonServer(file, 'mcpServers', 'clickstack-staging', { url: 'b' });
63+
expect(JSON.parse(fs.readFileSync(file, 'utf-8')).mcpServers).toEqual({
64+
clickstack: { url: 'a' },
65+
'clickstack-staging': { url: 'b' },
66+
});
67+
});
68+
5069
it('creates the file and its directory with owner-only permissions', () => {
5170
const file = path.join(dir, 'nested', 'mcp.json');
52-
upsertJsonServer(file, 'servers', { url: server.url });
71+
upsertJsonServer(file, 'servers', 'clickstack', { url: server.url });
5372
expect(fs.statSync(file).mode & 0o777).toBe(0o600);
5473
});
5574

5675
it('tightens an existing config to owner-only before writing the key', () => {
5776
const file = path.join(dir, 'mcp.json');
5877
fs.writeFileSync(file, '{}', { mode: 0o644 });
59-
upsertJsonServer(file, 'servers', { url: server.url });
78+
upsertJsonServer(file, 'servers', 'clickstack', { url: server.url });
6079
expect(fs.statSync(file).mode & 0o777).toBe(0o600);
6180
});
6281

6382
it('refuses JSON that is not an object', () => {
6483
const file = path.join(dir, 'mcp.json');
6584
fs.writeFileSync(file, 'null');
66-
expect(() => upsertJsonServer(file, 'servers', {})).toThrow(
85+
expect(() => upsertJsonServer(file, 'servers', 'clickstack', {})).toThrow(
6786
/Could not parse/,
6887
);
6988
});
7089

7190
it('refuses to rewrite a file it cannot parse', () => {
7291
const file = path.join(dir, 'mcp.json');
7392
fs.writeFileSync(file, '{ // comment\n "servers": {} }');
74-
expect(() => upsertJsonServer(file, 'servers', {})).toThrow(
93+
expect(() => upsertJsonServer(file, 'servers', 'clickstack', {})).toThrow(
7594
/Could not parse/,
7695
);
7796
expect(fs.readFileSync(file, 'utf-8')).toContain('// comment');
@@ -116,6 +135,29 @@ describe('upsertCodexServer', () => {
116135
).toBe(true);
117136
});
118137

138+
it('keeps a table installed under a name that shares a prefix', () => {
139+
const file = path.join(dir, 'config.toml');
140+
upsertCodexServer(file, { ...server, name: 'clickstack-staging' });
141+
upsertCodexServer(file, { ...server, url: 'https://prd/api/mcp' });
142+
upsertCodexServer(file, { ...server, url: 'https://prd2/api/mcp' });
143+
const out = fs.readFileSync(file, 'utf-8');
144+
expect(out).toContain(
145+
'[mcp_servers.clickstack-staging]\nurl = "https://example.com/api/mcp"',
146+
);
147+
expect(out).toContain(
148+
'[mcp_servers.clickstack]\nurl = "https://prd2/api/mcp"',
149+
);
150+
expect(out).not.toContain('https://prd/');
151+
});
152+
153+
it('writes the team header when a team was chosen', () => {
154+
const file = path.join(dir, 'config.toml');
155+
upsertCodexServer(file, { ...server, teamId: 't1' });
156+
expect(fs.readFileSync(file, 'utf-8')).toContain(
157+
'http_headers = { Authorization = "Bearer hdx_org_abc", x-hdx-team = "t1" }',
158+
);
159+
});
160+
119161
it('creates the config when Codex has none yet', () => {
120162
const file = path.join(dir, '.codex', 'config.toml');
121163
upsertCodexServer(file, server);
@@ -125,6 +167,219 @@ describe('upsertCodexServer', () => {
125167
});
126168
});
127169

170+
describe('mcpClients', () => {
171+
const readJson = (file: string) => JSON.parse(fs.readFileSync(file, 'utf-8'));
172+
const install = (id: string, teamId?: string) =>
173+
mcpClients(dir, 'linux')
174+
.find(c => c.id === id)!
175+
.install({ ...server, name: 'clickstack-prd', teamId });
176+
177+
it('writes the team header for Cursor and VS Code', () => {
178+
install('cursor', 't1');
179+
install('vscode', 't1');
180+
const headers = { Authorization: 'Bearer hdx_org_abc', 'x-hdx-team': 't1' };
181+
expect(
182+
readJson(path.join(dir, '.cursor', 'mcp.json')).mcpServers[
183+
'clickstack-prd'
184+
].headers,
185+
).toEqual(headers);
186+
expect(
187+
readJson(path.join(dir, '.config', 'Code', 'User', 'mcp.json')).servers[
188+
'clickstack-prd'
189+
].headers,
190+
).toEqual(headers);
191+
});
192+
193+
it('reports an entry as present only once it is installed', () => {
194+
const has = (id: string, name: string) =>
195+
mcpClients(dir, 'linux')
196+
.find(c => c.id === id)!
197+
.has(name);
198+
for (const id of ['cursor', 'vscode', 'codex']) {
199+
expect(has(id, 'clickstack-prd')).toBe(false);
200+
install(id);
201+
expect(has(id, 'clickstack-prd')).toBe(true);
202+
expect(has(id, 'clickstack')).toBe(false);
203+
}
204+
});
205+
206+
it('writes no team header when no team was chosen', () => {
207+
install('cursor');
208+
expect(
209+
readJson(path.join(dir, '.cursor', 'mcp.json')).mcpServers[
210+
'clickstack-prd'
211+
].headers,
212+
).toEqual({ Authorization: 'Bearer hdx_org_abc' });
213+
});
214+
});
215+
216+
describe('teamServers', () => {
217+
const team = (id: string, name: string) => ({ id, name, isCurrent: false });
218+
219+
it('keeps the name for one team and for no team', () => {
220+
expect(teamServers(server, [])).toEqual([{ ...server, teamId: undefined }]);
221+
expect(teamServers(server, [team('a', 'Demo')])).toEqual([
222+
{ ...server, teamId: 'a' },
223+
]);
224+
});
225+
226+
it('names one entry per team, falling back to the id on a clash', () => {
227+
expect(
228+
teamServers(server, [
229+
team('a', 'Prod EU'),
230+
team('b', 'Demo!'),
231+
team('c', 'demo'),
232+
team('d', '***'),
233+
]).map(s => [s.name, s.teamId]),
234+
).toEqual([
235+
['clickstack-prod-eu', 'a'],
236+
['clickstack-b', 'b'],
237+
['clickstack-c', 'c'],
238+
['clickstack-d', 'd'],
239+
]);
240+
});
241+
});
242+
243+
describe('installAll', () => {
244+
it('writes every server to every client and reports each entry', () => {
245+
const calls: string[] = [];
246+
const client = (id: string, failOn?: string) =>
247+
({
248+
id,
249+
install: (s: { name: string; teamId?: string }) => {
250+
if (s.name === failOn) throw new Error('disk full');
251+
calls.push(`${id}:${s.name}:${s.teamId}`);
252+
},
253+
}) as unknown as ReturnType<typeof mcpClients>[number];
254+
const servers = teamServers(server, [
255+
{ id: 'a', name: 'Demo', isCurrent: true },
256+
{ id: 'b', name: 'Prod', isCurrent: false },
257+
]);
258+
const results = installAll(
259+
[client('cursor'), client('codex', 'clickstack-demo')],
260+
servers,
261+
);
262+
expect(calls).toEqual([
263+
'cursor:clickstack-demo:a',
264+
'cursor:clickstack-prod:b',
265+
'codex:clickstack-prod:b',
266+
]);
267+
expect(results.map(r => [r.client.id, r.name, r.error])).toEqual([
268+
['cursor', 'clickstack-demo', undefined],
269+
['cursor', 'clickstack-prod', undefined],
270+
['codex', 'clickstack-demo', 'disk full'],
271+
['codex', 'clickstack-prod', undefined],
272+
]);
273+
});
274+
});
275+
276+
describe('isValidServerName', () => {
277+
it('rejects names that would break a TOML table header', () => {
278+
expect(isValidServerName('clickstack-prd_2')).toBe(true);
279+
expect(isValidServerName('a.b')).toBe(false);
280+
expect(isValidServerName('a]')).toBe(false);
281+
expect(isValidServerName('-h')).toBe(false);
282+
expect(isValidServerName('')).toBe(false);
283+
});
284+
});
285+
286+
describe('listTeams', () => {
287+
const realFetch = globalThis.fetch;
288+
afterEach(() => {
289+
globalThis.fetch = realFetch;
290+
});
291+
const respondText = (text: string, status = 200) => {
292+
const fetchMock = jest.fn(async (_url: string, _init?: RequestInit) => {
293+
return new Response(text, { status });
294+
});
295+
globalThis.fetch = fetchMock as unknown as typeof fetch;
296+
return fetchMock;
297+
};
298+
const sse = (toolText: string) =>
299+
`event: message\ndata: ${JSON.stringify({
300+
jsonrpc: '2.0',
301+
id: 1,
302+
result: { content: [{ type: 'text', text: toolText }] },
303+
})}\n\n`;
304+
const toolError = `event: message\ndata: ${JSON.stringify({
305+
jsonrpc: '2.0',
306+
id: 1,
307+
result: {
308+
isError: true,
309+
content: [
310+
{
311+
type: 'text',
312+
text: 'MCP error -32602: Tool clickstack_list_teams not found',
313+
},
314+
],
315+
},
316+
})}\n\n`;
317+
318+
it('reads teams from the MCP endpoint', async () => {
319+
const teams = [
320+
{ id: 'a', name: 'Demo', isCurrent: true },
321+
{ id: 'b', name: 'Prod', isCurrent: false },
322+
];
323+
const fetchMock = respondText(sse(JSON.stringify({ teams })));
324+
await expect(listTeams('https://example.com/', 'k')).resolves.toEqual(
325+
teams,
326+
);
327+
expect(fetchMock.mock.calls[0][0]).toBe('https://example.com/api/mcp');
328+
});
329+
330+
it('returns no teams when the server has no team listing', async () => {
331+
respondText(toolError);
332+
await expect(listTeams('https://example.com', 'k')).resolves.toEqual([]);
333+
});
334+
335+
it('throws when the tool exists but fails', async () => {
336+
respondText(
337+
toolError.replace(
338+
'Tool clickstack_list_teams not found',
339+
'user not found',
340+
),
341+
);
342+
await expect(listTeams('https://example.com', 'k')).rejects.toThrow(
343+
/user not found/,
344+
);
345+
});
346+
347+
const rpcError = (message: string) =>
348+
`event: message\ndata: ${JSON.stringify({
349+
jsonrpc: '2.0',
350+
id: 1,
351+
error: { code: -32602, message },
352+
})}\n\n`;
353+
354+
it('reads a JSON-RPC unknown-tool error as no team listing', async () => {
355+
respondText(rpcError('Tool clickstack_list_teams not found'));
356+
await expect(listTeams('https://example.com', 'k')).resolves.toEqual([]);
357+
});
358+
359+
it('throws on any other JSON-RPC error', async () => {
360+
respondText(rpcError('Invalid arguments'));
361+
await expect(listTeams('https://example.com', 'k')).rejects.toThrow(
362+
/Invalid arguments/,
363+
);
364+
});
365+
366+
it('skips other SSE messages and throws on a malformed team list', async () => {
367+
const notice = `event: message\ndata: ${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/message' })}\n\n`;
368+
const teams = [{ id: 'a', name: 'Demo', isCurrent: true }];
369+
respondText(notice + sse(JSON.stringify({ teams })));
370+
await expect(listTeams('https://example.com', 'k')).resolves.toEqual(teams);
371+
respondText(sse('not json'));
372+
await expect(listTeams('https://example.com', 'k')).rejects.toThrow(
373+
/unexpected team list/,
374+
);
375+
});
376+
377+
it('throws when the listing failed, so it is not read as one team', async () => {
378+
respondText('Too many requests', 429);
379+
await expect(listTeams('https://example.com', 'k')).rejects.toThrow(/429/);
380+
});
381+
});
382+
128383
describe('verifyKey', () => {
129384
const realFetch = globalThis.fetch;
130385
afterEach(() => {

0 commit comments

Comments
 (0)