> **Upgrade von v1?** Lies den [v1 → v2-Migrationsleitfaden](https://github.com/modelcontextprotocol/inspector/blob/HEAD/docs/v1-to-v2-migration.md) — CLI-Flags, die neue Aufteilung zwischen `--config` und `--catalog`, das Node-Engine-Upgrade und was nicht mehr mitgeliefert wird.

> **Repo-Status.** Dies ist die **v2**-Linie des Inspectors. Die aktive Entwicklung findet auf **`v2/main`** statt (dem Develop-Branch — alle v2-PRs zielen darauf), der bei Meilenstein-Releases in **`main`** zusammengeführt wird; `main` ist der Standard-Branch und enthält die neueste veröffentlichte v2-Version, die auf den npm-Tag `latest` veröffentlicht wird. Die Legacy-**v1**-Linie lebt auf **`v1/main`** weiter — nur Sicherheitskorrekturen, die direkt von diesem Branch auf den npm-Tag `v1-latest` veröffentlicht werden (`npx @modelcontextprotocol/inspector@v1-latest`). Siehe [`AGENTS.md`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/AGENTS.md) für Branch-/Board-Konventionen.

## Projektstruktur

v2 ist **kein** npm-Workspace. Jeder Client unter `clients/*` besitzt sein eigenes `package.json` und `node_modules`; gemeinsam genutzter Code liegt in `core/` und wird über einen `@inspector/core`-Build-Zeit-Alias konsumiert (ohne eigenes `package.json`). Ein einziges `npm install` im Root löst kaskadenartig Installationen in jedem Client aus (siehe [Setup](#setup)).```
inspector/
├── clients/
│   ├── web/          # Web client (Vite + React + Mantine). src/ = browser app; server/ = Node dev/prod 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)
│   ├── auth/         # OAuth: providers, discovery, storage, endpoint overrides, mid-session recovery (browser/node/remote backends)
│   ├── client/       # Install-level client config (`client.json`): browser-safe parse/validate + Node load/save, remote backend, secrets
│   ├── json/         # JSON + parameter/argument conversion utilities, and the nullable-union
│   │                 #   schema collapse shared by the web and TUI form builders
│   ├── logging/      # Silent pino logger singleton
│   ├── mcp/          # InspectorClient runtime, state stores, transports, config import,
│   │                 #   and the RFC 6570 URI-template helpers the web form and TUI expand through
│   ├── node/         # Node-only shared helpers: version reader, hostUrl (host normalize/canonicalize + all-interfaces/loopback detection)
│   ├── react/        # React hooks over the state stores
│   └── storage/      # File I/O helpers for the OAuth persist backends
├── test-servers/     # Composable MCP test servers + fixtures used by integration tests
├── scripts/          # Root build/verify tooling (install cascade, smokes, verify-build-gate, verify-format-coverage, verify-dep-lockstep, pack:verify)
├── docs/             # Task-oriented guides (v1→v2 migration, server configuration, MCP App review, launcher/config plan)
├── specification/    # Design/build specifications
├── AGENTS.md         # Contribution rules for agents AND humans (see below)
└── README.md         # You are here

- **Frischer Klon:** `npm install` im Repository-Root ausführen.
- **Nach einem Pull, der die Abhängigkeiten eines Clients ändert:** `npm install` erneut im Root ausführen, um jeden Client neu zu synchronisieren.

Die Kaskade (`scripts/install-clients.mjs`) ist nur für die Entwicklung gedacht – sie wird früh beendet, wenn das Paket als Abhängigkeit installiert ist, und das veröffentlichte Tarball enthält nur das `build/` jedes Clients, sodass Endbenutzer nicht betroffen sind. Setzen Sie `INSPECTOR_SKIP_CLIENT_INSTALL=1`, um sie zu überspringen.

**Wo eine Abhängigkeit deklariert wird.** Die MCP-SDK-Pakete (`@modelcontextprotocol/client`, `core`, `server`, `server-legacy`, `ext-apps`) leben ausschließlich in der **Root**-`package.json` – niemals in der eines Clients. Die Node-Auflösung wandert nach oben, sodass die Root-Installation in der Kette jedes Clients liegt und das Root-Manifest bereits das ist, gegen das das veröffentlichte Tarball aufgelöst wird. Sie pro Client zu deklarieren installiert eine zweite Kopie, die von der des Roots abweichen kann – so landeten vor [#1970](https://github.com/modelcontextprotocol/inspector/issues/1970) zwei Versionen von `ext-apps` (und des transitiven v1 `@modelcontextprotocol/sdk`) im Baum – und eine zweite Kopie von `client`/`core` ist der Fehler, für den `vitest.shared.mts` einen `dedupe`-Workaround enthält. Die gleiche Root-only-Platzierung gilt für alles, was ausschließlich über Root-eigenen Code ohne eigenes Manifest erreicht wird (`test-servers/src`, `core/`), und `vitest.shared.mts` aliasiert diese auf das Repository-Root – `express` und `yaml`, beide über `test-servers/src` erreicht, sind heute die beiden. **Ob ein solches Paket eine `dependency` oder eine `devDependency` ist, ergibt sich daraus, wer es zur Laufzeit konsumiert, nicht daraus, wo es deklariert ist:** Alles, was `core/` zur Laufzeit importiert, muss eine Root-**`dependency`** sein, weil die Client-Builds npm-Pakete externalisieren und eine veröffentlichte Installation sie aus dem Root-Manifest auflöst, wo devDependencies fehlen. `express` ist nur für Tests da und eine devDependency; `yaml` steht derzeit in `dependencies`. **`vite` und `@vitejs/plugin-react` sind aus demselben Grund Root-`dependencies`, nicht aus Versehen** – sie sehen nach Build-Werkzeugen aus, aber `clients/web/server/start-vite-dev-server.ts` importiert sie zur Laufzeit für `mcp-inspector --web --dev`, und `clients/web/tsup.runner.config.ts` listet beide als `external`, sodass eine veröffentlichte Installation sie aus dem Root-Manifest auflöst. Sie in `devDependencies` zu verschieben würde `--web --dev` für Konsumenten brechen (und das bedarfsgesteuerte `vite build` in `ensure-web-build.ts`), während alle lokalen Prüfungen bestanden würden. Es bedeutet, dass sie unter `npm audit --omit=dev` auftauchen, was ein Feature ist: Sie sind wirklich im Produktionsbaum.

## Entwicklung während der Laufzeit

Für die tägliche Web-Entwicklung führen Sie Vite direkt aus dem Web-Client aus (schnelles HMR, kein Launcher-Build erforderlich):```bash
cd clients/web && npm run dev

## Das gemeinsame Paket `@inspector/core`

![Gemeinsame Code-Architektur: die vier Clients über dem gemeinsamen Paket @inspector/core](https://assets.kitploit.com/production/public/readmes/50997/12951c8cb492b9d753ea13b98a8ea2475ef2e250a9e849227b05c3cfc7c5d31c/962dd293aaae81c94af868f086686d56189155e63449bfc6b537818e8725c812-display-v1.webp)

`core/` enthält die Logik, die allen drei Clients gemeinsam ist, sodass sich Web, CLI und TUI identisch verhalten. Der Einstiegspunkt ist die **`InspectorClient`**-Klasse (`core/mcp/`), die die Verbindung zu einem MCP-Server, den Request/Response-Lebenszyklus und eine Reihe von State-Stores besitzt; `core/react/` stellt React-Hooks für diese Stores bereit, die sowohl der Web- als auch der TUI-(Ink-)React-Baum konsumieren. OAuth (`core/auth/`) ist in isomorphe Logik plus Browser-/Node-/Remote-Backends aufgeteilt, sodass dieselben Abläufe im Browser, in Node und gegen ein Remote-Backend funktionieren.

`core/` hat absichtlich **kein `package.json`** — es wird nicht eigenständig veröffentlicht. Jeder Client bindet es über einen `@inspector/core`-Alias ein:

- **CLI / TUI:** `esbuildOptions.alias` in ihrer jeweiligen `tsup.config.ts` mappt `@inspector/core` → das `core/`-Verzeichnis des Repos, und `noExternal: [/^@inspector\/core/]` bindet es in das Bundle ein.
- **Web:** derselbe Alias in `clients/web/vite.config.ts` für die Browser-App und den Node-Backend-Runner.

Die Veröffentlichung von `core/` als eigenes Paket (z. B. damit Dritte darauf aufbauen können) ist bewusst aufgeschoben — siehe Issue [#1636](https://github.com/modelcontextprotocol/inspector/issues/1636).

## Web-Client: „dumme Komponenten“ + Storybook

Der Web-Client v2 ist aus **präsentationalen („dummen“) Komponenten** aufgebaut — sie akzeptieren Daten und Callbacks als Props und enthalten nur Anzeigelogik, ohne direkt Daten abzurufen oder Client-State zu halten. Der State stammt aus den `@inspector/core`-Hooks, die nahe der Spitze des Baums eingebunden sind. Dadurch bleiben Komponenten isoliert, testbar und dokumentierbar.

Dieser Ansatz macht **Storybook** hier erstklassig: Jede Screen- und Element-Komponente besitzt eine `*.stories.tsx`-Datei (96+ Stories), die sie mit Fixture-Props rendert. Storybooks **Play-Funktionen** dienen zugleich als Interaktionstests und laufen headless in CI (`npm run ci:storybook`, Chromium über Playwright).

Das Styling folgt einer strikten Mantine-first-Konvention (Theme-Varianten und Komponenten-Props statt CSS-Klassen, CSS-Custom-Properties der Form `--inspector-*` statt roher Farb-Literale). Die vollständigen Regeln stehen in [`AGENTS.md`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/AGENTS.md) unter **React-Anweisungen** — lies sie, bevor du die Web-UI anfasst. Element-Komponenten liegen in `clients/web/src/components/elements/`; Theme-Varianten in `clients/web/src/theme/`.

## Test-Server

`test-servers/` stellt **komponierbare MCP-Server** für die Integrations- und Smoke-Testsuiten bereit, sodass die Tests einen echten Server über einen echten Transport verwenden, statt auf Mocks zurückzugreifen. Ein Server wird aus **Presets** zusammengesetzt (Fixture-Fabriken in `test-servers/src/preset-registry.ts` — Tools, Resources, Prompts, Tasks, Elicitation, Sampling, OAuth, …) und kann auf zwei Arten betrieben werden:

- **Prozessintern** — importiere die Fabriken (`createTestServerHttp`, `createEchoTool`, …) und führe den Server innerhalb der Event-Loop des Tests aus (genutzt von den HTTP-Integrationspfaden).
- **Als Subprozess** — `test-servers/build/test-server-stdio.js` wird als echter stdio-Subprozess gestartet (genutzt von den CLI-Smoke-Tests und den Stdio-Integrationstests).

Konfiguriere einen Server deklarativ mit einer JSON-Konfiguration (siehe `test-servers/configs/*.json`), die Presets auswählt, und lade ihn dann über `--config`. Da die Server als echte Subprozesse gestartet werden, muss die Build-Ausgabe zuerst existieren:```bash
npm run test-servers:build   # (from clients/web) → tsc -p test-servers, emits test-servers/build/

Einzelne Clients: `build:web`, `build:cli`, `build:tui`, `build:launcher`. Der Web-Build erzeugt sowohl die Browser-SPA (`clients/web/dist`, Vite) als auch den Node-Prod-Server-Runner (`clients/web/build`, tsup).

## Testing & das Qualitäts-Gate

Jeder Client validiert sich selbst aus seinem eigenen Ordner; die Root-Skripte führen sie in einer Kette aus. Es gibt **kein** aggregiertes Root-`test`-Skript — verwenden Sie `validate` (schnell) oder `coverage` (das Gate).

| Script                              | Was es tut                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npm run validate`                  | Führt zuerst die drei dauerhaften Guards aus — `verify:format-coverage` (jede nachverfolgte Quelldatei ist format-gated), `verify:typecheck-coverage` (jede landet in einem tsconfig-Projekt), `verify:dep-lockstep` (keine Abhängigkeit, die aus zwei Installationen in ein `tsc`-Programm gelangt, weicht zwischen ihnen ab) — dann `test:scripts` (die eigenen Parser-Unit-Tests der Guards), dann `validate:core` (das gemeinsame `core/`-Gate aus `format:check` + `lint`), dann pro Client: `format:check` + `lint` + **`typecheck`** (cli/tui/launcher; web führt den Typecheck über `tsc -b` innerhalb seines `build` aus) + `build` + schnelle Unit-Tests. Der schnelle Inner-Loop-Check. |
| `npm run coverage`                  | Das **Pro-Datei-≥90%-Gate** (Zeilen/Anweisungen/Funktionen/Zweige) unter v8-Instrumentierung, pro Client. Von der CI erzwungen. Für Web läuft dabei auch das Integrationsprojekt und es wird die gemeinsame Laufzeit von `core/` abgedeckt (einschließlich `core/json` und `core/client`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `npm run smoke`                     | End-to-End-Smoke-Tests durch den gebauten Launcher (`--help`-Dispatch + Prod-CLI/TUI/Web), plus zwei Headless-Chromium-Smoke-Tests: ein Boot-Smoke, der das Prod-Web-Bundle ausführt und einen sauberen ersten Render bestätigt (kein unbehandelter Fehler — synchrone Exception oder unbehandelte Promise-Ablehnung, so wie sich ein in das Browser-Bundle gelangendes Node-Builtin äußert), und ein **MCP-Apps**-Smoke (`smoke:web:app`), der Verbinden → App öffnen → `data-app-status="ready"` gegen einen komponierbaren App-Server durchläuft und dabei den Sandbox-Proxy und die UI-Protokoll-Brücke abdeckt.                                                                                                                                                                                                                                                                                                                                   |
| `npm run verify:build-gate`         | Führt einen echten `vite build` mit einem Node-Builtin aus, das gewaltsam in den Browser-Graph eingefügt wird, und stellt fest, dass der Build über das #1769-Gate **fehlschlägt** (das Vites Warnung zur Browser-Externalisierung in einen harten Fehler verwandelt). Schützt davor, dass die Formulierung der Warnung bei einem Vite-Versionssprung abweicht und das Gate stillschweigend deaktiviert. Teil von `npm run ci`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `npm run verify:format-coverage`    | Extrahiert die `format:check`-Globs aus jeder `package.json` (nur die von `validate` aus erreichbaren), zählt alle nachverfolgten Quelldateien auf und **schlägt fehl**, wobei alle aufgelistet werden, die von keinem Glob abgedeckt sind — der dauerhafte Guard für die Invariante „jede First-Party-Quelldatei ist format-gated“ (#1792). Läuft zuerst in `validate`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `npm run test:scripts`              | Tabellenbasierte Unit-Tests (`node --test`) für die eigenen reinen Parser der Guards (`scripts/lib/npm-scripts.mjs`, `scripts/lib/tsc-program.mjs` + die exportierten Helfer von `verify-typecheck-coverage.mjs` und `verify-dep-lockstep.mjs`), jeweils ein Fall pro Regel, die sie kodieren, plus `scripts/lib/resolve-node-bin.test.mjs` — der plattformübergreifende Bin-Auflöser (#1939), fixiert an den tatsächlichen `bin`/`exports`-Formen der Pakete, die die Skripte tatsächlich starten. Läuft in `validate` — und `verify:typecheck-coverage` bewacht wiederum *dieses* Gate (von `validate` erreichbar, nicht-leere Testmenge, jede Testdatei vom `test:scripts`-Glob erfasst), da `node --test` eine Datei, die sein Glob verfehlt, stillschweigend überspringt und trotzdem mit 0 beendet.                                                                                                                                                                                                                                                                                                                                                       |
| `npm run verify:typecheck-coverage` | Das Typecheck-Coverage-Pendant zum obigen (#1791): Für jeden Node-Client (automatisch von der Platte erkannt — eingebunden über die Projekte seines `typecheck`-Skripts, oder bei einem `tsc -b`-Client wie `clients/web` über die `references` seiner `tsconfig.json`) führt es diese Projekte mit `tsc --listFilesOnly` aus, vereinigt sie und **schlägt fehl**, wobei jede nachverfolgte `.ts`/`.tsx`/`.mts`/`.cts`-Datei unter dem Client aufgelistet wird, die in keinem Projekt landet (damit eine neue Top-Level-Config/Helper nicht stillschweigend untypechecked bleibt). Es verlangt außerdem, deny-by-default, dass das First-Party-TS, das kein Client besitzt (`test-servers/src`, die root `vitest.shared.mts`, das gesamte `core/` und jeder neue Top-Level-Ort), in einem tsc-Durchlauf irgendeines Client-Projekts landet — so wird auch ein `core`-`*.tsx` erfasst, das die Web-Projekte nicht erreichen. Zudem stellt es sicher, dass das Gate verdrahtet ist (jeder Typecheck-Durchlauf eines Clients — sein `typecheck`-Skript oder das `tsc -b` des Webs — von seinem `validate` aus erreichbar ist und die Root-Kette das `validate` jedes Clients ausführt). Läuft in `validate`. |
| `npm run verify:dep-lockstep`       | Bewacht die Invariante „eine Version pro installationsübergreifende Abhängigkeit“ (#1896). v2 ist kein Workspace, daher kompiliert ein Testprojekt eines Clients das gemeinsame First-Party-TypeScript — `core/`, `test-servers/src` und die root-eigene `vitest.shared.mts`, die alle ihre Abhängigkeiten aus der **Root**-Installation auflösen — zusammen mit den eigenen Quellen des Clients, wodurch dasselbe Paket zweimal in ein `tsc`-Programm gelangt. Bei derselben Version ist das harmlos; bei Abweichung muss TypeScript zwei strukturell verschiedene Kopien jedes Typs zueinander in Beziehung setzen, was bei einer rekursiv-generischen Oberfläche exponentiell ist (zod `4.3.6` vs. `4.4.3` erschöpfte den 4GB-tsc-Heap in `clients/web`). Leitet seine Kandidatenmenge daraus ab, **was tatsächlich in jedes Programm gelangt** (#1965) — jedes Client-tsconfig-Projekt, das mit `tsc --listFilesOnly` über das gemeinsame `scripts/lib/tsc-program.mjs` aufgelistet wird, wobei jede aufgelöste `node_modules`-Datei ihrer besitzenden Installation zugeordnet wird, und behält die Pakete, die aus zwei Installationen in ein Programm gelangen (ein Paket, dessen Deklarationen nur über die `.d.ts` eines anderen Pakets ankommen, wie bei `@modelcontextprotocol/sdk`, ist für einen Scan von First-Party-Importen unsichtbar). Bewertet jede Kopie anhand des Lockfile-Eintrags für den genauen Installationspfad, den das Programm aufgelöst hat, vergleicht nur die Installationen, die sich in einem Programm getroffen haben, und **schlägt deny-by-default fehl** bei jeder Abweichung, die nicht in der annotierten `TOLERATED_SKEW`-Allowlist steht — heute leer —, wobei ein auf der Allowlist stehendes Paket nur *innerhalb einer Major-Version* toleriert wird. Läuft in `validate`. |
| `npm run ci`                        | **Verpflichtender Befehl vor dem Push.** `validate` → `coverage` → `verify:build-gate` → `smoke` → Storybook. Eine echte Obermenge der GitHub-CI.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `npm run pack:verify`               | Publish-Smoke-Test — siehe [Publishing](#publishing).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

Es gibt auch Pro-Client-Skripte (`validate:web`, `coverage:cli`, `smoke:tui`, …), dazu root `validate:core` / `format:core` für das gemeinsame `core/`-Paket, `format:scripts` für die Root-`scripts/`-Werkzeuge und `format:shared` / `lint:shared` für die Root-„shared“-Oberfläche (`test-servers/src/**`, `vitest.shared.mts`, die Root-`eslint.config.js`). Führen Sie vor dem Committen `npm run format` aus — das Root-`format` korrigiert `core/`, die Root-`scripts/`, die Shared-Oberfläche und jeden Client; `validate` führt das nicht korrigierende `format:check` aus und lässt CI bei jeder unformatierten Datei fehlschlagen.

**Das Linting ist typbewusst.** Alle fünf ESLint-Bereiche (`clients/{web,cli,tui,launcher}` plus das Root-`core/` + gemeinsame Gate) aktivieren `@typescript-eslint/no-floating-promises` auf `error`, sodass ein Promise, das weder awaited noch zurückgegeben, mit `.catch(…)` abgeschlossen noch explizit mit `void` verworfen wird, bei `lint` fehlschlägt — und damit bei `validate` ([#1959](https://github.com/modelcontextprotocol/inspector/issues/1959)). Die Regel benötigt Typinformationen, daher benennt die Konfiguration jedes Bereichs ein Parser-Projekt; das des Root-Bereichs ist **`tsconfig.lint.json`**, ein reines Lint-Projekt, das `core/**`, `test-servers/src/**` und `vitest.shared.mts` abdeckt, die kein eigenes tsconfig haben. Es erzeugt nichts und ändert keinen Typecheck — aber ein neuer First-Party-TS-Ort, der zum Root-Lint-Bereich hinzugefügt wird, muss zu dessen `include` hinzugefügt werden. Siehe **TypeScript-Anweisungen** in [`AGENTS.md`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/AGENTS.md) dazu, wann `void` akzeptabel ist.

Die vollständigen Testregeln — das ≥90%-Pro-Datei-Gate, wo Testdateien liegen, die Unit- vs. Integrations- vs. Storybook-Projekte und die `v8 ignore`-Richtlinie — finden Sie in [`AGENTS.md`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/AGENTS.md).

## Publishing

Das Root-Paket `@modelcontextprotocol/inspector` wird als **ein Tarball mit einer einzigen Versionsnummer** ausgeliefert — keine separaten Pakete `-web` / `-cli` / `-tui` / `-core`. `npm run build` baut jeden Client, dann läuft `prepack` vor `npm publish`. Laufzeitabhängigkeiten sind in der Root-`package.json` deklariert; Client-Builds bündeln `@inspector/core` und externalisieren npm-Pakete, die aus der Root-Installation aufgelöst werden.

### Was ausgeliefert wird und die Packaging-Invarianten

Die `"files"`-Allowlist der Root-`package.json` ist die maßgebliche Quelle für den Tarball. Einige nicht offensichtliche Einträge existieren, weil sie **zur Laufzeit** gelesen werden oder von npm's packlist stillschweigend entfernt wurden — entfernen Sie sie nicht, ohne `npm run pack:verify` erneut auszuführen:

- **Keine Source Maps.** Die Client-Bundler setzen `sourcemap: false` (`clients/{cli,tui}/tsup.config.ts`, `clients/web/tsup.runner.config.ts`); Vite und das `tsc` des Launchers erzeugen ohnehin keine. Maps machen etwa die Hälfte der entpackten Größe aus und werden zur Laufzeit nicht benötigt — debuggen Sie über `npm run dev` direkt im Quellcode.
- **`clients/web/build` wird über `clients/web/.npmignore` ausgeliefert.** `clients/web/.gitignore` listet `build/` auf, und npm's Packlist beachtet diese verschachtelte `.gitignore` gegenüber der Root-`"files"`-Allowlist — dadurch fehlte der Prod-Web-Server-Runner stillschweigend im Tarball, während `clients/web/dist` durchrutschte (seine `.gitignore` listet nur `dist-ssr`). `clients/web/.npmignore` überschreibt die `.gitignore` für die Veröffentlichung, sodass sowohl `build/` (Runner) als auch `dist/` (SPA) ausgeliefert werden. Die anderen Clients brauchen das nicht — keiner liefert eine verschachtelte `.gitignore` aus.
- **`clients/web/static` liefert den MCP-Apps-Sandbox-Proxy aus.** `clients/web/static/sandbox_proxy.html` ist eine kommittierte Quelldatei (kein Build-Artefakt), die zur Laufzeit von `clients/web/server/sandbox-controller.ts` von der Platte gelesen wird als `<runner dir>/../static/sandbox_proxy.html`. Sie fehlte vollständig in der Root-`"files"`-Allowlist, sodass jeder veröffentlichte Build den Apps-Tab mit **"Sandbox not loaded"** ([#1859](https://github.com/modelcontextprotocol/inspector/issues/1859)) scheitern ließ, während es im Repo einwandfrei funktionierte. Da der Pfad _relativ zu_ `clients/web/build` aufgelöst wird, muss das Verzeichnis an genau dieser Stelle ausgeliefert werden — `pack:verify` prüft sowohl den Tarball-Eintrag als auch den auf der Platte installierten Pfad.
- **Eine Abhängigkeit, die React rendert, wird gebündelt, nicht externalisiert.** Ein externalisiertes Paket löst sein eigenes `react` von dem Ort auf, an dem npm **es** im Baum des Konsumenten platziert hat, was nicht zwangsläufig der Ort ist, an dem das Bundle unseres auflöst — npm platziert ein Paket neben einem React, das seinen *Peer*-Bereich erfüllt, und diese Bereiche sind lockerer als unsere. `ink-form` und `ink-scroll-view` deklarieren `">=18"`, daher erfüllt ein Projekt mit React 18 sie und sorgt dafür, dass sie gehoistet werden, während das React 19 des Inspectors darunter verschachtelt wird: zwei React-Kopien, und die TUI stirbt mit `TypeError: Cannot read properties of null (reading 'useState')`, sobald ein Tool-Test-Formular oder eine Scroll-View gemountet wird ([#1952](https://github.com/modelcontextprotocol/inspector/issues/1952)). Beide werden daher von `clients/tui/tsup.config.ts` inline eingebunden und sind **keine** Root-Abhängigkeiten: Der Tarball liefert ihren Code innerhalb von `clients/tui/build/index.js`, statt sie vom Konsumenten installieren zu lassen. Das Bündeln fixiert außerdem ihre transitiven Abhängigkeiten auf das, was die Installation dieses Repos aufgelöst hat (insbesondere `ink-select-input@6` über `overrides`, die npm bei einem als Abhängigkeit installierten Paket ignoriert). **`ink` ist die eine Ausnahme, aus Kostengründen:** Das Bündeln funktioniert, fügt aber ~1.4 MB hinzu (`react-reconciler` und `yoga-layout` kommen mit, plus ein `createRequire`-Banner für das inline eingebundene CJS), daher bleibt es externalisiert — *nicht*, weil sein `">=19"`-Peer es sicher macht, was es nicht tut. Was das erträglich hält, ist der Root-`react`-Bereich: `"^19.0.0"` ist bewusst für die gesamte Major-Version offen, damit npm unser React mit jedem React 19 deduplizieren kann, das ein Konsument pinnt, sodass ein externalisiertes `ink` auf derselben Kopie bleibt, die das Bundle verwendet. **Eine Verengung dieses Bereichs öffnet den Bug für den Renderer selbst erneut** — `clients/tui/__tests__/tsupConfig.test.ts` pinnt ihn auf die Peer-Untergrenze von `ink` und sichert den Rest der Aufteilung ab; siehe [TUI README](https://github.com/modelcontextprotocol/inspector/blob/HEAD/clients/tui/README.md#bundling-react-rendering-dependencies-must-be-inlined-1952).
- **Eine einzige Versionsnummer, gelesen aus der Root-`package.json`.** Der Inspector wird als ein Paket mit einer Version ausgeliefert, daher trägt nur die **Root**-`package.json` eine `version` — die vier `clients/*/package.json`s haben bewusst keine. Jeder Node-Client (CLI, TUI und das Web-Backend) löst die Version über den gemeinsamen Reader `readInspectorVersion()` in `core/node/version.ts` auf, der bis zum Root-Manifest (im Tarball immer vorhanden) hochgeht. Keine Client-`package.json` wird zur Laufzeit gelesen, daher muss keine ausgeliefert werden. Der Web-**Browser** kann das Dateisystem nicht lesen; er erhält seine Version vom Backend über `GET /api/config` (siehe [#1639](https://github.com/modelcontextprotocol/inspector/issues/1639)).

### `npm run pack:verify` — Publish-Smoke-Test gegen den echten TarballDie `smoke:*`-Skripte laufen gegen den Build-Baum im Repository, der **nicht** das veröffentlichte Paket ist. `npm run pack:verify` (`scripts/pack-and-verify.mjs`) schließt diese Lücke: Es baut, packt den veröffentlichbaren Tarball mit `npm pack` (wobei sichergestellt wird, dass keine Source Maps ausgeliefert werden und die zur Laufzeit benötigten Dateien vorhanden sind), installiert den Tarball in einen **sauberen Wegwerf-Consumer** – ein frisches temporäres Verzeichnis, in dem es ein echtes `npm install <tgz>` ausführt (zieht Laufzeitabhängigkeiten, führt `postinstall` aus), genau wie es `npx @modelcontextprotocol/inspector` tun würde – und testet das installierte `mcp-inspector`-Binärprogramm Ende zu Ende: `--help`-Aufruf, ein echter `--cli tools/list`-Aufruf über stdio und ein Produktionsstart mit `--web`, der `/` aus dem ausgelieferten `dist`-Verzeichnis bedienen muss. Damit fängt es Pfad-/Paketierungsfehler ab, bei denen etwas „unter `--dev` funktioniert, unter `npx …` bricht“. Es erfordert Netzwerkzugriff (die Installation zieht Abhängigkeiten), ist also ein lokaler / Release-Check und **kein** Teil der schnellen `validate`/`ci`-Schleife.

### Ein Release erstellen

Die Veröffentlichung wird von zwei release-gesteuerten Jobs in [`.github/workflows/main.yml`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/.github/workflows/main.yml) automatisiert (`github.event_name == 'release'`, beide `needs: build`):

- **`publish`** — das npm-Paket. Führt `npm run pack:verify` als Pre-Publish-Gate aus, stellt sicher, dass das Release-Tag mit der Version der `package.json` im Wurzelverzeichnis übereinstimmt, und führt dann `npm publish --access public --provenance` aus — ein einzelner `npm publish`-Aufruf (v2 ist kein npm-Workspace, daher gibt es kein `publish-all`/`--workspaces` im v1-Stil), mit einer signierten Provenance-Bestätigung über GitHub OIDC (`id-token: write`, `environment: release`, `NPM_TOKEN`).
- **`publish-github-container-registry`** — das Container-Image (siehe [Docker](#docker)).

Ein v2-Release wird von **`main`** erstellt, nachdem die Arbeit des Meilensteins von `v2/main` dorthin gemerged wurde — nicht von `v2/main` selbst. (Die v1-Linie veröffentlicht unabhängig von `v1/main` auf das `v1-latest`-Tag und berührt `main` nie; siehe [Repo-Status](#mcp-inspector).)

Da es **eine einzige Versionsnummer** gibt (nur die `package.json` im Wurzelverzeichnis hat eine — die Clients tragen keine, es gibt also nichts zu synchronisieren und keinen `check-version`-Schritt), besteht der Release-Ablauf aus drei Schritten.

**1. Versionsanhebung auf `v2/main`, vor dem Merge des Meilensteins.** Die Versionsanhebung ist Teil der Arbeit des Meilensteins, gehört also in den Develop-Branch und fließt mit allem anderen in `main` ein:

Ersetzen Sie unten die echte Issue-Nummer und das Release — die Befehle sind so geschrieben, dass sie unverändert kopiert und eingefügt werden können (ein Minor-Bump von `2.2.0` → `2.3.0`):```bash
git checkout -b v2/chore/2010-bump-2-3-0 v2/main
npm version minor --no-git-tag-version   # or major / patch; bump only, no tag
# PR → v2/main

⚠️ **Tagge `origin/main`, nicht dein lokales `HEAD`.** `git checkout main && git pull` läuft über die von dir konfigurierte Merge- oder Rebase-Strategie, sodass ein divergierendes lokales `main` stillschweigend lokale Commits erzeugen oder erneut anwenden kann. `HEAD` dort zu taggen, taggt einen Commit, der nicht auf `origin/main` liegt, und `git push origin <tag>` pusht nur den Tag – zurück bleibt ein Release, dessen Commit nie veröffentlicht wurde. `origin/main` explizit zu benennen, sorgt dafür, dass der getaggte Commit exakt das ist, worauf der Remote-Branch zeigt, unabhängig vom lokalen Zustand.

⚠️ **Kein `v`-Präfix.** Die Release-Tags dieses Repos sind schlicht `x.y.z` – `2.2.0`, `2.1.0`, `2.0.0` – also tagge `2.3.0`, nicht `v2.3.0`. Beachte, dass das npm-eigene `tag-version-prefix` standardmäßig auf `v` gesetzt ist und das Repo keine `.npmrc` festlegt, sodass ein bloßes `npm version` einen Tag mit `v`-Präfix erzeugt hätte, der nicht zur Konvention passt. Manuelles Taggen (Schritt 3) hält es korrekt. Der Assert-Schritt des Workflows entfernt ein führendes `v` vor dem Vergleich, sodass ein Tag mit `v`-Präfix trotzdem veröffentlicht würde – er wäre nur inkonsistent mit jedem vorherigen Release.

Der Ziel-Commit des Releases bestimmt, welcher Workflow läuft, daher wird nur dann veröffentlicht, wenn ein Release aus einem Commit erstellt wird, der diesen (v2) Workflow trägt.

**Warum der Versions-Bump zuerst auf `v2/main` geht ([#2010](https://github.com/modelcontextprotocol/inspector/issues/2010)).** Früher passierte das auf dem Milestone-Merge-Branch, der von `main` abgezweigt wird – daher existierte der Bump nur *downstream* von `v2/main`, und nichts trug ihn zurück. `v2/main` blieb während der Releases 2.1.0 und 2.2.0 bei `2.0.0`. Das ist nicht kosmetisch: Ein von einem Milestone-Merge-Branch abgezweigter Branch trägt den Bump stillschweigend in einen unzusammenhängenden PR ein (das passierte in [#2009](https://github.com/modelcontextprotocol/inspector/issues/2009), wo ein Container-Bugfix mit einem `2.0.0 → 2.2.0`-Diff eintraf), und alles, was die Version während der Entwicklung liest — `readInspectorVersion()`, `--version`, `GET /api/config` — meldete eine Version, die zwei Releases alt war.

Versuch **nicht**, eine zukünftige Drift zu "reparieren", indem du `main` zurück in `v2/main` mergst. `main` trägt die gesamte Pre-v2-v1-Historie (erhalten durch `ec5d8e13 chore: replace main's tree with v2` — ~230 Commits, die `v2/main` nicht hat), ein Back-Merge würde also all das dauerhaft in das Log des Develop-Branchs einpflegen, nur um eine Zwei-Dateien-Änderung zu liefern. Wenn man zuerst bumpt, muss nichts zurückgemergt werden.

### Docker

Ein Container-Image wird vom Release-Workflow auf GHCR (`ghcr.io/modelcontextprotocol/inspector`, `linux/amd64` + `linux/arm64`) veröffentlicht. Das [`Dockerfile`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/Dockerfile) ist ein zweistufiger Build: Die erste Stufe installiert das veröffentlichbare Tarball und führt `npm pack` aus; die zweite Stufe installiert dieses Tarball per `npm install -g`, sodass das Image exakt dasselbe Artefakt wie npm ausliefert, mit einem sauberen `mcp-inspector`-Bin.```bash
# run the web UI (reads the auth token from the container logs)
docker run --rm -p 127.0.0.1:6274:6274 ghcr.io/modelcontextprotocol/inspector

# or build the image locally
docker build -t mcp-inspector .
docker run --rm -p 127.0.0.1:6274:6274 mcp-inspector

Veröffentliche ihn innen und außen auf **derselben Portnummer**. Die Sandbox-URL wird dem Browser über `/api/config` als `http://localhost:<container port>/sandbox` übergeben; ein Umapping (`-p 9000:6275`) bewirbt also einen Port, den der Browser nicht erreichen kann. Verwende stattdessen `-e MCP_SANDBOX_PORT=9000 -p 127.0.0.1:9000:9000`.

**Behalte das Präfix `127.0.0.1:` am veröffentlichten Port.** Ein bloßes `-p 6274:6274` veröffentlicht auf **jedem Host-Interface** und bringt den Inspector in dein lokales Netzwerk. Das `HOST=0.0.0.0` des Containers ist eine separate Angelegenheit – es betrifft die _Interfaces des Containers_, nicht die des Hosts – daher deckt das `DANGEROUSLY_BIND_ALL_INTERFACES`-Opt-in, das einen Wildcard-Bind außerhalb eines Containers absichert, dies nicht ab. Das ist hier wichtiger als bei einer gewöhnlichen Web-App: Das Backend startet auf Anfrage Prozesse, `GET /` bettet das API-Token in das ausgelieferte HTML ein, und eine Anfrage ohne **`Origin`-Header** überspringt die Origin-Allowlist vollständig – für jeden Nicht-Browser-Client ist das API-Token also die einzige Absicherung. Eine breitere Veröffentlichung erfordert eine echte Zugriffskontrollgrenze vor dem Inspector – einen Reverse-Proxy, der authentifiziert, einen SSH-Tunnel, ein privates Netzwerk. Das Setzen eines eigenen `MCP_INSPECTOR_API_TOKEN` ist **kein** Ersatz: `GET /` legt das jeweils verwendete Token offen, sodass ein benutzerdefiniertes genauso leicht abgegriffen werden kann wie ein generiertes.

**Die hinzugefügten Server behalten.** Der Inspector speichert deine Serverliste unter `$HOME/.mcp-inspector/mcp.json`, was im Image `/home/node/.mcp-inspector/mcp.json` ist – innerhalb der beschreibbaren Ebene des Containers, sodass `--rm` sie verwirft und jeder Lauf mit einer leeren Liste beginnt. Binde dort ein Volume ein, um sie zu behalten:```bash
docker run --rm -p 127.0.0.1:6274:6274 \
  -v mcp-inspector-data:/home/node/.mcp-inspector \
  ghcr.io/modelcontextprotocol/inspector

Das Image verwendet standardmäßig `--web`, gebunden an `0.0.0.0:6274`, wobei das automatische Öffnen des Browsers deaktiviert ist; überschreiben Sie die Argumente, um einen anderen Modus auszuführen (`docker run --rm ghcr.io/modelcontextprotocol/inspector --cli …`). Übergeben Sie `-e MCP_INSPECTOR_API_TOKEN=…`, um ein bekanntes Token zu setzen (andernfalls wird eines generiert und in den Logs ausgegeben), oder `-e DANGEROUSLY_OMIT_AUTH=true`, um die Authentifizierung zu deaktivieren. Das Binden an `0.0.0.0` (alle Netzwerkschnittstellen) wird außerhalb eines Containers standardmäßig verweigert — es setzt das Backend zum Starten von Prozessen dem lokalen Netzwerk aus — daher aktiviert das Image dies explizit mit `DANGEROUSLY_BIND_ALL_INTERFACES=true` (bereits im `Dockerfile` gesetzt); ein bloßes `HOST=0.0.0.0` ohne dieses Flag endet mit einem Fehler. Wenn Sie **den veröffentlichten Port neu zuordnen** (`-p 127.0.0.1:8080:6274`), stimmt die Origin des Browsers (`http://localhost:8080`) nicht mehr mit dem Port im Container überein; setzen Sie daher `-e ALLOWED_ORIGINS=http://localhost:8080,http://127.0.0.1:8080` (oder führen Sie `-e CLIENT_PORT=8080 -p 127.0.0.1:8080:8080` aus), sonst werden Verbindungen mit 403 beantwortet. `ALLOWED_ORIGINS` **ersetzt** die Standardliste, anstatt sie zu erweitern; listen Sie daher jede Loopback-Variante auf, von der aus Sie browsen (siehe [web README](https://github.com/modelcontextprotocol/inspector/blob/HEAD/clients/web/README.md#host-binding--the-origin-allow-list)). Das Image läuft als Nicht-Root-Benutzer `node` und besitzt einen `HEALTHCHECK`, der die Weboberfläche abfragt — er setzt den Standardmodus `--web` voraus; fügen Sie daher `--no-healthcheck` hinzu, wenn Sie `--cli`/`--tui` ausführen (die keinen Webserver besitzen).

## Mitwirken — `AGENTS.md` und `CLAUDE.md`

**[`AGENTS.md`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/AGENTS.md) ist der Vertrag für Änderungen an dieser Codebasis und gilt gleichermaßen für Menschen und KI-Agenten.** Es ist kein bloßes Boilerplate für Agenten — es enthält die tatsächlichen Konventionen des Projekts: den Issue- und Board-Workflow, die Branch-/Label-Regeln, die TypeScript- und Mantine/React-Standards, die Test- und Abdeckungsanforderungen sowie das verpflichtende Pre-Push-Gate. Lesen Sie es, bevor Sie Änderungen vornehmen, und halten Sie es aktuell, wenn Sie Struktur, Tooling oder Regeln ändern.

`CLAUDE.md` ist der Einstiegspunkt, den der [Claude Code](https://claude.com/claude-code)-Agent automatisch lädt; er bindet lediglich `AGENTS.md` und dieses README ein, sodass Agenten und Menschen auf dieselbe Quelle der Wahrheit zugreifen. Wenn Sie einen anderen Agenten verwenden, der `AGENTS.md` liest, gelten dieselben Regeln.

Eine wichtige Regel sei hier hervorgehoben: **Alle Arbeit ist issuebasiert.** Finden oder erstellen Sie vor Beginn ein Tracking-Issue auf dem v2-Projektboard; eröffnen Sie PRs gegen `v2/main` mit `Closes #<issue>`. Die genauen Anleitungen (Labels, Board-IDs, Statuswerte) finden Sie in `AGENTS.md`.

## Lizenz

MIT.