mcp-trial

Model Context Protocol을 배우면서 GitHub API용 서버를 구축해 본 프로젝트입니다. Python SDK v2를 사용하며, stdio를 통해 실행되고 Claude Code에 연결됩니다.

기능

두 가지 도구가 있습니다. 하나는 저장소 요약용이고, 다른 하나는 최근 커밋 메시지용입니다. 또한 저장소의 원본 README를 제공하는 리소스와, 저장소를 포트폴리오 작품으로 평가하기 위한 프롬프트 템플릿도 있습니다.

Related MCP server: MCP GitHub Reader

실행 방법

uv sync
uv run mcp dev server.py          # opens the inspector
uv run python test_server.py      # calls the server directly, no host needed

Claude Code에 등록하려면:

claude mcp add gh-lab -- uv run --directory /path/to/mcp-trial mcp run server.py

배운 점

타입 힌트가 곧 API 계약입니다. SDK가 함수 시그니처에서 직접 도구의 JSON 스키마를 만들기 때문입니다. limit: int = 5라고 작성하면 해당 매개변수는 선택 사항이 되어 모델이 생략할 수 있습니다.

Docstring은 생각보다 중요했습니다. 모델에게 도구 설명으로 전달되어 어떤 도구를 선택할지 결정하기 때문입니다. Claude Code에게 어떤 저장소가 활발히 유지 관리되는지 물어봤을 때, 두 도구를 모두 호출해서 스스로 판단했는데, 이는 설명 덕분에 두 도구가 조합 가능해 보였기 때문입니다.

도구가 반환하는 모든 것은 모델의 컨텍스트에 텍스트로 포함되므로, 각 필드는 토큰 비용이 듭니다. GitHub는 약 100개의 필드를 반환하지만 저는 5개만 반환합니다.

오류를 반환하는 것보다 발생시키는 것이 낫습니다. 발생시키면 호스트가 확인하는 플래그가 설정되고, 메시지가 모델에게 조치 가능한 형태로 전달되기 때문입니다.

비동기는 속도를 높이지 않습니다. 단일 호출은 어차피 같은 시간이 걸립니다. await가 하는 일은 함수를 일시 중지하고 이벤트 루프를 해제하여 대기하는 동안 다른 호출이 실행될 수 있게 하는 것입니다.

메모

mcp-reference.md에 이 프로젝트를 만들면서 정리한 작업 노트가 있습니다.