inspector

MCP Inspector는 Model Context Protocol(MCP) 서버를 검사하고 테스트하기 위한 개발자 중심 도구입니다. 단일 npm 패키지인 `@modelcontextprotocol/inspector`로 제공되며, 세 가지 모드로 실행되는 단일 전역 바이너리 `mcp-inspector`를 노출합니다: - **웹** — Node.js 백엔드를 갖춘 Vite + React + Mantine 단일 페이지 애플리케이션으로, 서버 검사를 위한 시각적 인터페이스를 제공합니다. - **CLI** — 자동화, CI 파이프라인 및 빠른 에이전트 피드백 루프를 위해 설계된 스크립트 가능한 명령줄 클라이언트입니다. - **TUI** — 터미널 기반 워크플로를 선호하는 사용자를 위해 Ink로 구축된 대화형 터미널 UI입니다. 세 가지 모드 모두 플래그와 함께 동일한 바이너리를 통해 호출됩니다: ```bash npx @modelcontextprotocol/inspector # 웹 UI (기본값) npx @modelcontextprotocol/inspector --cli # CLI 모드 npx @modelcontextprotocol/inspector --tui # TUI 모드 ``` ## 아키텍처 이 프로젝트는 npm 워크스페이스가 아닙니다. `clients/` 아래의 각 클라이언트는 자체 `package.json`과 `node_modules`를 유지합니다. 공유 코드는 `core/`에 있으며 `@inspector/core` 빌드 타임 별칭을 통해 사용됩니다. `core/`가 가져오는 런타임 종속성은 저장소 루트에 한 번 선언되며, 각 클라이언트는 자체 UI 스택, 번들러 인라인 패키지 및 개발 도구만 선언합니다. `clients/cli` 및 `clients/launcher` 패키지에는 자체 런타임 종속성이 없습니다. ## 프로젝트 구조 - `clients/web/` — 웹 클라이언트(Vite + React + Mantine). `src/` 디렉토리에는 브라우저 앱이 포함되고, `server/`에는 Node 백엔드가 있습니다. - `clients/cli/` — `@inspector/core` 별칭을 사용하여 tsup으로 번들된 CLI 클라이언트입니다. - `clients/tui/` — Ink + React로 구축되고 tsup으로 번들된 TUI 클라이언트입니다. - `clients/launcher/` — `mcp-inspector` 바이너리를 제공하고 적절한 클라이언트에 디스패치하는 공유 런처입니다. - `core/` — `@inspector/core` 별칭을 통해 사용되는 공유 코드로, `package.json`이 없습니다. - `test-servers/` — 통합 및 스모크 테스트에 사용되는 구성 가능한 MCP 테스트 서버 및 픽스처입니다. - `scripts/` — 설치 캐스케이드, 스모크 테스트 및 CI 자동화를 포함한 루트 빌드 및 검증 도구입니다. - `docs/` — 아키텍처, 테스트, 품질 게이트, 비밀 저장, 마이그레이션, Docker 사용 등을 다루는 작업 중심 가이드입니다. - `specification/` — 설계 및 빌드 사양입니다. - `.claude/skills/` — 각각 자체 디렉토리에 있는 에이전트 스킬로, 절차 이름으로 요청 시 로드됩니다. ## 개발 워크플로 Node `>=22.19.0`이 필요합니다. 저장소 루트에서 `npm install`을 실행한 후(postinstall 스크립트가 모든 클라이언트에 캐스케이드됨), `npm run build`를 실행하여 웹, CLI, TUI 및 런처를 순서대로 컴파일합니다. 빠른 웹 개발을 위해 `clients/web`에서 Vite를 직접 실행하여 런처를 다시 빌드하지 않고 빠른 핫 모듈 교체를 수행할 수 있습니다. 필수 푸시 전 게이트는 `npm run local:gate`로, 포맷 검사, 린팅, 타입 검사, 빌드, 단위 테스트, 커버리지 검증(파일당 90% 임계값), 스모크 테스트 및 Storybook 테스트를 연결합니다. 이는 전체 GitHub CI 검사를 로컬에서 미러링합니다. ## 문서 하이라이트 - **아키텍처** — 공유 `@inspector/core` 패키지 및 웹 클라이언트 구성 요소 모델에 대한 세부 정보입니다. - **테스트 및 품질 게이트** — 각 검증 스크립트가 확인하는 내용과 CI 대 로컬 게이트 분할에 대한 설명입니다. - **비밀 저장** — OS 키체인, 일반 텍스트 파일 및 인메모리 저장소에서 비밀이 관리되는 방법(암호화 및 잠금 포함)입니다. - **MCP 서버 스모크 테스트** — JSON 출력 및 종료 코드 매핑을 사용한 셸 또는 CI 작업을 위한 연결 → 목록 → 호출 → 어서션 워크플로입니다. - **v1에서 v2로 마이그레이션** — CLI 플래그 변경, `--config` 대 `--catalog` 분할, Node 엔진 업그레이드 및 환경 변수 이름 변경입니다. - **로드맵** — 게시된 MCP 로드맵에 맞춘 6개월 계획으로, 사양 준수, 공식 확장 지원 및 경험 개선을 다룹니다. ## 기여 기여는 이슈 중심 워크플로를 따릅니다. 모든 작업은 v2 프로젝트 보드에서 추적되어야 하며, PR은 `v2/main`에 대해 열리고 `Closes #<issue>`로 연결되어야 합니다. 외부 기여는 풀 리퀘스트가 아닌 이슈로 수락됩니다. `AGENTS.md` 파일은 버전 관리, TypeScript 표준, Mantine/React 규칙 및 테스트 요구 사항을 포함하여 인간 및 AI 기여자 모두에 대한 프로젝트 규칙을 정의합니다. `CLAUDE.md` 파일은 Claude Code의 진입점 역할을 하며, `AGENTS.md`를 자동으로 로드하여 에이전트와 인간이 동일한 소스에서 운영되도록 합니다. ## 라이선스 MCP 프로젝트는 MIT에서 Apache-2.0으로 전환 중입니다. 새로운 기여는 Apache-2.0, 문서(사양 제외)는 CC-BY-4.0으로 라이선스되며, 재라이선스 동의를 부여하지 않은 레거시 기여는 MIT로 유지됩니다.