smart-coding-mcp: AI 어시스턴트를 위한 지능형 시맨틱 코드 검색 MCP 서버

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

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

IDE / App	설정 가이드 (Setup Guide)	`${workspaceFolder}` 지원
VS Code	[가이드 보기 (View Guide)]	✅ 예 (Yes)
Cursor	[가이드 보기 (View Guide)]	✅ 예 (Yes)
Windsurf	[가이드 보기 (View Guide)]	❌ 절대 경로만 가능 (Absolute paths only)
Claude Desktop	[가이드 보기 (View Guide)]	❌ 절대 경로만 가능 (Absolute paths only)
OpenCode	[가이드 보기 (View Guide)]	❌ 절대 경로만 가능 (Absolute paths only)
Raycast	[가이드 보기 (View Guide)]	❌ 절대 경로만 가능 (Absolute paths only)
Antigravity	[가이드 보기 (View Guide)]	❌ 절대 경로만 가능 (Absolute paths only)

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

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

IDE	OS	경로 (Path)
Claude Desktop	macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop	Windows	`%APPDATA%\Claude\claude_desktop_config.json`
OpenCode	Global	`~/.config/opencode/opencode.json`
OpenCode	Project	프로젝트 루트의 `opencode.json`
Windsurf	macOS	`~/.codeium/windsurf/mcp_config.json`
Windsurf	Windows	`%USERPROFILE%\.codeium\windsurf\mcp_config.json`

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

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

변수 (Variable)	기본값 (Default)	설명 (Description)
`SMART_CODING_VERBOSE`	`false`	상세 로깅 (detailed logging) 활성화
`SMART_CODING_MAX_RESULTS`	`5`	반환되는 최대 검색 결과 수
`SMART_CODING_BATCH_SIZE`	`100`	병렬로 처리할 파일 수
`SMART_CODING_MAX_FILE_SIZE`	`1048576`	최대 파일 크기 (바이트 단위, 1MB)
`SMART_CODING_CHUNK_SIZE`	`25`	청크 (chunk) 당 코드 라인 수
`SMART_CODING_EMBEDDING_DIMENSION`	`128`	MRL 차원 (64, 128, 256, 512, 768)
`SMART_CODING_EMBEDDING_MODEL`	`nomic-ai/nomic-embed-text-v1.5`	AI 임베딩 (embedding) 모델
`SMART_CODING_DEVICE`	`cpu`	추론 장치 (inference device) (`cpu`, `webgpu`, `auto`)
`SMART_CODING_SEMANTIC_WEIGHT`	`0.7`	시맨틱 (semantic) 대 정확한 일치 (exact matching) 가중치
`SMART_CODING_EXACT_MATCH_BOOST`	`1.5`	정확한 텍스트 일치에 대한 부스트 배수
`SMART_CODING_MAX_CPU_PERCENT`	`50`	인덱싱 (indexing) 중 최대 CPU 사용률 (10-100%)
`SMART_CODING_CHUNKING_MODE`	`smart`	코드 청킹 (code chunking) 모드 (`smart`, `ast`, `line`)
`SMART_CODING_WATCH_FILES`	`false`	파일 변경 시 자동 재인덱싱 (auto-reindex)
`SMART_CODING_AUTO_INDEX_DELAY`	`5000`	백그라운드 인덱싱 전 지연 시간 (ms), 비활성화하려면 `false` 설정

환경 변수를 사용한 예시:

{
"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)"]
...

구성 요소	기술
프로토콜 (Protocol)	Model Context Protocol (JSON-RPC)
AI 모델 (AI Model)	nomic-embed-text-v1.5 (MRL)
추론 (Inference)	transformers.js + ONNX Runtime
청킹 (Chunking)	Smart regex / Tree-sitter AST
검색 (Search)	코사인 유사도 (Cosine similarity) + 완전 일치 부스트 (exact match boost)
캐시 (Cache)	WAL 모드가 적용된 SQLite

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

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

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

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

smart-coding-mcp: AI 어시스턴트를 위한 지능형 시맨틱 코드 검색 MCP 서버

요약

핵심 포인트

댓글