mcp-deepcontext

Claude Code에서 심볼 인식 의미론적 검색을 가능하게 하는 MCP 서버

동기

대부분의 코드 검색 도구는 코드를 텍스트로만 취급하여 코드를 의미 있게 만드는 의미론적 구조를 무시합니다. 대규모 코드베이스에서 작업할 때 단순히 문자열이 나타나는 위치를 찾는 것만으로는 부족합니다. 함수가 호출되는 위치, 타입이 구현된 위치, 또는 특정 심볼에 의존하는 모듈이 무엇인지 알고 싶을 것입니다.

이 MCP 서버는 Claude에게 의미론적 코드 분석 기능을 제공함으로써 이러한 간극을 메워줍니다. 텍스트를 grep하는 대신, Claude는 "이 인터페이스는 어디에 구현되어 있나요?" 또는 "이 함수의 호출자는 모두 누구인가요?"와 같은 질문을 하고 정확한 심볼 인식 결과를 얻을 수 있습니다. 이를 통해 익숙하지 않은 코드베이스에 대해서도 실제로 유용한 대화가 가능해집니다.

아키텍처

graph TD
    A[Claude Desktop] -->|MCP Protocol| B[mcp-deepcontext Server]
    B -->|Parse & Index| C[Symbol Database]
    B -->|AST Analysis| D[TypeScript Compiler API]
    B -->|Semantic Search| E[Vector Embeddings]
    
    C -->|Symbol Locations| B
    D -->|Type Information| B
    E -->|Similarity Scores| B
    
    F[Your Codebase] -->|Watch & Reindex| B

시작하기

설치

npm install -g mcp-deepcontext

퀵스타트

Claude Desktop 설정(~/Library/Application Support/Claude/claude_desktop_config.json)에 추가하세요:

{
  "mcpServers": {
    "deepcontext": {
      "command": "mcp-deepcontext",
      "args": ["--workspace", "/path/to/your/project"]
    }
  }
}

그런 다음 Claude Desktop을 재시작하세요. 서버가 시작 시 코드베이스를 인덱싱합니다.

작동 원리

이 서버는 TypeScript 컴파일러 API를 사용하여 코드베이스의 완전한 심볼 그래프를 구축합니다. 여기에는 타입 정의, 함수 시그니처, 클래스 계층 구조 및 임포트 관계가 포함됩니다. Claude가 정보를 쿼리하면 서버는 정확한 위치와 컨텍스트로 응답할 수 있습니다.

의미론적 검색을 위해 서버는 코드 심볼과 주변 컨텍스트에 대한 임베딩을 생성합니다. 이를 통해 정확한 텍스트 일치가 아닌 의도에 기반한 퍼지 매칭이 가능합니다. 심볼 데이터베이스는 파일 변경 사항을 감지하는 파일 감시자를 통해 증분 재인덱싱을 수행하여 동기화 상태를 유지합니다.

MCP 프로토콜은 search_symbols, find_references, get_definition, find_implementations와 같은 도구를 통해 이를 노출합니다. Claude는 이러한 도구를 연결하여 코드 구조와 관계에 대한 복잡한 질문에 답할 수 있습니다.

설정

서버는 다음과 같은 명령줄 인수를 허용합니다:

• --workspace <path>: 인덱싱할 프로젝트의 루트 디렉토리 (필수)

• --languages <list>: 인덱싱할 언어의 쉼표로 구분된 목록 (기본값: typescript,javascript)

• --exclude <patterns>: 제외할 Glob 패턴 (기본값: node_modules,dist,build,.git)

• --max-file-size <bytes>: 이 크기보다 큰 파일은 건너뜀 (기본값: 1MB)

• --embedding-model <name>: 임베딩에 사용할 모델 (기본값: text-embedding-3-small)

환경 변수:

• OPENAI_API_KEY: 임베딩 생성에 필수

• DEEPCONTEXT_LOG_LEVEL: 상세 로그를 보려면 debug로 설정

FAQ

Q: 어떤 언어가 지원되나요?

현재 TypeScript와 JavaScript에 대해 완전한 타입 인식을 지원합니다. Python과 Go 지원은 계획 중입니다.

Q: 대규모 코드베이스에서도 작동하나요?

네, 인덱싱은 증분 방식으로 이루어지며 심볼 데이터베이스는 효율적인 그래프 구조를 사용합니다. 50만 라인 규모의 코드베이스에서도 문제없이 테스트되었습니다.

Q: 임베딩 생성 비용은 얼마나 드나요?

일반적인 10만 라인 코드베이스의 경우, 초기 인덱싱 시 약 1만 개의 임베딩이 생성되며 text-embedding-3-small 기준으로 약 $0.02의 비용이 발생합니다. 증분 업데이트는 훨씬 저렴합니다.

Q: 임베딩 없이 사용할 수 있나요?

네, --no-embeddings를 전달하여 의미론적 검색을 비활성화할 수 있습니다. 여전히 참조 찾기 및 정의로 이동과 같은 모든 심볼 인식 도구를 사용할 수 있습니다.

Q: 이 도구가 내 코드를 외부 서비스로 전송하나요?

추출된 심볼 이름과 그 주변 컨텍스트만 임베딩 생성을 위해 OpenAI로 전송됩니다. 완전히 로컬에서 작동하려면 --no-embeddings를 사용하여 이를 비활성화할 수 있습니다.

라이선스

MIT