Madhyamas 프록시 — AI 에이전트 가이드
Madhyamas는 Rust로 구축된 오픈소스 HTTP/HTTPS 디버깅 프록시입니다. 클라이언트와 서버 간 트래픽을 캡처, 검사 및 조작합니다. 통합된 madhyamas 바이너리는 프록시 서버, 웹 UI, MCP 서버, CLI를 제공합니다.
빠른 시작
# 1. 설치 (하나 선택)
cargo install madhyamas # crates.io에서 설치
cargo build --release -p madhyamas # 소스에서 빌드
# 또는 GitHub Releases에서 미리 빌드된 바이너리 다운로드
# 2. 프록시 서버 시작
madhyamas serve
# 프록시는 :8888에서 수신, API/웹 UI는 :3001에서 수신
# 3. 확인
curl http://localhost:3001/api/health
# 반환: OK
클라이언트가 프록시 localhost:8888을 사용하도록 구성하세요. HTTPS 가로채기를 위해 ~/.madhyamas/certs/madhyamas-ca.pem에서 CA 인증서를 설치하거나 (GET /api/cert/ca를 통해 다운로드) 설치하세요.
자세한 설치, 구성 및 CA 인증서 설정은 references/setup.md를 참조하세요.
인터페이스 선택
Madhyamas는 세 가지 인터페이스를 제공합니다. 컨텍스트에 따라 사용 가능한 것을 선택하세요:
| 인터페이스 | 사용 시기 | 설정 | 참조 |
|---|---|---|---|
| MCP 도구 | MCP 호환 에이전트(Claude Desktop, Windsurf 등) 내부에서 사용 | madhyamas mcp (stdio 전송) | references/mcp-tools.md |
| CLI 명령어 | 셸 액세스, 스크립팅, 터미널 기반 에이전트 | madhyamas <명령어> <하위명령어> | references/cli-commands.md |
| REST API | 세밀한 제어, 사용자 정의 스크립트, 직접 HTTP | curl http://localhost:3001/api/... | references/rest-api.md |
세 인터페이스 모두 동일한 기본 기능을 제공합니다. MCP 도구와 CLI 명령어는 REST API를 래핑한 것입니다.
주요 개념
- 프록시 포트: 프록시는
:8888(HTTP/HTTPS 트래픽), API/UI는:3001에서 수신 - CA 인증서:
~/.madhyamas/certs/에 자동 생성됨. HTTPS 가로채기를 위해 시스템 신뢰 저장소에 설치 - 세션: 트래픽을 명명된 세션으로 구성. 기본 세션이 자동 생성됨
- 캡처 모드: 기록(기본값) 모드는 트래픽을 캡처하고, 통과 모드는 기록 없이 전달
- 가로채기 파이프라인 순서: 재작성(우선순위 10) → 모의(20) → 중단점(30) → 조절(40)
- 데이터 디렉터리:
~/.madhyamas/에는certs/,logs/,traffic.db(SQLite)가 포함됨 - MCP 서버:
madhyamas mcp를 실행하여 stdio 기반 MCP 전송 사용.MADHYAMAS_API_URL을 설정하여 실행 중인 프록시 인스턴스에 연결
핵심 워크플로우
| 워크플로우 | 설명 | 참조 |
|---|---|---|
| 설정 | 설치, 구성, 클라이언트 연결, CA 인증서 설치 | setup.md |
| 트래픽 검사 | 캡처된 HTTP/HTTPS 트래픽 목록, 필터, 검색, 분석 | traffic-inspection.md |
| 모의 응답 | 가로채어 가짜 응답을 반환하는 모의 규칙 생성 | mocking.md |
| 중단점 | 요청/응답을 일시 중지하여 검사 및 수정 | breakpoints.md |
| 재작성 | 일치하는 트래픽의 URL, 헤더, 본문 수정 | rewrites.md |
| 조절 | 느리거나 불안정한 네트워크 조건 시뮬레이션 | throttling.md |
| 재생 | 수정과 함께 캡처된 요청 재실행 | replay.md |
| 세션 | 디버깅 세션 생성, 전환, 내보내기, 가져오기 | sessions.md |
| gRPC 검사 | gRPC 연결, 스트림, 프레임 검사 (실험적) | grpc.md |
| 스크립팅 | JS/TS 스크립트로 트래픽 조작 자동화 (실험적) | scripting.md |
| 플러그인 | 확장 기능을 위한 Rust 플러그인 관리 (실험적) | plugins.md |
| WebSocket | WebSocket 연결 트래픽 및 메시지 검사 | websockets.md |
| 내보내기/가져오기 | HAR 내보내기, cURL 내보내기, 규칙 영구 저장 | export-import.md |
| 문제 해결 | 인증서 오류, 포트 충돌, DB 잠금, TLS 실패 | troubleshooting.md |
| Harness 설정 | Claude, Windsurf, Cursor 등을 위한 MCP 구성 | harness-setup.md |
참조 색인
| 파일 | 읽어야 할 시기 |
|---|---|
references/setup.md | 최초 설정, 설치, CA 인증서, 클라이언트 구성 |
references/mcp-tools.md | 67개 MCP 도구 전체 참조 (매개변수 포함) |
references/cli-commands.md | 58개 CLI 하위 명령어 전체 참조 (플래그 포함) |
references/rest-api.md | 130개 이상의 REST API 엔드포인트 전체 참조 |
references/traffic-inspection.md | 캡처된 트래픽 필터링, 검색, 분석 |
references/mocking.md | 모의 응답 생성 및 관리 |
references/breakpoints.md | 트래픽 일시 중지 및 수정 |
references/rewrites.md | URL/헤더/본문 재작성 규칙 |
references/throttling.md | 네트워크 조건 시뮬레이션 |
references/replay.md | 요청 재생 및 저장 |
references/sessions.md | 세션 관리 |
references/grpc.md | gRPC 트래픽 검사 |
references/scripting.md | JavaScript/TypeScript 스크립팅 |
references/plugins.md | 플러그인 관리 |
references/websockets.md | WebSocket 트래픽 검사 |
references/export-import.md | HAR/cURL 내보내기, 영구 저장 |
references/troubleshooting.md | 일반적인 문제 및 해결 방법 |
references/harness-setup.md | Harness별 MCP 구성 |
MCP 서버 설정
AI 에이전트 통합을 위해 MCP 서버를 실행하세요:
madhyamas mcp # stdio 전송, localhost:3001에 연결
MADHYAMAS_API_URL=http://host:3001 madhyamas mcp # 사용자 정의 API URL
에이전트 MCP 구성에 추가:
{
"mcpServers": {
"madhyamas": {
"command": "/path/to/madhyamas",
"args": ["mcp"],
"env": { "MADHYAMAS_API_URL": "http://127.0.0.1:3001" }
}
}
}
Harness별 구성(Claude Desktop, Windsurf, Cursor, OpenCode, CommandCode, Devin)은 references/harness-setup.md를 참조하세요.
일반 패턴
실패한 API 호출 디버깅:
- 프록시 시작:
madhyamas serve - 클라이언트가 프록시를 사용하도록 구성
- 문제 재현
- 트래픽 검사:
madhyamas traffic list --status 500또는 MCPmadhyamas_get_traffic(status=500) - 세부 정보 확인:
madhyamas traffic get <id>또는 MCPmadhyamas_get_traffic_entry
**API 엔드포인트 모의:
- 모의 생성:
madhyamas mocks create --url-pattern "*/api/auth*" --status-code 200 --body '{"token":"fake"}' - 또는 MCP:
madhyamas_create_mock(url_pattern="/api/auth", status_code=200, body='{"token":"fake"}') - 클라이언트에서 모의 엔드포인트 테스트
느린 네트워크에서 테스트:
- 조절 활성화:
madhyamas throttle set --download-bps 50000 --delay-ms 200 && madhyamas throttle enable - 또는 MCP:
madhyamas_set_throttle(download_bps=50000, delay_ms=200, enabled=true) - 워크플로우를 재현하여 느린 조건에서의 동작 확인