contextshrinker

contextshrinker는 Go로 작성된 제로 의존성, 헤드리스 Model Context Protocol(MCP) 서버입니다. 로컬 코드베이스를 임베디드 Kùzu 그래프 데이터베이스에 인덱싱하여 자율 AI 에이전트(Claude Code, Cursor, Antigravity IDE, Aider, Claude Desktop 등)의 LLM 토큰 비대화를 획기적으로 줄여줍니다.

AI 에이전트가 원시 소스 파일을 읽거나 번거로운 grep 기반 검색을 실행하도록 강요하는 대신, contextshrinker는 에이전트가 프로젝트의 아키텍처 의존성, 함수 호출 체인, 클래스 상속 구조에 대한 의미론적 그래프를 질의할 수 있게 하여 입력 컨텍스트 소비를 90% to 98% 줄입니다.

🚀 주요 기능

• 범용 에이전트 호환성: 표준 I/O(stdio)를 통해 모든 MCP 호환 코딩 도구 또는 IDE에 매끄럽게 연결됩니다.

• 외부 데이터베이스 불필요: 완전히 자체 포함됩니다. 프로젝트의 로컬 .contextshrinker/ 디렉터리 안에서 프로세스 내 그래프 데이터베이스(Kùzu)를 실행합니다.

• 자동 관리 LSP 데몬: 프로젝트 언어를 자동으로 감지하고, 누락된 경우 샌드박스 언어 서버(Go용 gopls, Python용 pyright 등)를 프로그래밍 방식으로 프로비저닝한 후 백그라운드에서 해당 RPC 인터페이스를 질의하여 호출 그래프를 구축합니다.

• 다중 언어 지원: Go, Python, JavaScript, TypeScript, Java에 대한 전체 AST 구문 파싱 및 의미론적 인덱싱을 제공합니다.

• 깔끔한 프로젝트 격리: 각 워크스페이스는 격리된 구성 규칙(.contextshrinker/ignore)과 그래프 데이터베이스 파일(.contextshrinker/db/)이 포함된 자체 .contextshrinker/ 디렉터리를 유지합니다.

• 실시간 상태 동기화: fsnotify를 사용하여 파일을 재귀적으로 감시합니다. 저장 시 디바운스된 델타 업데이트가 이전 노드를 제거하고 수정된 파일을 실시간으로 다시 인덱싱합니다.

• 대화형 그래프 시각화: 필요 시 멋진 Vis.js 기반 다크 모드 HTML 코드베이스 시각화(.contextshrinker/contextshrinker_graph.html)를 생성합니다.

Related MCP server: code-graph-mcp

🛠️ 아키텍처: 2단계 수집

코드를 깔끔하게 인덱싱하기 위해 contextshrinker는 2단계 수집 시퀀스를 실행합니다:

graph TD
    A[Walk Workspace] -->|Filter via .contextshrinker/ignore| B[Pass 1: Tree-sitter Syntax]
    B -->|Create Nodes| C[(Kùzu Graph DB)]
    C --> D[Pass 2: LSP Semantic Cross-References]
    D -->|Create CALLS / IMPLEMENTS Edges| C

1. 1단계(Tree-sitter AST 추출): 소스 파일을 빠르게 스캔하여 엔터티(함수/메서드, 클래스/구조체, 변수)와 연결된 docstring을 추출하고 이를 노드로 삽입합니다.

2. 2단계(LSP 의미론적 해석): 백그라운드 Language Server Protocol(LSP) 데몬에 교차 참조를 질의하여 호출(CALLS), 임포트(IMPORTS), 클래스 상속(IMPLEMENTS / EXTENDS)을 식별하고 연결합니다.

📥 설치

옵션 1: 사전 컴파일된 바이너리(가장 빠름)

Go를 설치하고 싶지 않다면 플랫폼용 사전 컴파일된 휴대용 패키지를 다운로드할 수 있습니다.

1. Releases 페이지로 이동합니다.

2. 운영 체제에 맞는 아카이브(.tar.gz 또는 .zip)를 다운로드합니다.

3. 아카이브를 압축 해제합니다. 실행 파일(contextshrinker)과 동적 라이브러리(libkuzu / kuzu_shared)를 같은 폴더에 유지합니다.

4. 해당 디렉터리에서 실행 파일을 실행합니다.

macOS / Linux:

chmod +x contextshrinker
./contextshrinker --help

Windows:

contextshrinker.exe --help

옵션 2: 소스에서 빌드(Go 필요)

사전 요구 사항

• Go(1.21 이상)

• Node.js 및 npm(JS/TS 및 Python LSP를 자동으로 설치하기 위해)

컴파일

리포지토리를 클론하고 실행합니다:

go build -o contextshrinker

시스템 PATH에 바로 설치하려면:

go install

🔌 코딩 에이전트에 통합

contextshrinker는 코딩 에이전트의 자식 프로세스로 온디맨드 실행됩니다. 컴파일된 바이너리의 절대 경로를 클라이언트에 등록하세요.

1. Antigravity IDE(Gemini 에이전트 패널)

1. Antigravity IDE를 엽니다.

2. 에이전트 패널에서 ...(추가 옵션) 메뉴를 클릭합니다.

3. "MCP 서버 관리" $\rightarrow$ "원본 구성 보기" 를 선택합니다.

4. mcp_config.json에 서버를 등록합니다:

   {
     "mcpServers": {
       "contextshrinker": {
         "command": "/absolute/path/to/contextshrinker"
       }
     }
   }

2. Claude Code(CLI)

서버를 자동으로 추가합니다:

claude mcp add contextshrinker /absolute/path/to/contextshrinker

3. Cursor IDE

1. 설정 $\rightarrow$ 기능 $\rightarrow$ MCP로 이동합니다.

2. + 새 MCP 서버 추가를 클릭합니다.

3. 구성을 설정합니다:

   • 이름: contextshrinker

   • 유형: command

   • 명령: /absolute/path/to/contextshrinker

4. Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json 파일에 추가합니다:

{
  "mcpServers": {
    "contextshrinker": {
      "command": "/absolute/path/to/contextshrinker"
    }
  }
}

🧰 노출되는 도구

구성이 완료되면 다음 도구가 AI 코딩 에이전트에서 자동으로 사용 가능해집니다.

1. search_codebase

   • 인자: query (string)

   • 설명: 클래스, 함수, 변수 전반의 구조와 docstring을 매칭하기 위해 Full-Text Search 및 Cypher 쿼리를 실행합니다.

2. get_call_chain

   • 인자: target_function (string), depth (integer, max 5)

   • 설명: 가변 길이 경로 Cypher 쿼리를 사용하여 업스트림 호출자 체인을 해석하고 호출 의존성을 매핑합니다.

3. get_file_structure

   • 인자: file_path (string)

   • 설명: 원시 텍스트 내용을 컨텍스트 창에 넣지 않고 단일 파일에 포함된 전체 추상 노드 구조(클래스, 인터페이스, 메서드, 변수)를 검색합니다.

4. visualize_codebase

   • 설명: 온디맨드 HTML 내보내기를 트리거하여 .contextshrinker/ 디렉터리 안에 contextshrinker_graph.html을 저장합니다.

5. get_architecture_report

   • 설명: God Object, 결합 핫스팟, 순환, 죽은 비공개 함수, AI 메트릭(SCR, DCR, BVI, AOI, Call Chain Depth Index - CDI) 및 실행 가능한 코드 품질 지침(Jeff Dean 원칙)과 AI 시스템 프롬프트 지시문이 포함된 전체 코드베이스 아키텍처 상태 보고서를 검색합니다.

🏛️ 코드베이스 및 아키텍처 최적화

LLM을 사용하여 결합을 체계적으로 감사하고, 도메인 경계(DDD)를 분석하고, 코드 재구조화(예: 모놀리스를 모듈로 분할)를 안내하는 데 contextshrinker를 사용할 수 있습니다.

최적화 워크플로

1. 아키텍처 메트릭 및 지침 생성: 터미널에서 분석 명령을 실행하여 코드베이스 그래프를 검사하고 보고서를 생성하세요.

   ./contextshrinker analyze

   이 명령은 God Object(높은 외향 결합), Black Hole(높은 내향 호출), 순환 임포트 경로, 죽은 코드(사용되지 않는 비공개 함수), AI 메트릭(Call Chain Depth Index - CDI 포함) 및 실행 가능한 코드 품질 및 LLM 아키텍처 지침(Jeff Dean 원칙)에 대한 메트릭이 포함된 contextshrinker-report.md를 생성합니다.

2. 시스템 프롬프트 얻기: CLI에서 수석 시스템 아키텍트 프롬프트를 검색합니다.

   ./contextshrinker prompt architect

3. LLM으로 분석하기:

   • prompt architect 명령의 출력을 LLM의 시스템 프롬프트로 설정합니다.

   • 생성된 contextshrinker-report.md의 내용을 컨텍스트 / 입력으로 제공합니다.

   • LLM에게 경계 컨텍스트 분할이나 인터페이스 경계를 제안하도록 요청합니다.

4. 에이전트 / 도구 사용 워크플로: MCP 호환 에이전트(Antigravity IDE, Claude Code, Cursor 등)를 사용하는 경우 직접 요청할 수 있습니다.

   "contextshrinker 분석 보고서를 실행하고 생성된 마크다운을 읽은 다음, 시스템 아키텍트로서 설계 핫스팟을 감사하세요. 구체적인 모듈 추출을 제안하기 전에 get_call_chain 및 get_file_structure 도구를 사용하여 결합을 검사하세요."

⚙️ 구성 및 무시 규칙

워크스페이스 그래프 비대화를 방지하기 위해 표준 라이브러리 및 의존성 폴더(node_modules/, vendor/, .git/ 등)는 기본적으로 무시됩니다.

사용자 지정 무시 규칙을 추가하려면 프로젝트를 초기화하고 다음을 실행하여 워크스페이스 루트에 .csignore 파일을 생성하세요.

contextshrinker init

.csignore의 각 줄은 재귀적으로 매칭됩니다.

# Custom project ignores
*.log
tmp-output/
dist/
.vitepress

💡 대규모 프로젝트를 위한 모범 사례

중대형 프로젝트(예: 수백 또는 수천 개의 파일)에서 contextshrinker를 사용하는 경우, LLM/에이전트 프롬프트(Claude Code, Cursor 등) 내부에서 직접 초기 코드베이스 수집을 실행하면 에이전트 시간 초과 문제가 발생할 수 있습니다. 이는 에이전트가 첫 워크스페이스 파싱 및 LSP 참조 해석이 완료될 때까지 기다리는 동안 제한된 시간 초과 한도(일반적으로 60초)가 있기 때문입니다.

이를 방지하려면 에이전트를 시작하기 전에 터미널에서 다음 최적화 워크플로를 따르세요.

1. 워크스페이스 초기화: 초기화 명령을 실행하여 구성 디렉터리와 기본 무시 목록을 생성하세요.

   contextshrinker init

2. 무시 규칙 구성: 워크스페이스 루트에 생성된 .csignore 파일을 열고 제외하려는 대용량 디렉터리(예: 문서 사이트, 테스트 자산, 빌드 폴더)를 추가하세요.

3. 오프라인으로 데이터베이스 구축: 터미널에서 analyze 명령을 한 번 실행하여 초기 그래프 데이터베이스를 구축하세요.

   contextshrinker analyze

   이렇게 하면 Tree-sitter 파싱 및 LSP 의미론적 교차 참조라는 무거운 작업이 오프라인에서 수행됩니다. 데이터베이스가 채워지면 이후의 에이전트 요청과 실시간 상태 동기화는 몇 초 내에 증분 방식으로 실행되어 향후 시간 초과를 방지할 수 있습니다.

📊 명령줄 인터페이스(CLI) 모드

코드베이스 그래프를 질의하거나, MCP 서버 데몬을 명시적으로 시작하거나, 시스템 아키텍트 프롬프트를 검색하거나, 상태 분석 보고서를 터미널에서 직접 생성할 수 있습니다.

1. MCP 서버 시작

기본적으로 인수 없이 ./contextshrinker를 실행하면 MCP 서버 데몬이 시작됩니다. 명시적으로 실행할 수도 있습니다.

./contextshrinker start

2. 코드베이스 아키텍처 분석 실행

코드베이스 구조(God object, 내부 호출 핫스팟, 순환 임포트, 죽은 코드, Call Chain Depth Index - CDI, LLM 코드 품질 지침)를 분석하고 contextshrinker-report.md에 보고서를 작성합니다.

./contextshrinker analyze

3. 수석 시스템 아키텍트 프롬프트 출력

Domain-Driven Design(DDD) 수석 시스템 아키텍트 시스템 프롬프트를 stdout으로 출력합니다.

./contextshrinker prompt architect

4. 코드베이스 검색

쿼리와 일치하는 함수, 클래스 또는 변수를 찾습니다.

./contextshrinker search "IngestWorkspace"

5. 호출 체인 추적

대상 함수 이름의 업스트림 호출자를 추적합니다(기본 깊이는 3, 최대는 5).

./contextshrinker call-chain "IngestWorkspace" --depth 3

6. 파일 구조 검색

파일의 전체 텍스트 내용을 읽지 않고 파일 구조를 가져옵니다.

./contextshrinker structure "main.go"

7. 대화형 시각화 생성

Vis.js 코드베이스 그래프 표현을 생성합니다.

./contextshrinker visualize

생성된 .contextshrinker/contextshrinker_graph.html을 아무 브라우저에서 열어 프로젝트 아키텍처를 대화형으로 탐색하세요.

옵션(전역 플래그)

• --workspace <path>: 프로젝트 디렉터리를 지정합니다(기본값은 .).

• --db <path>: 데이터베이스 저장 디렉터리를 지정합니다(기본값은 .contextshrinker/db).

• --reindex: 쿼리를 실행하기 전에 전체 워크스페이스 수집 스캔(코드 재파싱 및 LSP 관계 매핑)을 강제합니다. 데이터베이스가 비어 있으면 수집이 자동으로 실행됩니다.

• 참고: Kuzu DB는 배타적 파일 수준 잠금을 설정하므로, 활성 데이터베이스에서 CLI 명령을 실행할 때 IDE의 MCP 클라이언트를 일시 중지하거나 중지했는지 확인하거나 CLI 플래그로 다른 워크스페이스/db 디렉터리를 사용하세요.

📄 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.