Integrations
Utilizes .env files for configuration management, particularly for storing API keys like the OpenAI API key
Supports cloning repositories from GitHub to be used as part of the documentation corpus, with examples showing direct integration with Swarms, Autogen, LangGraph, and OpenAI repositories
Provides access to LangGraph documentation through dedicated corpus integration, enabling agents to efficiently retrieve information about this framework
🐝 Swarms MCP Documentation Server
📖 Description
This program is an Agent Framework Documentation MCP Server built on FastMCP, designed to enable AI agents to efficiently retrieve information from your documentation database. It combines hybrid semantic (vector) and keyword (BM25) search, chunked indexing, and a robust FastMCP tools API for seamless agent integration.
Key Capabilities:
- Efficient, chunk-level retrieval using both semantic and keyword search
- Agents can query, list, and retrieve documentation using FastMCP tools
- Local-first, low-latency design (all data indexed and queried locally)
- Automatic reindexing on file changes
- Modular: add any repos to
corpora/
, support for all major filetypes - Extensible: add new tools, retrievers, or corpora as needed
Main modules:
embed_documents.py
→ Loads, chunks, and embeds documentsswarms_server.py
→ Brings up the MCP server and FastMCP tools
🌟 Key Features
- Hybrid Retriever 🔍: Combines semantic and keyword search.
- Dynamic Markdown Handling 📄: Smart loader based on file size.
- Specialized Loaders ⚙️:
.py
,.ipynb
,.md
,.txt
,.yaml
,.yml
. - Chunk and File Summaries 📈: Displays chunk counts along with file counts.
- Live Watchdog 🔥: Instantly responds to any changes in
corpora/
. - User Confirmation for Costs ✅: Confirms before expensive embeddings.
- Healthcheck Endpoint 🚑: Ensure server is ready for use.
- Local-First 🗂️: All repos indexed locally without external dependencies.
- Safe Deletion Helper 🔥: Auto-delete broken/mismatched indexes.
🏗️ Version History
Version | Date | Highlights |
---|---|---|
2.2 | 2025‑04‑25 | Split embed/load from server; full chunk counting in loading summaries |
1.0 | 2025‑04‑25 | Dynamic Markdown loader, color logs, Healthcheck tool |
0.7 | 2025‑04‑25 | Specialized file loaders for .py , .ipynb , .md |
0.5 | 2025‑04‑10 | OpenAI large model embeddings, extended MCP tools |
0.1 | 2025‑04‑10 | Initial version with generic loaders |
📚 Managing Your Corpora (Local Repos)
Because Swarms and other frameworks are very large, full corpora are not pushed to GitHub.
Instead, you clone them manually under corpora/
:
✅ Notes:
- Add any repo — public, private, custom.
- Build your own custom AI knowledge base locally.
- Large repos (>500MB) are fine; all indexing is local.
🚀 Quick Start
⚙️ Configuration
- Corpus: Drop repos inside
corpora/
- Environment Variables:
.env
must containOPENAI_API_KEY
- Index File Support:
- Both
chroma-collections.parquet
andchroma.sqlite3
are supported..parquet
is preferred if both exist.
- Both
- Auto-Embedding:
- If no index is found, the server will prompt you to embed and index your documents automatically.
- Optional:
- Disable Chroma compaction if you prefer:Copy
- Disable Chroma compaction if you prefer:
- Command-Line Flags:
--reindex
→ trigger a refresh reindex during server run.
🔄 File Watching & Auto Reindexing
The MCP Server watches corpora/
for any file changes:
- Any modification, creation, or deletion triggers a live reindex.
- No need to restart the server.
🛠️ Available FastMCP Tools
Tool | Description |
---|---|
swarm_docs.search | Search relevant documentation chunks |
swarm_docs.list_files | List all indexed files |
swarm_docs.get_chunk | Get a specific chunk by path and index |
swarm_docs.reindex | Force reindex (full or incremental) |
swarm_docs.healthcheck | Check MCP Server status |
❓ Troubleshooting
- Q: I get 'No valid existing index found' when starting the server.
- A: The server will now prompt you to embed and index documents. Accept the prompt to proceed, or run
python embed_documents.py
manually first.
- A: The server will now prompt you to embed and index documents. Accept the prompt to proceed, or run
- Q: Which index file is used?
- A: The server will use
chroma-collections.parquet
if available, otherwisechroma.sqlite3
.
- A: The server will use
- Q: I want to force a reindex.
- A: Run
python swarms_server.py --reindex
or use theswarm_docs.reindex
tool.
- A: Run
📋 Example Usage
🧰 Extending & Rebuilding
- Add new docs → drop into
corpora/
, then:Copy - Schema changes → (e.g. different metadata structure):Copy
- Add new repo → Drop folder under
corpora/
, reindex. - Recommended for mostly read-only repos:Copy
🔗 IDE Integration
Plug directly into Windsurf Cascade:
Then you can access swarm_docs.*
tools from Cascade automations.
📦 Requirements
💡 Python 3.11 Environment Required
Create your environment explicitly:
Then install with:
✅ MCP Server Ready
After boot:
- Proper loading summaries
- Safe confirmation before expensive actions
- Auto file watching and reindexing
- Windsurf plug-in ready
- Full tool coverage
You're good to cascade it! 🏄♂️
📈 Flow Diagram
This server cannot be installed
An Agent Framework Documentation server that enables AI agents to efficiently retrieve information from documentation databases using hybrid semantic and keyword search for seamless agent integration.
Related MCP Servers
- AsecurityAlicenseAqualityAn MCP server implementation that provides tools for retrieving and processing documentation through vector search, enabling AI assistants to augment their responses with relevant documentation contextLast updated -76281TypeScriptMIT License
- -securityFlicense-qualityA Model Context Protocol server utilizing Claude AI for generating intelligent queries and offering documentation assistance based on API documentation analysis.Last updated -32TypeScript
- -securityFlicense-qualityEnables AI assistants to enhance their responses with relevant documentation through a semantic vector search, offering tools for managing and processing documentation efficiently.Last updated -6213TypeScript
- -securityFlicense-qualityA smart documentation server that provides AI-assisted code improvement and documentation management through Claude Desktop integration.Last updated -7TypeScript