MCP Inspector

Uno strumento per sviluppatori per ispezionare i server Model Context Protocol (MCP). Viene distribuito come un singolo pacchetto, @modelcontextprotocol/inspector, che offre tre modalità per ispezionare un server:

• Web — un'app single-page Vite + React + Mantine con backend Node.
• CLI — un client da riga di comando scriptabile per automazione, CI e cicli rapidi di feedback per agenti.
• TUI — un'interfaccia terminale interattiva costruita con Ink.

Tutte e tre vengono eseguite tramite un unico binario globale mcp-inspector:

npx @modelcontextprotocol/inspector          # web UI (default)
npx @modelcontextprotocol/inspector --cli    # CLI
npx @modelcontextprotocol/inspector --tui    # TUI

Aggiornamento dalla v1? Leggi la guida alla migrazione v1 → v2 — flag CLI, la nuova suddivisione --config vs. --catalog, l'innalzamento del motore Node e cosa non viene più distribuito.

Stato del repository. Questa è la linea v2 dell'Inspector. Lo sviluppo attivo avviene su v2/main (il ramo di sviluppo — tutte le PR v2 puntano a esso), che viene unito in main in corrispondenza delle release milestone; main è il ramo predefinito e contiene l'ultima v2 rilasciata, pubblicata sul tag npm latest. La linea legacy v1 vive su v1/main — solo fix di sicurezza, pubblicati direttamente da quel ramo sul tag npm v1-latest (npx @modelcontextprotocol/inspector@v1-latest). Vedi AGENTS.md per le convenzioni su rami/board.

Avvio rapido (sviluppo)

Richiede Node >=22.19.0.

npm install          # nella root del repo; il postinstall si propaga in ogni client
npm run build        # web → cli → tui → launcher

Per l'iterazione quotidiana sul web, esegui Vite direttamente — HMR veloce, nessuna build del launcher necessaria:

cd clients/web && npm run dev

Gli script guidati dal launcher eseguono il launcher compilato, quindi compila prima:

npm run web        # launcher web di produzione contro clients/web/dist
npm run web:dev    # launcher web in modalità --dev (Vite)

La v2 non è un npm workspace — ogni client sotto clients/* mantiene il proprio package.json e node_modules, e il codice condiviso vive in core/, consumato tramite un alias di build-time @inspector/core. Ogni dipendenza runtime importata da core/ è dichiarata una sola volta, nel package.json della root del repo, e ogni client dichiara solo ciò che quel singolo client consuma — il suo stack UI, i suoi pacchetti inlining dal bundler, i suoi strumenti di sviluppo — il che lascia clients/cli e clients/launcher senza dipendenze runtime proprie. Cosa significa per l'aggiunta di una dipendenza (root vs. client, dependencies vs. devDependencies, e le liste external del bundler) è spiegato nella skill local-dev.

Struttura del progetto

inspector/
├── clients/
│   ├── web/          Client web (Vite + React + Mantine). src/ = app browser; server/ = backend Node
│   ├── cli/          Client CLI (bundle tsup, alias @inspector/core)
│   ├── tui/          Client TUI (Ink + React, bundle tsup)
│   └── launcher/     Launcher condiviso — fornisce il bin `mcp-inspector`, smista verso web/cli/tui
├── core/             Codice condiviso consumato tramite l'alias `@inspector/core` (nessun package.json)
├── test-servers/     Server MCP di test componibili + fixture usati dai test di integrazione e smoke
├── scripts/          Tooling root di build/verifica (cascata di installazione, smoke, guardie verify:*)
│                     e automazione del repo eseguita da CI (le sweep di dipendenze, alert Dependabot e SDK)
├── docs/             Guide orientate ai task — vedi sotto
├── specification/    Specifiche di design/build
├── .claude/skills/   Skill per agenti: le procedure del repo, invocabili per nome
├── AGENTS.md         Regole di contribuzione per agenti E umani
└── README.md         Sei qui

Ogni client ha il proprio README con dettagli specifici del client: web · cli · tui · launcher.

Documentazione

Test e quality gate

Ogni client si auto-valida dalla propria cartella; gli script root li concatenano. Non esiste uno script test aggregato alla root.

npm run validate     # ciclo interno veloce: format:check + lint + typecheck + build + unit test
npm run coverage     # la soglia per-file ≥90% (linee/istruzioni/funzioni/rami)
npm run local:gate   # OBBLIGATORIO prima del push — un superset rigoroso della GitHub CI

npm run local:gate concatena ogni controllo sotto elencato, più gli smoke e i test Storybook. Test e quality gate possiede l'elenco delle fasi e spiega cosa copre ciascuna e perché due sono solo locali; AGENTS.md contiene le regole di testing vere e proprie.

Contribuire — AGENTS.md, CLAUDE.md e le skill

AGENTS.md è il contratto per modificare questo codebase e si applica sia agli umani sia agli agenti AI. Non è boilerplate solo per agenti — contiene le regole reali del progetto: le convenzioni di versione/etichette, gli standard TypeScript e Mantine/React, i requisiti di testing e coverage e il gate obbligatorio pre-push. Leggilo prima di apportare modifiche e tienilo aggiornato quando cambi struttura, tooling o regole.

Le procedure del repo — ricette multi-step con comandi e ID live — vivono invece in .claude/skills/, una directory per procedura, così vengono caricate solo quando il task le richiede. Sono normali Markdown committati: un agente che non comprende le skill può leggerli, e AGENTS.md porta un indice di ciò che esiste. Gli utenti di Claude Code le invocano per nome (/release, /issue-triage, …).

CLAUDE.md è il punto di ingresso che Claude Code carica automaticamente; include AGENTS.md, così agenti e umani lavorano dalla stessa fonte di verità. Se usi un agente diverso che legge AGENTS.md, ottieni le stesse regole.

Una regola chiave che vale la pena evidenziare qui: tutto il lavoro è guidato dagli issue. Prima di iniziare, trova o crea un issue di tracciamento sulla project board v2; apri le PR contro v2/main con Closes #<issue>. I contributi esterni sono accettati come issue, non pull request — vedi CONTRIBUTING.md.

Licenza

MIT.