MCP 서버로서의 MCP Inspector

License: MIT Node.js TypeScript

LLM이 다른 MCP 서버를 검사하고 테스트할 수 있도록 하는 가벼운 MCP 서버입니다. 외부 CLI를 호출하지 않고 MCP SDK를 직접 사용하는 독립형 구현입니다.

기능

직접적인 SDK 통합: 서버 및 클라이언트 작업 모두에 @modelcontextprotocol/sdk를 직접 사용
모든 전송 유형: stdio, SSE 및 HTTP(스트리밍 가능) 전송 지원
최소한의 설치 공간: 단일 종속성 (@modelcontextprotocol/sdk)
전체 MCP 검사: 도구 나열, 도구 호출, 리소스 나열, 리소스 읽기, 프롬프트 나열, 프롬프트 가져오기
세션 관리: 자동 가비지 컬렉션이 포함된 지속적 연결
이벤트 버퍼링: 디버깅을 위한 알림, 트래픽 및 오류 캡처

설치

npm install
npm run build

사용법

MCP 서버로서

MCP 구성에 추가하세요. 하네스마다 약간의 차이가 있지만 일반적인 형식은 동일합니다:

{
  "mcpServers": {
    "mcp-inspector": {
      "command": "node",
      "args": ["/path/to/mcp-inspector-as-mcp-server/dist/server.js"]
    }
  }
}

사용 가능한 도구

세션 관리 (v2.0에서 새로 추가됨)

도구	설명
`insp_connect`	MCP 서버에 대한 지속적 연결을 설정합니다. `session_id`를 반환합니다.
`insp_disconnect`	지속적 세션을 닫고 리소스를 해제합니다.
`insp_list_sessions`	상태 및 유휴 시간과 함께 모든 활성 세션을 나열합니다.
`insp_read_events`	세션에서 버퍼링된 이벤트(알림, 트래픽, 오류)를 읽습니다.
`insp_inject_steering`	세션의 큐에 인간의 조종 메시지를 주입합니다.

검사 도구

도구	설명
`insp_tools_list`	MCP 서버가 노출하는 모든 도구를 나열합니다
`insp_tools_call`	MCP 서버의 도구를 호출합니다
`insp_resources_list`	MCP 서버가 노출하는 모든 리소스를 나열합니다
`insp_resources_read`	특정 리소스를 읽습니다
`insp_resources_templates`	리소스 템플릿을 나열합니다
`insp_prompts_list`	모든 프롬프트를 나열합니다
`insp_prompts_get`	특정 프롬프트를 가져옵니다

연결 매개변수

모든 도구는 다음 연결 매개변수를 허용합니다:

stdio 전송(로컬 명령)의 경우:

command: 실행할 명령 (예: "node", "python")
args: 인수 배열 (예: ["path/to/server.js"])

SSE/HTTP 전송(원격 서버)의 경우:

url: 서버 URL (예: "http://localhost:3000/sse")
headers: 선택적 HTTP 헤더 객체

공통:

transport: 전송 유형 강제 지정 ("stdio", "sse" 또는 "http"). 지정하지 않으면 자동 감지됩니다.
session_id: (선택 사항) 일시적인 연결을 만드는 대신 기존 지속적 세션을 사용합니다.

세션 워크플로우

상태 저장 서버 동작을 디버깅하려면 지속적 세션을 사용하세요:

1. insp_connect → returns session_id
2. insp_tools_list (with session_id) → uses persistent connection
3. insp_tools_call (with session_id) → state is preserved
4. insp_read_events (with session_id) → see notifications
5. insp_disconnect (with session_id) → cleanup

세션은 30분 동안 활동이 없으면 자동으로 닫힙니다.

인간 조종 및 관찰 가능성

이 검사기는 LLM 기반 MCP 테스트를 실시간으로 관찰하고 안내할 수 있는 인간 개입(human-in-the-loop) 워크플로우를 가능하게 합니다.

작동 방식

┌─────────────┐     MCP calls      ┌─────────────────┐     forwards     ┌─────────────┐
│   LLM Agent │ ◄────────────────► │  MCP Inspector  │ ◄──────────────► │  Target MCP │
│  (Antigravity)                   │    (v2.0)       │                  │   Server    │
└─────────────┘                    └────────┬────────┘                  └─────────────┘
                                            │
                                   Events logged to
                                   session EventBuffer
                                            │
                    ┌───────────────────────┼───────────────────────┐
                    │                       │                       │
                    ▼                       ▼                       ▼
            insp_read_events         HTTP :9847/api          mcp-steer CLI
            (LLM reads events)       (external access)       (human injection)

활동 보기

LLM을 통해: 에이전트가 insp_read_events를 호출하여 무슨 일이 일어나고 있는지 확인할 수 있습니다:

{
  "session_id": "sess_abc123",
  "types": ["traffic_in", "traffic_out"],
  "limit": 20
}

HTTP를 통해: 조종 API를 직접 쿼리합니다:

curl http://127.0.0.1:9847/api/sessions

에이전트 조종

LLM의 다음 도구 응답에 나타나는 안내 메시지를 주입합니다.

CLI 사용:

./bin/mcp-steer.mjs "Focus on testing the error handling paths"
./bin/mcp-steer.mjs --session sess_abc123 "Try calling with invalid params"

HTTP 사용:

curl -X POST http://127.0.0.1:9847/api/steer \
  -H "Content-Type: application/json" \
  -d '{"message": "Check the authentication flow next"}'

MCP 도구 사용:

{
  "tool": "insp_inject_steering",
  "arguments": {
    "session_id": "sess_abc123",
    "message": "Great progress! Now test edge cases."
  }
}

이벤트 유형

유형	설명
`traffic_out`	대상 서버로 전송된 메시지
`traffic_in`	대상 서버로부터 수신된 메시지
`notification`	대상 서버로부터의 MCP 알림
`error`	통신 중 발생한 오류
`steering`	세션에 주입된 인간 조종 메시지

일반적인 워크플로우

LLM이 세션 생성: insp_connect → sess_abc123 획득
LLM이 테스트 시작: session_id와 함께 insp_tools_call 호출
인간이 관찰: curl http://127.0.0.1:9847/api/sessions
인간이 조종: ./bin/mcp-steer.mjs "배치 엔드포인트도 테스트하세요"
LLM이 조종 수신: 다음 도구 응답에 ⚡ STEERING from human: ... 포함
LLM이 적응: 인간의 안내를 고려하여 작업 수행

예시

로컬 MCP 서버의 도구 나열 (일시적):

{
  "command": "node",
  "args": ["/path/to/some-mcp-server/dist/server.js"]
}

지속적 세션 생성:

{
  "command": "node",
  "args": ["/path/to/some-mcp-server/dist/server.js"]
}
// Returns: { "session_id": "sess_abc123", "server_info": {...} }

세션을 사용하여 도구 호출:

{
  "session_id": "sess_abc123",
  "tool_name": "search",
  "tool_args": {"query": "hello"}
}

아키텍처

├── src/
│   ├── server.ts     # MCP server exposing inspector tools
│   ├── client.ts     # Client wrapper (hybrid stateless/session mode)
│   ├── transport.ts  # Transport factory (stdio, SSE, HTTP) + TracingWrapper
│   ├── session.ts    # SessionRegistry with GC (30-min TTL)
│   └── events.ts     # EventBuffer (ring buffer for notifications)
├── bin/
│   └── mcp-steer.mjs # CLI tool for human steering
├── tests/            # Integration test scripts (run with npx tsx)
└── vitest.config.ts  # Unit test + coverage config

이 프로젝트가 존재하는 이유

기존 MCP Inspector는 여러 프로젝트에 걸쳐 있는 웹 기반 UI + CLI 조합입니다. 이 프로젝트는 핵심 기능을 LLM이 다음을 수행할 수 있는 단일 가벼운 MCP 서버로 통합합니다:

MCP 서버를 반복적으로 개발하고 디버깅
대화를 떠나지 않고 MCP 서버 기능 테스트
MCP 서버가 노출하는 도구/리소스/프롬프트 탐색
지속적 세션으로 상태 저장 동작 디버깅

개발

npm install          # install dependencies
npm run build        # compile TypeScript
npm run dev          # watch mode
npm test             # run unit tests
npm run test:cov     # run tests with coverage
npm run lint         # lint source files
npm run format       # auto-format with Prettier
npm run typecheck    # type-check without emitting

변경 로그

v2.1.0

인간 개입 워크플로우를 위한 인간 조종(insp_inject_steering) 추가
외부 조종/관찰 가능성을 위해 9847 포트에 HTTP API 추가
쉬운 인간 상호작용을 위한 mcp-steer.mjs CLI 도구 추가
핸들러 캡처 타이밍으로 인해 메시지 손실이 발생하던 TracingTransportWrapper의 치명적인 버그 수정

v2.0.0

세션 관리 추가 (insp_connect, insp_disconnect, insp_list_sessions)
이벤트 버퍼링 추가 (insp_read_events)
모든 검사 도구가 이제 지속적 연결을 위한 선택적 session_id 지원
자동 가비지 컬렉션 추가 (유휴 세션에 대해 30분 TTL)
하위 호환성: 기존의 일시적인 동작을 위해 session_id 생략 가능

v1.0.0

일시적 연결을 포함한 초기 릴리스

라이선스

MIT

MCP Inspector as MCP Server