Claude Code를 위한 TypeScript 구조 인덱싱 MCP 서버 개발 사례

커뮤니티 반응

작성자가 공개한 오픈소스 도구에 대해 긍정적인 반응이며, 특히 토큰 절감 수치에 대해 높은 관심을 보이고 있다.

주요 논점

01찬성다수

구조적 인덱싱은 AI 에이전트의 지능 한계를 보완하고 실질적인 비용 절감을 가능하게 하는 필수적인 도구이다.

합의점 vs 논쟁점

합의점

AI 에이전트가 대규모 코드베이스를 다룰 때 구조적 인식(Structural Awareness)이 부족하면 성능이 급격히 떨어진다.
MCP(Model Context Protocol)는 에이전트의 기능을 확장하고 최적화하는 데 유용한 프레임워크이다.

논쟁점

동적 타이핑이나 복잡한 의존성 주입 패턴이 있는 프로젝트에서 정적 인덱싱의 정확도 유지 문제

실용적 조언

TypeScript 프로젝트에서 Claude Code를 사용할 때 토큰 비용이 부담된다면 MCP 서버를 통한 인덱싱 도입을 고려하라.
에이전트에게 파일 전체를 읽게 하기보다 필요한 특정 라인 범위만 제공하도록 프롬프트나 도구를 설계하라.

섹션별 상세

AI 에이전트의 코드 탐색 비효율 문제를 해결하기 위해 SQLite 기반의 구조적 인덱싱을 도입했다. 에이전트가 단순 grep 검색 대신 SQLite 인덱스를 통해 심볼, 호출 지점, 임포트, 클래스 계층 구조를 직접 쿼리하도록 구현했다. 이를 통해 에이전트가 매 세션마다 처음부터 코드를 읽어야 하는 부담을 줄이고 정확한 파일 위치로 즉시 이동이 가능하다.

31개 파일 규모의 프로젝트에서 수행한 벤치마크 결과 토큰 사용량이 획기적으로 감소했다. 함수 찾기 작업에서 기존 grep 방식은 1350토큰을 소모했으나 인덱스 방식은 500토큰으로 63% 절감됐다. 15개 이상의 파일에 걸친 상속 구조 맵핑 작업에서는 4800토큰에서 1000토큰으로 줄어들어 최대 79%의 절감율을 기록했다.

토큰 절감의 핵심 요인은 심볼 조회보다 호출 그래프(Call Graph) 쿼리와 부분 읽기(Partial Reads) 기능에 있다. get_callers 기능을 통해 에이전트가 함수 호출자를 찾기 위해 여러 파일을 뒤지는 과정을 생략했다. 또한 정확한 라인 번호를 파악하여 파일 전체가 아닌 필요한 20줄 내외만 읽도록 처리한 것이 전체 절감액의 절반 이상을 차지했다.

미들웨어 추적 기능을 통해 라우트 핸들러 이전에 실행되는 로직을 에이전트가 즉시 파악하도록 지원한다. 기존에는 에이전트가 라우터 파일을 읽고 각 미들웨어 파일을 순차적으로 확인하며 실행 순서를 재구성해야 했으나 trace_middleware 기능으로 이 과정을 단축했다. 다만 동적 메서드 이름이나 의존성 주입 패턴이 복잡한 경우 인덱싱에 한계가 존재한다.

용어 해설

모델 컨텍스트 프로토콜(MCP): — AI 에이전트가 데이터 소스나 도구에 연결할 수 있도록 Anthropic에서 공개한 개방형 표준이다. 에이전트가 코드베이스, 데이터베이스, API 등 외부 환경과 구조적으로 상호작용하게 하여 정보 접근성을 높인다.
호출 그래프(Call Graph): — 프로그램 내에서 함수나 서브루틴 간의 호출 관계를 나타내는 제어 흐름 그래프이다. 어떤 함수가 어떤 함수를 호출하는지 시각화하거나 분석하여 코드의 실행 경로를 파악하는 데 사용된다.
토큰 최적화(Token Optimization): — LLM 입력에 사용되는 텍스트 단위를 줄여 비용을 절감하고 컨텍스트 윈도우 효율을 높이는 기법이다. 필요한 정보만 선별하여 전달함으로써 모델의 추론 속도를 높이고 불필요한 비용 발생을 억제한다.
구조적 인식(Structural Awareness): — 단순한 텍스트 검색을 넘어 코드의 심볼, 클래스 계층, 임포트 관계 등 프로그래밍 언어적 구조를 이해하는 능력이다. AI 에이전트가 코드베이스의 전체적인 맥락을 더 정확하게 파악하도록 돕는다.

언급된 도구

Claude Code추천

Anthropic의 공식 AI 코딩 에이전트

Cursor중립

AI 기반 코드 에디터

MCP추천

모델 컨텍스트 프로토콜 (에이전트 연결 표준)

SQLite중립

코드베이스 구조 인덱스 저장용 데이터베이스