⚔ token-savior

AI에게 코드베이스 전체를 먹이지 마세요. 대신 메스를 쥐여주세요.

Python 3.11+ MCP

코드베이스를 구조적으로 인덱싱하고 정밀한 쿼리 도구를 제공하는 MCP 서버입니다. AI 에이전트가 200개의 파일을 읽는 대신 200자의 정보만 읽도록 합니다.

find_symbol("send_message")           →  67 chars    (was: 41M chars of source)
get_change_impact("LLMClient")        →  16K chars   (154 direct + 492 transitive deps)
get_function_source("compile")        →  4.5K chars  (exact source, no grep, no cat)
analyze_config()                      →  finds duplicates, secrets, orphan keys

782개의 실제 세션에서 측정된 결과: 99% 토큰 절감.

왜 필요한가요?

모든 AI 코딩 세션은 동일하게 시작됩니다. 에이전트는 cat이나 grep을 사용하여 수십 개의 파일을 읽어 함수 하나를 찾고, 무엇이 더 깨질지 파악하느라 컨텍스트를 낭비합니다. 결국 첫 번째 수정이 이루어지기도 전에 토큰 예산의 절반이 사라집니다.

token-savior는 이러한 패턴을 완전히 대체합니다. 구조적 인덱스를 한 번 구축하고 git과 자동으로 동기화하며, "X가 어디에 있는가", "무엇이 X를 호출하는가", "X를 수정하면 무엇이 깨지는가"에 대한 질문에 밀리초 단위로 응답합니다. 응답 크기는 코드베이스 전체가 아닌 답변 내용에 맞춰집니다.

수치

실제 세션에서의 토큰 절감 효과

프로젝트	세션	쿼리	사용된 문자	문자 (기본값)	절감률
project-alpha	35	360	4,801,108	639,560,872	99%
project-beta	26	189	766,508	20,936,204	96%
project-gamma	30	232	410,816	3,679,868	89%
합계	92	782	5,981,476	664,229,092	99%

"문자 (기본값)" = 에이전트가 cat/grep으로 읽었을 모든 파일의 총 소스 크기입니다. 이러한 절감 효과는 모델에 구애받지 않으며, 제공업체와 관계없이 인덱스가 컨텍스트 윈도우의 압박을 줄여줍니다.

쿼리 응답 시간 (110만 라인에서 밀리초 단위)

쿼리	RMLPlus	FastAPI	Django	CPython
`find_symbol`	0.01ms	0.01ms	0.03ms	0.08ms
`get_dependencies`	0.00ms	0.00ms	0.00ms	0.01ms
`get_change_impact`	0.02ms	0.00ms	2.81ms	0.45ms
`get_function_source`	0.01ms	0.02ms	0.03ms	0.10ms

인덱스 구축 성능

프로젝트	파일	라인	인덱스 시간	메모리
소규모 프로젝트	36	7,762	0.9s	2.4 MB
FastAPI	2,556	332,160	5.7s	55 MB
Django	3,714	707,493	36.2s	126 MB
CPython	2,464	1,115,334	55.9s	197 MB

영구 캐시를 사용하면 이후 재시작 시 전체 빌드 과정을 건너뜁니다. CPython의 경우 캐시 적중 시 56초에서 1초 미만으로 단축됩니다.

지원 범위

언어 / 형식	파일	추출 항목
Python	`.py`, `.pyw`	함수, 클래스, 메서드, 임포트, 의존성 그래프
TypeScript / JS	`.ts`, `.tsx`, `.js`, `.jsx`	함수, 화살표 함수, 클래스, 인터페이스, 타입 별칭
Go	`.go`	함수, 메서드(리시버), 구조체, 인터페이스, 타입 별칭
Rust	`.rs`	함수, 구조체, 열거형, 트레이트, impl 블록, macro_rules
C#	`.cs`	클래스, 인터페이스, 구조체, 열거형, 메서드, XML 문서 주석
Markdown / Text	`.md`, `.txt`, `.rst`	헤딩 감지를 통한 섹션
JSON	`.json`	깊이 4까지의 중첩 키 구조, `$ref` 교차 참조
YAML	`.yaml`, `.yml`	중첩 키 계층, 배열 마커, 깊이 제한 4
TOML	`.toml`	테이블, 키-값 쌍, 중첩 구조
INI / Properties	`.ini`, `.cfg`, `.properties`	섹션, 키-값 쌍
Environment	`.env`	변수 이름, 값 (보안 마스킹 포함)
XML / Plist / SVG	`.xml`, `.plist`, `.svg`, `.xhtml`	요소 계층, 속성
HCL / Terraform	`.hcl`, `.tf`	블록, 중첩 리소스, 키-값 쌍
Conf	`.conf`	키-값 쌍, 블록 구조
Dockerfile	`Dockerfile`, `*.dockerfile`	명령어, 멀티 스테이지 빌드, FROM/RUN/COPY/ENV
기타 모든 파일	`*`	라인 수 (일반 대체)

51개의 도구

탐색

도구	기능
`find_symbol`	심볼 정의 위치 확인 — 파일, 라인, 타입, 20줄 미리보기
`get_function_source`	함수 또는 메서드의 전체 소스
`get_class_source`	클래스의 전체 소스
`get_functions`	파일 또는 프로젝트 내 모든 함수
`get_classes`	메서드와 기반 클래스를 포함한 모든 클래스
`get_imports`	모듈, 이름, 라인을 포함한 모든 임포트
`get_structure_summary`	파일 또는 프로젝트 구조 요약
`list_files`	선택적 glob 필터가 포함된 인덱싱된 파일 목록
`get_project_summary`	파일 수, 패키지, 주요 클래스/함수
`search_codebase`	인덱싱된 모든 파일에 대한 정규식 검색
`reindex`	전체 재인덱싱 강제 실행 (거의 필요 없음)

컨텍스트 및 발견

도구	기능
`get_edit_context`	올인원: 심볼 소스 + 의존성 + 호출자를 한 번의 호출로 가져옴 (3번의 호출 절약)
`get_feature_files`	기능 키워드와 관련된 모든 파일을 찾고 임포트를 추적
`get_routes`	API 경로 및 페이지 감지 (Next.js App Router, Express, pages/api)
`get_components`	React 컴포넌트 감지 (`.tsx`/`.jsx` 파일 내 JSX 반환 함수)
`get_env_usage`	코드베이스 전체에서 환경 변수 참조 찾기

영향 분석

도구	기능
`get_dependencies`	심볼이 호출/사용하는 항목
`get_dependents`	심볼을 호출/사용하는 항목
`get_change_impact`	직접 + 간접 의존성을 한 번의 호출로 확인
`get_call_chain`	두 심볼 간의 최단 의존성 경로 (BFS)
`get_file_dependencies`	특정 파일이 임포트하는 파일들
`get_file_dependents`	특정 파일을 임포트하는 파일들

Git 및 Diff

도구	기능
`get_git_status`	브랜치, 앞서감/뒤처짐, 스테이징, 미스테이징, 추적되지 않음
`get_changed_symbols`	변경된 파일을 텍스트 diff가 아닌 심볼 수준 요약으로 확인
`get_changed_symbols_since_ref`	특정 git 참조 이후의 심볼 수준 변경 사항
`summarize_patch_by_symbol`	텍스트 diff 대신 심볼을 사용한 간결한 검토 뷰
`build_commit_summary`	변경된 파일로부터 간결한 커밋 요약 생성

안전한 편집

도구	기능
`replace_symbol_source`	파일의 나머지 부분을 건드리지 않고 심볼 소스 교체
`insert_near_symbol`	심볼 앞이나 뒤에 내용 삽입
`create_checkpoint`	편집 전 파일 세트 스냅샷 생성
`restore_checkpoint`	체크포인트에서 복원
`compare_checkpoint_by_symbol`	체크포인트와 현재 상태를 심볼 수준에서 비교
`list_checkpoints`	사용 가능한 체크포인트 목록

테스트 및 실행

도구	기능
`find_impacted_test_files`	변경된 심볼로부터 영향을 받을 가능성이 있는 pytest 파일 추론
`run_impacted_tests`	영향받은 테스트만 실행 — 원시 로그가 아닌 간결한 요약
`apply_symbol_change_and_validate`	편집 + 영향받은 테스트 실행을 한 번의 호출로 수행
`apply_symbol_change_validate_with_rollback`	편집 + 검증 + 실패 시 자동 롤백
`discover_project_actions`	프로젝트 파일에서 테스트/린트/빌드/실행 명령어 감지
`run_project_action`	제한된 출력으로 발견된 작업 실행

설정 분석

도구	기능
`analyze_config`	설정 파일에서 중복, 비밀 정보, 오타, 고아 키 스캔

세 가지 검사를 실행합니다 (checks 매개변수를 통해 개별적으로 전환 가능):

중복 — 동일한 파일 내에서 두 번 정의된 키, Levenshtein 기반 오타 감지 (예: db_hsot vs db_host)
비밀 정보 — 알려진 비밀 형식(API 키, 토큰, 개인 키)에 대한 정규식 패턴 및 고엔트로피 문자열에 대한 Shannon 엔트로피 분석
고아 키 — 실제 코드 사용량과 설정 키를 교차 참조합니다. 코드가 읽지 않는 키와 코드가 기대하지만 설정되지 않은 환경 변수를 감지합니다. os.environ, process.env, os.Getenv, std::env::var 등을 이해합니다.

지원 형식: .yaml, .yml, .toml, .ini, .cfg, .properties, .env, .xml, .plist, .hcl, .tf, .conf, .json

코드 품질

도구	기능
`find_dead_code`	호출자가 없는 함수/클래스 찾기 (진입점, 테스트, 데코레이트된 라우트 제외)
`find_hotspots`	복잡도 점수(라인, 분기, 중첩, 매개변수 수)별 함수 순위 매기기
`detect_breaking_changes`	현재 함수 시그니처를 git 참조와 비교 — 제거/이름 변경된 매개변수, 변경된 기본값 플래그 지정

Docker

도구	기능
`analyze_docker`	Dockerfile 감사: 베이스 이미지, 노출된 포트, ENV/ARG 교차 참조, `latest` 태그 경고

다중 프로젝트

도구	기능
`find_cross_project_deps`	프로젝트 간 임포트를 교차 참조하여 공유 의존성 찾기

통계

도구	기능
`get_usage_stats`	세션별 프로젝트당 누적 토큰 절감액

LSP와의 비교

LSP는 "이것이 어디에 정의되어 있는가?"에 답하고, token-savior는 "이것을 수정하면 무엇이 깨지는가?"에 답합니다.

LSP는 포인트 쿼리입니다: 하나의 심볼, 하나의 파일, 하나의 위치. LLMClient가 어디에 정의되어 있고 누가 직접 참조하는지는 찾을 수 있습니다. "LLMClient를 리팩토링하면 무엇이 간접적으로 깨지는가?"라고 물으면 LSP는 답을 주지 못합니다. AI는 수십 번의 참조 찾기 호출을 재귀적으로 수행하며 매 단계마다 파일을 읽어야 합니다.

CPython에서 get_change_impact("TestCase")를 실행하면 0.45ms 만에 154개의 직접 의존성과 492개의 간접 의존성을 찾아내며, 41MB를 읽는 대신 16KB의 문자만 반환합니다. 또한 LSP와 달리 언어 서버가 전혀 필요하지 않습니다. 하나의 바이너리로 Python + TS/JS + Go + Rust + C# + 설정 파일 + Dockerfile을 즉시 지원합니다.

설치

git clone https://github.com/Mibayy/token-savior
cd token-savior
python3 -m venv ~/.local/token-savior-venv
~/.local/token-savior-venv/bin/pip install -e ".[mcp]"

설정

Claude Code / Cursor / Windsurf / Cline

프로젝트 루트의 .mcp.json에 추가하세요:

{
  "mcpServers": {
    "token-savior": {
      "command": "/path/to/.local/token-savior-venv/bin/token-savior",
      "env": {
        "WORKSPACE_ROOTS": "/path/to/project1,/path/to/project2",
        "TOKEN_SAVIOR_CLIENT": "claude-code"
      }
    }
  }
}

Hermes Agent

~/.hermes/config.yaml에 추가하세요:

mcp_servers:
  token-savior:
    command: ~/.local/token-savior-venv/bin/token-savior
    env:
      WORKSPACE_ROOTS: /path/to/project1,/path/to/project2
      TOKEN_SAVIOR_CLIENT: hermes
    timeout: 120
    connect_timeout: 30

TOKEN_SAVIOR_CLIENT는 선택 사항이지만, 라이브 대시보드에서 클라이언트별 절감액을 집계할 수 있게 해줍니다.

에이전트가 실제로 사용하게 만들기

AI 어시스턴트는 더 나은 도구를 사용할 수 있을 때도 기본적으로 grep과 cat을 사용합니다. 부드러운 지시는 합리화되어 무시되기 쉽습니다. CLAUDE.md 또는 이에 상응하는 파일에 다음을 추가하세요:

## Codebase Navigation — MANDATORY

You MUST use token-savior MCP tools FIRST.

- ALWAYS start with: find_symbol, get_function_source, get_class_source,
  search_codebase, get_dependencies, get_dependents, get_change_impact
- Only fall back to Read/Grep when token-savior tools genuinely don't cover it
- If you catch yourself reaching for grep to find code, STOP

다중 프로젝트 워크스페이스

하나의 서버 인스턴

token-savior