내 코드베이스를 MCP로 검색 가능하게 만들어보자

내 코드베이스를 MCP로 검색 가능하게 만들어보자

개인 검색 인프라 프로젝트를 만들어도 LLM 에이전트가 직접 쓸 방법이 없으면 매번 내가 검색해서 결과를 복사해 붙여줘야 한다. MCP 도구 3개를 노출해서 에이전트가 스스로 검색하게 만들었다.

1. 서론 (Introduction)

• 문제/상황 (Problem): 검색이 잘 되는 시스템을 만들어도, 결과를 컨텍스트에 넣는 건 여전히 사람 몫이었다. 질문 → 검색 → 복붙 → 질문의 반복이 매 세션마다 발생했다.
• 목적 (Purpose): LLM 에이전트가 직접 호출할 수 있는 MCP 도구로 검색 기능을 노출한다.
• 대상 (Target Audience): 개인 검색·지식 인프라를 에이전트가 쓰게 만들고 싶은 개발자.

2. 방법 및 과정 (Methods & Process)

• 배경 조사 및 데이터 (Data Collection): 이 검색 시스템은 원래 문서 저장소·코드 저장소·이슈트래커처럼 성격이 다른 DB 여러 개로 나뉘어 있었다. 도구를 DB 개수만큼 만들면 에이전트가 어떤 도구를 언제 써야 하는지부터 헷갈린다.

  노출 방식	에이전트 입장	문제
  DB별 개별 도구	DB 개수만큼 도구 이름 암기 필요	도구 선택 자체가 부담
  통합 도구 3개	search/advanced_search/get_related만 알면 됨	DB 추가 시 도구는 안 늘어남

• 접근 방법 (Approach Methods):
  • [방법 1]: 도구 세 개를 한 번에 설계하지 않았다. 처음엔 전체 소스를 다 훑는 search 하나로 시작했는데, 메타데이터 필드별로 세밀하게 걸러 찾고 싶은 요구가 생기면서 advanced_search를 별도 도구로 분리했고, 특정 문서와 연관된 문서를 찾는 get_related까지 더해져 지금의 3종 구성이 됐다. 실제로 아쉬운 지점이 생길 때마다 도구를 하나씩 얹은 셈이다.
  • [방법 2]: 여러 DB를 동시에 쓰는 federation 상황은 MultiRepository 같은 클래스로 통합해 도구 뒤에 감춘다. 도구 함수는 MultiRepository.search() 하나만 호출하고, DB가 몇 개든 몇 종류든 늘어나도 도구 시그니처는 그대로다.
• 분석 및 해결 프로세스 (Analysis Flow):
  • 도구/기술: FastMCP, Python dataclass, (fastmcp 미설치 환경 대비) 딕셔너리 기반 폴백 레지스트리.
  • 주요 단계: DB별 Repository 구현 $\rightarrow$ MultiRepository로 federation $\rightarrow$ FastMCP @app.tool()로 3개 함수 등록 $\rightarrow$ 에이전트가 MCP 프로토콜로 도구 호출.
  • 결과 도출 및 검증: 문서·코드·이슈 3종 저장소를 등록하고 search("검색")을 호출했다. 세 저장소 각각에서 매칭된 문서가 source 태그와 함께 한 번에 반환됐다. fastmcp가 없는 환경에서도 같은 등록 패턴을 흉내낸 폴백 레지스트리로 동일한 호출이 그대로 동작했다.

3. 결과 (Results)

• 분석 결과 요약: 도구 개수는 DB 개수와 무관하게 3개로 고정됐다. 실제로 이 접근에서 수치로 남길 만한 벤치마크는 없다 — 솔직히 이 작업은 성능 최적화가 아니라 구조 설계가 핵심이었다. “몇 밀리초 빨라졌다”보다 “에이전트가 도구 3개만 알면 된다”는 인터페이스 단순화가 실제로 얻은 것이다.

4. 인사이트 및 액션 (Insights & Action)

• 인사이트 (Insight): 검색 시스템을 잘 만드는 것과, 그걸 에이전트가 실제로 쓸 수 있게 만드는 것은 별개의 작업이다. federation 뒤에 통합 클래스를 하나 두면 도구 인터페이스는 DB 증감과 완전히 분리된다.
• 실행 방안 (Action Plan): 새 DB를 추가할 때는 도구를 늘리는 대신 Repository 구현체 하나를 MultiRepository에 등록하는 방식을 기본으로 삼는다. 도구 시그니처는 되도록 건드리지 않는다.
• 한 줄 결론 (Key Takeaway): 검색 인프라를 MCP 도구 3개 뒤에 감추면 DB가 늘어도 에이전트가 배워야 할 인터페이스는 늘지 않는다. 샘플 코드
• 다음 스텝 (Next Step): 지금은 도구 3개가 모든 DB를 동일한 방식으로 다룬다. DB마다 검색 품질 특성이 다르면(예: 코드 저장소는 정확 매칭이 유리하고 문서 저장소는 의미 검색이 유리한 경우) 도구 레벨에서 이 차이를 흡수할지, MultiRepository 내부에서 흡수할지는 아직 정리되지 않았다.