Repository navigation
feat(cli): name, team and agent choices for hdx mcp install - #3670
Conversation
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
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
🦋 Changeset detectedLatest commit: 65e490c The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
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 |
🟡 Tier 3 — StandardIntroduces new logic, modifies core functionality, or touches areas with non-trivial risk. Why this tier:
Review process: Full human review — logic, architecture, edge cases. Stats
|
Duplicate code analysisNo new duplicate code introduced by this PR. jscpd compared this branch against |
PR Review
2 finding(s): 🔴 0 critical · 🟠 0 major · 🔵 2 minor None could be anchored to changed lines; they are listed below. Findings outside the changed lines2 minor
Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides. |
Deep ReviewScope: ✅ 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
🔵 P3 nitpicks (6)
Pre-existing (not introduced by this PR)
Reviewers (11): security, adversarial, maintainability, testing, kieran-typescript, reliability, project-standards, julik-frontend-races, previous-comments, agent-native, learnings-researcher. Testing gaps:
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.
|
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. |
E2E Test Results✅ All tests passed • 465 passed • 1 skipped • 992s
Tests ran across 4 shards in parallel. |
| const unknownTool = | ||
| /tool .*not found/i.test(failure) || | ||
| error?.code === -32601 || | ||
| error?.code === -32602; |
There was a problem hiding this comment.
🔵 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
There was a problem hiding this comment.
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.
| teamId?: string; | ||
| } | ||
|
|
||
| export interface McpTeam { |
There was a problem hiding this comment.
🔵 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
There was a problem hiding this comment.
Fixed in 65e490c: McpTeam is now MeTeam & { isCurrent: boolean }.
| if (!isValidServerName(opts.name)) { | ||
| _origError( | ||
| chalk.red( | ||
| '--name can only contain letters, numbers, hyphens, and underscores.\n', |
There was a problem hiding this comment.
🔵 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
There was a problem hiding this comment.
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.
|
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. |
Summary
hdx mcp installcould keep only one ClickStack server per agent: every run wrote an entry namedclickstackand 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.<name>-<team>, each pinned withx-hdx-team.Breaking changes
None. Without
--namethe entry is stillclickstackand a rerun still replaces it.One behaviour change: with a multi-team key the entry now carries
x-hdx-teamfor the chosen team, where before it had no team header and followed the key's default.Backwards compatibility
clickstack_list_teamsMCP tool. A server without that tool (single-team deployments) skips the team step and writes no team header.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:cd packages/cli && yarn dev mcp install -a <app-url>against one deployment, then again against a second.clickstackentry pointing at the second deployment.On this branch:
cd packages/cli && yarn dev mcp install -a <app-url> --name clickstack-testclaude mcp get clickstack-test-<team>,~/.cursor/mcp.jsonand~/.codex/config.toml: one entry per team with itsx-hdx-team, and the existingclickstackentry 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