- TypeScript 90.8%
- JavaScript 8.8%
- CSS 0.2%
- HTML 0.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
6711593a37
Three findings, all real. The first is a security hole introduced by round 1's own fix. 1. The analysis job could have published live secrets. Round 1 pinned `Bash(gh issue comment <N>:*)` to the tracked issue and treated that as scoping, but a `Bash(...)` grant matches a command PREFIX and says nothing about the flags that follow — so `gh issue comment <N> --body-file /proc/self/environ` matched it, and this job's subprocess environment holds ANTHROPIC_API_KEY and GITHUB_TOKEN. A prompt injection from upstream release notes could have posted live credentials into a public issue. The model now has no tool that can write anywhere. It returns its write-up as `--json-schema` structured output, and a deterministic, model-free step posts it: the body arrives through the environment rather than the command line, so nothing in it can be read as a flag or a path, and the issue number comes from the matrix. That step is the only thing in the job holding a token that can write. WebFetch is denied as well. It was not raised, but with `Read` available an outbound fetch the model controls is the same exfiltration channel by another route; `gh release view` already covered the need. The remaining grant is read-only and accepts no attacker-chosen file path. The general rule is now in AGENTS.md rather than only this instance: a prefix grant on any command that accepts a file path is an arbitrary-file read with a publish attached. 2. Issue existence was standing in for analysis completion. A failed or timed-out `analyze` job left an issue the next sweep matched, emitted `[]` for, and reported as a green no-op — so the promised analysis was never retried. The posting step now stamps ANALYSIS_MARKER on its comment, and a sweep finding an existing issue without one re-queues it. The marker is matched with `startsWith`, so a maintainer quoting it cannot suppress the retry. 3. A failed supersession note was unrecoverable. Creation succeeding and the note failing left a state where every retry matched the target's own marker and skipped reconciliation entirely, so the note was never posted. An existing issue is now ADOPTED rather than skipped: the loop takes its number and runs the same follow-up it would for a new one. The existing announced-marker check prevents duplication, and a `stale.number === number` guard stops an issue superseding itself. Findings 2 and 3 share one restructure — replacing the early `continue` with adoption is what gives both the retry path. ANALYSIS_MARKER is necessarily duplicated in the workflow, since the posting step is shell. Drift would be invisible from either file alone and would make every issue read as permanently unanalyzed, so a test asserts the workflow contains the exact constant. Mutation-checked, each failing a different minimal set: if (match) continue; restored -> supersession-retry + re-queue tests hasAnalysis -> always true -> re-queue + hasAnalysis tests workflow marker misspelled -> the drift-guard test 47 tests in this file; `npm run local:gate` green end to end. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019JWUZxLDnPgLQzjBrtk1x9 Signed-off-by: cliffhall <cliff@futurescale.com> |
||
| .claude | ||
| .github | ||
| clients | ||
| core | ||
| docs | ||
| scripts | ||
| specification | ||
| test-servers | ||
| .dockerignore | ||
| .gitattributes | ||
| .gitignore | ||
| .mcp.json | ||
| .npmignore | ||
| AGENTS.md | ||
| CLAUDE.md | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| Dockerfile | ||
| eslint.config.js | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| SECURITY.md | ||
| tsconfig.base.json | ||
| tsconfig.lint.json | ||
| vitest.shared.mts | ||
MCP Inspector
A developer tool for inspecting Model Context Protocol (MCP) servers. It ships as a single package, @modelcontextprotocol/inspector, that provides three ways to inspect a server:
- Web — a Vite + React + Mantine single-page app with a Node backend.
- CLI — a scriptable command-line client for automation, CI, and fast agent feedback loops.
- TUI — an interactive terminal UI built with Ink.
All three run through one global mcp-inspector binary:
npx @modelcontextprotocol/inspector # web UI (default)
npx @modelcontextprotocol/inspector --cli # CLI
npx @modelcontextprotocol/inspector --tui # TUI
Upgrading from v1? Read the v1 → v2 migration guide — CLI flags, the new
--configvs.--catalogsplit, the Node engine bump, and what no longer ships.
Repo status. This is the v2 line of the Inspector. Active development happens on
v2/main(the develop branch — all v2 PRs target it), which is merged intomainat milestone releases;mainis the default branch and holds the latest released v2, published to the npmlatesttag. The legacy v1 line lives onv1/main— security fixes only, published straight from that branch to the npmv1-latesttag (npx @modelcontextprotocol/inspector@v1-latest). SeeAGENTS.mdfor branch/board conventions.
Quick start (development)
Requires Node >=22.19.0.
npm install # at the repo root; postinstall cascades into every client
npm run build # web → cli → tui → launcher
For day-to-day web iteration, run Vite directly — fast HMR, no launcher build needed:
cd clients/web && npm run dev
The launcher-driven scripts run the built launcher, so build first:
npm run web # prod web launcher against clients/web/dist
npm run web:dev # web launcher in --dev mode (Vite)
v2 is not an npm workspace — each client under clients/* keeps its own package.json and node_modules, and shared code lives in core/, consumed via a @inspector/core build-time alias. Every runtime dependency core/ imports is declared once, in the repo-root package.json, and each client declares only what that client alone consumes — its UI stack, its bundler-inlined packages, its dev tooling — which leaves clients/cli and clients/launcher with no runtime dependencies of their own. What that means for adding a dependency (root vs. client, dependencies vs. devDependencies, and the bundler external lists) is in the local-dev skill.
Project layout
inspector/
├── clients/
│ ├── web/ Web client (Vite + React + Mantine). src/ = browser app; server/ = Node backend
│ ├── cli/ CLI client (tsup bundle, @inspector/core alias)
│ ├── tui/ TUI client (Ink + React, tsup bundle)
│ └── launcher/ Shared launcher — provides the `mcp-inspector` bin, dispatches to web/cli/tui
├── core/ Shared code consumed via the `@inspector/core` alias (no package.json)
├── test-servers/ Composable MCP test servers + fixtures used by integration and smoke tests
├── scripts/ Root build/verify tooling (install cascade, smokes, the verify:* guards)
│ and repo automation run from CI (the dependency, Dependabot-alert and SDK sweeps)
├── docs/ Task-oriented guides — see below
├── specification/ Design/build specifications
├── .claude/skills/ Agent skills: the repo's procedures, invokable by name
├── AGENTS.md Contribution rules for agents AND humans
└── README.md You are here
Each client has its own README with client-specific detail: web · cli · tui · launcher.
Documentation
| Guide | Covers |
|---|---|
| Architecture | The @inspector/core shared package, and the web client's "dumb components" + Storybook approach |
| Testing and the quality gate | What each validate / coverage / smoke / verify:* script covers, the GitHub-CI-vs-local-gate split, and the supported browsers |
| Writing a skill | How to write a skill description that actually fires, and eval cases that measure it — the case shapes that work, and the tuning loop |
| Test servers | The composable test servers and the showcase config for every feature — what to run, what to click, and what the broken build did |
| Publishing | What ships in the tarball, the packaging invariants, and pack:verify |
| Docker | Running the container image — ports, volumes, and where secrets go |
| Migrating from v1 to v2 | CLI flag mapping, --config vs. --catalog, the Node engine bump, env-var renames |
| MCP server configuration | Which server(s) the Inspector connects to, and the config file format |
| Reviewing an MCP App | The CLI-first → one-shot-web recipe for automated App-tool review |
| Launcher and config consolidation | Why the launcher runs a client in-process rather than spawning it |
Testing and the quality gate
Each client self-validates from its own folder; the root scripts chain them. There is no aggregate root test script.
npm run validate # fast inner loop: format:check + lint + typecheck + build + unit tests
npm run coverage # the per-file ≥90% gate (lines/statements/functions/branches)
npm run local:gate # MANDATORY before pushing — a strict superset of GitHub CI
npm run local:gate chains every check below, plus the smokes and the Storybook tests. Testing and the quality gate owns the stage list and says what each one covers and why two are local-only; AGENTS.md holds the testing rules themselves.
Contributing — AGENTS.md, CLAUDE.md, and the skills
AGENTS.md is the contract for changing this codebase, and it applies to humans and AI agents alike. It is not agent-only boilerplate — it holds the project's real rules: the version/label conventions, the TypeScript and Mantine/React standards, the testing and coverage requirements, and the mandatory pre-push gate. Read it before making changes, and keep it up to date when you change structure, tooling, or rules.
The repo's procedures — multi-step recipes with commands and live IDs — live in .claude/skills/ instead, one directory per procedure, so they are loaded only when the task calls for them. They are ordinary committed Markdown: an agent that doesn't understand skills can read them, and AGENTS.md carries an index of what exists. Claude Code users invoke one by name (/release, /issue-triage, …).
CLAUDE.md is the entry point Claude Code loads automatically; it includes AGENTS.md, so agents and humans work from the same source of truth. If you use a different agent that reads AGENTS.md, you get the same rules.
A key rule worth surfacing here: all work is issue-driven. Before starting, find or create a tracking issue on the v2 project board; open PRs against v2/main with Closes #<issue>. External contributions are accepted as issues, not pull requests — see CONTRIBUTING.md.
License
MIT.