RAGSync

Características

• Amplio soporte de fuentes — indexa carpetas locales (texto, PDF, Markdown) y páginas web; no limitado a un solo tipo de archivo o formato
• Impulsado por configuración — un archivo YAML define fuentes, estrategia de fragmentación, modelo de embeddings y almacén vectorial; sin necesidad de código
• Recarga en vivo — la observación del sistema de archivos y el sondeo mantienen el índice actualizado a medida que cambian las fuentes; editar la propia configuración aplica cambios sin reiniciar
• Embeddings flexibles — fastembed local funciona de fábrica sin clave API; cambia a OpenAI o Voyage por fuente
• Superficie de herramientas MCP estable — cinco herramientas independientes de la fuente (search, list_sources, get_document, get_index_status, reindex) que nunca cambian al añadir fuentes

Instalación

La forma más rápida es con uvx — sin clonar ni instalar:

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

Añade esto a la configuración de tu cliente MCP:

Las rutas dentro de la configuración se resuelven contra el directorio del archivo de configuración (no el directorio de trabajo del cliente), por lo que una configuración puede vivir en el repositorio y hacer referencia al contenido del repositorio con rutas relativas como path: ./docs. Sin embargo, dale a --config una ruta absoluta — el cliente elige desde dónde lanza el servidor, por lo que es la única ruta que debe poder encontrar sin ambigüedad.

Fija una versión con "ragsync@0.2.0" si quieres lanzamientos reproducibles. (Si el cliente no puede encontrar uvx en su PATH, usa la ruta absoluta al binario uvx — which uvx.)

{
  "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"]
    }
  }
}

Claves de embeddings alojados

Para fuentes openai/voyage, la configuración nombra una variable de entorno (api_key_env) en lugar de la clave en sí. Proporciona esa variable al subproceso mediante env:

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

Después de guardar, reinicia/recarga el cliente. Listará las cinco herramientas (search, list_sources, get_document, get_index_status, reindex); el agente llama a search para responder preguntas de tus fuentes indexadas. El primer lanzamiento descarga el modelo de embeddings local, por lo que el arranque inicial puede tardar un poco más.

Configuración

Un único archivo YAML define defaults global y una lista de sources. Cada fuente se convierte en una colección buscable con su propio cargador, fragmentación, modelo de embeddings, colección de almacén vectorial y observador. El aislamiento por fuente permite que diferentes fuentes usen diferentes modelos de embeddings de forma segura.

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

El directorio examples/ tiene configuraciones ejecutables:

• config.example.yaml — un ejemplo completo de múltiples fuentes (apuntando al contenido de muestra en examples/docs y examples/playbooks).
• folder.yaml — una única fuente folder.
• website.yaml — una única fuente website.

Tipos de fuente

Los globs de inclusión/exclusión usan coincidencia estilo gitignore (p. ej. **/internal/**).

Proveedores de embeddings

fastembed (local, predeterminado), openai y voyage (alojados). Los proveedores alojados leen su clave API de la variable de entorno nombrada por api_key_env — las claves nunca se escriben en la configuración.

Herramientas MCP

Cinco herramientas, deliberadamente pequeñas e independientes de la fuente. Nunca cambian al añadir fuentes:

• search — búsqueda semántica en una o todas las fuentes, con filtrado de metadatos opcional. Devuelve resultados con puntuaciones [0, 1] normalizadas.
• list_sources — descubre fuentes disponibles y su salud/metadatos.
• get_document — obtiene un documento completo después de que search muestre un fragmento.
• get_index_status — frescura/salud de indexación para una fuente o todas.
• reindex — fuerza un re-escaneo completo de una fuente.

Las herramientas devuelven objetos {"error": "..."} estructurados en lugar de lanzar excepciones, para que el agente que llama pueda recuperarse conversacionalmente.

Alcance de acceso

El aislamiento por fuente es un límite de seguridad: delimita el acceso ejecutando instancias de servidor separadas con configuraciones separadas. No existe una ruta de "buscar todo" entre instancias.

Desarrollo

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

Las pruebas se ejecutan completamente sin conexión inyectando un embedder determinista en lugar de fastembed (ver tests/conftest.py). La arquitectura y el contrato de extensión — cómo añadir un nuevo tipo de fuente — están documentados en AGENTS.md.

Publicación

Las publicaciones se automatizan a partir de Conventional Commits. CI (.github/workflows/ci.yml) ejecuta la suite de pruebas en cada pull request. Al fusionar en main, el flujo de trabajo de publicación (.github/workflows/release.yml) ejecuta las pruebas de nuevo, luego python-semantic-release inspecciona los commits desde la última etiqueta y decide la siguiente versión:

Cuando hay un cambio publicable, incrementa version en pyproject.toml, actualiza CHANGELOG.md, etiqueta el commit, crea una release de GitHub y publica el paquete en PyPI. Una vez publicado, cualquiera puede ejecutarlo con uvx ragsync --config <path> (o pip install ragsync).