코드 요약기

Gemini Flash 2.0을 사용하여 주어진 디렉터리의 코드 파일을 요약하는 명령줄 도구입니다. 이제 LLM 도구와의 통합을 위해 MCP 서버 지원이 추가되었습니다!

특징

• 디렉토리의 코드 파일을 재귀적으로 처리합니다.

• .gitignore 규칙을 존중합니다.

• node_modules , dist 등과 같은 관련 없는 디렉토리를 건너뜁니다.

• Gemini Flash 2.0을 사용하여 코드 파일을 요약합니다.

• 텍스트 파일에 요약을 출력합니다.

• 구성 가능한 세부 수준 및 요약 길이

• Claude Desktop 및 기타 LLM 도구와 통합하기 위한 MCP 서버

• 다른 애플리케이션에 쉽게 통합할 수 있는 모듈식 디자인

• 안전한 API 키 관리

• MCP 서버 엔드포인트에 대한 인증

• LLM 호출에 대한 지수 백오프를 사용한 재시도 메커니즘

• 남용을 방지하기 위한 속도 제한

요구 사항

• 노드.js 18+

설치

1. 저장소를 복제합니다

   지엑스피1

2. 종속성 설치:

   npm install

3. Google API 키로 .env 파일을 만듭니다.

   GOOGLE_API_KEY=your_api_key_here

4. 프로젝트를 빌드하세요:

   npm run build

MCP 서버 설정 및 통합

코드 요약기에는 Claude Desktop, Cursor AI, Cline과 같은 LLM 도구가 코드 요약 및 파일 콘텐츠에 액세스할 수 있도록 하는 MCP(Model Context Protocol) 서버가 포함되어 있습니다.

MCP 서버 시작

기본적으로 서버는 포트 24312에서 실행됩니다. 구성에서 이를 변경할 수 있습니다.

Claude Desktop과 연결

1. 코드 요약기 MCP 서버 시작

2. Claude Desktop을 열고 Claude 메뉴를 클릭한 다음 "설정..."을 클릭하세요.

3. "개발자" 섹션으로 이동하세요

4. 다음 내용이 포함된 ~/.claude/claude_desktop_config.json (macOS/Linux) 또는 %USERPROFILE%\.claude\claude_desktop_config.json (Windows)에 파일을 만듭니다.

5. Claude Desktop을 다시 시작하세요

6. 다시 시작한 후 Claude에게 코드베이스에 액세스하도록 요청할 수 있습니다(예: "내 프로젝트의 파일 요약").

Claude Desktop에 대한 프롬프트 예시:

• "제 프로젝트의 모든 JavaScript 파일을 요약해 주실 수 있나요?"

• "제 코드베이스에 대한 간략한 개요를 알려주세요."

• 'src/config/config.ts' 파일이 무엇을 하는지 설명하세요.

• "내 코드에서 인증과 관련된 모든 기능을 찾으세요."

커서 AI와 연결하기

1. 코드 요약기 MCP 서버 시작

2. 프로젝트 디렉토리에 .cursor/mcp.json 파일을 만듭니다.

3. 커서를 다시 시작하거나 프로젝트를 다시 로드하세요.

4. Cursor에게 코드에 대해 물어보세요. 예를 들어, "제 코드베이스를 요약해 주실 수 있나요?"

커서에 대한 프롬프트 예:

• "이 코드베이스의 구조를 요약해 주세요."

• "이 프로젝트의 핵심 구성 요소는 무엇입니까?"

• "MCP 서버 구현에 대한 자세한 설명을 해주세요."

• "재시도 메커니즘이 어떻게 작동하는지 알려주세요."

클라인과 연결

1. 코드 요약기 MCP 서버 시작

2. Cline에서는 다음 명령을 사용하여 MCP 서버를 추가할 수 있습니다.

3. 그런 다음 API 키로 인증하세요.

4. 그런 다음 Cline에게 코드 요약기를 사용하도록 요청할 수 있습니다. 예: "내 코드 파일을 요약해 주세요"

Cline에 대한 예시 프롬프트:

• "프로젝트의 각 파일은 무슨 역할을 하나요?"

• "모든 TypeScript 파일의 요약을 만듭니다."

• "이 코드베이스의 인증 흐름을 설명하세요."

• 'summarizer' 디렉토리의 주요 기능은 무엇인가요?

MCP 통합으로 할 수 있는 일

MCP 통합을 사용하면 다음을 수행할 수 있습니다.

1. 파일 요약 받기 : 특정 파일의 기능에 대한 간략한 설명을 요청합니다.

2. 디렉토리 탐색 : 코드베이스 구조를 탐색합니다.

3. 일괄 처리 : 여러 파일을 한 번에 요약

4. 타겟 쿼리 : 코드에서 특정 패턴이나 기능 찾기

5. 요약 사용자 정의 : 세부 수준 및 요약 길이 제어

6. 설정 업데이트 : MCP 인터페이스를 통해 구성 옵션 변경

MCP 서버는 코드베이스를 체계적인 방식으로 LLM 도구에 노출하여 코드 조각을 수동으로 붙여넣지 않고도 코드를 읽고, 탐색하고, 요약할 수 있도록 합니다.

MCP 서버 통합 세부 정보

MCP 리소스

• code://file/* - 개별 코드 파일에 액세스

• code://directory/* - 디렉토리에 있는 코드 파일 나열

• summary://file/* - 특정 파일에 대한 요약을 가져옵니다.

• summary://batch/* - 여러 파일에 대한 요약을 가져옵니다.

MCP 도구

• summarize_file - 옵션을 사용하여 단일 파일을 요약합니다.

• summarize_directory - 옵션을 사용하여 디렉토리 요약

• set_config - 구성 옵션 업데이트

MCP 프롬프트

• code_summary - 코드 요약을 위한 프롬프트 템플릿

• directory_summary - 전체 디렉토리를 요약하기 위한 프롬프트 템플릿

문제 해결

일반적인 MCP 연결 문제

1. 연결 거부됨

   • MCP 서버가 실행 중인지 확인하세요( npm start -- server )

   • 구성에서 포트가 올바른지 확인하세요

   • 연결을 차단하는 방화벽 문제가 있는지 확인하세요

2. 인증 오류

   • 헤더에 올바른 API 키( x-api-key )를 추가했는지 확인하세요.

   • API 키가 유효하고 올바른 형식인지 확인하세요.

   • 환경 변수가 올바르게 설정되었는지 확인하세요

3. 전송 오류

   • 올바른 전송 유형이 지정되었는지 확인하세요(SSE)

   • URL에 올바른 엔드포인트( /sse )가 포함되어 있는지 확인하세요.

   • 클라이언트와 서버 간의 네트워크 연결을 확인하세요

4. 권한 문제

   • MCP 서버에 코드베이스에 대한 읽기 액세스 권한이 있는지 확인하세요.

   • 특정 파일에 대한 요약이 실패하면 파일 권한을 확인하세요.

5. Claude Desktop에서 MCP 서버를 찾을 수 없음

   • claude_desktop_config.json 의 경로가 올바른지 확인하세요.

   • 명령과 인수가 올바른 위치를 가리키는지 확인하세요.

   • Claude Desktop 로그에서 구성 오류가 있는지 확인하세요.

6. 속도 제한

   • "요청이 너무 많습니다" 오류가 표시되면 잠시 기다렸다가 나중에 다시 시도하세요.

   • 서버 코드에서 속도 제한 설정을 조정하는 것을 고려하세요.

다른 문제에 대해서는 서버 로그를 확인하거나 GitHub 저장소에서 문제를 열어보세요.

용법

명령줄 인터페이스

구성 관리

API 인증

MCP 서버에 연결할 때 요청 헤더에 API 키를 포함해야 합니다.

모든 엔드포인트( /health 제외)에는 인증이 필요합니다.

옵션

• --detail , -d : 요약의 세부 정보 수준을 설정합니다. 옵션은 '낮음', '보통', '높음'입니다. 기본값은 '보통'입니다.

• --max-length , -l : 각 요약의 최대 길이(문자 수). 기본값은 500입니다.

보안 기능

API 키 관리

• API 키는 안전하게 저장되며 구성 파일보다 환경 변수가 우선합니다.

• 키는 사용 전에 적절한 형식인지 검증됩니다.

• API 키는 로그나 오류 메시지에 노출되지 않습니다.

• 환경 변수를 통해 제공되는 경우 구성 파일은 API 키를 저장하지 않습니다.

입증

• 모든 MCP 서버 엔드포인트(상태 확인 제외)에는 API 키를 통한 인증이 필요합니다.

• 인증은 보안 전송을 위해 x-api-key 헤더를 사용합니다.

• 실패한 인증 시도는 보안 모니터링을 위해 기록됩니다.

속도 제한

• 내장된 속도 제한 기능으로 서비스 남용을 방지합니다.

• 기본값: IP 주소당 분당 60개 요청

• 서버 설정을 통해 구성 가능

오류 처리

• 분류를 통한 구조화된 오류 시스템

• 민감한 정보는 오류 메시지에 노출되지 않습니다.

• 다양한 실패 시나리오에 대해 적절한 오류 코드가 반환됩니다.

LLM 통화 회복력

• 일시적인 실패에 대한 지수적 백오프를 통한 자동 재시도

• 최대 재시도 횟수, 지연 횟수, 백오프 계수를 포함한 구성 가능한 재시도 설정

• 무리의 급격한 문제를 방지하기 위해 재시도 타이밍에 지터가 추가되었습니다.

• 시스템 전반의 문제 추적을 위한 ID 추적 요청

지원되는 파일 유형

• 타입스크립트(.ts, .tsx)

• 자바스크립트(.js, .jsx)

• 파이썬(.py)

• 자바(.java)

• C++(.cpp)

• 씨(.씨)

• 고(.go)

• 루비(.rb)

• PHP(.php)

• C#(.cs)

• 스위프트(.swift)

• 녹(.rs)

• 코틀린(.kt)

• 스칼라(.scala)

• 뷰(.vue)

• HTML(.html)

• CSS(.css, .scss, .less)

작동 원리

1. 이 도구는 .gitignore 규칙을 준수하여 지정된 디렉토리를 재귀적으로 스캔합니다.

2. 지원되는 확장자를 기준으로 파일을 필터링합니다.

3. 지원되는 각 파일에 대해 콘텐츠를 읽고 프로그래밍 언어를 결정합니다.

4. 이 명령은 세부 수준 및 길이 제한을 포함하여 요약하라는 메시지와 함께 코드를 Gemini Flash 2.0으로 전송합니다.

5. 요약은 수집되어 지정된 출력 파일에 기록됩니다.

출력 형식

출력 파일의 형식은 다음과 같습니다.

프로젝트 구조

• index.ts : 주요 CLI 구현

• src/ : 소스 코드 디렉토리

  • summarizer/ : 핵심 요약 기능

  • mcp/ : MCP 서버 구현

  • config/ : 구성 관리

• bin/ : CLI 진입점

• config.json : 기본 설정 파일

• tsconfig.json : TypeScript 구성

• package.json : 프로젝트 종속성 및 스크립트

• .env.example : 환경 변수 설정을 위한 템플릿

• .gitignore : Git에서 무시할 파일 및 디렉토리

• __tests__ : 단위 및 통합 테스트

• __mocks__/mock-codebase : 테스트를 위한 모의 코드베이스

환경 변수

다음 환경 변수를 사용하여 애플리케이션을 구성할 수 있습니다.

템플릿은 .env.example 참조하세요.

개발

테스트 실행

향후 개선 사항

• 더 많은 파일 유형 지원

• 대체 LLM 제공자 지원

• GUI 인터페이스를 위한 Electron 앱과의 통합

• 향상된 MCP 서버 기능

• 고급 토큰 사용 추적

• OpenTelemetry 기반 관찰성

• 향상된 감사 로깅 기능

• 비밀 스캐닝 통합