code-analyze-mcp

[!NOTE] 네이티브 에이전트 도구(정규식 검색, 경로 매칭, 파일 읽기)는 특정 대상을 찾는 조회에 적합합니다. aptu-coder는 기계적이고 AI가 아닌 작업, 즉 디렉터리 구조 매핑, 심볼 추출, 호출 그래프 추적을 처리합니다. 이 작업을 전용 도구에 오프로드하면 토큰 사용량이 줄어들고 정확도가 높아져 코딩 속도가 빨라집니다.

벤치마크

Django(Python) 소스 트리를 대상으로 한 Claude Code의 인증 마이그레이션 작업. 전체 방법론.

OpenFAST(Fortran) 소스 트리를 대상으로 한 Claude Code의 AeroDyn 통합 감사 작업. 전체 방법론.

Related MCP server: CodeGraphMCPServer

개요

aptu-coder는 AI 에이전트에게 코드베이스의 정확한 구조적 맥락, 즉 디렉터리 트리, 심볼 정의, 호출 그래프를 원시 파일을 읽지 않고 제공하는 Model Context Protocol 서버입니다. 18개 언어를 지원하며(자세한 내용은 지원 언어 참조) 모든 MCP 호환 오케스트레이터와 통합됩니다.

지원 언어

설치

Homebrew (macOS 및 Linux)

brew install clouatre-labs/tap/aptu-coder

업데이트: brew upgrade aptu-coder

cargo-binstall (Rust 불필요)

cargo binstall aptu-coder

cargo install (Rust 툴체인 필요)

cargo install aptu-coder

빠른 시작

소스에서 빌드

cargo build --release

바이너리는 target/release/aptu-coder에 있습니다.

MCP 클라이언트 구성

두 가지 전송 방식이 제공됩니다. Streamable HTTP는 델리게이트를 생성하는 오케스트레이터(예: goose coder)를 사용할 때 권장됩니다. 단일 서버 프로세스가 오케스트레이터와 모든 에이전트 간에 공유되어, 각 stdio 하위 프로세스가 자체 격리 인스턴스를 가질 때 발생하는 확장 드리프트를 제거합니다.

Streamable HTTP (멀티 에이전트 설정에 권장)

Homebrew를 사용하면 한 번의 명령으로 로그인 시 서버가 시작되고 계속 실행됩니다:

brew services start aptu-coder

Homebrew 포뮬러는 기본적으로 포트 49200에서 서버를 시작합니다. 그런 다음 확장을 ~/.config/goose/config.yaml에 한 번 추가합니다:

extensions:
  aptu-coder:
    type: streamable_http
    uri: http://127.0.0.1:49200/mcp
    name: aptu-coder
    timeout: 300

또는 Claude Code의 경우:

claude mcp add --transport http aptu-coder http://127.0.0.1:49200/mcp

다른 포트를 사용하려면 재시작 전에 APTU_CODER_PORT를 설정하세요:

APTU_CODER_PORT=4000 brew services restart aptu-coder

brew services 없이 직접 시작하려면:

aptu-coder --port 49200
# or equivalently
APTU_CODER_PORT=49200 aptu-coder

stdio (단일 클라이언트 사용)

하나의 프로세스만 서버가 필요할 때 적합합니다. 클라이언트가 프로세스 수명 주기를 소유하고 자동으로 생성합니다:

claude mcp add --transport stdio aptu-coder -- aptu-coder

또는 프로젝트 루트의 .mcp.json에 수동으로 추가합니다(버전 관리를 통해 팀과 공유):

{
  "mcpServers": {
    "aptu-coder": {
      "command": "aptu-coder",
      "args": []
    }
  }
}

도구

모든 선택적 매개변수는 생략할 수 있습니다. analyze_directory, analyze_file, analyze_symbol의 공통 선택적 매개변수:

도구 매개변수, 제약 조건 및 예시는 MCP 클라이언트의 도구 검사기 또는 tools/list 응답에서 확인할 수 있습니다.

MCP 리소스

지식 그래프 기능은 analyze_symbol 호출 중에 구축된 구조적 그래프를 탐색하기 위한 MCP 리소스 템플릿을 노출합니다. 리소스는 URI 주소로 지정됩니다. 사용 가능한 템플릿을 찾으려면 resources/templates/list를 사용하세요.

페이지네이션: 결과는 페이지로 나뉩니다. 이전 응답의 불투명한 cursor 값을 전달하여 다음 페이지를 가져옵니다.

깊이 매개변수: blast-radius 템플릿은 선택적 depth 쿼리 매개변수(1-5 범위의 정수, 기본값 3)를 허용합니다.

콜드 캐시: 먼저 디렉터리에서 analyze_symbol을 호출하여 그래프를 구축하세요. 그래프를 사용할 수 있을 때까지 리소스는 정보 메시지를 반환합니다.

출력 관리

대규모 코드베이스의 경우 여러 메커니즘이 컨텍스트 오버플로를 방지합니다.

페이지네이션

analyze_file 및 analyze_symbol은 출력이 잘릴 때 NEXT_CURSOR: 줄을 추가합니다. 토큰을 cursor로 다시 전달하여 다음 페이지를 가져옵니다. summary=true와 cursor는 상호 배타적입니다. 둘 다 전달하면 오류가 반환됩니다.

# Response ends with:
NEXT_CURSOR: eyJvZmZzZXQiOjUwfQ==

# Fetch next page:
analyze_symbol path: /my/project symbol: my_function cursor: eyJvZmZzZXQiOjUwfQ==

exec_command 출력 상한

exec_command는 대규모 명령 출력이 컨텍스트를 넘치게 하는 것을 방지하기 위해 세 가지 독립적인 바이트 수준 상한을 적용합니다:

30k stdout 상한은 데이터 기반입니다: 관찰된 27,981건의 exec_command 호출 분석 결과 0.33%만이 이 한도를 초과합니다. 어떤 상한이 발동되면 응답에 output_truncated: true가 설정되고 JSONL 메트릭에 기록됩니다.

drain_timeout_secs는 자식 프로세스가 종료된 후에도 파이프를 계속 잡고 있는 백그라운드 서브프로세스가 있는 경우 서버가 얼마나 오래 기다릴지를 제어합니다. 기본값은 500ms입니다(0 또는 생략). 음수 값은 INVALID_PARAMS를 반환합니다. 드레인 창이 파이프가 닫히기 전에 만료되면 output_truncated: true가 설정됩니다.

exec_command 출력 필터

내장 필터 테이블은 출력이 모델에 도달하기 전에 수다스러운 CLI 도구의 파일별 노이즈를 억제합니다. 필터는 성공 시에만 stdout, stderr 및 인터리브된 출력에 적용됩니다. 실패 시 원시 출력은 항상 보존됩니다.

프로젝트 로컬 규칙은 .aptu/filters.toml에 추가할 수 있습니다. 파싱 오류 및 인식할 수 없는 schema_version 값(version != 1)은 경고를 기록한 후 내장 테이블로 폴백되며 충돌이 발생하지 않습니다. 필터가 발동되면 structuredContent의 filter_applied가 어떤 규칙이 일치했는지 식별합니다.

비대화형 파이프라인

단일 패스 서브에이전트 세션에서는 프롬프트 캐시가 기록되지만 재사용되지 않습니다. 벤치마크에 따르면 MCP 응답은 네이티브 전용 워크플로보다 캐시에 약 2배 더 많이 기록하여 품질 향상 없이 비용만 추가했습니다. DISABLE_PROMPT_CACHING=1(또는 Haiku 전용 파이프라인의 경우 DISABLE_PROMPT_CACHING_HAIKU=1)을 설정하여 이러한 오버헤드를 방지하세요.

서버 자체 지침은 알 수 없는 저장소에 대한 4단계 권장 워크플로를 제시합니다: max_depth=2로 analyze_directory를 사용하여 저장소 루트를 조사하고, 소스 패키지로 파고들어 핵심 파일에 대해 analyze_module을 실행하여 함수/임포트 인덱스를 얻거나(서명과 타입이 필요할 때는 analyze_file), 그런 다음 analyze_symbol을 사용하여 호출 그래프를 추적합니다. 서버 지침을 표시하는 MCP 클라이언트는 이 워크플로를 에이전트에게 자동으로 제시합니다.

환경 변수

캐시 및 런타임

관측 가능성

JSONL 스키마, OTel 구성 및 스팬 속성 정책에 대해서는 다음을 참조하세요:

• OBSERVABILITY.md (저장소 루트)

• docs/METRICS.md

문서

• AGENTS.md - 기여자 참조: 프로젝트 구조, 명령, rmcp 함정, 도구 매개변수 제약 조건

• ARCHITECTURE.md - 설계 목표, 모듈 맵, 데이터 흐름, 언어 핸들러 시스템, 캐싱 전략

• CONTRIBUTING.md - 개발 워크플로, 커밋 규칙, PR 체크리스트

• DESIGN-GUIDE.md - 고성능 MCP 서버 구축을 위한 설계 결정, 근거 및 재현 가이드

• MCP Best Practices - 에이전틱 루프, 오케스트레이션 패턴, MCP 도구 설계, 메모리 관리 및 안전 제어를 위한 모범 사례

• METRICS.md - 메트릭 스키마, JSONL 형식 및 보존 정책

• ROADMAP.md - 개발 이력 및 향후 방향

• SECURITY.md - 보안 정책 및 취약점 신고

라이선스

Apache-2.0. 자세한 내용은 LICENSE를 참조하세요.