jCodeMunch로 Claude Code와 Codex CLI 토큰 절약하기

큰 저장소를 에이전트에게 맡기면 초반부터 토큰을 많이 먹습니다. 파일을 통째로 열어 관계없는 import와 테스트 코드까지 읽다 보면, 정작 고쳐야 할 함수는 한참 뒤에야 찾게 됩니다. jCodeMunch MCP는 이 부분을 심볼 검색으로 줄여주는 도구입니다.

1. 쓰는 이유

jCodeMunch는 저장소를 한 번 인덱싱해두면 함수, 클래스, 메서드, 파일 outline을 MCP 도구로 바로 꺼내 씁니다. README는 tree-sitter AST 기반 심볼 검색, byte offset 기반 구현 조회, token-budgeted context 조립을 핵심으로 꼽습니다. 공식 벤치마크 표에는 2026-07-23 실행 기준 15개 task-run에서 평균 99.6% token reduction이 적혀 있습니다.

이 숫자를 모든 작업의 비용 절감으로 읽으면 곤란합니다. 효과가 큰 곳은 코드 탐색이고, 이미 파일 하나를 끝까지 읽어야 하는 리팩터링이라면 이득이 크지 않습니다. 제 기준으로는 대형 repo 리뷰, 낯선 모듈 파악, Claude Code·Codex CLI에서 파일을 반복해서 읽어야 하는 작업부터 붙여보겠습니다.

2. 설치와 MCP 연결

README의 빠른 설치 경로는 PyPI 패키지와 uvx입니다. 최신 GitHub release는 v1.108.168이고, 패키지 버전도 1.108.168입니다. 라이선스는 GitHub API 기준 Other로 표시되며, README에는 개인 사용은 무료지만 상업 사용은 유료 라이선스 조건이 따로 있다고 적혀 있습니다.

pip install jcodemunch-mcp
uvx jcodemunch-mcp

Claude Code에는 아래처럼 user scope로 추가하면 됩니다. 다른 프로젝트에서도 같은 서버를 쓸 거라면 -s user가 안전합니다.

claude mcp add -s user jcodemunch uvx jcodemunch-mcp

Codex CLI는 ~/.codex/config.toml에 MCP 서버를 등록합니다.

[mcp_servers.jcodemunch]
command = "uvx"
args = ["jcodemunch-mcp"]

3. 실제로 쓰게 만드는 설정

설치만 해둔다고 에이전트가 파일부터 읽는 습관을 버리지는 않습니다. README와 USER_GUIDE 모두 agent policy를 같이 넣으라고 권합니다. 사실 이게 핵심입니다.

Use jcodemunch-mcp for code lookup whenever available. Prefer symbol search, outlines, and targeted retrieval over reading full files.

비슷한 맥락의 에이전트 설정은 Hermes Mobile GitHub 설치 흐름에서처럼, 클라이언트별로 설정 위치부터 확인해야 덜 꼬입니다.

4. 사용 흐름

처음 보는 repo라면 파일부터 열지 말고 outline부터 봅니다.

index_repo: { "url": "fastapi/fastapi" }
get_repo_outline: { "repo": "fastapi/fastapi" }
get_file_tree: { "repo": "fastapi/fastapi", "path_prefix": "fastapi" }

함수 이름을 어느 정도 알 때는 search_symbols로 찾은 다음 get_symbol_source로 구현부만 읽습니다.

search_symbols: { "repo": "owner/repo", "query": "authenticate", "kind": "function" }
get_symbol_source: { "repo": "owner/repo", "symbol_id": "src/auth.py::authenticate#function" }

로컬 프로젝트는 index_folder, 특정 파일 갱신은 index_file, 일반 문자열은 search_text, 변경 영향은 get_blast_radius로 확인하시면 됩니다. 설정 확인은 jcodemunch-mcp config, 전제 조건 검사는 jcodemunch-mcp config --check면 됩니다.

5. 적용 범위

맞을 때: Python·TypeScript·Go·Rust처럼 지원 언어가 섞인 큰 저장소를 다룰 때, 코드 리뷰 전에 훑어볼 때, 함수 단위로 손볼 때, context window를 오래 아껴야 하는 에이전트 작업일 때입니다.

맞지 않을 때: 작은 스크립트 한두 개, 전체 파일 맥락을 반드시 읽어야 하는 대규모 재배치, 회사 코드가 외부 요약 제공자로 나가면 안 되는 환경이라면 굳이 쓸 이유가 없습니다. 원격 AI summary는 설정에 따라 달라지니 allow_remote_summarizer와 API key 사용 범위부터 확인해보시기 바랍니다.

확인

uvx --from jcodemunch-mcp jcodemunch-mcp --version
jcodemunch-mcp config --check

첫 명령이 jcodemunch-mcp 1.108.168처럼 버전을 출력하고 config --check에서 storage·transport 조건이 통과하면 기본 설치는 끝난 겁니다. MCP 클라이언트에서는 /mcp나 해당 설정 화면에서 jcodemunch 연결 상태를 확인하면 됩니다.