whistle.agent-mcp

English

MCP를 지원하는 AI 어시스턴트가 Whistle이 현재 캡처한 HTTP, HTTPS, WebSocket 트래픽을 직접 조회할 수 있게 합니다.

세션을 내보내거나, 응답 내용을 복사하거나, 요청 정보를 수동으로 정리할 필요가 없습니다. 연결 후 AI에게 요청 검색, 전체 세션 확인, WebSocket 프레임 분석을 직접 지시할 수 있습니다.

사용 용도

• 최근 실패, 타임아웃 또는 특정 URL에 해당하는 요청 찾기.

• 특정 요청의 요청 헤더, 응답 헤더, 본문, 소요 시간 및 매칭 규칙 확인.

• WebSocket 메시지 내용과 송수신 방향 문제 해결.

• Whistle 구성과 캡처 데이터를 수정하지 않고 AI로 네트워크 문제를 분석.

Related MCP server: Android Proxy MCP

빠른 시작

요구 사항: Node.js 20+, Whistle>=2.10.7.

처음 사용할 때 아래의 모든 명령을 복사하여 실행하세요:

npm install -g whistle@latest
w2 install @wilson_janet/whistle.agent-mcp
w2 start

Whistle이 이미 실행 중이라면 플러그인을 설치하고 재시작하기만 하면 됩니다:

w2 install @wilson_janet/whistle.agent-mcp
w2 restart

플러그인 사용 가능 여부 확인:

curl http://127.0.0.1:8899/whistle.agent-mcp/health

MCP 클라이언트의 구성 파일에 다음을 추가하세요:

{
  "mcpServers": {
    "whistle": {
      "url": "http://127.0.0.1:8899/whistle.agent-mcp/mcp"
    }
  }
}

연결이 완료되면 다음과 같이 직접 질문할 수 있습니다:

查找最近 20 个状态码为 500 的请求。
查看 URL 包含 /api/orders 的最新请求，分析它为什么失败。
读取会话 1750000000000-001 的请求、响应和耗时。
查看指定 WebSocket 会话最近由服务端发送的消息。

제공되는 도구

검색 결과의 세션 ID는 상세 정보 및 프레임 조회 도구에 그대로 전달할 수 있습니다.

보안 및 제한 사항

• 모든 도구는 읽기 전용이며 규칙, 프록시 설정 또는 캡처 데이터를 수정하지 않고 요청을 재생하지도 않습니다.

• authorization, cookie, API Key, Token 등 민감한 요청 헤더는 자동으로 [REDACTED]로 대체됩니다.

• 텍스트 본문은 최대 200,000자까지 반환되며, 바이너리 콘텐츠는 제한된 길이의 base64 미리보기만 반환됩니다.

• 데이터는 Whistle 메모리 캐시에서 가져오므로 오래된 세션은 만료되었을 수 있습니다.

• 기본적으로 로컬 Origin만 허용합니다. 인증 없이 Whistle UI 포트를 신할 수 없는 네트워크에 노출하지 마세요.

MCP 엔드포인트에 Bearer Token을 추가하려면 Whistl 시작 시 설정하세요:

WHISTLE_MCP_TOKEN='your-token' w2 restart

그런 다음 MCP 클라이언트에서 해당 서비스에 동일한 Bearer Token을 구서하세요. WHSITLE_MCP_ALLOWED_ORIGINS를 통해 추가 정확한 Origin을 등록할 수도 있으며, 여러 값은 쉼표로 구분합니다.

개발

프로젝트 디렉터리로 이동한 후 의존성을 설치하고 빌드하세요:

npm install
npm run build

소스에서 로컬 플러그인을 로드할 때 -A는 whistl.agent-mcp를 포하하는 상위 디렉터리를 가리켜야 합니다:

w2 start -A ..

TypeScript watcher, Whistle 및 로컬 플러그인 리로드를 시작합니다:

npm run dev

전체 검증:

npm run check
npm test
npm run build
npm run smoke

npm run smoke:api는 추가로 로컬에 설치된 Whistle Local Agent API에 연결하여 현재 캡처된 데이터로 조회 기능을 검증합니다.

프로젝트 구조

index.cjs              Whistle 插件入口
src/
  plugin/handler.ts    HTTP 路由与访问控制
  mcp/server.ts        MCP 工具定义
  whistle/             API 适配、查询、脱敏、错误与类型
  testing/smoke.ts     构建后的端到端 smoke test
test/
  whistle/             Whistle 相关单元测试
scripts/dev.sh         本地开发脚本