algokit-mcp 1.0.1 → 1.0.3

package/README.md

@@ -1,6 +1,6 @@
 # AlgoKit-mcp
 
-**백준(BOJ)과 프로그래머스 알고리즘 문제 학습을 돕는 MCP 서버 + Skill**
+**AI 에이전트와 함께하는 알고리즘 학습 MCP 툴킷 (백준, 프로그래머스 지원)**
 
 AI 기반 힌트 생성, 문제 분석, 복습 템플릿 제공으로 효율적인 알고리즘 학습을 지원합니다.
 
@@ -12,9 +12,117 @@ AI 기반 힌트 생성, 문제 분석, 복습 템플릿 제공으로 효율적
 - 📝 **복습 템플릿**: 자동 생성되는 마크다운 복습 문서
 - 🧪 **코드 분석**: 제출 코드의 시간/공간 복잡도 분석 및 개선 제안
 
+## 플랫폼별 설정 경로
+
+| 항목 | Claude Code | Codex | Gemini CLI |
+|------|-------------|-------|------------|
+| **Skills 기능명** | Skills | Agent Skills | Agent Skills |
+| **Skills 호출** | `/skill-name` | `$skill-name` or 자동 | 모델 자율 판단 |
+| **MCP 설정 (프로젝트)** | `.mcp.json` | `.codex/config.toml` | `.gemini/settings.json` |
+| **MCP 설정 (전역)** | `~/.claude.json` | `~/.codex/config.toml` | `~/.gemini/settings.json` |
+| **Skills (프로젝트)** | `.claude/skills/` | `.codex/skills/` | `.gemini/skills/` |
+| **Skills (전역)** | `~/.claude/skills/` | `~/.codex/skills/` | `~/.gemini/skills/` |
+
+> Skills는 MCP 서버 첫 기동 시 감지된 플랫폼에 자동 설치됩니다.
+
+---
+
 ## 설치
 
-### Claude Code (추천)
+> **Skills 자동 설치**: MCP 서버 첫 기동 시 설치된 AI 에이전트를 자동으로 감지하여 Skills를 설치합니다.
+
+### Claude Code
+
+#### 자동 설치
+
+```bash
+# 전역 설정 (모든 프로젝트에서 사용)
+claude mcp add --scope user algokit -- npx -y algokit-mcp
+
+# 프로젝트 설정 (.mcp.json 생성)
+claude mcp add --scope project algokit -- npx -y algokit-mcp
+
+
+```
+
+#### 수동 설치
+
+`~/.claude.json` (전역) 편집:
+
+```json
+{
+  "mcpServers": {
+    "algokit": {
+      "command": "npx",
+      "args": ["-y", "algokit-mcp"]
+    }
+  }
+}
+```
+
+또는 프로젝트 루트에 `.mcp.json` 생성 ([예시](.claude/examples/claude-code-config.json)):
+
+```json
+{
+  "mcpServers": {
+    "algokit": {
+      "command": "npx",
+      "args": ["-y", "algokit-mcp"]
+    }
+  }
+}
+```
+
+#### Skills 위치
+
+| 등록 방식 | Skills 위치 |
+|----------|------------|
+| `--scope user` (전역) | `~/.claude/skills/` |
+| `--scope project` (`.mcp.json` 있음) | `<프로젝트>/.claude/skills/` |
+
+
+---
+
+### Codex
+
+#### 자동 설치
+
+```bash
+# 전역 설치
+codex mcp add algokit -- npx -y algokit-mcp
+```
+
+#### 수동 설치
+
+`~/.codex/config.toml` (전역) 또는 `.codex/config.toml` (프로젝트) 편집 ([예시](.claude/examples/codex-config.toml)):
+
+```toml
+[mcp.servers.algokit]
+command = "npx"
+args = ["-y", "algokit-mcp"]
+```
+
+#### Skills 위치
+
+| 등록 방식 | Skills 위치 |
+|----------|------------|
+| 프로젝트 (`.codex/` 있음) | `<프로젝트>/.codex/skills/` |
+| 전역 (`~/.codex/` 있음) | `~/.codex/skills/` |
+
+---
+
+### Gemini CLI
+
+#### 자동 설치
+
+```bash
+# 전역 설치
+gemini mcp add algokit -- npx -y algokit-mcp
+```
+
+#### 수동 설치
+
+`~/.gemini/settings.json` (전역) 또는 `.gemini/settings.json` (프로젝트) 편집 ([예시](.claude/examples/gemini-config.json)):
 
 ```json
 {
@@ -27,15 +135,22 @@ AI 기반 힌트 생성, 문제 분석, 복습 템플릿 제공으로 효율적
 }
 ```
 
+#### Skills 위치
+
+| 등록 방식 | Skills 위치 |
+|----------|------------|
+| 프로젝트 (`.gemini/` 있음) | `<프로젝트>/.gemini/skills/` |
+| 전역 (`~/.gemini/` 있음) | `~/.gemini/skills/` |
+
 ## MCP 도구
 
 ### 백준 (BOJ)
 
 | 도구 | 설명 |
 |------|------|
-| `search_problems` | 문제 검색 (티어, 태그, 키워드) |
-| `get_problem` | 문제 상세 조회 |
-| `search_tags` | 알고리즘 태그 검색 |
+| `search_problems_boj` | 문제 검색 (티어, 태그, 키워드) |
+| `get_problem_boj` | 문제 상세 조회 |
+| `search_tags_boj` | 알고리즘 태그 검색 |
 | `fetch_problem_content_boj` | 문제 본문 스크래핑 |
 | `analyze_problem_boj` | 문제 분석 및 힌트 가이드 |
 | `generate_hint_boj` | 3단계 힌트 생성 |
@@ -46,45 +161,190 @@ AI 기반 힌트 생성, 문제 분석, 복습 템플릿 제공으로 효율적
 
 | 도구 | 설명 |
 |------|------|
-| `search_programmers_problems` | 문제 검색 (난이도, 카테고리) |
-| `get_programmers_problem` | 문제 상세 조회 |
+| `search_problems_programmers` | 문제 검색 (난이도, 카테고리) |
+| `get_problem_programmers` | 문제 상세 조회 |
 | `fetch_problem_content_programmers` | 문제 본문 스크래핑 |
 | `analyze_problem_programmers` | 문제 분석 |
 | `generate_hint_programmers` | 힌트 생성 |
 | `generate_review_template_programmers` | 복습 템플릿 |
 | `analyze_code_submission_programmers` | 코드 분석 |
 
-## MCP Skill (Claude Code 전용)
+## Skills
 
-**Skill 이름**: `algo:`
+**Skill 이름**: `algo:` (BOJ/프로그래머스 자동 선택)
 
-플랫폼(BOJ/프로그래머스)을 자동으로 선택하여 자연스러운 학습 경험을 제공합니다.
+Claude Code, Codex, Gemini CLI 모두 동일한 `algo:` Skills를 지원합니다.
+MCP 서버 첫 기동 시 감지된 에이전트에 자동으로 설치되며, 수동으로도 설치할 수 있습니다.
 
-### 설치 방법
+### 수동 설치
 
 ```bash
-# Skill 파일 복사 (프로젝트별)
-cp skills/* /your/project/.claude/skills/
+# Claude Code
+cp -r skills/* ~/.claude/skills/          # 전역
+cp -r skills/* .claude/skills/            # 프로젝트
+
+# Codex
+cp -r skills/* ~/.codex/skills/           # 전역
+cp -r skills/* .codex/skills/             # 프로젝트
 
-# 또는 전역 설정
-cp skills/* ~/.claude/skills/
+# Gemini CLI
+cp -r skills/* ~/.gemini/skills/          # 전역
+cp -r skills/* .gemini/skills/            # 프로젝트
 ```
 
 ### 사용 예시
 
+#### `algo:search` - 문제 검색
+
+```
+You: "골드 난이도 DP 문제 추천해줘"
+
+Claude: "백준에서 골드 티어의 DP 문제를 검색했습니다.
+
+**추천 문제 3개:**
+1. 🥇 [G5] 12865번 - 평범한 배낭 (✅ 16,234명)
+2. 🥇 [G4] 9251번 - LCS (✅ 13,892명)
+3. 🥇 [G3] 1932번 - 정수 삼각형 (✅ 18,234명)
+
+어떤 문제부터 시작하시겠어요?"
 ```
-You: "백준 골드 난이도 DP 문제 3개 추천해줘"
-Claude: [자동으로 BOJ search_problems 호출]
 
-You: "이 문제 분석해줘: https://www.acmicpc.net/problem/1927"
-Claude: [URL 파싱 → analyze_problem_boj 자동 호출]
+```
+You: "https://www.acmicpc.net/problem/1927"
+
+Claude: "백준 1927번 '최소 힙' 문제를 조회했습니다.
+
+**문제 정보:**
+- 난이도: 🥈 Silver I
+- 분류: 자료구조, 우선순위 큐
+- 해결: 28,456명 | 정답률: 47.2%
+
+본문을 보시겠어요? (/algo:fetch)"
+```
+
+#### `algo:hint` - 단계별 힌트
+
+```
+You: "1927번 힌트 줘"
+
+Claude: "**💡 Level 1 힌트 (접근 방향)**
+
+이 문제는 **우선순위 큐(Priority Queue)** 자료구조를 사용합니다.
+Python의 `heapq` 모듈 또는 C++의 `priority_queue`를 활용하면
+O(log N) 시간에 최솟값을 찾을 수 있어요.
+
+더 구체적인 힌트가 필요하신가요?"
+```
+
+```
+You: "더 구체적으로 알려줘"
+
+Claude: "**💡 Level 2 힌트 (구현 방법)**
+
+1. **최소 힙** 사용 (Python: heapq, C++: priority_queue<int, greater<int>>)
+2. x가 0이 아니면 → `heappush(x)`
+3. x가 0이면 → `heappop()` (빈 경우 0 출력)
+
+시간복잡도: O(N log N)
+공간복잡도: O(N)
+
+코드 예시를 보시겠어요? (/algo:hint 정답)"
+```
+
+#### `algo:code-review` - 코드 분석
+
+```
+You: "1927번 내 코드 분석해줘"
+You: [Python 코드 붙여넣기]
+
+Claude: "코드를 분석했습니다! ✨
+
+**✅ 좋은 점:**
+- heapq 모듈을 올바르게 사용
+- 시간복잡도 O(N log N) 달성
+
+**⚠️ 개선 가능:**
+1. `sys.stdin.readline()` 사용 → 입력 속도 개선 (30% 빠름)
+2. 빈 힙 체크를 `if heap:` 대신 `if len(heap):`로 명시
+
+**예상 성능:**
+- 현재: 약 300ms
+- 개선 후: 약 200ms
+
+수정 코드를 보여드릴까요?"
+```
 
-You: "프로그래머스 Level 2 문제 찾아줘"
-Claude: [search_programmers_problems 자동 호출]
+#### `algo:review` - 복습 템플릿
 
-You: "힌트 더 줘"
-Claude: [이전 대화 분석 → 적절한 Level 힌트 제공]
 ```
+You: "1927번 복습 문서 만들어줘"
+
+Claude: "복습 템플릿을 생성했습니다! 📝
+
+# 백준 1927번 - 최소 힙
+
+## 문제 요약
+최솟값을 빠르게 찾는 자료구조 구현
+
+## 핵심 알고리즘
+- **우선순위 큐** (최소 힙)
+- 삽입: O(log N), 삭제: O(log N)
+
+## 풀이 과정
+1. heapq 모듈 import
+2. 입력에 따라 push/pop 수행
+...
+
+이 템플릿을 파일로 저장하시겠어요?"
+```
+
+---
+
+## 학습 워크플로우
+
+### 새 문제 접근하기
+
+```
+1. You: "골드 3~5 DP 문제 추천"
+   → Claude: [문제 3개 추천]
+
+2. You: "1932번 본문 보여줘"
+   → Claude: [문제 본문 표시]
+
+3. You: "힌트 줘"
+   → Claude: [Level 1 힌트]
+
+4. You: "더 구체적으로"
+   → Claude: [Level 2 힌트]
+```
+
+### 풀이 후 복습하기
+
+```
+1. You: "1932번 내 코드 분석해줘" + [코드]
+   → Claude: [시간복잡도, 개선점 제시]
+
+2. You: "복습 문서 만들어줘"
+   → Claude: [마크다운 템플릿 생성]
+```
+
+---
+
+## 사용 방법
+
+### 일반 사용 (자연스러운 대화)
+```
+You: "골드 DP 문제 추천해줘"
+→ Claude가 맥락 파악 → MCP 도구 자동 호출 → 결과 제공
+```
+
+### Skill 사용 (명시적 호출, 권장)
+```
+You: "/algo:search 골드 DP 문제 추천해줘"
+→ Skill이 의도 명확히 파악 → 더 정확한 MCP 도구 선택
+```
+
+**차이점**: 둘 다 MCP 도구를 호출하지만, Skill 사용 시 더 명시적이고 정확한 응답을 받을 수 있습니다.
 
 ## 개발
 
@@ -131,7 +391,7 @@ MIT
 
 <div align="center">
 
-**[GitHub](https://github.com/itsme-shawn/AlgoKit-mcp)** • **[Issues](https://github.com/itsme-shawn/algoKit-mcp/issues)** • **[NPM](https://www.npmjs.com/package/algokit-mcp-server)**
+**[GitHub](https://github.com/itsme-shawn/AlgoKit-mcp)** • **[Issues](https://github.com/itsme-shawn/algoKit-mcp/issues)** • **[NPM](https://www.npmjs.com/package/algokit-mcp)**
 
 
 </div>

package/dist/api/boj-scraper.js

@@ -79,7 +79,7 @@ export class BOJScraper {
         // 캐시 확인
         const cached = this.cache.get(problemId);
         if (cached !== undefined) {
-            console.log(`[BOJScraper] 캐시 히트: 문제 ${problemId}`);
+            process.stderr.write(`[BOJScraper] 캐시 히트: 문제 ${problemId}\n`);
             return cached;
         }
         // Rate Limiting (백업 보호, 캐시 미스 시에만)

package/dist/api/boj-scraper.js.map

@@ -1 +1 @@
-{"version":3,"file":"boj-scraper.js","sourceRoot":"","sources":["../../src/api/boj-scraper.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"boj-scraper.js","sourceRoot":"","sources":["../../src/api/boj-scraper.ts"],"names":[],"mappings":"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"}

package/dist/api/programmers-scraper.d.ts

@@ -11,7 +11,6 @@ export declare class ProgrammersScrapeError extends Error {
  * 프로그래머스 스크래퍼
  */
 export declare class ProgrammersScraper {
-    private browserPool;
     private rateLimiter;
     private searchCache;
     private problemCache;
@@ -25,10 +24,6 @@ export declare class ProgrammersScraper {
      * @throws {ProgrammersScrapeError}
      */
     searchProblems(options?: ProgrammersSearchOptions): Promise<ProgrammersProblemSummary[]>;
-    /**
-     * 검색 URL 생성
-     */
-    private buildSearchUrl;
     /**
      * 문제 상세 페이지 HTML 가져오기 (fetch 기반, BOJScraper 패턴)
      *

package/dist/api/programmers-scraper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"programmers-scraper.d.ts","sourceRoot":"","sources":["../../src/api/programmers-scraper.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,yBAAyB,CAAC;AAGjC;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAGtC,IAAI,EACP,SAAS,GACT,oBAAoB,GACpB,kBAAkB,GAClB,aAAa;IACV,aAAa,CAAC,EAAE,OAAO;gBAN9B,OAAO,EAAE,MAAM,EACR,IAAI,EACP,SAAS,GACT,oBAAoB,GACpB,kBAAkB,GAClB,aAAa,EACV,aAAa,CAAC,EAAE,OAAO,YAAA;CAKjC;AAED;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,WAAW,CAAgD;IACnE,OAAO,CAAC,YAAY,CAA6C;IACjE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;;IAe9D;;;;;;OAMG;IACG,cAAc,CAClB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,yBAAyB,EAAE,CAAC;IA4JvC;;OAEG;IACH,OAAO,CAAC,cAAc;IAsBtB;;;;;;OAMG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA8C1D;;OAEG;YACW,iBAAiB;IAsE/B;;OAEG;IACH,OAAO,CAAC,MAAM;IAId;;;;OAIG;IACH,aAAa;;;;IAOb;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;;;;;OAMG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC;CA2BvE"}
+{"version":3,"file":"programmers-scraper.d.ts","sourceRoot":"","sources":["../../src/api/programmers-scraper.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,yBAAyB,CAAC;AAGjC;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAGtC,IAAI,EACP,SAAS,GACT,oBAAoB,GACpB,kBAAkB,GAClB,aAAa;IACV,aAAa,CAAC,EAAE,OAAO;gBAN9B,OAAO,EAAE,MAAM,EACR,IAAI,EACP,SAAS,GACT,oBAAoB,GACpB,kBAAkB,GAClB,aAAa,EACV,aAAa,CAAC,EAAE,OAAO,YAAA;CAKjC;AAED;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,WAAW,CAAgD;IACnE,OAAO,CAAC,YAAY,CAA6C;IACjE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;;IAc9D;;;;;;OAMG;IACG,cAAc,CAClB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,yBAAyB,EAAE,CAAC;IAgJvC;;;;;;OAMG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA8C1D;;OAEG;YACW,iBAAiB;IAsE/B;;OAEG;IACH,OAAO,CAAC,MAAM;IAId;;;;OAIG;IACH,aAAa;;;;IAOb;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;;;;;OAMG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC;CA2BvE"}

package/dist/api/programmers-scraper.js

@@ -1,4 +1,9 @@
-import { BrowserPool } from '../utils/browser-pool.js';
+/**
+ * 프로그래머스 웹 스크래핑 클라이언트
+ *
+ * 검색: 프로그래머스 내부 JSON API (fetch 기반)
+ * 상세 페이지: cheerio (fetch 기반)
+ */
 import { RateLimiter } from '../utils/rate-limiter.js';
 import { LRUCache } from '../utils/lru-cache.js';
 import { parseProgrammersProblemContent } from '../utils/html-parser.js';
@@ -19,13 +24,11 @@ export class ProgrammersScrapeError extends Error {
  * 프로그래머스 스크래퍼
  */
 export class ProgrammersScraper {
-    browserPool;
     rateLimiter;
     searchCache;
     problemCache;
     baseUrl = 'https://school.programmers.co.kr';
     constructor() {
-        this.browserPool = BrowserPool.getInstance();
         // 초당 1회 요청 (보수적)
         this.rateLimiter = new RateLimiter({
             capacity: 2,
@@ -50,121 +53,87 @@ export class ProgrammersScraper {
         // 캐시 확인
         const cached = this.searchCache.get(cacheKey);
         if (cached !== undefined) {
-            console.log('[ProgrammersScraper] 캐시 히트: 검색 결과');
+            process.stderr.write('[ProgrammersScraper] 캐시 히트: 검색 결과\n');
             // limit 적용 후 반환
             return limit && limit > 0 ? cached.slice(0, limit) : cached;
         }
         // Rate limiting (캐시 미스 시에만)
         await this.rateLimiter.acquire();
-        let browser = null;
         try {
-            // 1. BrowserPool에서 브라우저 획득
-            browser = await this.browserPool.acquire();
-            const browserPage = await browser.newPage();
-            // 2. 검색 URL 생성
-            const searchUrl = this.buildSearchUrl({
-                levels,
-                order,
-                page,
-                query,
-            });
-            console.log(`[ProgrammersScraper] 검색 URL: ${searchUrl}`);
-            // 3. 페이지 이동 및 로딩 대기
-            try {
-                await browserPage.goto(searchUrl, {
-                    waitUntil: 'networkidle2',
-                    timeout: 30000,
-                });
+            // 1. 프로그래머스 내부 API URL 생성
+            const params = new URLSearchParams();
+            params.set('page', String(page));
+            params.set('perPage', '20');
+            params.set('order', order);
+            for (const level of levels) {
+                params.append('levels[]', String(level));
             }
-            catch (error) {
-                throw new ProgrammersScrapeError(`페이지 로딩 실패: ${searchUrl}`, 'NAVIGATION_ERROR', error);
+            if (query) {
+                params.set('search', query);
             }
-            // 4. JavaScript 렌더링 대기
+            const apiUrl = `${this.baseUrl}/api/v2/school/challenges/?${params.toString()}`;
+            process.stderr.write(`[ProgrammersScraper] API URL: ${apiUrl}\n`);
+            // 2. API 호출
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 10000);
+            let apiResponse;
             try {
-                await browserPage.waitForSelector('table tbody tr', {
-                    timeout: 10000,
+                const response = await fetch(apiUrl, {
+                    signal: controller.signal,
+                    headers: {
+                        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+                        Accept: 'application/json',
+                        'Accept-Language': 'ko-KR,ko;q=0.9,en-US;q=0.8,en;q=0.7',
+                    },
                 });
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    throw new ProgrammersScrapeError(`API 요청 실패: HTTP ${response.status}`, 'NAVIGATION_ERROR');
+                }
+                apiResponse = await response.json();
             }
             catch (error) {
-                // 빈 결과일 수 있으므로 스크린샷 저장 후 빈 배열 반환
-                await browserPage.screenshot({
-                    path: 'programmers-search-empty.png',
-                });
-                const rowCount = await browserPage.$$eval('table tbody tr', (rows) => rows.length);
-                if (rowCount === 0) {
-                    console.log('[ProgrammersScraper] 검색 결과 없음');
-                    await browserPage.close();
-                    return [];
+                clearTimeout(timeoutId);
+                if (error instanceof ProgrammersScrapeError) {
+                    throw error;
+                }
+                if (error.name === 'AbortError') {
+                    throw new ProgrammersScrapeError('요청이 타임아웃되었습니다 (10000ms 초과)', 'TIMEOUT', error);
                 }
-                throw new ProgrammersScrapeError('table tbody tr selector를 찾을 수 없습니다', 'SELECTOR_NOT_FOUND', error);
+                throw new ProgrammersScrapeError(`API 요청 실패: ${error.message}`, 'NAVIGATION_ERROR', error);
             }
-            // 5. 문제 목록 추출
+            // 3. API 응답 → ProgrammersProblemSummary 매핑
             let problems;
             try {
-                problems = await browserPage.$$eval('table tbody tr', (rows) => {
-                    return rows.map((row) => {
-                        const titleLink = row.querySelector('td.title a[href*="/lessons/"]');
-                        const categoryEl = row.querySelector('td.title small.part-title');
-                        const levelSpan = row.querySelector('td.level span[class*="level-"]');
-                        const finishedEl = row.querySelector('td.finished-count');
-                        const rateEl = row.querySelector('td.acceptance-rate');
-                        const href = titleLink?.getAttribute('href') || '';
-                        const problemId = href.match(/lessons\/(\d+)/)?.[1] || '';
-                        const title = titleLink?.textContent?.trim() || '';
-                        const category = categoryEl?.textContent?.trim() || '기타';
-                        const levelClass = levelSpan?.className || '';
-                        const level = parseInt(levelClass.match(/level-(\d+)/)?.[1] || '0');
-                        const finishedText = finishedEl?.textContent?.trim() || '0명';
-                        const finishedCount = parseInt(finishedText.replace(/,/g, '').replace('명', '') || '0');
-                        const rateText = rateEl?.textContent?.trim() || '0%';
-                        const acceptanceRate = parseInt(rateText.replace('%', '') || '0');
-                        return {
-                            problemId,
-                            title,
-                            level,
-                            category,
-                            url: `https://school.programmers.co.kr${href}`,
-                            finishedCount,
-                            acceptanceRate,
-                        };
-                    });
-                });
+                problems = (apiResponse.result ?? []).map((item) => ({
+                    problemId: String(item.id),
+                    title: item.title,
+                    level: item.level,
+                    category: item.partTitle,
+                    finishedCount: item.finishedCount,
+                    acceptanceRate: item.acceptanceRate,
+                    url: `${this.baseUrl}/learn/courses/30/lessons/${item.id}`,
+                }));
             }
             catch (error) {
                 throw new ProgrammersScrapeError('문제 목록 파싱 실패', 'PARSE_ERROR', error);
             }
-            await browserPage.close();
-            // 6. 캐시에 저장 (limit 적용 전 전체 결과 저장)
+            // 4. 캐시에 저장 (limit 적용 전 전체 결과 저장)
             this.searchCache.set(cacheKey, problems);
-            // 7. limit 적용
+            // 5. limit 적용
             if (limit && limit > 0) {
                 problems = problems.slice(0, limit);
             }
-            console.log(`[ProgrammersScraper] ${problems.length}개 문제 검색 완료`);
+            process.stderr.write(`[ProgrammersScraper] ${problems.length}개 문제 검색 완료\n`);
             return problems;
         }
-        finally {
-            // 7. 브라우저 반환 (필수!)
-            if (browser) {
-                await this.browserPool.release(browser);
+        catch (error) {
+            if (error instanceof ProgrammersScrapeError) {
+                throw error;
             }
+            throw new ProgrammersScrapeError(`검색 실패: ${error.message}`, 'NAVIGATION_ERROR', error);
         }
     }
-    /**
-     * 검색 URL 생성
-     */
-    buildSearchUrl(options) {
-        const params = new URLSearchParams();
-        params.set('order', options.order);
-        params.set('page', options.page.toString());
-        if (options.levels.length > 0) {
-            params.set('levels', options.levels.join(','));
-        }
-        if (options.query) {
-            params.set('query', options.query);
-        }
-        return `${this.baseUrl}/learn/challenges?${params.toString()}`;
-    }
     /**
      * 문제 상세 페이지 HTML 가져오기 (fetch 기반, BOJScraper 패턴)
      *
@@ -283,7 +252,7 @@ export class ProgrammersScraper {
         // 캐시 확인
         const cached = this.problemCache.get(problemId);
         if (cached !== undefined) {
-            console.log(`[ProgrammersScraper] 캐시 히트: 문제 ${problemId}`);
+            process.stderr.write(`[ProgrammersScraper] 캐시 히트: 문제 ${problemId}\n`);
             return cached;
         }
         // 1. HTML 가져오기 (캐시 미스 시에만)