Skip to content

Commit d2108e9

Browse files
cliffhallclaude
andcommitted
docs(client-smoke): spawn the web launcher from the worktree root
Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 0749824 commit d2108e9

1 file changed

Lines changed: 35 additions & 26 deletions

File tree

‎.claude/skills/client-smoke/SKILL.md‎

Lines changed: 35 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,11 @@ record is in `/pr-flow` (client evidence); building and starting the server is
1414

1515
Three clients, in the order to reach for them:
1616

17-
| Client | Driven by | Use it for |
18-
| --- | --- | --- |
19-
| Inspector **CLI** | A command. This is the **scripted path**, and the one an agent runs | One request, one JSON result: the evidence that goes in a PR |
17+
| Client | Driven by | Use it for |
18+
| -------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
19+
| Inspector **CLI** | A command. This is the **scripted path**, and the one an agent runs | One request, one JSON result: the evidence that goes in a PR |
2020
| Inspector **web** UI | A Playwright script in headless Chromium, which an agent writes and runs | What the CLI cannot do: elicitation and sampling round-trips, URL elicitation, tasks, notifications arriving, a long-running tool's progress |
21-
| An **LLM client** | A prompt | Whether a model picks the tool and uses its result, which the PR checklist asks for |
21+
| An **LLM client** | A prompt | Whether a model picks the tool and uses its result, which the PR checklist asks for |
2222

2323
Build first (`npm run build -w src/<server>`). Every command below runs the
2424
last build of a TypeScript server, not your edit.
@@ -85,7 +85,7 @@ That rule produces the three failures people actually hit:
8585
`--cli -e KEY=VALUE node …` leaves no server command at all, and the CLI
8686
falls back to your personal catalog (`~/.mcp-inspector/mcp.json`). With
8787
several servers in it that fails with `Multiple servers found in config
88-
file. Please specify one with --server`. Either way it is no longer talking
88+
file. Please specify one with --server`. Either way it is no longer talking
8989
to your build, so move the option after the command.
9090
- **`Method is required`** means the options ended up on the wrong side of a
9191
`--`.
@@ -106,13 +106,13 @@ $INSPECT node src/memory/dist/index.js \
106106

107107
The exit code is the verdict, so check it rather than reading the text:
108108

109-
| Outcome | stdout | stderr | Exit |
110-
| --- | --- | --- | --- |
111-
| The request succeeded | `{"result": …}` | | 0 |
112-
| The tool ran and returned `isError: true` | `{"result":{"content": …, "isError": true}}` | `{"error":{"code":"tool_is_error", …}}` | 5 |
113-
| No such tool | | `{"error":{"code":"tool_not_found", …}}` | 5 |
114-
| An HTTP server could not be reached (refused, DNS, timeout) | | `{"error":{"code":"unreachable", …}}` | 4 |
115-
| Bad arguments, a failed version negotiation, or a stdio server that exited | | `{"error":{"code":"error", …}}` | 1 |
109+
| Outcome | stdout | stderr | Exit |
110+
| -------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------- | ---- |
111+
| The request succeeded | `{"result": …}` | | 0 |
112+
| The tool ran and returned `isError: true` | `{"result":{"content": …, "isError": true}}` | `{"error":{"code":"tool_is_error", …}}` | 5 |
113+
| No such tool | | `{"error":{"code":"tool_not_found", …}}` | 5 |
114+
| An HTTP server could not be reached (refused, DNS, timeout) | | `{"error":{"code":"unreachable", …}}` | 4 |
115+
| Bad arguments, a failed version negotiation, or a stdio server that exited | | `{"error":{"code":"error", …}}` | 1 |
116116

117117
These are the codes observed on 2.9.0 for the cases this repo's servers
118118
produce; the CLI defines others (schema and skill checks, authentication)
@@ -166,11 +166,11 @@ or session code; it is deprecated but must keep working.
166166
The Inspector connects in one of three eras, chosen with `--protocol-era` (the
167167
CLI) or **Server Settings → Protocol Era** (the web UI):
168168

169-
| Era | What the Inspector does |
170-
| --- | --- |
171-
| `legacy` (the default) | A plain `initialize`. Negotiates 2025-11-25 or older |
172-
| `modern` | Pins 2026-07-28 through `server/discover`, with no fallback |
173-
| `auto` | Probes `server/discover`, and falls back to `initialize` |
169+
| Era | What the Inspector does |
170+
| ---------------------- | ----------------------------------------------------------- |
171+
| `legacy` (the default) | A plain `initialize`. Negotiates 2025-11-25 or older |
172+
| `modern` | Pins 2026-07-28 through `server/discover`, with no fallback |
173+
| `auto` | Probes `server/discover`, and falls back to `initialize` |
174174

175175
**Every server serves both eras**: the Python servers since #4853, the
176176
TypeScript servers since #4852 (stdio through the SDK's `serveStdio`, and
@@ -219,7 +219,10 @@ server's environment with `-e KEY=VALUE` before the `--`.
219219

220220
Install Playwright in a scratch directory **outside the worktree**, never as a
221221
dependency of this repo (`npm i [email protected]`, then
222-
`npx playwright install chromium`), and run the script from there.
222+
`npx playwright install chromium`), and run the script from there. The
223+
launcher inherits the script's working directory, so spawn it with `cwd` set
224+
to the worktree root: the server commands above use paths relative to it, and
225+
from the scratch directory no server would start.
223226

224227
### The recipe
225228

@@ -271,25 +274,31 @@ dependency of this repo (`npm i [email protected]`, then
271274
Era differences that change what to expect, beyond the tool list (see
272275
[Protocol eras](#protocol-eras)):
273276

274-
| Scenario | 2025-11-25 (`legacy`) | 2026-07-28 (`modern`) |
275-
| --- | --- | --- |
276-
| `trigger-url-elicitation` with `errorPath` on | **Two** dialogs: the -32042 error path, then the retry's | **One**: there is no -32042 on 2026-07-28 |
277-
| `trigger-sampling-request`, rejected | **Results** with a **Tool Error** alert | **Tool Call Failed** |
278-
| Each prompt for input | Plain dialog | The dialog also shows `input_required` (the answer is sent as a retry) |
277+
| Scenario | 2025-11-25 (`legacy`) | 2026-07-28 (`modern`) |
278+
| --------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- |
279+
| `trigger-url-elicitation` with `errorPath` on | **Two** dialogs: the -32042 error path, then the retry's | **One**: there is no -32042 on 2026-07-28 |
280+
| `trigger-sampling-request`, rejected | **Results** with a **Tool Error** alert | **Tool Call Failed** |
281+
| Each prompt for input | Plain dialog | The dialog also shows `input_required` (the answer is sent as a retry) |
279282

280283
A sketch of one scenario, with the launch and teardown above:
281284

282285
```js
283286
const page = await browser.newPage();
284287
await page.goto(url);
285-
await page.getByRole("switch", { name: /Connect or disconnect/ }).check({ force: true });
288+
await page
289+
.getByRole("switch", { name: /Connect or disconnect/ })
290+
.check({ force: true });
286291
await page.locator('label[for$="-Tools"]').click();
287-
await page.getByRole("button", { name: / trigger-elicitation-request$/ }).click();
292+
await page
293+
.getByRole("button", { name: / trigger-elicitation-request$/ })
294+
.click();
288295
await page.getByRole("button", { name: "Execute Tool" }).click();
289296
const dialog = page.getByRole("dialog", { name: "Elicitation Request" });
290297
await dialog.getByRole("textbox", { name: "String", exact: true }).fill("Ada");
291298
await dialog.getByRole("button", { name: "Submit" }).click();
292-
await page.getByRole("heading", { name: /^(Results|Tool Call Failed)$/ }).waitFor();
299+
await page
300+
.getByRole("heading", { name: /^(Results|Tool Call Failed)$/ })
301+
.waitFor();
293302
// → Results: "✅ User provided the requested information! … Name: Ada"
294303
await page.close();
295304
```

0 commit comments

Comments
 (0)