# github-portfolio-mcp

GitHub 포트폴리오 레포를 검색하고 조회하는 토이 MCP 서버입니다.

## 📋 개요

[우아한형제들 기술 블로그의 MCP 해커톤 후기](https://techblog.woowahan.com/22342/)를 참고해 MCP의 개념 및 구조를 학습하고,  
이를 참고하여 GitHub API를 연동한 MCP 서버를 구현하고 Claude Desktop에 연결해본 토이 프로젝트입니다.

## 🛠️ 기능

Claude Desktop에 연결하면 자연어로 GitHub 포트폴리오를 조회할 수 있습니다.

- **list_repos** — 전체 공개 레포 목록과 설명을 가져온다
- **search_repos** — 키워드로 레포 이름/설명을 검색한다
- **get_readme** — 특정 레포의 README 내용을 가져온다 (최대 3000자)

## 💡 배운 점

- **MCP SDK v1 → v2 마이그레이션**: 개발 중 SDK가 v2로 업데이트되면서 `FastMCP` 클래스가 `MCPServer`로 이름이 바뀜 (`mcp.server.fastmcp` → `mcp.server.mcpserver`). 공식 마이그레이션 가이드를 참고해 import 경로만 수정해서 해결. 데코레이터(`@mcp.tool()`)나 나머지 로직은 그대로 유지됨.
- **tool의 description이 곧 사용성**: LLM은 함수의 docstring만 보고 언제/어떻게 호출할지 스스로 판단하기 때문에, 이 설명을 얼마나 명확히 쓰느냐가 tool의 실사용성을 좌우한다.
- **시스템 Python 격리**: macOS 기본 Python(3.9.6)을 건드리지 않고 `uv`로 프로젝트별 Python 버전(3.12)을 관리하는 방식으로 진행.

## ⚠️ 한계

- `search_repos`는 이름/설명에 대한 단순 부분 문자열 매칭이라, README 본문 검색이나 유사어 검색은 불가능합니다 (예: "RAG"로 검색해도 이름에 "RAG"가 없으면 못 찾음).
- `get_readme`는 3000자 이후 내용이 잘립니다.
- GitHub 공개 레포만 조회 가능합니다. (private 레포 미지원).

## 🖥️ 실행 예시

Claude Desktop에서 자연어로 질문하면 실제 GitHub API를 호출해서 답합니다.

![search_repos와 get_readme 실행 예시](./example.png)