MCP Inspector

MCP Inspector

Uma ferramenta de desenvolvimento para inspecionar servidores Model Context Protocol (MCP). Ela é distribuída como um único pacote, @modelcontextprotocol/inspector, que oferece três formas de inspecionar um servidor:

• Web — um aplicativo de página única Vite + React + Mantine com um backend Node.
• CLI — um cliente de linha de comando scriptável para automação, CI e ciclos rápidos de feedback de agentes.
• TUI — uma interface de terminal interativa construída com Ink.

Todos os três são executados por meio de um único binário global mcp-inspector:

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

[!WARNING] O Inspector gerencia segredos — tokens OAuth, segredos de cliente OAuth e valores stdio env: — e os armazena no chaveiro do sistema operacional, se disponível, por padrão. Em uma máquina sem chaveiro — Linux sem libsecret ou um Secret Service, sessões headless e SSH, Termux e contêineres com volume montado — eles são salvos em ~/.mcp-inspector/secrets.json em vez disso, sem criptografia, a menos que você forneça uma chave. Consulte Onde os segredos são armazenados para saber como recuperar um chaveiro, criptografar o arquivo ou manter os segredos apenas na memória.

Atualizando da v1? Leia o guia de migração v1 → v2 — flags de CLI, a nova divisão --config vs. --catalog, o aumento da versão do Node e o que não é mais incluído.

Status do repositório. Esta é a linha v2 do Inspector. O desenvolvimento ativo acontece em v2/main (o branch develop — todos os PRs da v2 o têm como alvo), que é mesclado em main nos lançamentos de marcos; main é o branch padrão e contém a v2 mais recente publicada, publicada na tag npm latest. A linha legada v1 vive em v1/main — apenas correções de segurança, publicadas diretamente desse branch para a tag npm v1-latest (npx @modelcontextprotocol/inspector@v1-latest). Consulte AGENTS.md para convenções de branch/quadro.

Início rápido (desenvolvimento)

Requer Node >=22.19.0.

npm install          # at the repo root; postinstall cascades into every client
npm run build        # web → cli → tui → launcher

Para iteração web do dia a dia, execute o Vite diretamente — HMR rápido, sem necessidade de build do launcher:

cd clients/web && npm run dev

Os scripts orientados por launcher executam o launcher compilado, então compile primeiro:

npm run web        # prod web launcher against clients/web/dist
npm run web:dev    # web launcher in --dev mode (Vite)

A v2 não é um workspace npm — cada cliente em clients/* mantém seu próprio package.json e node_modules, e o código compartilhado fica em core/, consumido por meio de um alias de tempo de build @inspector/core. Cada dependência de runtime que core/ importa é declarada uma vez, no package.json da raiz do repositório, e cada cliente declara apenas o que esse cliente consome — sua pilha de UI, seus pacotes embutidos no bundler, suas ferramentas de desenvolvimento — o que deixa clients/cli e clients/launcher sem dependências de runtime próprias. O que isso significa para adicionar uma dependência (raiz vs. cliente, dependencies vs. devDependencies e as listas do bundler external) está na habilidade local-dev.

Estrutura do projeto

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),
│                     repo automation run from CI (the dependency, Dependabot-alert and SDK sweeps)
│                     and the Docker image's HEALTHCHECK probe
├── 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

Cada cliente tem seu próprio README com detalhes específicos do cliente: web · cli · tui · launcher.

Documentação

Guia	Abrange
Arquitetura	O pacote compartilhado @inspector/core e a abordagem de "componentes burros" + Storybook do cliente web
Testes e o portão de qualidade	O que cada script validate / coverage / smoke / verify:* cobre, a divisão GitHub-CI vs. portão local e os navegadores suportados
Escrevendo uma habilidade	Como escrever uma descrição de habilidade que realmente dispara e casos de avaliação que a medem — os formatos de caso que funcionam e o ciclo de ajuste
Servidores de teste	Os servidores de teste compostos e a configuração de demonstração para cada recurso — o que executar, o que clicar e o que o build quebrado fez
Publicação	O que é incluído no tarball, as invariantes de empacotamento e pack:verify
Docker	Executando a imagem do contêiner — portas, volumes e como tornar segredos duráveis em um contêiner
Onde os segredos são armazenados	Como o armazenamento de segredos é escolhido em cada runtime — chaveiro do SO, secrets.json ou memória — além de criptografia de arquivo, bloqueio e retorno a um chaveiro
Migrando da v1 para a v2	Mapeamento de flags de CLI, --config vs. --catalog, o aumento da versão do Node, renomeações de variáveis de ambiente
Variáveis de ambiente	Cada variável que altera o comportamento do runtime — autenticação, portas, armazenamento, armazenamento de segredos, registro, proxies — além das variáveis TLS do Node para um servidor autoassinado
Configuração do servidor MCP	A qual(is) servidor(es) o Inspector se conecta e o formato do arquivo de configuração
Revisando um aplicativo MCP	A receita CLI-primeiro → web de uso único para revisão automatizada de ferramentas de aplicativos
Teste de fumaça de um servidor MCP	O fluxo de trabalho conectar → listar → chamar → afirmar para um trabalho de shell ou CI: --format json + jq, o mapa de códigos de saída e como manter o OAuth não interativo
Consolidação de launcher e configuração	Por que o launcher executa um cliente no processo em vez de gerá-lo
Roteiro, ago 2026 → fev 2027	O plano de seis meses: trabalho de conformidade com a especificação alinhado ao roteiro MCP publicado, suporte oficial a extensões e o trabalho de experiência que escolhemos
MCP Inspector: Nossa fábrica de software de IA	Como as contribuições realmente acontecem desde a v2.0.0 — trabalho orientado por issues de ponta a ponta, a divisão regras/habilidades, as varreduras que substituíram o Dependabot, o portão de qualidade e para onde está indo

Testes e o portão de qualidade

Cada cliente se autovalida a partir de sua própria pasta; os scripts da raiz os encadeiam. Não há um script agregado test na raiz.

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 — every GitHub CI check, plus one local-only one

npm run local:gate encadeia todas as verificações abaixo, além dos testes de fumaça e dos testes do Storybook. Testes e o portão de qualidade é responsável pela lista de etapas e explica o que cada uma cobre e por que uma é apenas local; AGENTS.md contém as próprias regras de teste.

Contribuindo — AGENTS.md, CLAUDE.md e as habilidades

AGENTS.md é o contrato para alterar este código-base e se aplica tanto a humanos quanto a agentes de IA. Não é um boilerplate apenas para agentes — contém as regras reais do projeto: as convenções de versão/rótulo, os padrões TypeScript e Mantine/React, os requisitos de teste e cobertura e o portão obrigatório antes do push. Leia-o antes de fazer alterações e mantenha-o atualizado quando mudar estrutura, ferramentas ou regras.

Os procedimentos do repositório — receitas de várias etapas com comandos e IDs ativos — ficam em .claude/skills/ em vez disso, um diretório por procedimento, para que sejam carregados apenas quando a tarefa os exigir. São Markdown comum commitado: um agente que não entende habilidades pode lê-los, e AGENTS.md carrega um índice do que existe. Usuários do Claude Code os invocam pelo nome (/release, /issue-triage, …).

CLAUDE.md é o ponto de entrada que o Claude Code carrega automaticamente; ele inclui AGENTS.md, para que agentes e humanos trabalhem a partir da mesma fonte de verdade. Se você usar um agente diferente que lê AGENTS.md, você obtém as mesmas regras.

Uma regra importante que vale destacar aqui: todo o trabalho é orientado por issues. Antes de começar, encontre ou crie uma issue de rastreamento no quadro do projeto v2; abra PRs contra v2/main com Closes #<issue>. Contribuições externas são aceitas como issues, não pull requests — consulte CONTRIBUTING.md.

Licença

Consulte LICENSE. O projeto MCP está em transição da Licença MIT para Apache-2.0: novas contribuições de código são licenciadas sob Apache-2.0, documentação (excluindo especificações) sob CC-BY-4.0, e contribuições cujos autores originalmente as licenciaram sob MIT e não concederam consentimento de relicenciamento permanecem sob MIT. O arquivo contém os textos completos de Apache-2.0 e MIT e vincula o código legal CC-BY-4.0.