algokit-mcp 1.0.0

package/README.md

@@ -0,0 +1,137 @@
+# AlgoKit-mcp
+
+**백준(BOJ)과 프로그래머스 알고리즘 문제 학습을 돕는 MCP 서버 + Skill**
+
+AI 기반 힌트 생성, 문제 분석, 복습 템플릿 제공으로 효율적인 알고리즘 학습을 지원합니다.
+
+## 주요 기능
+
+- 🔍 **문제 검색**: 난이도, 태그, 키워드로 문제 검색
+- 💡 **단계별 힌트**: Level 1~3 단계별 맞춤 힌트 생성
+- 📊 **문제 분석**: 알고리즘 분류, 난이도 분석, 학습 가이드
+- 📝 **복습 템플릿**: 자동 생성되는 마크다운 복습 문서
+- 🧪 **코드 분석**: 제출 코드의 시간/공간 복잡도 분석 및 개선 제안
+
+## 설치
+
+### Claude Code (추천)
+
+```json
+{
+  "mcpServers": {
+    "algokit": {
+      "command": "npx",
+      "args": ["-y", "algokit-mcp"]
+    }
+  }
+}
+```
+
+## MCP 도구
+
+### 백준 (BOJ)
+
+| 도구 | 설명 |
+|------|------|
+| `search_problems` | 문제 검색 (티어, 태그, 키워드) |
+| `get_problem` | 문제 상세 조회 |
+| `search_tags` | 알고리즘 태그 검색 |
+| `fetch_problem_content_boj` | 문제 본문 스크래핑 |
+| `analyze_problem_boj` | 문제 분석 및 힌트 가이드 |
+| `generate_hint_boj` | 3단계 힌트 생성 |
+| `generate_review_template_boj` | 복습 템플릿 생성 |
+| `analyze_code_submission_boj` | 코드 분석 및 피드백 |
+
+### 프로그래머스 (Programmers)
+
+| 도구 | 설명 |
+|------|------|
+| `search_programmers_problems` | 문제 검색 (난이도, 카테고리) |
+| `get_programmers_problem` | 문제 상세 조회 |
+| `fetch_problem_content_programmers` | 문제 본문 스크래핑 |
+| `analyze_problem_programmers` | 문제 분석 |
+| `generate_hint_programmers` | 힌트 생성 |
+| `generate_review_template_programmers` | 복습 템플릿 |
+| `analyze_code_submission_programmers` | 코드 분석 |
+
+## MCP Skill (Claude Code 전용)
+
+**Skill 이름**: `algo:`
+
+플랫폼(BOJ/프로그래머스)을 자동으로 선택하여 자연스러운 학습 경험을 제공합니다.
+
+### 설치 방법
+
+```bash
+# Skill 파일 복사 (프로젝트별)
+cp .claude/skills/algokit.md /your/project/.claude/skills/
+
+# 또는 전역 설정
+cp .claude/skills/algokit.md ~/.claude/skills/
+```
+
+### 사용 예시
+
+```
+You: "백준 골드 난이도 DP 문제 3개 추천해줘"
+Claude: [자동으로 BOJ search_problems 호출]
+
+You: "이 문제 분석해줘: https://www.acmicpc.net/problem/1927"
+Claude: [URL 파싱 → analyze_problem_boj 자동 호출]
+
+You: "프로그래머스 Level 2 문제 찾아줘"
+Claude: [search_programmers_problems 자동 호출]
+
+You: "힌트 더 줘"
+Claude: [이전 대화 분석 → 적절한 Level 힌트 제공]
+```
+
+## 개발
+
+### 빌드 및 테스트
+
+```bash
+# 의존성 설치
+npm install
+
+# 빌드
+npm run build
+
+# 테스트
+npm test
+
+# 개발 모드
+npm run dev
+```
+
+### 프로젝트 구조
+
+```
+src/
+├── api/           # solved.ac API, BOJ/프로그래머스 scrapping
+├── tools/         # MCP 도구 (15개)
+├── services/      # 비즈니스 로직
+├── prompts/       # 힌트 가이드 프롬프트
+└── utils/         # 유틸리티 (캐싱, Rate Limiting)
+```
+
+## 기술 스택
+
+- **Runtime**: Node.js (>=18.0.0)
+- **Language**: TypeScript 5.9
+- **MCP SDK**: @modelcontextprotocol/sdk v1.26.0
+- **Validation**: Zod
+- **Testing**: Vitest
+
+## 라이선스
+
+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)**
+
+
+</div>

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

@@ -0,0 +1,68 @@
+/**
+ * BOJ 문제 페이지 스크래퍼
+ *
+ * Phase 6 - P6-002: 문제 본문 스크래퍼 구현
+ *
+ * fetch를 사용하여 BOJ 페이지 HTML을 가져옵니다.
+ * 윤리적 스크래핑을 위해 요청 간 최소 3초 간격을 유지합니다.
+ */
+/**
+ * BOJ 스크래핑 에러
+ */
+export declare class BojFetchError extends Error {
+    code: 'NOT_FOUND' | 'NETWORK_ERROR' | 'TIMEOUT' | 'PARSE_ERROR';
+    originalError?: unknown | undefined;
+    constructor(message: string, code: 'NOT_FOUND' | 'NETWORK_ERROR' | 'TIMEOUT' | 'PARSE_ERROR', originalError?: unknown | undefined);
+}
+/**
+ * BOJ 문제 페이지 스크래퍼
+ */
+export declare class BOJScraper {
+    /** 마지막 요청 시간 (윤리적 스크래핑을 위한 간격 제어) */
+    private lastRequestTime;
+    /** Rate Limiter (백업 보호) */
+    private rateLimiter;
+    /** HTML 캐시 (30일 TTL) */
+    private cache;
+    constructor();
+    /**
+     * 지정된 문제 번호의 HTML 페이지를 가져옵니다.
+     *
+     * 윤리적 스크래핑을 위해 요청 간 최소 3초 간격을 유지합니다.
+     *
+     * @param problemId - BOJ 문제 번호 (예: 1000)
+     * @returns HTML 문자열
+     * @throws {BojFetchError} 스크래핑 실패 시
+     *
+     * @example
+     * ```typescript
+     * const scraper = new BOJScraper();
+     * const html = await scraper.fetchProblemPage(1000);
+     * console.log(html.length); // HTML 길이 출력
+     * ```
+     */
+    fetchProblemPage(problemId: number): Promise<string>;
+    /**
+     * 타임아웃 적용된 HTTP 요청
+     */
+    private _fetchWithTimeout;
+    /**
+     * 윤리적 스크래핑: 마지막 요청으로부터 최소 간격 보장
+     */
+    private _ensureRequestInterval;
+    /**
+     * 지연 함수 (재시도 간격 및 윤리적 스크래핑 간격)
+     */
+    private _delay;
+    /**
+     * 캐시 통계 조회
+     *
+     * @returns 캐시 통계
+     */
+    getCacheStats(): import("../utils/lru-cache.js").CacheStats;
+    /**
+     * 캐시 초기화
+     */
+    clearCache(): void;
+}
+//# sourceMappingURL=boj-scraper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"boj-scraper.d.ts","sourceRoot":"","sources":["../../src/api/boj-scraper.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAqBH;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;IAG7B,IAAI,EAAE,WAAW,GAAG,eAAe,GAAG,SAAS,GAAG,aAAa;IAC/D,aAAa,CAAC,EAAE,OAAO;gBAF9B,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,WAAW,GAAG,eAAe,GAAG,SAAS,GAAG,aAAa,EAC/D,aAAa,CAAC,EAAE,OAAO,YAAA;CAKjC;AAED;;GAEG;AACH,qBAAa,UAAU;IACrB,qCAAqC;IACrC,OAAO,CAAC,eAAe,CAAK;IAE5B,2BAA2B;IAC3B,OAAO,CAAC,WAAW,CAAc;IAEjC,wBAAwB;IACxB,OAAO,CAAC,KAAK,CAA2B;;IAcxC;;;;;;;;;;;;;;;OAeG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA4D1D;;OAEG;YACW,iBAAiB;IAqE/B;;OAEG;YACW,sBAAsB;IAcpC;;OAEG;IACH,OAAO,CAAC,MAAM;IAId;;;;OAIG;IACH,aAAa;IAIb;;OAEG;IACH,UAAU,IAAI,IAAI;CAGnB"}

package/dist/api/boj-scraper.js

@@ -0,0 +1,197 @@
+/**
+ * BOJ 문제 페이지 스크래퍼
+ *
+ * Phase 6 - P6-002: 문제 본문 스크래퍼 구현
+ *
+ * fetch를 사용하여 BOJ 페이지 HTML을 가져옵니다.
+ * 윤리적 스크래핑을 위해 요청 간 최소 3초 간격을 유지합니다.
+ */
+import { RateLimiter } from '../utils/rate-limiter.js';
+import { LRUCache } from '../utils/lru-cache.js';
+/**
+ * BOJ 스크래퍼 설정
+ */
+const BOJ_CONFIG = {
+    /** BOJ 문제 페이지 URL 템플릿 */
+    BASE_URL: 'https://www.acmicpc.net/problem',
+    /** User-Agent (Chrome 브라우저 형식 - BOJ 요구사항) */
+    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',
+    /** 타임아웃 (밀리초) */
+    TIMEOUT: 10000,
+    /** 재시도 횟수 */
+    MAX_RETRIES: 2,
+    /** 윤리적 스크래핑: 요청 간 최소 간격 (밀리초) */
+    REQUEST_INTERVAL: 3000,
+};
+/**
+ * BOJ 스크래핑 에러
+ */
+export class BojFetchError extends Error {
+    code;
+    originalError;
+    constructor(message, code, originalError) {
+        super(message);
+        this.code = code;
+        this.originalError = originalError;
+        this.name = 'BojFetchError';
+    }
+}
+/**
+ * BOJ 문제 페이지 스크래퍼
+ */
+export class BOJScraper {
+    /** 마지막 요청 시간 (윤리적 스크래핑을 위한 간격 제어) */
+    lastRequestTime = 0;
+    /** Rate Limiter (백업 보호) */
+    rateLimiter;
+    /** HTML 캐시 (30일 TTL) */
+    cache;
+    constructor() {
+        // Rate Limiter: 초당 5회 (3초 간격보다 관대, 백업 역할)
+        this.rateLimiter = new RateLimiter({
+            capacity: 5,
+            refillRate: 5,
+            maxWaitTime: 15000,
+        });
+        // HTML 캐시: 50개 항목, 30일 TTL
+        this.cache = new LRUCache(50, 30 * 24 * 60 * 60 * 1000);
+    }
+    /**
+     * 지정된 문제 번호의 HTML 페이지를 가져옵니다.
+     *
+     * 윤리적 스크래핑을 위해 요청 간 최소 3초 간격을 유지합니다.
+     *
+     * @param problemId - BOJ 문제 번호 (예: 1000)
+     * @returns HTML 문자열
+     * @throws {BojFetchError} 스크래핑 실패 시
+     *
+     * @example
+     * ```typescript
+     * const scraper = new BOJScraper();
+     * const html = await scraper.fetchProblemPage(1000);
+     * console.log(html.length); // HTML 길이 출력
+     * ```
+     */
+    async fetchProblemPage(problemId) {
+        if (!Number.isInteger(problemId) || problemId <= 0) {
+            throw new BojFetchError(`유효하지 않은 문제 번호: ${problemId}`, 'PARSE_ERROR');
+        }
+        // 캐시 확인
+        const cached = this.cache.get(problemId);
+        if (cached !== undefined) {
+            console.log(`[BOJScraper] 캐시 히트: 문제 ${problemId}`);
+            return cached;
+        }
+        // Rate Limiting (백업 보호, 캐시 미스 시에만)
+        await this.rateLimiter.acquire();
+        // 윤리적 스크래핑: 마지막 요청으로부터 최소 3초 경과 보장
+        await this._ensureRequestInterval();
+        const url = `${BOJ_CONFIG.BASE_URL}/${problemId}`;
+        let lastError;
+        // 재시도 로직
+        for (let attempt = 0; attempt <= BOJ_CONFIG.MAX_RETRIES; attempt++) {
+            try {
+                const html = await this._fetchWithTimeout(url);
+                // 요청 성공 시 현재 시간 기록
+                this.lastRequestTime = Date.now();
+                // 캐시에 저장
+                this.cache.set(problemId, html);
+                return html;
+            }
+            catch (error) {
+                lastError = error;
+                // 404는 재시도 불필요
+                if (error instanceof BojFetchError && error.code === 'NOT_FOUND') {
+                    throw error;
+                }
+                // 마지막 시도가 아니면 재시도
+                if (attempt < BOJ_CONFIG.MAX_RETRIES) {
+                    await this._delay(BOJ_CONFIG.REQUEST_INTERVAL); // 윤리적 스크래핑: 재시도도 3초 간격
+                    continue;
+                }
+            }
+        }
+        // 모든 재시도 실패
+        throw new BojFetchError(`문제 ${problemId}번을 ${BOJ_CONFIG.MAX_RETRIES + 1}번 시도했으나 실패했습니다.`, 'NETWORK_ERROR', lastError);
+    }
+    /**
+     * 타임아웃 적용된 HTTP 요청
+     */
+    async _fetchWithTimeout(url) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), BOJ_CONFIG.TIMEOUT);
+        try {
+            const response = await fetch(url, {
+                signal: controller.signal,
+                headers: {
+                    'User-Agent': BOJ_CONFIG.USER_AGENT,
+                    'Accept': 'text/html',
+                    'Accept-Language': 'ko-KR,ko;q=0.9,en-US;q=0.8,en;q=0.7',
+                },
+            });
+            clearTimeout(timeoutId);
+            // 404 처리
+            if (response.status === 404) {
+                throw new BojFetchError(`문제를 찾을 수 없습니다: ${url}`, 'NOT_FOUND');
+            }
+            // 기타 HTTP 에러
+            if (!response.ok) {
+                throw new BojFetchError(`HTTP 에러 ${response.status}: ${response.statusText}`, 'NETWORK_ERROR');
+            }
+            const html = await response.text();
+            // HTML 검증
+            if (!html || html.length < 100) {
+                throw new BojFetchError('빈 HTML 응답을 받았습니다.', 'PARSE_ERROR');
+            }
+            return html;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            // 이미 BojFetchError면 그대로 throw
+            if (error instanceof BojFetchError) {
+                throw error;
+            }
+            // AbortError는 타임아웃
+            if (error.name === 'AbortError') {
+                throw new BojFetchError(`요청이 타임아웃되었습니다 (${BOJ_CONFIG.TIMEOUT}ms 초과)`, 'TIMEOUT', error);
+            }
+            // 기타 네트워크 에러
+            throw new BojFetchError(`네트워크 요청 실패: ${error.message}`, 'NETWORK_ERROR', error);
+        }
+    }
+    /**
+     * 윤리적 스크래핑: 마지막 요청으로부터 최소 간격 보장
+     */
+    async _ensureRequestInterval() {
+        if (this.lastRequestTime === 0) {
+            // 첫 요청은 즉시 실행
+            return;
+        }
+        const elapsed = Date.now() - this.lastRequestTime;
+        const remaining = BOJ_CONFIG.REQUEST_INTERVAL - elapsed;
+        if (remaining > 0) {
+            await this._delay(remaining);
+        }
+    }
+    /**
+     * 지연 함수 (재시도 간격 및 윤리적 스크래핑 간격)
+     */
+    _delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * 캐시 통계 조회
+     *
+     * @returns 캐시 통계
+     */
+    getCacheStats() {
+        return this.cache.getStats();
+    }
+    /**
+     * 캐시 초기화
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+}
+//# sourceMappingURL=boj-scraper.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,70 @@
+import { ProgrammersSearchOptions, ProgrammersProblemSummary, ProgrammersProblemDetail } from '../types/programmers.js';
+/**
+ * 프로그래머스 스크래핑 에러
+ */
+export declare class ProgrammersScrapeError extends Error {
+    code: 'TIMEOUT' | 'SELECTOR_NOT_FOUND' | 'NAVIGATION_ERROR' | 'PARSE_ERROR';
+    originalError?: unknown | undefined;
+    constructor(message: string, code: 'TIMEOUT' | 'SELECTOR_NOT_FOUND' | 'NAVIGATION_ERROR' | 'PARSE_ERROR', originalError?: unknown | undefined);
+}
+/**
+ * 프로그래머스 스크래퍼
+ */
+export declare class ProgrammersScraper {
+    private browserPool;
+    private rateLimiter;
+    private searchCache;
+    private problemCache;
+    private readonly baseUrl;
+    constructor();
+    /**
+     * 프로그래머스 문제 검색
+     *
+     * @param options 검색 옵션
+     * @returns 문제 목록
+     * @throws {ProgrammersScrapeError}
+     */
+    searchProblems(options?: ProgrammersSearchOptions): Promise<ProgrammersProblemSummary[]>;
+    /**
+     * 검색 URL 생성
+     */
+    private buildSearchUrl;
+    /**
+     * 문제 상세 페이지 HTML 가져오기 (fetch 기반, BOJScraper 패턴)
+     *
+     * @param problemId 문제 ID
+     * @returns HTML 문자열
+     * @throws {ProgrammersScrapeError}
+     */
+    fetchProblemPage(problemId: string): Promise<string>;
+    /**
+     * 타임아웃 적용된 HTTP 요청 (fetch 기반, BOJScraper 패턴)
+     */
+    private _fetchWithTimeout;
+    /**
+     * 지연 함수 (재시도 간격)
+     */
+    private _delay;
+    /**
+     * 캐시 통계 조회
+     *
+     * @returns 검색 및 문제 캐시 통계
+     */
+    getCacheStats(): {
+        search: import("../utils/lru-cache.js").CacheStats;
+        problem: import("../utils/lru-cache.js").CacheStats;
+    };
+    /**
+     * 캐시 초기화
+     */
+    clearCache(): void;
+    /**
+     * 문제 상세 정보 조회 (fetch + cheerio 기반)
+     *
+     * @param problemId 문제 ID
+     * @returns 문제 상세 정보
+     * @throws {ProgrammersScrapeError}
+     */
+    getProblem(problemId: string): Promise<ProgrammersProblemDetail>;
+}
+//# sourceMappingURL=programmers-scraper.d.ts.map

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

@@ -0,0 +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"}