🐝 Swarms MCP 문서 서버
📖 설명
이 프로그램은 FastMCP 기반으로 구축된 에이전트 프레임워크 문서화 MCP 서버로, AI 에이전트가 문서 데이터베이스에서 정보를 효율적으로 검색할 수 있도록 설계되었습니다. 하이브리드 시맨틱(벡터) 및 키워드(BM25) 검색, 청크 인덱싱, 그리고 원활한 에이전트 통합을 위한 강력한 FastMCP 도구 API를 결합합니다.
주요 역량:
- 의미 검색과 키워드 검색을 모두 사용한 효율적인 청크 수준 검색
- 에이전트는 FastMCP 도구를 사용하여 문서를 쿼리, 나열 및 검색할 수 있습니다.
- 로컬 우선, 저지연 디자인(모든 데이터가 로컬에서 인덱싱 및 쿼리됨)
- 파일 변경 시 자동 재색인화
- 모듈식:
corpora/ 에 모든 저장소 추가, 모든 주요 파일 유형 지원 - 확장 가능: 필요에 따라 새로운 도구, 검색기 또는 코퍼스 추가
주요 모듈:
embed_documents.py → 문서를 로드, 청크 및 임베드합니다.swarms_server.py → MCP 서버와 FastMCP 도구를 불러옵니다.
🌟 주요 특징
- 하이브리드 리트리버 🔍: 의미 검색과 키워드 검색을 결합했습니다.
- 동적 마크다운 처리 📄: 파일 크기에 따른 스마트 로더.
- 특수 로더 ⚙️:
.py , .ipynb , .md , .txt , .yaml , .yml . - 청크 및 파일 요약 📈: 파일 수와 함께 청크 수를 표시합니다.
- 라이브 워치독 🔥:
corpora/ 의 모든 변경 사항에 즉시 대응합니다. - 비용에 대한 사용자 확인 ✅: 값비싼 임베딩 전에 확인합니다.
- Healthcheck Endpoint 🚑: 서버가 사용 가능한지 확인합니다.
- 로컬 우선 🗂️: 모든 저장소가 외부 종속성 없이 로컬에서 색인됩니다.
- 안전 삭제 도우미 🔥: 손상되었거나 일치하지 않는 인덱스를 자동으로 삭제합니다.
🏗️ 버전 기록
| 버전 | 날짜 | 하이라이트 |
|---|
| 2.2 | 2025‑04‑25 | 서버에서 임베드/로드 분할, 로딩 요약에서 전체 청크 계산 |
| 1.0 | 2025‑04‑25 | 동적 마크다운 로더, 색상 로그, Healthcheck 도구 |
| 0.7 | 2025‑04‑25 | .py , .ipynb , .md 용 특수 파일 로더 |
| 0.5 | 2025‑04‑10 | OpenAI 대규모 모델 임베딩, 확장된 MCP 도구 |
| 0.1 | 2025‑04‑10 | 일반 로더가 포함된 초기 버전 |
📚 코퍼라(로컬 리포지토리) 관리
Swarms와 다른 프레임워크는 매우 크기 때문에 전체 코퍼스가 GitHub에 푸시되지 않습니다 .
대신, corpora/ 에서 수동으로 복제합니다 .
지엑스피1
✅ 참고사항:
- 공개, 비공개, 사용자 정의 등 모든 저장소를 추가합니다.
- 로컬에서 맞춤형 AI 지식 기반을 구축하세요.
- 대용량 저장소 (500MB 이상)는 괜찮습니다. 모든 인덱싱은 로컬에서 수행됩니다.
🚀 빠른 시작
# 1. Activate virtual environment
venv\Scripts\Activate.ps1
# 2. Install all dependencies
pip install -r requirements.txt
# 3. Configure OpenAI API Key
echo OPENAI_API_KEY=sk-... > .env
# 4. (Load and embed documents
python embed_documents.py
# 5. Start MCP server
python swarms_server.py
# If no index is found, the server will prompt you to embed documents automatically.
⚙️ 구성
- Corpus :
corpora/ 내부에 저장소 삭제 - 환경 변수 :
.env 에는 OPENAI_API_KEY 포함되어야 합니다.
- 인덱스 파일 지원 :
chroma-collections.parquet 과 chroma.sqlite3 가 모두 지원됩니다. 둘 다 존재하는 경우 .parquet 사용하는 것이 좋습니다.
- 자동 임베딩 :
- 인덱스를 찾을 수 없는 경우 서버에서 자동으로 문서를 임베드하고 인덱싱하라는 메시지를 표시합니다.
- 선택 사항 :
- 원하는 경우 Chroma 압축을 비활성화하세요.
setx CHROMA_COMPACTION_SERVICE__COMPACTOR__DISABLED_COLLECTIONS "swarms_docs"
- 명령줄 플래그 :
--reindex → 서버 실행 중에 새로 고침 재인덱스를 트리거합니다.
🔄 파일 감시 및 자동 재색인화
MCP 서버는 corpora/ 파일 변경 사항을 감시합니다.
- 모든 수정, 생성 또는 삭제는 라이브 재색인을 트리거합니다.
- 서버를 다시 시작할 필요가 없습니다.
🛠️ 사용 가능한 FastMCP 도구
| 도구 | 설명 |
|---|
swarm_docs.search | 관련 문서 청크 검색 |
swarm_docs.list_files | 모든 인덱스된 파일 나열 |
swarm_docs.get_chunk | 경로 및 인덱스로 특정 청크 가져오기 |
swarm_docs.reindex | 강제 재색인화(전체 또는 증분) |
swarm_docs.healthcheck | MCP 서버 상태 확인 |
❓ 문제 해결
- 질문: 서버를 시작할 때 '유효한 기존 인덱스를 찾을 수 없습니다'라는 메시지가 나타납니다.
- A: 이제 서버에서 문서를 임베드하고 색인화하라는 메시지를 표시합니다. 메시지를 수락하여 계속 진행하거나, 먼저
python embed_documents.py 수동으로 실행하세요.
- 질문: 어떤 인덱스 파일을 사용하나요?
- A: 서버는 사용 가능한 경우
chroma-collections.parquet 사용하고, 그렇지 않은 경우 chroma.sqlite3 합니다.
- 질문: 강제로 재색인을 실행하고 싶습니다.
- 답변:
python swarms_server.py --reindex 실행하거나 swarm_docs.reindex 도구를 사용하세요.
📋 사용 예시
# Search the documentation
result = swarm_docs.search("How do I load a notebook?")
print(result)
# List all available files
files = swarm_docs.list_files()
print(files)
# Get a specific document chunk
chunk = swarm_docs.get_chunk(path="examples/agent.py", chunk_idx=2)
print(chunk["content"])
🧰 확장 및 재구축
- 새로운 문서를 추가 →
corpora/ 에 넣은 후:python swarms_server.py --reindex
- 스키마 변경 → (예: 다른 메타데이터 구조):
python swarms_server.py --reindex --full
- 새로운 저장소 추가 →
corpora/ 아래에 폴더를 끌어다 놓고 다시 색인합니다. - 주로 읽기 전용 저장소에 권장됩니다 .
setx CHROMA_COMPACTION_SERVICE__COMPACTOR__DISABLED_COLLECTIONS "swarms_docs"
🔗 IDE 통합
Windsurf Cascade에 직접 연결:
"swarms": {
"command": "C:/…/Swarms/venv/Scripts/python.exe",
"args": ["swarms_server.py"]
}
그러면 Cascade 자동화에서 swarm_docs.* 도구에 액세스할 수 있습니다.
📦 요구 사항
💡 Python 3.11 환경 필요
환경을 명시적으로 생성하세요.
다음으로 설치합니다.
pip install -r requirements.txt
✅ MCP 서버 준비 완료
부팅 후:
- 적절한 로딩 요약
- 비용이 많이 드는 작업 전 안전한 확인
- 자동 파일 감시 및 재색인화
- 윈드서핑 플러그인 준비 완료
- 전체 도구 적용
캐스케이드를 사용해 보세요! 🏄♂️
📈 흐름도
+------------------+
| 🖥️ MCP Server |
+------------------+
|
+---------------------------------------------------+
| |
+-------------+ +-----------------+
| 📁 Corpora | | 🔎 FastMCP Tools |
| Folder | | (search, list, |
| (markdown, | | get_chunk, etc.) |
| code, etc) | +-----------------+
+-------------+ |
| |
+-----------------+ +----------------+
| 📚 Loaders | | 🧠 Ensemble |
| (Python, MD, TXT)| | Retriever (BM25|
| Split into Chunks| | + Chroma) |
+-----------------+ +----------------+
| |
+-----------------+ +----------------+
| ✂️ Text Splitter | | 🧩 Similarity |
| (RecursiveCharacter) | | Search (chunks) |
+-----------------+ +----------------+
| |
+-----------------+ +----------------+
| 💾 Embed chunks | —OpenAI Embedding (small)—> | 🛢️ Chroma Vector |
| via OpenAI API | | DB (Local Store) |
+-----------------+ +----------------+
| |
+-----------------+ +----------------+
| 📡 Reindex Watcher| | 👀 File Watchdog |
| (Auto detect | | (Auto reindex |
| new/modified files| | on file events) |
+-----------------+ +----------------+