TypeScript 프로젝트용 MCP 서버, Claude Code의 Grep 패턴을 인덱싱된 심볼 조회로 대체

한 개발자가 Claude Code의 TypeScript 프로젝트 성능을 향상시키기 위해 grep-and-guess 패턴을 인덱싱된 심볼 조회로 대체하는 MCP 서버를 만들었습니다. 이 도구는 무료 오픈 소스입니다.

현재 에이전트 동작의 문제점

TypeScript 프로젝트에서 Claude Code와 Cursor를 사용할 때 흔히 발생하는 패턴은: 에이전트가 파일을 검색하고, 가능성이 높은 일치 항목을 열고, 상당량의 코드를 읽고, 잘못된 위치임을 깨닫고, 다시 시도하는 것입니다. 에이전트는 코드베이스의 구조적 인식이 부족하며 각 세션을 처음부터 시작합니다.

MCP 서버 작동 방식

이 서버는 프로젝트의 실시간 SQLite 인덱스를 유지하여 코드베이스에 대한 구조적 접근을 제공합니다. 인덱스에는 다음이 포함됩니다:

• 심볼
• 호출 위치
• 임포트
• 클래스 계층 구조

이를 통해 에이전트가 구조를 직접 쿼리할 수 있습니다. "handleRequest"를 검색하는 대신, 에이전트는 해당 심볼의 정확한 파일과 줄로 바로 이동할 수 있습니다.

성능 벤치마크

31개 파일로 구성된 TypeScript 프로젝트에서 동일한 작업을 인덱스 사용 여부에 따라 수행한 테스트 결과:

• 함수 하나 찾기: grep 사용 시 1,350 토큰 vs 인덱스 사용 시 500 토큰 (63% 감소)
• 3개 파일에 걸친 호출자 추적: grep 사용 시 2,850 토큰 vs 인덱스 사용 시 900 토큰 (68% 감소)
• 15개 이상 파일에 걸친 상속 관계 매핑: grep 사용 시 4,800 토큰 vs 인덱스 사용 시 1,000 토큰 (79% 감소)

grep 성능은 코드베이스가 커질수록 저하되는 반면, 인덱스 쿼리는 일관성을 유지합니다.

절감 효과의 원천

개발자는 처음에 심볼 조회가 주요 이점일 것이라고 생각했지만, 인덱스가 상당한 효율성 향상을 제공하는 세 가지 핵심 영역을 발견했습니다:

• get_callers 쿼리는 에이전트가 함수를 호출하는 주체를 파악하기 위해 4-5개 파일을 읽는 패턴을 대체합니다
• 부분 읽기: 정확한 줄을 알면 전체 파일 대신 20줄만 읽으면 됩니다 (절감 효과의 절반 이상을 차지)
• trace_middleware는 에이전트에게 라우트 핸들러 실행 전에 무엇이 실행되는지 알려주어, 라우터, 각 미들웨어 파일을 읽고 순서를 재구성할 필요를 없앱니다

제한 사항

이 도구는 다음에서 어려움을 겪습니다:

• 동적 패턴 (계산된 메서드 이름 등)
• 의존성 주입 설정
• 자체 코드베이스 외부의 모든 것

완벽하지는 않지만, 이 도구는 에이전트 지원 개발에서 시행착오 루프를 상당히 줄여줍니다.