MCP Inspector

Model Context Protocol(MCP) 서버를 검사하기 위한 개발자 도구입니다. 단일 패키지인 @modelcontextprotocol/inspector로 제공되며, 서버를 검사하는 세 가지 방법을 제공합니다:

• 웹(Web) — Node 백엔드를 갖춘 Vite + React + Mantine 단일 페이지 앱.
• CLI — 자동화, CI 및 빠른 에이전트 피드백 루프를 위한 스크립트 가능한 명령줄 클라이언트.
• TUI — Ink로 구축된 대화형 터미널 UI.

세 가지 모두 단일 전역 mcp-inspector 바이너리로 실행됩니다:

npx @modelcontextprotocol/inspector          # 웹 UI (기본값)
npx @modelcontextprotocol/inspector --cli    # CLI
npx @modelcontextprotocol/inspector --tui    # TUI

v1에서 업그레이드하시나요? v1 → v2 마이그레이션 가이드를 읽어보세요 — CLI 플래그, 새로운 --config 대 --catalog 구분, Node 엔진 버전 상향, 그리고 더 이상 제공되지 않는 항목에 대해 설명합니다.

저장소 상태. 이 저장소는 Inspector의 v2 라인입니다. 활발한 개발은 v2/main(개발 브랜치 — 모든 v2 PR이 이 브랜치를 대상으로 함)에서 이루어지며, 마일스톤 릴리스 시점에 **main**으로 병합됩니다. main은 기본 브랜치이며 최신 릴리스된 v2를 보유하고 npm latest 태그로 게시됩니다. 레거시 v1 라인은 **v1/main**에 있으며 — 보안 수정만 적용되며, 해당 브랜치에서 npm v1-latest 태그(npx @modelcontextprotocol/inspector@v1-latest)로 직접 게시됩니다. 브랜치/보드 규칙은 AGENTS.md를 참조하세요.

빠른 시작 (개발)

Node >=22.19.0 필요.

npm install          # 저장소 루트에서 실행; postinstall이 모든 클라이언트로 연쇄 실행됨
npm run build        # web → cli → tui → launcher

일상적인 웹 반복 작업의 경우 Vite를 직접 실행하세요 — 빠른 HMR, 런처 빌드 불필요:

cd clients/web && npm run dev

런처 기반 스크립트는 빌드된 런처를 실행하므로 먼저 빌드하세요:

npm run web        # clients/web/dist에 대한 프로덕션 웹 런처
npm run web:dev    # --dev 모드의 웹 런처 (Vite)

v2는 npm 워크스페이스가 아닙니다 — clients/* 아래의 각 클라이언트는 자체 package.json과 node_modules를 유지하며, 공유 코드는 core/에 있으며 @inspector/core 빌드 타임 별칭을 통해 사용됩니다. core/가 가져오는 모든 런타임 의존성은 저장소 루트 package.json에 한 번만 선언되며, 각 클라이언트는 해당 클라이언트만 사용하는 것(UI 스택, 번들러 인라인 패키지, 개발 도구)만 선언하므로 clients/cli와 clients/launcher에는 자체 런타임 의존성이 없습니다. 의존성 추가(루트 대 클라이언트, dependencies 대 devDependencies, 번들러 external 목록)의 의미는 local-dev 스킬에 있습니다.

프로젝트 구조

inspector/
├── clients/
│   ├── web/          웹 클라이언트 (Vite + React + Mantine). src/ = 브라우저 앱; server/ = Node 백엔드
│   ├── cli/          CLI 클라이언트 (tsup 번들, @inspector/core 별칭)
│   ├── tui/          TUI 클라이언트 (Ink + React, tsup 번들)
│   └── launcher/     공유 런처 — `mcp-inspector` bin 제공, web/cli/tui로 디스패치
├── core/             `@inspector/core` 별칭을 통해 사용되는 공유 코드 (package.json 없음)
├── test-servers/     통합 및 스모크 테스트에 사용되는 구성 가능한 MCP 테스트 서버 + 픽스처
├── scripts/          루트 빌드/검증 도구 (설치 연쇄, 스모크, verify:* 가드)
│                     및 CI에서 실행되는 저장소 자동화 (의존성, Dependabot 알림 및 SDK 스윕)
├── docs/             작업 중심 가이드 — 아래 참조
├── specification/    설계/빌드 사양
├── .claude/skills/   에이전트 스킬: 저장소의 절차, 이름으로 호출 가능
├── AGENTS.md         에이전트와 인간 모두를 위한 기여 규칙
└── README.md         현재 위치

각 클라이언트에는 클라이언트별 세부 정보가 담긴 자체 README가 있습니다: web · cli · tui · launcher.

문서

테스팅 및 품질 게이트

각 클라이언트는 자체 폴더에서 자체 검증을 수행하며, 루트 스크립트가 이를 연결합니다. 집계된 루트 test 스크립트는 없습니다.

npm run validate     # 빠른 내부 루프: format:check + lint + typecheck + build + 단위 테스트
npm run coverage     # 파일별 ≥90% 게이트 (lines/statements/functions/branches)
npm run local:gate   # 푸시 전 필수 — GitHub CI의 엄격한 상위 집합

npm run local:gate는 아래의 모든 검사와 스모크 및 Storybook 테스트를 연결합니다. 테스팅 및 품질 게이트는 단계 목록을 관리하며 각 단계가 다루는 내용과 두 단계가 로컬 전용인 이유를 설명합니다. AGENTS.md에는 테스팅 규칙 자체가 있습니다.

기여 — AGENTS.md, CLAUDE.md 및 스킬

AGENTS.md는 이 코드베이스를 변경하기 위한 계약이며 인간과 AI 에이전트 모두에게 적용됩니다. 에이전트 전용 보일러플레이트가 아닙니다 — 프로젝트의 실제 규칙(버전/라벨 규칙, TypeScript 및 Mantine/React 표준, 테스팅 및 커버리지 요구 사항, 필수 푸시 전 게이트)을 담고 있습니다. 변경하기 전에 읽고, 구조, 도구 또는 규칙을 변경할 때 최신 상태로 유지하세요.

저장소의 절차(명령과 실제 ID가 포함된 다단계 레시피)는 대신 .claude/skills/에 있으며, 절차별로 하나의 디렉터리로 구성되어 작업이 필요할 때만 로드됩니다. 이는 일반 커밋된 Markdown입니다: 스킬을 이해하지 못하는 에이전트도 읽을 수 있으며, AGENTS.md에는 존재하는 항목의 인덱스가 포함되어 있습니다. Claude Code 사용자는 이름으로 호출합니다(/release, /issue-triage, …).

CLAUDE.md는 Claude Code가 자동으로 로드하는 진입점입니다. AGENTS.md를 포함하므로 에이전트와 인간은 동일한 진실 소스에서 작업합니다. AGENTS.md를 읽는 다른 에이전트를 사용한다면 동일한 규칙을 얻습니다.

여기서 강조할 핵심 규칙: 모든 작업은 이슈 기반입니다. 시작하기 전에 v2 프로젝트 보드에서 추적 이슈를 찾거나 생성하세요. Closes #<issue>와 함께 v2/main에 대해 PR을 여세요. 외부 기여는 풀 리퀘스트가 아닌 이슈로 받습니다 — CONTRIBUTING.md를 참조하세요.

라이선스

MIT.