github-portfolio-mcp

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

📋 개요

우아한형제들 기술 블로그의 MCP 해커톤 후기를 참고해 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를 호출해서 답합니다.