LSP(Language Server Protocol)의 파싱 능력과 자체 LLM 에이전트 추론망을 병합하여, 파일 트리의 호출 계층(Call Hierarchy) 및 각 메서드의 역할을 그래프 및 시맨틱 벡터 저장소에 구조화하는 인덱싱 시스템입니다.
- LSP 인덱서 (
src/indexer):typescript-language-server등 네이티브 언어 서버를 스폰하여 로컬 타겟 코드의 심볼과 호출 의존성(outgoingCalls)을 정확하게 역추적함. - PostgreSQL / Apache AGE (
src/db): 추출된 호출망을 Cypher 문법의 N-Depth 관계로codesexer_graph공간에 투영하고, 연계된 메타데이터를 아웃박스 테이블(sync_events) 트랜잭션으로 적재함. - Outbox Poller (
src/worker): LLM 트래픽 포화를 방지하기 위해 분리된 모듈. PENDING 이벤트 레코드를SKIP LOCKED로 격리하여 1건씩 안전하게 가져옴. - Ollama / OpenSearch: 발췌한 코드 원문을 기반으로 LLM(
qwen3.5:35b등)을 이용해 함수 동작 원리와 목적을 생성하고, 추출된 1024D 벡터(qwen3-embedding)를 결합하여 OpenSearch에 적재(BM25/k-NN 혼합)함.
인덱서를 구동하기 위한 전제 조건 런타임들이 전역 변수(PATH) 레벨에서 해금되어 있어야 합니다.
- 인프라 필수 조건: Docker/Docker Compose, Node.js (v18+)
- 타겟 랭귀지 서버 (Language Servers):
- TypeScript / Node.js
npm install -g typescript-language-server typescript
- Go
go install golang.org/x/tools/gopls@latest
- PHP
npm install -g intelephense
- C / C++ (Windows 전용 설치)
winget install -e --id LLVM.LLVM
- TypeScript / Node.js
- 프로젝트 루트 기준
.env파일 환경(데이터베이스 자격증명 및 API 주소)을 설정합니다. - 베이스 컨테이너 띄우기:
docker-compose up -d- PostgreSQL/AGE 스키마 체계화 및 Outbox 테이블 마이그레이션 적용:
npm run db:initOllama에 쿼리하여 설명 및 벡터를 할당할 처리기가 필수적으로 백그라운드 구동 중이어야 합니다.
npm run start:worker로컬 루트(/)에 대한 문맥 분석 트리거는 다음 스크립트들을 통해 작동합니다. 분석 엔진은 자동적으로 src/indexer/runner.js에 주입되어 구문 트리를 따라갑니다.
npm run index:ts(TypeScript/JavaScript 전용 인덱싱)npm run index:cpp(C/C++ 전용 인덱싱)npm run index:go(Go 전용 인덱싱)npm run index:php(PHP 전용 인덱싱)
이 프로젝트는 Cursor, Claude Desktop 등의 LLM 에이전트가 직접 상호작용할 수 있는 MCP 서버를 지원합니다.
에이전트의 MCP 서버 등록 설정에서 command 유형을 선택하고 패키지 내부 스크립트를 지정합니다.
명령어: node [절대경로]/src/mcp/server.js
(터미널 Stdout 오염을 피하기 위해 npm run start:mcp 사용 대신 반드시 직접 node 바이너리를 호출하십시오.)
설치 없이 런타임에 직접 코드를 당겨와 구동할 수 있습니다.
명령어: npx github:snowmerak/codesexer
[주의점] npx 실행 시 환경변수(Env) 통제 npx를 통해 원격으로 MCP 서버를 기동시키면 로컬의
.env파일을 읽을 수 없으므로, 에디터의 MCP 설정(Env 탭)에 다음과 같은 필수 인프라 포인터를 명시적으로 제공해야 서버가 죽지 않습니다.
PG_HOST,PG_PORT,PG_USER,PG_PASSWORD,PG_DATABASE: PostgreSQL AGE 목적지 엔드포인트OS_NODE: OpenSearch 3.x 클러스터 주소 (ex:https://localhost:9200)OS_USERNAME,OS_PASSWORD: 인증 정보OLLAMA_BASE_URL: 임베딩 추출 워커 주소 (ex:http://localhost:11434/v1)
기본적으로 .env 환경 변수 속성을 통해 동적인 언어 모델 및 임베딩 모델 교체를 지원합니다.
OLLAMA_CHAT_MODEL: 분석 및 요약을 담당할 텍스트 추론 모델 (예:llama3,qwen3.5:35b등)OLLAMA_EMBEDDING_MODEL: 벡터 치환을 담당할 임베딩 모델명 (예:nomic-embed-text,text-embedding-3-small등)OLLAMA_EMBEDDING_DIM: 해당 임베딩 모델이 반환하는 공간 벡터 차원 수 (기본값:1024)
[주의] OpenSearch 매핑 불변성 한 번 생성된 OpenSearch 인덱스의 차원 수(
dimension)는 사후 수정이 불가능합니다. 만약 모델 교체로 인해 벡터 크기가 변경된 경우, 데이터베이스 초기화 명령을 통해 기존 인덱스를 날린 후 워커를 재가동해야 합니다.curl -X DELETE -k -u admin:Str0ngP@ssw0rd! https://localhost:9200/codesexer_symbols