ickyMCP

의미론적 문서 검색을 위한 RAG MCP 서버입니다. sqlite-vec을 사용하여 로컬 문서 컬렉션을 SQLite로 인덱싱한 다음, 인덱싱된 문서를 인덱싱, 검색, 새로 고침, 나열 및 삭제하기 위한 MCP 도구를 제공합니다.

기능

• PDF, Word, PowerPoint, Excel, Markdown 및 텍스트 파일에 대한 의미론적 검색

• 선택적 레거시 단일 데이터베이스 모드를 포함한 사용자별 데이터베이스 격리

• 채팅 또는 특정 사안 범위의 검색을 위한 문서 ID 필터

• 파일 크기 및 수정 시간을 기반으로 한 증분 인덱싱

• 기본적으로 Voyage AI 임베딩을 사용하며, 오프라인 로컬 sentence-transformers 백엔드 지원

• 무시된 로컬 데이터베이스 아티팩트가 포함된 휴대용 SQLite 저장소

Related MCP server: MCP-RAGNAR

설정

python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt

예제에서 로컬 환경 설정을 생성합니다:

copy .env.example .env

기본 Voyage 백엔드를 사용할 때 ICKY_VOYAGE_API_KEY를 설정하십시오. 오프라인 사용의 경우 ICKY_EMBEDDING_PROVIDER=local로 설정하십시오.

구성

Claude MCP 구성

{
  "mcpServers": {
    "ickyMCP": {
      "command": "python",
      "args": ["C:\\Users\\devan\\OneDrive\\Desktop\\Projects\\ickyMCP\\run.py"],
      "env": {
        "ICKY_EMBEDDING_PROVIDER": "voyage",
        "ICKY_VOYAGE_API_KEY": "YOUR_VOYAGE_API_KEY",
        "ICKY_CHUNK_SIZE": "5000",
        "ICKY_CHUNK_OVERLAP": "500"
      }
    }
  }
}

도구

• index: 파일 또는 디렉토리 인덱싱; user_id, patterns, exclude, force 허용

• search: 인덱싱된 청크에 대한 의미론적 쿼리; document_ids, path_filter, file_types 허용

• similar: 제공된 텍스트와 유사한 청크 찾기

• refresh: 변경된 파일 재인덱싱 및 인덱스에서 삭제된 파일 제거

• list: 인덱싱된 문서 및 해당 ID 나열

• delete: 경로, 문서 ID 또는 모든 문서별 삭제

• status: 데이터베이스, 임베딩 및 청킹 상태 반환

검증

python -m compileall -q src run.py fast_index.py
python -c "from src.config import EMBEDDING_PROVIDER; print(EMBEDDING_PROVIDER)"

루트의 test_*.py 파일은 docs/ 아래의 로컬 문서를 기대하며, 기본 백엔드의 경우 구성된 Voyage API 키를 기대하는 통합 스크립트입니다.

데이터 위생

생성된 데이터베이스 및 로컬 문서 폴더는 git에서 무시됩니다: *.db, *.db.bak, *.sqlite, *.sqlite3, data/, docs/. 실제 API 키는 추적되는 파일이 아닌 환경 변수나 .env에 보관하십시오.

라이선스

MIT