* chore: close a batch of quality-gate & tidy gaps (#1785#1787#1789#1790#1767)
Bundles five small, related tidy/gate items into one PR:
- #1785: delete the dead src/types/navigation.ts InspectorTab (0 importers;
duplicated/drifted from utils/inspectorTabs InspectorTabId). src/types/
now holds only ambient .d.ts stubs.
- #1787: add src/hooks/** to the web coverage `include` (it was silently
outside the ≥90 gate) and add tests for the two untested hooks,
useServerJsonImport and useImportClientConfig, bringing every hook to
≥90 on lines/statements/functions/branches.
- #1789: widen clients/{cli,tui,launcher} format/format:check to their
top-level configs; add root format:shared / format:check:shared covering
test-servers/src/**, vitest.shared.mts, and the repo-root eslint.config.js.
- #1790: pin prettier to an exact version (3.8.4, dropping the ^3.8.1
caret) in all five package.json files so the format gate's verdict can't
shift with an in-range patch bump; lockfiles synced.
- #1767: its root-file format+lint gap is closed here (format:shared +
a new lint:shared via a second files block in the root eslint.config.js;
web/server/ was already gated in #1788). Its larger cli/tui __tests__
typecheck piece (76 type errors) is split out to #1791.
Prettier-normalized the newly-covered files (pure formatting). No runtime
behavior change. `npm run ci` green.
Closes#1785Closes#1787Closes#1789Closes#1790Closes#1767
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
* chore: address PR #1792 review findings
- #1789 gap: widen clients/web format to include .storybook and clients/
launcher format to include scripts/; reformat the 3 .storybook files
(were non-conforming under the pinned prettier 3.8.4). Audited all 885
tracked source files — now fully prettier-clean.
- Export VALIDATE_DEBOUNCE_MS / COLLAPSE_DELAY_MS / HIGHLIGHT_DURATION_MS
from useServerJsonImport and use them in the test instead of hardcoded
300/1000/250 (so a tuned constant can't silently desync the test).
- Assert the symmetric renameErrors["alpha"] alongside ["beta"] so a
one-directional collision-check regression fails.
- Comment the blank-rename test as exercising a UI-unreachable defensive
branch (canImport gates submit).
- Un-stale the two specification/v2_ux_interfaces_plan.md references to the
now-removed navigation.ts InspectorTab.
npm run ci green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
* docs: sync AGENTS.md format-surface description with the widened globs (#1792 review r2)
1ce3b64 added .storybook to clients/web's format glob and scripts/ to
clients/launcher's, but AGENTS.md:222 still described the pre-fix scope.
Bring it in line and note the non-recursive top-level glob is why nested
dirs are named explicitly. Docs only.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
* chore: handle PR #1792 round-3 follow-ups in-place (format-coverage guard, uniform globs, theme gate)
Rather than defer these to tickets, fold them into this PR:
- Obs 2: widen every client + root format glob to a uniform
*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} so a future .mts/.cjs/.tsx top-level
file can't silently slip the gate.
- Obs 1: add scripts/verify-format-coverage.mjs (wired into `validate`) —
it parses the format:check globs out of every package.json, enumerates
all tracked source files, and fails listing any not covered by a glob.
The durable, standing version of #1789's one-shot audit; negative-tested.
- Obs 3: bring src/theme/** under the coverage gate (21/23 files were
already ≥90 transitively; add Paper.test.tsx for the one laggard,
Paper.ts). src/App.tsx (~4.5k lines, ~42% branches) is converted from a
silent omission into an explicit, documented exclusion (comment on the
coverage `include` + AGENTS.md) — gating it is a dedicated effort, not a
whitelist tweak.
npm run ci green (the new guard reports 885/885 tracked source files gated).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
* chore: address PR #1792 round-4 findings (guard hardening, docs, exclusion list)
- Harden verify-format-coverage: only harvest format:check globs from
scripts transitively reachable from `validate` (via npm run refs), so an
unwired/renamed format:check no longer counts as coverage. Negative-tested
— renaming clients/web format:check to an unreferenced name now fails the
guard (627 files flagged) instead of passing.
- Name src/main.tsx and src/index.ts (browser + bin bootstraps) alongside
src/App.tsx in the coverage-include comment and AGENTS.md, so the
documented exclusion list is complete rather than claiming App.tsx is the
only one.
- Doc sync: document verify:format-coverage (AGENTS.md + README script table
+ scripts/ layout line), fix the `validate` ordering (verify:format-
coverage now runs before validate:core) in AGENTS.md and README, and
update the quoted globs to the uniform *.{ts,tsx,mts,cts,js,jsx,mjs,cjs} /
test-servers *.{ts,tsx,mts,cts}.
npm run ci green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
* chore: address PR #1792 round-5 findings (airtight guard + doc/config sync)
- verify-format-coverage: assert the root `validate` chain invokes each
client's `validate` (cd <dir> && npm run validate), closing the last
reachability edge — a client dropped from the root chain now fails the
guard even though its own globs still exist. Negative-tested.
- eslint.config.js: widen the shared `files` block to
test-servers/src/**/*.{ts,tsx,mts,cts} to match the widened lint:shared
glob, so a future .mts/.cts there is lint-gated, not just prettier-gated.
- AGENTS.md: scope the "uniform extension set" claim to client globs
(core stays {ts,tsx}, shared {ts,tsx,mts,cts}), with verify:format-coverage
as the backstop — removing the self-contradiction with the line below.
npm run ci green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* refactor(web): sharpen src/lib vs src/utils rule and move misfiled modules (#1776)
Codify the empirical rule the web client already followed loosely — utils =
pure functions that compute; lib = things that instantiate, adapt, or touch
the environment — in AGENTS.md and clients/web/README.md, and move the modules
that sat on the wrong side of it.
Moves (source + co-located test):
- lib/sandbox-csp -> utils (pure CSP-string construction; type-only import)
- utils/browserTabVisibility -> lib (registers visibilitychange listeners)
- utils/oauthResume -> lib (reads/writes sessionStorage)
- utils/clearServerOAuthState -> lib (drives live InspectorClient / OAuthStorage)
Borderline audits (kept in place): pendingReauth (pure type declarations),
deepLink / correlateTransportErrors / mcpNetworkHeaders / oauthUx / oauthFlow /
oauthNetworkPhase (pure transforms / type-only core imports) stay in utils;
downloadFile stays whole in lib (dominant side is DOM side effects).
Also relocate the lone src/test/lib/downloadFile.test.ts straggler beside its
source at src/lib/downloadFile.test.ts, and document the test-placement rule
(side-by-side by default; src/test/ only for core/ tests, the integration
project, and shared scaffolding).
Pure move — no behavior change; no build/coverage config keys off the boundary.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
* refactor(web): address review — fix stale paths, move customHeaders, one-way arrows (#1776)
Responds to the @claude review on PR #1784:
1. Stale path references (fixed): update the four in-repo pointers left at
pre-move paths — specification/v2_auth_mid_session.md (oauthResume,
browserTabVisibility → lib/), and the two load-bearing sandbox security
comments (sandbox_proxy.html, sandbox-controller.ts → src/utils/sandbox-csp).
2. lib/types/customHeaders (moved): it's pure (types + pure transforms), the
rule's clearest counterexample. Moved lib/types/customHeaders.{ts,test.ts} →
utils/ (no external importers; only its own test) and removed the
undocumented lib/types/ subdir. Documented that utils/ is the home for pure
shared domain types + their constructors — no separate types/ bucket.
3. One-way arrows (item 3): declare OAuthResumeAuthKind in utils/pendingReauth
and re-export it from lib/oauthResume, so the only cross-directory arrow now
points lib → utils. Codified that invariant in AGENTS.md.
Wording nit: AGENTS.md + README now state diagnostic logging
(console.warn/error) doesn't count as a side effect for the utils rule.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
* docs: address review round 2 — stale customHeaders refs, rule wording (#1776)
Doc-only follow-up to the round-2 @claude review on PR #1784 (no code changed):
1. Stale paths (same class as round-1 item 1): the customHeaders move left
three references to the deleted lib/types/customHeaders.ts path in
specification/ (v2_ux_interfaces_phase_0_4_inventory.md,
v2_ux_interfaces_plan.md ×2) — updated to utils/customHeaders.ts.
2. customHeaders anchor: note in AGENTS.md that its shape is staged for
ServerSettingsForm (per v2_ux_interfaces_plan.md), so its zero-importer
state reads as intentional rather than rot; kept as the no-types/-bucket
illustration and led the anchor list with load-bearing modules.
3. Type-only-import clause: split the conflated clause — a type-only import
(pendingReauth) and re-exporting core's pure functions/constants
(oauthUx/oauthFlow) are distinct reasons to stay in utils; what makes a
module lib is wrapping core's stateful runtime. Fixed in both AGENTS.md
and the web README.
Cosmetic: re-padded the v2_auth_mid_session.md table row to column width.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
* docs: address review round 3 — scope the "no types/ bucket" claim (#1776)
Doc-only follow-up to the round-3 @claude review on PR #1784 (no code changed):
1. "no separate types/ bucket" overreached: clients/web/src/types/ does exist
(navigation.ts + react-syntax-highlighter .d.ts ambient stubs wired via
tsconfig.app.json paths). Scoped the claim in both AGENTS.md and the web
README to "no types/ sub-bucket INSIDE lib/utils", and noted src/types/ is
for ambient .d.ts stubs, not domain types.
2. README example list drifted from AGENTS.md's round-2 load-bearing anchors —
realigned it (inspectorTabs/mcpNetworkHeaders, dropped the zero-importer
customHeaders from the headline list).
3. Clarified v2_ux_interfaces_plan.md:185 so the v2 path reads as the copy's
destination, not as the v1.5 source location.
Follow-up filed as #1785 (board Todo): src/types/navigation.ts InspectorTab is
dead and duplicates utils/inspectorTabs.ts — kept out of this pure-move PR.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
* docs: address review round 4 — reconcile src/types/ claim with #1785 (#1776)
Doc-only follow-up to the round-4 @claude review on PR #1784 (no code changed):
The round-3 scope fix overshot: it asserted src/types/ holds "not domain types
at all", but the dead navigation.ts InspectorTab is a plain-.ts domain type
still living there, and specification/v2_ux_interfaces_plan.md:181-182 actively
prescribes placing InspectorTab there — so AGENTS.md and that spec doc gave
opposite guidance about the same directory.
- AGENTS.md + web README: softened to "not the place for new domain types"
and added a parenthetical that the one lingering domain type (dead
navigation.ts) is tracked for removal in #1785; until then a pure domain
type belongs in utils/, not src/types/.
- v2_ux_interfaces_plan.md:181: marked the tab-enum placement guidance as
superseded by #1785 (live type is InspectorTabId in utils/inspectorTabs.ts).
Self-heals on merge of #1785.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
* docs: address review round 5 — fix garbled #1785 clause, restructure utils rule (#1776)
Doc-only follow-up to the round-5 @claude review on PR #1784 (no code changed):
1. Grammar (item 1): the round-4 #1785 clause read "superseding [#1785] will
remove it" — a participle with no subject. Reworded to "the dead
navigation.ts InspectorTab, which #1785 will remove".
2. Readability (item 2): the src/utils/ bullet had accreted into a single
~1,400-char blob across five review rounds. Promoted the carve-outs to
scannable sub-bullets (Domain types / Diagnostic logging / Importing from
core) and lifted the src/types/ note out to its own line, since it's a
statement about a sibling directory, not about utils.
AGENTS.md only; the README's parallel sentence was already clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
* docs+config: address review round 6 — correct the coverage-glob claim (#1776)
Responds to the round-6 @claude review on PR #1784:
1. "no build/coverage glob" was factually wrong (should-fix): the web coverage
include in clients/web/vite.config.ts DOES enumerate src/lib/** and
src/utils/**. The conclusion (a move between them is coverage-neutral)
survives, but the reason was wrong. Reworded both AGENTS.md and the web
README to say nothing *enforces* the boundary — no path alias, and the
include lists both dirs so a move is coverage-neutral — plus the important
whitelist caveat: a module outside components/lib/utils/server falls out of
the ≥90 gate entirely.
2. Removed a pre-existing duplicate glob in vite.config.ts (src/lib/**/*.{ts,tsx}
appeared twice, lines 161 and 163). Inert (vitest de-dupes) but it sat three
lines from the config the doc now describes.
Nits: gave the README bullet the same round-5 sub-bullet restructure as
AGENTS.md, and made its #1785 reference a real markdown link (bare #N doesn't
autolink in rendered repo markdown).
npm run ci green (config change re-verified through coverage + smokes + Storybook).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a specification/v2_auth.md landing page summarizing the four auth specs
(EMA / XAA, Hardening, Mid-session, Smoke testing) with a section submenu,
mirroring the V2 UX index pattern.
Add a V2 Auth link (after V2 UX) and a V2 New Spec Impact link to every spec
page's top menu so the top-level nav is uniform, and restructure the four
v2_auth_*.md pages onto the shared two-tier menu (top menu + auth submenu).
Docs only.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S3fTN8H3R8YV4yUGvZjYnX
ToolsScreen, PromptsScreen, and ResourcesScreen each tracked the user's
current selection via `selectedXxxName` / `onSelectXxx` props, hoisting
screen-local UI state into whatever rendered them. InspectorView never
threaded those callbacks anywhere, so clicks in the controls panel did
not display the matching detail panel — the detail panel only rendered
if a parent fed selection back in.
Move selection into `useState` inside each screen and drop the
`selectedXxxName` / `onSelectXxx` props. MCP-derived data (`callState`,
`getPromptState`, `readState`) keeps flowing in from `InspectorView` as
props. ResourcesScreen wraps `onReadResource` so a template-expanded URI
becomes the selected resource for preview rendering.
Update each screen's stories to drop the deleted props. Stories that
need a pre-selected item use a `play` function to click it — no
component coupling to Storybook.
Add Phase 4.3 to the interfaces plan describing the rule.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The interfaces doc was produced by parallel research subagents that
were instructed to prefix uncertain hook names with (likely) rather
than fail to fill in a section. The result is 52 instances of "likely"
in v2_ux_interfaces.md, almost all attached to hook names that were
never cross-checked against v1.5/main. Several are actively wrong:
- useTools / usePrompts / useResources do not exist in v1.5; the
actual hooks are useManagedTools / useManagedPrompts /
useManagedResources.
- useTasks does not exist; v1.5 has useManagedRequestorTasks (and
Task itself is a raw SDK 1.x type, not an Inspector wrapper).
- useMcpClient does not exist; v1.5 has useInspectorClient.
- useLogs conflates three v1.5 hooks: useMessageLog, useStderrLog,
useFetchRequestLog.
- useHistory does not exist; v1.5 uses useMessageLog as the history.
- useElicitation / useSampling / useRoots do not exist as discrete
React hooks in v1.5; those flows are handled inside InspectorClient
via SDK request handlers.
- useServerCapabilities is not a separate hook; capabilities live on
useInspectorClient's result.
- Appendix A's "v1.5 bundles primitive logic in App.tsx" claim is
wrong about v1.5 in this repo; that's true of upstream
modelcontextprotocol/inspector v1.x mainline, not v1.5/main here,
which has the full core/react/* split.
Adds Phase 0.3 to walk every (likely) instance and either resolve it
against v1.5 source or strike it, with a confirmed rename table and
explicit definition-of-done (zero "likely" matches in
v2_ux_interfaces.md after the pass). Adds Risk #11 capturing the
underlying rule: hedging words next to type/hook/file claims must be
vetted before a planning doc ships.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds specification/v2_ux_interfaces_plan.md, the implementation plan
for the component interface refactor scoped in v2_ux_interfaces.md.
Uses the v1.5/main branch of this repo as the source of truth for
Inspector-owned wrapper types (MCPServerConfig, ConnectionStatus,
MessageEntry, FetchRequestEntry, StderrLogEntry, ServerState, the
*Invocation cache types) and pins @modelcontextprotocol/sdk at the
latest 1.x line (^1.29.0). Includes a name-mapping table that
translates the Inspector* placeholders in v2_ux_interfaces.md to
v1.5's actual type names.
Plan organizes the work into phases: foundations (SDK + wrapper
types), elements, group+screen feature clusters (folded together to
keep the build green at every commit), views, and a cleanup sweep.
Calls out the discovered ServerCard auto-connect useEffect violation
to fix in-place during the server cluster, and flags that Task is
already exported by the SDK 1.x so the InspectorTask wrapper framing
in v2_ux_interfaces.md is stale and needs a follow-up correction.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Cliff Hall