github-repo-mcp: AI가 모든 GitHub 리포지토리를 수동으로 클론하지 않고 탐색할 수 있게 하다

어시스턴트가 로컬에 가지고 있지 않은 코드베이스를 이해해야 할 때, 일반적인 옵션은 파일을 붙여넣거나 수동으로 클론하는 것입니다. 저는 더 나은 것이 필요했습니다. 즉, 어시스턴트에게 owner/repo 주소를 지정하여 개발자가 하는 것처럼 탐색하게 만드는 것입니다. 그래서 저는 로컬 Model Context Protocol 서버인 github-repo-mcp를 작성했습니다.

아키텍처 (Architecture)

이 서버는 stdio 위에서 실행됩니다. 리포지토리는 한 번 클론되어 로컬 캐시에서 재사용됩니다.

REQUEST PATH
      Claude  (MCP client)
  ──▶ github-repo-mcp  (stdio server, written in TypeScript on Bun)
...

작동 방식 (How it works)

• load_repo: 리포지토리를 클론하거나 캐시된 사본을 재사용하고, 언어 목록, 파일 개수, 최상위 트리 구조, 그리고 README 발췌문을 반환합니다. 이 정보만으로 다음에 어디를 살펴볼지 결정할 수 있습니다.
• get_repo_map: 경로와 내보내진 심볼(exported symbols)의 구조적 맵을 구축합니다. TypeScript는 빠른 추출 경로를 얻고, Python과 같은 다른 언어는 tree-sitter로 파싱됩니다.
• grep은 속도를 위해 ripgrep을 사용하며, ripgrep이 설치되어 있지 않으면 순수 JS 검색으로 폴백(fallback)합니다.
• GitHub 토큰은 선택 사항이며 비공개 리포지토리에서만 필요합니다. 경로 가드(Path guards)는 읽기 작업을 클론된 리포지토리 내부에 머무르게 합니다.

이 워크플로우가 가능하게 하는 것 (The workflow it enables)

리포를 로드하고, 맵을 읽어 올바른 모듈을 찾고, 호출 사이트(call sites)에 대해 grep 검색을 수행한 다음, 필요한 라인만 읽습니다. 어시스턴트는 코드를 스크롤하는 데 컨텍스트를 소모하는 것이 아니라 코드 이해에 집중할 수 있습니다.

이는 의도적으로 작은 표면적(surface area)을 가진 작은 서버입니다: 다섯 가지 도구, 하나의 캐시 디렉토리, 그리고 가드와 파서 주변의 테스트로 구성되어 있습니다.

원래는 my portfolio에 게시되었습니다.