Swarms

You run a local, fast MCP server that lets AI agents query your documentation and code repositories. It combines semantic and keyword search for chunked results, watches for file changes to auto-reindex, and exposes a set of FastMCP tools you can call from your agent or automation scripts. Everything stays local, with low latency and offline-friendly indexing, so you can build a private knowledge base from corpora you control.

How to use

Start the MCP server from your local environment and use an MCP client to send tool requests. You can search for relevant documentation chunks, list indexed files, retrieve specific chunks by path and index, and trigger index refreshes. The server will handle embedding requests and return structured results that your agent can consume.

How to install

# 1. Create and activate a Python virtual environment
python3 -m venv venv
source venv/bin/activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure your OpenAI API key
# Create a file named .env at the project root with the following line
OPENAI_API_KEY=sk-...

# 4. Prepare and embed documents
python embed_documents.py

# 5. Start the MCP server
python swarms_server.py

Configuration and usage notes

Environment variables and file setup are essential for a smooth run. Place repositories under corpora/ to be indexed. The server uses local indexing files, and you can reindex automatically when files change. If you do not have an index yet, you will be prompted to embed and index documents when starting the server.

File watching, reindexing, and health

The MCP Server monitors the corpora/ folder for changes. Any modification, addition, or removal triggers an automatic reindex without restarting the server. Use the healthcheck tool to verify the server is ready for queries.

Troubleshooting

If the server cannot find a valid index on startup, it will prompt you to embed and index documents. You can also manually run the embedding step before starting the server to ensure an index exists.

Examples of typical usage

# Search for documentation chunks about notebooks
result = swarm_docs.search("How do I load a notebook?")
print(result)

# List all indexed 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"])

Available tools

swarm_docs.search

Search relevant documentation chunks within the indexed corpora

swarm_docs.list_files

List all indexed files currently available in the MCP store

swarm_docs.get_chunk

Retrieve a specific chunk by its file path and index position

swarm_docs.reindex

Force a reindex of all or changed documents to refresh results

swarm_docs.healthcheck

Check MCP Server status and readiness