crawl-api-spec

name	crawl-api-spec
description	Crawls exchange API documentation and generates structured markdown specs. Use when integrating a new exchange or updating API specifications.
disable-model-invocation	true
user-invocable	true
argument-hint	<서비스명> <문서URL> [출력파일경로]
allowed-tools	mcp__playwright__*, Write, Read
context	fork

API 문서 크롤링 및 스펙 문서 생성

입력

$ARGUMENTS 형식: <서비스명> <문서URL> [출력파일경로]

예시:

• upbit https://docs.upbit.com/kr/reference docs/exchange/upbit_openapi_spec.md
• bithumb https://apidocs.bithumb.com docs/exchange/bithumb_openapi_spec.md
• kis https://apiportal.koreainvestment.com docs/exchange/kis_openapi_spec.md

---

실행 절차

Phase 1: 사이트 구조 파악

1. Playwright MCP browser_navigate로 문서 URL 접속
2. browser_snapshot으로 페이지 구조 확인 (사이드바 네비게이션, API 카테고리)
3. 약관 동의 팝업이 있으면 자동 클릭하여 통과
4. API 카테고리 목록과 각 API 페이지 URL을 수집

Phase 2: 배치 크롤링

5. browser_run_code를 사용하여 배치 단위(4~7개 페이지)로 크롤링:

   async (page) => {
     const pages = ['url1', 'url2', ...];
     const results = {};
     for (const p of pages) {
       await page.goto(p, { waitUntil: 'domcontentloaded', timeout: 15000 });
       await page.waitForTimeout(1500);
       const content = await page.evaluate(() => {
         const article = document.querySelector('article') || document.querySelector('main') || document.body;
         return article.innerText.substring(0, 5000);
       });
       results[p] = content;
     }
     return JSON.stringify(results);
   }
   

6. 각 배치에서 추출할 정보:
   • API 이름, Method (GET/POST/DELETE), URL 경로
   • 입력 파라미터 (이름, 타입, 필수여부, 설명)
   • 출력 필드 (이름, 타입, 설명)
   • Rate Limit, 인증 방식
7. 크롤링 대상 우선순위:
   • 필수: 인증, 시세조회(현재가/호가/체결/캔들), 주문(생성/취소/조회), 잔고, WebSocket
   • 선택: 입출금, 서비스 상태, 공지 등

Phase 3: 동적 로딩 대응

8. JavaScript SPA 사이트에서 내용이 안 보이면:
   • browser_wait_for 사용하여 특정 텍스트 로딩 대기
   • browser_evaluate로 DOM 직접 탐색
   • 그래도 불가능하면 [크롤링 불가 - 수동 확인 필요]로 표시
9. 테이블이 HTML table이 아닌 커스텀 컴포넌트인 경우:
   • innerText 기반 추출 후 파싱
   • 탭/줄바꿈 패턴으로 필드 분리

Phase 4: 문서 생성

10. 수집된 데이터를 아래 표준 형식으로 정리:

출력 템플릿은 output-template.md를 참조합니다.

---

에러 대응

상황	대응
사이트 접속 불가	3회 재시도 후 실패 보고
약관/CAPTCHA 차단	사용자에게 수동 통과 요청
내용 누락	[미확인 - 수동 확인 필요]로 표시
Rate Limit	배치 간 3초 대기