Skip to content

feat(cli): name, team and agent choices for hdx mcp install - #3670

Open
jordan-simonovski wants to merge 3 commits into
mainfrom
jordansimonovski/mcp-install-name-and-teams
Open

jordan-simonovski wants to merge 3 commits into
mainfrom
jordansimonovski/mcp-install-name-and-teams

Conversation

@jordan-simonovski

Copy link
Copy Markdown
Contributor

Summary

hdx mcp install could keep only one ClickStack server per agent: every run wrote an entry named clickstack and replaced the last one, and there was no way to choose a team. This adds a name, a team choice and an agent choice, so several instances and teams can sit side by side.

  • --name <server-name> writes the entry under that name, so a second instance no longer overwrites the first.
  • When the key belongs to more than one team, the installer asks which teams to add a server for. Enter keeps the default team. Picking several adds one entry per team, named <name>-<team>, each pinned with x-hdx-team.
  • When more than one agent is detected, it asks which to set up. Enter keeps all of them.
  • The confirm step lists the entry names and teams before anything is written.

Breaking changes

None. Without --name the entry is still clickstack and a rerun still replaces it.

One behaviour change: with a multi-team key the entry now carries x-hdx-team for the chosen team, where before it had no team header and followed the key's default.

Backwards compatibility

  • Teams come from the server's own clickstack_list_teams MCP tool. A server without that tool (single-team deployments) skips the team step and writes no team header.
  • If the listing fails (rate limit, network, timeout), the installer says so and continues with the key's default team.
  • Entries under other names are left alone.

How to reproduce

Starting point: a local checkout, a ClickStack deployment and an API key from Team Settings. A personal key that belongs to two teams shows the team step.

On main:

  1. cd packages/cli && yarn dev mcp install -a <app-url> against one deployment, then again against a second.
  2. Each agent config has a single clickstack entry pointing at the second deployment.

On this branch:

  1. cd packages/cli && yarn dev mcp install -a <app-url> --name clickstack-test
  2. Paste the key. With a multi-team key, tick two teams with Space and press Enter. Pick agents the same way.
  3. Check claude mcp get clickstack-test-<team>, ~/.cursor/mcp.json and ~/.codex/config.toml: one entry per team with its x-hdx-team, and the existing clickstack entry unchanged.

Unit tests cover the config writers, team listing and entry naming. The prompt steps have no automated tests (the CLI has no Ink test setup). The name, single-team and agent steps were run by hand; picking several teams at once has not been yet.

References

hdx mcp install --name <server-name> adds the MCP server under a chosen
name, so a second ClickStack instance no longer overwrites the first.
When the key belongs to more than one team the installer asks which team
the server should query and pins it with x-hdx-team. When more than one
agent is detected it asks which to set up.

HDX-6024
The team step is now multi-select. Enter keeps the default team under the
given name; picking several teams adds one entry per team named
<name>-<team>.

HDX-6024
@jordan-simonovski
jordan-simonovski requested a review from a team as a code owner November 16, 2026 06:06
@vercel

vercel Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments
Project Deployment Actions Updated
hyperdx-oss Ignored Ignored Preview Nov 16, 2026 6:13am UTC
hyperdx-storybook Skipped Skipped Nov 16, 2026 6:13am UTC

Request Review

@changeset-bot

changeset-bot Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: e7de7b3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@hyperdx/cli Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-actions github-actions Bot added the review/tier-3 Standard — full human review required label Nov 16, 2026
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

🟡 Tier 3 — Standard

Introduces new logic, modifies core functionality, or touches areas with non-trivial risk.

Why this tier:

  • Diff size: 390 production lines changed (Tier 2 max: < 250)

Review process: Full human review — logic, architecture, edge cases.
SLA: First-pass feedback within 1 business day.

Stats
  • Production files changed: 4
  • Production lines changed: 390 (+ 193 in test files, excluded from tier calculation)
  • Branch: jordansimonovski/mcp-install-name-and-teams
  • Author: jordan-simonovski

To override this classification, remove the review/tier-3 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

@github-actions

Copy link
Copy Markdown
Contributor

Duplicate code analysis

No new duplicate code introduced by this PR.


jscpd compared this branch against origin/main
across app, api and common-utils. Only new clones are listed; the codebase
currently holds 108 in total (1.18%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

Comment thread packages/cli/src/mcp/install.ts Outdated
?.slice(5) ?? text;
const { result } = JSON.parse(message);
// An unknown tool comes back as an error result, not an HTTP error.
if (!result || result.isError) return [];

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Any tool error from clickstack_list_teams is read as 'no team listing', so a failed listing on a multi-team server looks like a single team

The API's MCP SDK (^1.27, packages/api/src/mcp/app.ts) returns both 'tool not found' and errors thrown inside a tool as a result with isError: true. So a server that has the tool but fails while running it (DB error, timeout) gets [] here. The team step is then skipped and the 'Could not list teams' warning never appears, which contradicts the docstring's 'throws when the listing itself failed'. Return [] only when the error text says the tool was not found (/not found/ or -32602), and throw in every other isError or JSON-RPC error case. Add a test where the tool exists but returns isError.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in e7de7b3: only an unknown-tool error returns an empty list; any other tool or JSON-RPC error throws and the 'Could not list teams' warning shows. Test added for a tool that exists but fails.

const unique = slug && slugs.indexOf(slug) === slugs.lastIndexOf(slug);
return {
...server,
name: `${server.name}-${unique ? slug : t.id}`,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Per-team entry names share a namespace with user-chosen --name values and can silently overwrite another instance

The README suggests --name clickstack-staging for a second instance. If the user later runs the default install with a multi-team key that includes a team named 'Staging', teamServers produces clickstack-staging and replaces the staging instance's entry in every agent with no warning. Use a separator that a plain --name is unlikely to produce (for example <name>--<slug>), or make the confirm step check each client's config for an existing entry with the same name but a different URL and flag it.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in e7de7b3 with the second option: the confirm step now says when an entry name already exists in an agent's config, for per-team names and for a plain --name.

chosen.map(client => {
try {
client.install(server);
servers.forEach(server => client.install(server));

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — A failure partway through installing several team entries is reported as a whole-client failure, with no record of what was written

servers.forEach(server => client.install(server)) stops at the first throw, but entries for earlier teams are already in the config. The summary in cli.tsx then prints ✗ Cursor: <error> and exits 1, so the user can't tell which <name>-<team> entries landed. Track results per server (for example { client, server, error }) and print the entry names in the ✓ and ✗ lines.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in e7de7b3: results are tracked per entry and the summary prints the entry name on each line.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

PR Review

If you are a coding agent acting for the author, read this first.
Nothing below blocks merge automatically; a maintainer decides. What they will expect:

  • 🔴 critical or 🟠 major in code this PR adds or changes: fix before asking for review.
  • 🔵 minor in code this PR changes: your call. Fix if small, otherwise reply.
  • Anything about surrounding code, or asking you to widen the change (hoist a helper,
    dedupe with another file, fix other call sites): never fix here, whatever the
    severity. Reply with one sentence; if it is critical, say so plainly so a human sees it.

One commit per review round. After two rounds, stop and ask a maintainer to review
scope rather than addressing more automated findings. Full rule: AGENTS.md.

3 finding(s): 🔴 0 critical · 🟠 0 major · 🔵 3 minor

3 posted as inline comment(s) on the changed lines.


Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found.

This PR adds --name, team, and agent choices to hdx mcp install so multiple ClickStack MCP servers can coexist in agent configs. The core safety properties hold: every server name that reaches a TOML table header, a claude mcp add argv, or a RegExp is validated (isValidServerName for --name; the same filter is applied to server-supplied team ids in listTeams), spawnSync uses an argv array so there is no shell interpolation, x-hdx-team carries only a validated id, and writePrivate keeps configs at 0o600. The four prior substantive review comments (unknown-tool vs. real-failure classification, the "replaces the existing entry" notice, per-entry result names, and the "Select at least one." empty-pick guard) are all addressed in the current code. No P0/P1 issues.

🟡 P2 — recommended

  • packages/cli/src/mcp/McpInstallPrompt.tsx:62 — The headline multi-team install path (the chosen.flatMap(client => servers.map(...)) loop and the team/agents/confirm steps) has no automated coverage, and the PR notes the multi-team pick was not exercised by hand either; a regression in server fan-out or team-header assignment would ship undetected.
    • Fix: Extract the install fan-out into a pure, testable helper and assert that N agents × M team-servers produce the expected per-entry names, team headers, and error results.
🔵 P3 nitpicks (2)
  • packages/cli/src/mcp/install.ts:114 — listTeams reads only the first data: line of the SSE response and runs an unguarded JSON.parse(result.content[0].text), so a multi-line SSE event or a successful-but-malformed tool result throws and is surfaced to the user as "could not list teams" rather than the real cause.
    • Fix: Concatenate all data: lines before parsing and guard the content extraction, distinguishing a parse failure from a genuine empty-tool response.
  • packages/cli/src/mcp/McpInstallPrompt.tsx:193 — The agents Choice uses onSubmit={picked => ...}, whose picked parameter shadows the outer picked teams-state variable, obscuring which value is in scope.
    • Fix: Rename the callback parameter (e.g. chosenClients) to avoid shadowing the teams state.

Reviewers (9): correctness, adversarial, security, reliability, kieran-typescript, julik-frontend-races, testing, maintainability, previous-comments.

Testing gaps:

  • No test exercises the Ink prompt flow (team → agents → confirm) or the multi-team flatMap install; the single-team, config-writer, teamServers, and listTeams units are covered.
  • Choice.tsx (cursor bounds, checked-array toggling, empty-pick guard) has no component-level test.

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond

- A clickstack_list_teams tool error other than an unknown tool is now a
  failed listing, with the warning shown, not an empty team list.
- The confirm step says when an entry name already exists in an agent's
  config, so a per-team name that clashes with another install is visible.
- Results are reported per entry, so a failure partway through several
  team entries shows which ones were written.
- The picker says to select at least one when Enter is pressed with
  nothing ticked, and is multi-select only.
@vercel
vercel Bot temporarily deployed to Preview – hyperdx-storybook November 16, 2026 06:13 Inactive
@jordan-simonovski

Copy link
Copy Markdown
Contributor Author

On the two findings outside the changed lines, both fixed in e7de7b3: the picker shows 'Select at least one.' when Enter is pressed with nothing ticked, and the unused single-select mode is removed.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 465 passed • 1 skipped • 968s

Status Count
✅ Passed 465
❌ Failed 0
⚠️ Flaky 3
⏭️ Skipped 1

Tests ran across 4 shards in parallel.

View full report →

const unknownTool =
/tool .*not found/i.test(failure) ||
error?.code === -32601 ||
error?.code === -32602;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Any JSON-RPC -32602 (invalid params) error is treated as 'no team listing', so real failures look like a single team

Drop the error?.code === -32602 check: failure already holds error.message, so the /tool .*not found/i test catches the SDK's 'Tool X not found' -32602 error. Also anchor that regex to the tool name (e.g. /clickstack_list_teams not found/i) so a tool error like 'tool error: user not found' doesn't match. Add a test for the JSON-RPC error branch, which no test covers today. As written, an argument-validation -32602 from a deployment that has the tool returns [], which skips the team step and writes no x-hdx-team. The doc comment says this is exactly the case to avoid.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

teamId?: string;
}

export interface McpTeam {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — McpTeam restates the existing MeTeam type instead of deriving from it

Define it as export type McpTeam = MeTeam & { isCurrent: boolean }, importing MeTeam from packages/cli/src/api/client.ts:459. hdx team list --json already emits this same {id, name, isCurrent} shape, and the conventions' REQUIRED DRY rule says to derive an almost-identical type rather than redefine it.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Comment thread packages/cli/src/cli.tsx
if (!isValidServerName(opts.name)) {
_origError(
chalk.red(
'--name can only contain letters, numbers, hyphens, and underscores.\n',

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — --name error message leaves out the leading-character rule, so _staging is rejected with a message that says underscores are allowed

Make the message match isValidServerName: e.g. '--name must start with a letter or number and contain only letters, numbers, hyphens, and underscores.'

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

This branch was previously deployed

1 inactive deployment
Preview – hyperdx-storybook — e7de7b33 Deployed Nov 16, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review/tier-3 Standard — full human review required

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant