🐝 Swarms MCP 문서 서버

버전 2.2

📖 설명

이 프로그램은 FastMCP 기반으로 구축된 에이전트 프레임워크 문서화 MCP 서버로, AI 에이전트가 문서 데이터베이스에서 정보를 효율적으로 검색할 수 있도록 설계되었습니다. 하이브리드 시맨틱(벡터) 및 키워드(BM25) 검색, 청크 인덱싱, 그리고 원활한 에이전트 통합을 위한 강력한 FastMCP 도구 API를 결합합니다.

주요 역량:

의미 검색과 키워드 검색을 모두 사용한 효율적인 청크 수준 검색
에이전트는 FastMCP 도구를 사용하여 문서를 쿼리, 나열 및 검색할 수 있습니다.
로컬 우선, 저지연 디자인(모든 데이터가 로컬에서 인덱싱 및 쿼리됨)
파일 변경 시 자동 재색인화
모듈식: corpora/ 에 모든 저장소 추가, 모든 주요 파일 유형 지원
확장 가능: 필요에 따라 새로운 도구, 검색기 또는 코퍼스 추가

주요 모듈:

embed_documents.py → 문서를 로드, 청크 및 임베드합니다.
swarms_server.py → MCP 서버와 FastMCP 도구를 불러옵니다.

Related MCP server: MCP Expert Server

🌟 주요 특징

하이브리드 리트리버 🔍: 의미 검색과 키워드 검색을 결합했습니다.
동적 마크다운 처리 📄: 파일 크기에 따른 스마트 로더.
특수 로더 ⚙️: .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 환경 필요

환경을 명시적으로 생성하세요.

python3.11 -m venv venv

다음으로 설치합니다.

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) |
+-----------------+                                   +----------------+

Swarms MCP Documentation Server