inspector

MCP Inspector is a developer-focused tool for inspecting and testing Model Context Protocol (MCP) servers. It ships as a single npm package, `@modelcontextprotocol/inspector`, and exposes one global binary, `mcp-inspector`, that runs in three modes: - **Web** — a Vite + React + Mantine single-page application with a Node.js backend, offering a visual interface for server inspection. - **CLI** — a scriptable command-line client designed for automation, CI pipelines, and fast agent feedback loops. - **TUI** — an interactive terminal UI built with Ink for users who prefer a terminal-based workflow. All three modes are invoked through the same binary with flags: ```bash npx @modelcontextprotocol/inspector # web UI (default) npx @modelcontextprotocol/inspector --cli # CLI mode npx @modelcontextprotocol/inspector --tui # TUI mode ``` ## Architecture The project is not an npm workspace. Each client under `clients/` maintains its own `package.json` and `node_modules`. Shared code lives in `core/` and is consumed through a `@inspector/core` build-time alias. Runtime dependencies imported by `core/` are declared once at the repo root, while each client declares only its own UI stack, bundler-inlined packages, and dev tooling. The `clients/cli` and `clients/launcher` packages have no runtime dependencies of their own. ## Project layout - `clients/web/` — Web client (Vite + React + Mantine). The `src/` directory contains the browser app; `server/` holds the Node backend. - `clients/cli/` — CLI client, bundled with tsup using the `@inspector/core` alias. - `clients/tui/` — TUI client, built with Ink + React and bundled with tsup. - `clients/launcher/` — Shared launcher that provides the `mcp-inspector` binary and dispatches to the appropriate client. - `core/` — Shared code consumed via the `@inspector/core` alias; has no `package.json`. - `test-servers/` — Composable MCP test servers and fixtures used in integration and smoke tests. - `scripts/` — Root build and verification tooling, including install cascades, smoke tests, and CI automation. - `docs/` — Task-oriented guides covering architecture, testing, quality gates, secret storage, migration, Docker usage, and more. - `specification/` — Design and build specifications. - `.claude/skills/` — Agent skills, each in its own directory, loaded on demand by procedure name. ## Development workflow Node `>=22.19.0` is required. After running `npm install` at the repository root (the postinstall script cascades into every client), run `npm run build` to compile web, CLI, TUI, and the launcher in sequence. For rapid web development, you can run Vite directly from `clients/web` for fast hot-module replacement without rebuilding the launcher. The mandatory pre-push gate is `npm run local:gate`, which chains format checks, linting, type-checking, builds, unit tests, coverage verification (per-file threshold of 90%), smoke tests, and Storybook tests. This mirrors the full GitHub CI check locally. ## Documentation highlights - **Architecture** — Details on the shared `@inspector/core` package and the web client component model. - **Testing and the quality gate** — Coverage of what each validation script verifies and the CI-vs-local gate split. - **Secret storage** — How secrets are managed across OS keychains, plaintext files, and in-memory stores, including encryption and locking. - **Smoke-testing an MCP server** — A connect → list → call → assert workflow for shell or CI jobs, with JSON output and exit-code mapping. - **Migrating from v1 to v2** — CLI flag changes, the `--config` vs. `--catalog` split, the Node engine bump, and env-var renames. - **Roadmap** — A six-month plan aligned to the published MCP roadmap, covering spec compliance, official extension support, and experience improvements. ## Contributing Contributions follow an issue-driven workflow. All work should be tracked on the v2 project board, with PRs opened against `v2/main` and linked via `Closes #<issue>`. External contributions are accepted as issues rather than pull requests. The `AGENTS.md` file defines the project's rules for both human and AI contributors, covering versioning, TypeScript standards, Mantine/React conventions, and testing requirements. The `CLAUDE.md` file serves as the entry point for Claude Code, automatically loading `AGENTS.md` so both agents and humans operate from the same source of truth. ## License The MCP project is transitioning from MIT to Apache-2.0. New contributions are licensed under Apache-2.0, documentation (excluding specifications) under CC-BY-4.0, and legacy contributions that have not granted relicensing consent remain under MIT.