RAGSync

Configuration-driven RAG MCP server — ingest, watch, and search arbitrary knowledge sources behind a stable tool surface.

- Broad source support— index local folders (text, PDF, Markdown) and web pages; not limited to a single file type or format
- Config-driven— one YAML file defines sources, chunking strategy, embedding model, and vector store; no code required
- Live reload— filesystem watching and polling keep the index current as sources change; editing the config itself applies changes without a restart
- Flexible embeddings— localfastembedworks out of the box with no API key; swap in OpenAI or Voyage per source
- Stable MCP tool surface— five source-agnostic tools (search,list_sources,get_document,get_index_status,reindex) that never change as sources are added

The fastest way is withuvx— no clone or install step:

{ "mcpServers": { "ragsync": { "command": "uvx", "args": ["ragsync", "--config", "/abs/path/to/config.yaml"] } } }

Paths inside the config are resolved against the config file's directory(not the client's working directory), so a config can live in the repo and reference repo content with relative paths likepath: ./docs. Give--configitself anabsolutepath, though — the client chooses where it launches the server from, so that's the one path it must be able to find unambiguously.

Pin a version with"ragsync@0.2.0"if you want reproducible launches. (If the client can't finduvxon itsPATH, use the absolute path to theuvxbinary —which uvx.)

Option B — run in place with uv (no install, from a clone)

uv run --directoryruns the server from the cloned repo without installing it:

{ "mcpServers": { "ragsync": { "command": "uv", "args": [ "run", "--directory", "/abs/path/to/ragsync-mcp", "ragsync", "--config", "/abs/path/to/ragsync-mcp/examples/config.example.yaml" ] } } }

uv tool install ragsync # from PyPI; or a local path to a clone

{ "mcpServers": { "ragsync": { "command": "ragsync", "args": ["--config", "/abs/path/to/config.yaml"] } } }

(Equivalently,"command": "python","args": ["-m", "ragsync_mcp", "--config", "…"]if the package is installed in the active environment.)

Foropenai/voyagesources, the config names an env var (api_key_env) rather than the key itself. Provide that variable to the subprocess viaenv:

{ "mcpServers": { "ragsync": { "command": "ragsync", "args": ["--config", "/abs/path/to/config.yaml"], "env": { "OPENAI_API_KEY": "sk-..." } } } }

After saving, restart/reload the client. It will list the five tools (search,list_sources,get_document,get_index_status,reindex); the agent callssearchto answer questions from your indexed sources. First launch downloads the local embedding model, so initial startup can take a little longer.

A single YAML file defines globaldefaultsand a list ofsources. Each source becomes one searchable collection with its own loader, chunking, embedding model, vector-store collection, and watcher. Per-source isolation lets different sources use different embedding models safely.

defaults: chunking: strategy: recursive_character chunk_size: 800 chunk_overlap: 100 embedding: provider: fastembed model: BAAI/bge-small-en-v1.5 } vector_store: backend: chroma persist_directory: ./vector_db sources: - name: product-docs type: folder description: Product documentation and how-to guides. connection: path: ./docs # relative to the config file's directory include: ["/.md"] exclude: ["/internal/"] watch: enabled: true mode: filesystem chunking: strategy: markdown chunk_size: 1000 chunk_overlap: 150 vector_store: collection: product_docs metadata: product: example audience: public

- search— semantic search across one or all sources, with optional metadata filtering. Returns results with normalized[0, 1]scores.
- list_sources— discover available sources and their health/metadata.
- get_document— fetch a full document aftersearchsurfaces a chunk.
- get_index_status— indexing freshness/health for one source or all.
- reindex*— force a full re-scan of a source.

Tools return structured{"error": "..."}objects rather than raising, so the calling agent can recover conversationally.

Per-source isolation is a security boundary: scope access by running separate server instances with separate configs. There is no cross-instance "search everything" path.

uv sync --extra dev # install test dependencies uv run pytest

Tests run fully offline by injecting a deterministic embedder in place of fastembed (seetests/conftest.py). The architecture and extension contract — how to add a new source type — are documented inAGENTS.md.

Releases are automated fromConventional Commits. CI (.github/workflows/ci.yml) runs the test suite on every pull request. On merge tomain, the release workflow (.github/workflows/release.yml) runs the tests again, thenpython-semantic-releaseinspects the commits since the last tag and decides the next version:

Creates a personal, always-current knowledge base for AI by indexing documentation from websites, GitHub, npm, PyPI, and local files.