AI 어시스턴트를 위해 지능형 시맨틱 (Semantic) 코드 검색을 제공하는 확장 가능한 Model Context Protocol (MCP) 서버입니다. 유연한 임베딩 (Embedding) 차원(64-768d)을 위해 Matryoshka Representation Learning (MRL)을 사용하여 로컬 AI 모델로 구축되었습니다.

AI 코딩 어시스턴트는 관련 코드를 빠르게 찾을 수 있을 때 더 잘 작동합니다. 전통적인 키워드 검색은 한계가 있습니다. 예를 들어 "인증(authentication)은 어디서 처리하나요?"라고 물었을 때, 코드에서 "login"이나 "session"이라는 용어를 사용한다면 키워드 검색은 이를 놓치게 됩니다.

이 MCP 서버는 AI 임베딩 (Embeddings)으로 코드베이스를 인덱싱하여 이 문제를 해결합니다. 귀하의 AI 어시스턴트는 정확한 키워드 대신 의미(Meaning)를 기반으로 검색할 수 있어, 용어가 다르더라도 관련 코드를 찾아낼 수 있습니다.

코드베이스 탐색을 위한 주요 도구입니다. 단순히 키워드를 매칭하는 것이 아니라, AI 임베딩 (Embeddings)을 사용하여 사용자가 무엇을 찾고 있는지 이해합니다.

작동 방식: 자연어 쿼리를 벡터 (Vector)로 변환한 다음, 코사인 유사도 (Cosine similarity)와 정확한 일치 부스팅 (Exact match boosting)을 사용하여 의미가 유사한 코드 청크 (Code chunks)를 찾습니다.

최적의 용도:

• 익숙하지 않은 코드베이스 탐색:
  "How does authentication work?" (인증은 어떻게 작동하나요?)

• 관련 코드 찾기:
  "Where do we validate user input?" (사용자 입력을 어디서 검증하나요?)

• 개념적 검색:
  "error handling patterns" (에러 처리 패턴)

• 오타가 있어도 작동:
  "embeding modle initializashun" (임베딩 모델 초기화)

여전히 임베딩 코드를 찾아냅니다.

쿼리 예시:

"Where do we handle cache persistence?"
"How is the database connection managed?"
"Find all API endpoint definitions"

공식 레지스트리에서 모든 패키지의 최신 버전을 가져옵니다. 20개 이상의 생태계(Ecosystems)를 지원합니다.

작동 방식: 공식 패키지 레지스트리(npm, PyPI, Crates.io 등)를 실시간으로 조회합니다. 추측하거나 오래된 학습 데이터를 사용하지 않습니다.

지원되는 생태계: npm, PyPI, Crates.io, Maven, Go, RubyGems, NuGet, Packagist, Hex, pub.dev, Homebrew, Conda 등.

최적의 용도:

• 의존성(Dependencies)을 추가하기 전:
  "express"

→ 4.18.2

• 업데이트 확인:
  "pip:requests"

→ 2.31.0

• 멀티 생태계 프로젝트:
  "npm:react",
  "go:github.com/gin-gonic/gin"

사용 예시:

"lodash의 최신 버전은 무엇인가요?"
"axios의 더 새로운 버전이 있는지 확인해 주세요"

코드베이스의 전체 재인덱싱 (reindex)을 트리거합니다. 인덱싱은 자동적이고 점진적(incremental)으로 이루어지므로 일반적으로는 필요하지 않습니다.

작동 방식: 모든 파일을 스캔하고, 새로운 임베딩 (embeddings)을 생성하며, SQLite 캐시를 업데이트합니다. 점진적 인덱싱 (progressive indexing)을 사용하여 인덱싱이 실행되는 동안에도 검색이 가능합니다.

사용 시점:

• 대규모 리팩토링 (refactoring) 또는 브랜치 전환 후
• 원격 저장소로부터 대규모 변경 사항을 가져온 (pull) 후
• 검색 결과가 오래되었거나 불완전해 보일 때
• 임베딩 설정 (차원 (dimension), 모델 (model))을 변경한 후

임베딩 캐시를 완전히 삭제하여, 다음 검색 시 전체 재인덱싱을 강제합니다.

작동 방식: .smart-coding-cache/ 디렉토리를 삭제합니다. 다음 검색 또는 인덱싱 작업이 새로 시작됩니다.

사용 시점:

• 캐시 손상 (드물지만 발생 가능함)
• 임베딩 모델 또는 차원 변경 시
• 대규모 코드베이스 구조 재편성 후 새로 시작할 때
• 검색 문제 해결 (troubleshooting) 시

서버를 재시작하지 않고 런타임 (runtime) 중에 워크스페이스 (workspace) 경로를 변경합니다.

작동 방식: 내부 워크스페이스 참조를 업데이트하고, 새 경로에 대한 캐시 폴더를 생성하며, 선택적으로 재인덱싱을 트리거합니다.

사용 시점:

• 한 세션 내에서 여러 프로젝트를 작업할 때
• 모노레포 (Monorepo) 내 패키지 간 이동 시
• 관련된 저장소 (repositories) 간 전환 시

MCP 서버에 대한 종합적인 상태 정보를 반환합니다.

표시 정보:

• 서버 버전 및 가동 시간 (uptime)
• 워크스페이스 경로 및 캐시 위치
• 인덱싱 상태 (준비됨, 인덱싱 중, 완료 백분율)
• 인덱싱된 파일 수 및 청크 (chunk) 수
• 모델 설정 (이름, 차원, 장치)
• 캐시 크기 및 유형

사용 시점:

• 모든 기능이 정상 작동하는지 확인하기 위한 세션 시작 시
• 연결 또는 인덱싱 문제 디버깅 (debugging) 시
• 대규모 코드베이스의 인덱싱 진행 상황 확인 시

npm install -g smart-coding-mcp

업데이트 방법:

npm update -g smart-coding-mcp

선호하는 환경에 대한 상세 설정 지침:

MCP 설정 파일(config file)에 추가하세요:

{
"mcpServers": {
"smart-coding-mcp": {
...

{
"mcpServers": {
"smart-coding-frontend": {
...

환경 변수 (environment variables)를 통해 동작을 사용자 정의하세요:

환경 변수를 사용한 예시:

{
"mcpServers": {
"smart-coding-mcp": {
...

점진적 인덱싱 (Progressive Indexing) - 인덱싱이 백그라운드에서 계속 진행되는 동안 즉시 검색이 가능합니다. 대규모 코드베이스를 기다릴 필요가 없습니다.

리소스 스로틀링 (Resource Throttling) - 기본적으로 CPU 사용량이 50%로 제한됩니다. 인덱싱 중에도 컴퓨터의 반응성을 유지합니다.

SQLite 캐시 (SQLite Cache) - JSON보다 5~10배 빠릅니다. 이전 JSON 캐시로부터 자동 마이그레이션(migration)을 지원합니다.

증분 업데이트 (Incremental Updates) - 변경된 파일만 재인덱싱합니다. 5개 배치마다 저장하므로 중단되더라도 데이터 손실이 없습니다.

최적화된 기본값 (Optimized Defaults) - 128차원 임베딩 (품질 저하를 최소화하면서 256차원보다 2배 빠름), 스마트 배치 크기 조정, 병렬 처리.

flowchart TB
subgraph IDE["IDE / AI Assistant"]
Agent["AI Agent<br/>(Claude, GPT, Gemini)"]
...

모든 기능은 **100% 로컬 (locally)**에서 실행됩니다:

• AI 모델이 사용자의 기기에서 실행됩니다 (API 호출 없음)
• 코드는 시스템을 절대 벗어나지 않습니다
• 텔레메트리 (Telemetry) 또는 분석 데이터 수집이 없습니다
• 캐시는 .smart-coding-cache/에 저장됩니다

이 프로젝트는 시맨틱 검색 (semantic search)이 AI 코딩 에이전트의 성능을 평균 12.5% 향상시킨다는 Cursor의 연구를 바탕으로 구축되었습니다. 핵심 통찰은 다음과 같습니다: AI 어시스턴트는 컨텍스트의 방대한 양보다 관련성 있는 (relevant) 컨텍스트로부터 더 큰 도움을 받습니다.

MIT License - Copyright (c) 2025 Omar Haris

전체 텍스트는 LICENSE를 참조하세요.