inspector

O MCP Inspector é uma ferramenta voltada para desenvolvedores, destinada a inspecionar e testar servidores do Model Context Protocol (MCP). É distribuído como um único pacote npm, `@modelcontextprotocol/inspector`, e expõe um único binário global, `mcp-inspector`, que é executado em três modos: - **Web** — uma aplicação de página única em Vite + React + Mantine com um backend Node.js, oferecendo uma interface visual para inspeção de servidores. - **CLI** — um cliente de linha de comando scriptável, projetado para automação, pipelines de CI e ciclos rápidos de feedback de agentes. - **TUI** — uma interface de terminal interativa construída com Ink para usuários que preferem um fluxo de trabalho baseado em terminal. Todos os três modos são invocados através do mesmo binário com flags: ```bash npx @modelcontextprotocol/inspector # web UI (default) npx @modelcontextprotocol/inspector --cli # CLI mode npx @modelcontextprotocol/inspector --tui # TUI mode ``` ## Arquitetura O projeto não é um workspace npm. Cada cliente em `clients/` mantém seu próprio `package.json` e `node_modules`. O código compartilhado fica em `core/` e é consumido através de um alias de tempo de build `@inspector/core`. As dependências de runtime importadas por `core/` são declaradas uma vez na raiz do repositório, enquanto cada cliente declara apenas sua própria stack de UI, pacotes embutidos pelo bundler e ferramentas de desenvolvimento. Os pacotes `clients/cli` e `clients/launcher` não têm dependências de runtime próprias. ## Estrutura do projeto - `clients/web/` — Cliente Web (Vite + React + Mantine). O diretório `src/` contém o aplicativo do navegador; `server/` contém o backend Node. - `clients/cli/` — Cliente CLI, empacotado com tsup usando o alias `@inspector/core`. - `clients/tui/` — Cliente TUI, construído com Ink + React e empacotado com tsup. - `clients/launcher/` — Launcher compartilhado que fornece o binário `mcp-inspector` e despacha para o cliente apropriado. - `core/` — Código compartilhado consumido via o alias `@inspector/core`; não possui `package.json`. - `test-servers/` — Servidores de teste MCP componíveis e fixtures usados em testes de integração e smoke tests. - `scripts/` — Ferramentas de build e verificação na raiz, incluindo cascatas de instalação, smoke tests e automação de CI. - `docs/` — Guias orientados a tarefas cobrindo arquitetura, testes, portões de qualidade, armazenamento de segredos, migração, uso de Docker e mais. - `specification/` — Especificações de design e build. - `.claude/skills/` — Skills de agentes, cada uma em seu próprio diretório, carregadas sob demanda pelo nome do procedimento. ## Fluxo de trabalho de desenvolvimento É necessário Node `>=22.19.0`. Após executar `npm install` na raiz do repositório (o script postinstall cascateia para cada cliente), execute `npm run build` para compilar web, CLI, TUI e o launcher em sequência. Para desenvolvimento web rápido, você pode executar o Vite diretamente de `clients/web` para hot-module replacement rápido sem reconstruir o launcher. O portão obrigatório de pré-push é `npm run local:gate`, que encadeia verificações de formatação, linting, type-checking, builds, testes unitários, verificação de cobertura (limite por arquivo de 90%), smoke tests e testes do Storybook. Isso espelha a verificação completa do GitHub CI localmente. ## Destaques da documentação - **Arquitetura** — Detalhes sobre o pacote compartilhado `@inspector/core` e o modelo de componentes do cliente web. - **Testes e o portão de qualidade** — Cobertura do que cada script de validação verifica e a divisão entre o portão de CI e o local. - **Armazenamento de segredos** — Como os segredos são gerenciados entre keychains de sistemas operacionais, arquivos em texto simples e armazenamentos em memória, incluindo criptografia e locking. - **Smoke-testing de um servidor MCP** — Um fluxo de trabalho connect → list → call → assert para jobs de shell ou CI, com saída JSON e mapeamento de códigos de saída. - **Migração de v1 para v2** — Mudanças nas flags da CLI, a divisão entre `--config` e `--catalog`, o aumento da versão do engine Node e renomeações de variáveis de ambiente. - **Roadmap** — Um plano de seis meses alinhado ao roadmap publicado do MCP, cobrindo conformidade com a especificação, suporte oficial a extensões e melhorias de experiência. ## Contribuindo As contribuições seguem um fluxo de trabalho orientado por issues. Todo o trabalho deve ser rastreado no quadro do projeto v2, com PRs abertos contra `v2/main` e vinculados via `Closes #<issue>`. Contribuições externas são aceitas como issues em vez de pull requests. O arquivo `AGENTS.md` define as regras do projeto tanto para contribuidores humanos quanto para IA, cobrindo versionamento, padrões TypeScript, convenções Mantine/React e requisitos de teste. O arquivo `CLAUDE.md` serve como ponto de entrada para o Claude Code, carregando automaticamente o `AGENTS.md` para que tanto agentes quanto humanos operem a partir da mesma fonte de verdade. ## Licença O projeto MCP está em transição de MIT para Apache-2.0. Novas contribuições são licenciadas sob Apache-2.0, a documentação (excluindo especificações) sob CC-BY-4.0, e contribuições legadas que não concederam consentimento de relicenciamento permanecem sob MIT.