Repository navigation
feat(cli): name, team and agent choices for hdx mcp install - #3670
jordan-simonovski wants to merge 3 commits into
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: e7de7b3 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 |
| ?.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 []; |
There was a problem hiding this comment.
🔵 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
There was a problem hiding this comment.
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}`, |
There was a problem hiding this comment.
🔵 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
There was a problem hiding this comment.
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)); |
There was a problem hiding this comment.
🔵 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
There was a problem hiding this comment.
Fixed in e7de7b3: results are tracked per entry and the summary prints the entry name on each line.
PR Review
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. |
Deep Review✅ No critical issues found. This PR adds 🟡 P2 — recommended
🔵 P3 nitpicks (2)
Reviewers (9): correctness, adversarial, security, reliability, kieran-typescript, julik-frontend-races, testing, maintainability, previous-comments. 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 • 968s
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
| 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
| 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
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