RAGSync

Recursos

• Suporte amplo a fontes — indexe pastas locais (texto, PDF, Markdown) e páginas da web; não limitado a um único tipo de arquivo ou formato
• Orientado por configuração — um arquivo YAML define fontes, estratégia de chunking, modelo de embedding e armazenamento vetorial; sem necessidade de código
• Recarga ao vivo — monitoramento do sistema de arquivos e polling mantêm o índice atualizado à medida que as fontes mudam; editar a própria configuração aplica mudanças sem reiniciar
• Embeddings flexíveis — fastembed local funciona imediatamente sem chave de API; troque por OpenAI ou Voyage por fonte
• Superfície estável de ferramentas MCP — cinco ferramentas agnósticas de fonte (search, list_sources, get_document, get_index_status, reindex) que nunca mudam à medida que fontes são adicionadas

Instalação

A maneira mais rápida é com uvx — sem etapa de clone ou instalação:

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

Adicione isto à configuração do seu cliente MCP:

Os caminhos dentro da configuração são resolvidos em relação ao diretório do arquivo de configuração (não ao diretório de trabalho do cliente), então uma configuração pode viver no repositório e referenciar conteúdo do repositório com caminhos relativos como path: ./docs. Dê a --config um caminho absoluto, no entanto — o cliente escolhe de onde ele inicia o servidor, então esse é o único caminho que ele precisa encontrar sem ambiguidade.

Fixe uma versão com "ragsync@0.2.0" se quiser lançamentos reproduzíveis. (Se o cliente não conseguir encontrar uvx em seu PATH, use o caminho absoluto para o binário 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"]
    }
  }
}

Chaves de embedding hospedadas

Para fontes openai/voyage, a configuração nomeia uma variável de ambiente (api_key_env) em vez da chave em si. Forneça essa variável ao subprocesso via env:

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

Após salvar, reinicie/recarregue o cliente. Ele listará as cinco ferramentas (search, list_sources, get_document, get_index_status, reindex); o agente chama search para responder perguntas das suas fontes indexadas. O primeiro lançamento baixa o modelo de embedding local, então a inicialização inicial pode demorar um pouco mais.

Configuração

Um único arquivo YAML define defaults global e uma lista de sources. Cada fonte se torna uma coleção pesquisável com seu próprio carregador, chunking, modelo de embedding, coleção de armazenamento vetorial e observador. O isolamento por fonte permite que diferentes fontes usem diferentes modelos de embedding com segurança.

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

O diretório examples/ tem configurações executáveis:

• config.example.yaml — um exemplo completo de múltiplas fontes (apontando para o conteúdo de exemplo em examples/docs e examples/playbooks).
• folder.yaml — uma única fonte folder.
• website.yaml — uma única fonte website.

Tipos de fonte

Globs de inclusão/exclusão usam correspondência no estilo gitignore (ex.: **/internal/**).

Provedores de embedding

fastembed (local, padrão), openai e voyage (hospedados). Provedores hospedados leem sua chave de API da variável de ambiente nomeada por api_key_env — chaves nunca são escritas na configuração.

Ferramentas MCP

Cinco ferramentas, deliberadamente pequenas e agnósticas de fonte. Elas nunca mudam à medida que fontes são adicionadas:

• search — busca semântica em uma ou todas as fontes, com filtragem opcional de metadados. Retorna resultados com pontuações [0, 1] normalizadas.
• list_sources — descubra fontes disponíveis e sua saúde/metadados.
• get_document — busque um documento completo depois que search expõe um chunk.
• get_index_status — frescor/saúde da indexação para uma fonte ou todas.
• reindex — force uma re-varredura completa de uma fonte.

As ferramentas retornam objetos {"error": "..."} estruturados em vez de lançar erros, para que o agente chamador possa se recuperar conversacionalmente.

Escopo de acesso

O isolamento por fonte é um limite de segurança: escopo o acesso executando instâncias de servidor separadas com configurações separadas. Não há caminho entre instâncias de "buscar tudo".

Desenvolvimento

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

Os testes rodam totalmente offline injetando um embedder determinístico no lugar do fastembed (veja tests/conftest.py). A arquitetura e o contrato de extensão — como adicionar um novo tipo de fonte — estão documentados em AGENTS.md.

Lançamentos

Os lançamentos são automatizados a partir de Conventional Commits. CI (.github/workflows/ci.yml) executa a suíte de testes em cada pull request. Ao mesclar em main, o fluxo de trabalho de lançamento (.github/workflows/release.yml) executa os testes novamente, então python-semantic-release inspeciona os commits desde a última tag e decide a próxima versão:

Quando há uma mudança publicável, ele incrementa version em pyproject.toml, atualiza CHANGELOG.md, marca o commit com uma tag, cria um release no GitHub e publica o pacote no PyPI. Uma vez publicado, qualquer pessoa pode executá-lo com uvx ragsync --config <path> (ou pip install ragsync).