Skip to content

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

Merged
jordan-simonovski merged 4 commits into
mainfrom
jordansimonovski/mcp-install-name-and-teams
Nov 16, 2026
Merged

jordan-simonovski merged 4 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 9:21am UTC
hyperdx-storybook Skipped Skipped Nov 16, 2026 9:21am UTC

Request Review

@changeset-bot

changeset-bot Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 65e490c

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: 428 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: 428 (+ 267 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 Resolved
Comment thread packages/cli/src/mcp/install.ts Resolved
@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.

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

None could be anchored to changed lines; they are listed below.

Findings outside the changed lines

2 minor
  • 🔵 packages/cli/src/mcp/McpInstallPrompt.tsx:653 — Choosing several teams leaves the old <name> entry in place, so the agent gets a duplicate server → Take a user who already has a clickstack entry (from an earlier run, or added by hand from the Team Settings snippet). If they now tick two teams, teamServers writes clickstack-<teamA> and clickstack-<teamB>, and the plain clickstack entry stays. That entry has no team header, so it still points at the default team, and the agent now loads the same tools twice for that team. The confirm step only warns about entries that will be replaced, never about this leftover. Fix: when servers has more than one entry, check chosen.some(c => c.has(name)) for the base name. If it exists, either remove it as part of the install or show a line in the confirm step saying it will remain.
  • 🔵 packages/cli/src/mcp/install.ts:784 — listTeams and readJsonObject use any and as casts instead of a Zod schema → This breaks the TypeScript conventions in .hdx/context.md: avoid any, avoid as casts, use Zod for runtime validation. Three places are affected: reply: { result?: any; error?: any }, (teams as McpTeam[]) (isCurrent is never checked), and readJsonObject(): Record<string, any>. Fix: parse the JSON-RPC reply and the { teams: [{ id, name, isCurrent }] } payload with small Zod schemas. Use safeParse so a malformed reply still reaches the 'unexpected team list' error. Have readJsonObject return Record<string, unknown>.

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

Scope: hdx mcp install gains a --name flag, an interactive team choice, and an agent choice so several ClickStack MCP servers/teams coexist. Diff: 4 production files + tests + docs/changeset, base 0096a355c.
Mode: report-only (read-only; no edits, no artifacts).

✅ No critical issues found. No P0/P1: no data loss on the happy path, no injection, no auth bypass, no guaranteed crash. Security, agent-native parity, and all 8 previously-raised review comments verified as genuinely addressed. The recommendations below are correctness-hardening and maintainability.

🟡 P2 — recommended

  • packages/cli/src/mcp/install.ts:172 — teamServers guarantees uniqueness only within the slug set, but the final entry name is either <name>-<slug> or <name>-<teamId>, and those two namespaces are never cross-checked, so two teams can produce an identical entry name that silently overwrites the first in every agent config (one team's server, with its teamId, is lost, and the confirm screen still shows two distinct lines).
    • Fix: deduplicate on the fully composed entry name across the whole team set, not only among slugs, before falling back to the id.
    • adversarial, maintainability, kieran-typescript
  • packages/cli/src/mcp/McpInstallPrompt.tsx:202 — the confirm view maps over servers (from teamServers) but recovers each team's display label from the separate picked array by positional index; the 1:1 alignment is an unwritten invariant that only holds because teamServers happens to preserve order and length today.
    • Fix: carry the team name/label on the returned server entry (or return {server, team} pairs) so the view does not depend on cross-array index alignment.
    • maintainability, kieran-typescript
🔵 P3 nitpicks (6)
  • packages/cli/src/mcp/McpInstallPrompt.tsx:197 — chosen.filter(c => c.has(s.name)) runs synchronous readFileSync/readJsonObject disk reads per client on every render pass of the confirm step, not once.
    • Fix: compute the "replaces existing entry" set once (memoize, or when entering the confirm step).
  • packages/cli/src/mcp/install.ts:116 — the JSON-RPC reply type { result?: any; error?: any }, readJsonObject(): Record<string, any>, and the (teams as McpTeam[]) cast all use any/assertion at the untrusted MCP/file boundary; the validating filter never checks isCurrent despite the cast asserting it.
    • Fix: type these as unknown and narrow each field (including typeof t.isCurrent === 'boolean') before use.
    • kieran-typescript, maintainability
  • packages/cli/src/mcp/install.ts:117 — listTeams sends id: 1 but accepts the last SSE message carrying any result/error, ignoring the JSON-RPC id, so an extra result-bearing message on the stream could be read as the reply.
    • Fix: match the reply on parsed?.id === 1 before accepting it.
  • packages/cli/src/mcp/Choice.tsx:37 — the key.return branch reads checked[i] from the render-closure snapshot while the Space toggle uses a functional updater, so a batched Space+Enter (held keys / pasted newline) can submit the pre-toggle selection.
    • Fix: derive the chosen set from the latest state via a functional read or a ref that both branches update.
  • packages/cli/src/mcp/install.ts:403 — the file now reaches 403 lines, past the repo's 300-line component-size guideline in AGENTS.md.
    • Fix: split the team/listTeams/teamServers logic (or the mcpClients factory) into a separate module.
  • .changeset/mcp-install-name.md:2 — a feat adding user-facing flags and flows is marked patch.
    • Fix: confirm patch is the intended semver bump for @hyperdx/cli rather than minor.

Pre-existing (not introduced by this PR)

  • packages/cli/src/mcp/install.ts:57 — verifyKey() has no fetch timeout and the checking step binds no input handler, so a hung/slow server blocks with no in-app cancel; the new verifyKey → listTeams chain lengthens that window (listTeams does add a 15s timeout).
  • packages/cli/src/mcp/install.ts:109 — the claude-code installer removes the existing entry before claude mcp add; a failed add leaves no entry (reported, exit 1, but destructive), now multiplied across one entry per team.
  • packages/cli/src/mcp/McpInstallPrompt.tsx — rapid double-Enter or a trailing newline on the key/confirm steps can invoke verifyKey+listTeams or installAll+onDone twice (Ink unmounts asynchronously); guard with an in-flight/done latch.

Reviewers (11): security, adversarial, maintainability, testing, kieran-typescript, reliability, project-standards, julik-frontend-races, previous-comments, agent-native, learnings-researcher.

Testing gaps:

  • No Ink test harness, so Choice.tsx and McpInstallPrompt step-routing/confirm glue are untested — extracting the next-step decision (teamCount × clientCount) into a pure helper would make the highest-value branch unit-testable.
  • listTeams is untested for CRLF SSE endings, a reply split across multiple data: lines, multiple result/error messages, and the invalid-team-id filter branch.
  • teamServers is untested for the duplicate composed-name (slug == another team's id) case.
  • No test for submitKey treating a listTeams rejection as teamsError + default-team install, for double-submit idempotency, or for the --name validation exit(1) path.
  • Coverage note: the correctness reviewer (session model) did not return before synthesis; 11 of 12 reviewers contributed. docs/solutions/ does not exist, so no prior-learnings pass was possible. No migrations, so schema-drift/deployment reviewers did not apply.

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 • 992s

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

Tests ran across 4 shards in parallel.

View full report →

Comment thread packages/cli/src/mcp/install.ts Outdated
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

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 65e490c: the error-code checks are gone and only 'clickstack_list_teams not found' returns an empty list. Tests added for the JSON-RPC error branch and for an unrelated 'not found' tool error.

Comment thread packages/cli/src/mcp/install.ts Outdated
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

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 65e490c: McpTeam is now MeTeam & { isCurrent: boolean }.

Comment thread packages/cli/src/cli.tsx Outdated
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

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 65e490c: the message now states the leading-character rule.

- Only a 'clickstack_list_teams not found' error means no team listing;
  other invalid-params or not-found errors are a failed listing, and the
  warning now gives the reason.
- The team listing reads the reply to its own request from the SSE stream
  and rejects a malformed team list.
- The install loop is a helper with a test for several agents and teams.
- McpTeam derives from MeTeam, and the --name error states the
  leading-character rule.
@vercel
vercel Bot temporarily deployed to Preview – hyperdx-storybook November 16, 2026 09:20 Inactive
@jordan-simonovski

Copy link
Copy Markdown
Contributor Author

On the Deep Review findings, all in 65e490c: the install loop is now an installAll helper with a test for several agents and team servers including a failed entry; listTeams picks the reply to its own request out of the SSE stream and rejects a malformed team list, with the reason shown in the warning; the shadowed callback parameter is renamed. Component tests for Choice and the prompt steps are not added here, since packages/cli has no Ink test setup and adding one would widen this PR.

@jordan-simonovski
jordan-simonovski merged commit a25e945 into main Nov 16, 2026
35 checks passed
@jordan-simonovski
jordan-simonovski deleted the jordansimonovski/mcp-install-name-and-teams branch November 16, 2026 10:46

This branch was previously deployed

1 inactive deployment
Preview – hyperdx-storybook — 65e490cb 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.

3 participants