Local RAG

Servidor RAG local com foco em privacidade para busca semântica de documentos sem APIs externas

Documentação

MCP Local RAG

Pesquise documentos privados a partir de um cliente MCP ou do terminal sem enviá-los a uma API de embedding.

O mcp-local-rag indexa arquivos PDF, DOCX, Markdown e texto na sua máquina. A busca combina similaridade semântica com correspondência de palavras-chave, para que as consultas possam corresponder tanto à intenção quanto a termos técnicos exatos, como nomes de APIs, nomes de classes e códigos de erro.

Recursos

Execução local: análise de documentos, embeddings, armazenamento e busca são executados na sua máquina. Após o download inicial do modelo, a ingestão de texto e a busca funcionam offline.
Busca híbrida: a recuperação semântica encontra conceitos relacionados, enquanto a correspondência de palavras-chave reforça termos técnicos exatos.
Fragmentação semântica: os documentos são divididos em limites de tópico, em vez de contagens fixas de caracteres. Blocos de código Markdown permanecem intactos.
MCP e CLI: use o mesmo índice a partir de uma ferramenta de codificação com IA ou diretamente do terminal.

Nenhuma chave de API, Docker, Python ou banco de dados externo é necessário.

Início Rápido

Requisitos

Node.js 22 ou posterior
Acesso à internet no primeiro uso para baixar o pacote npm e o modelo de embedding
Um diretório contendo os documentos que você deseja pesquisar

Defina BASE_DIR para esse diretório. Ele também é o limite de segurança para operações de arquivo. Substitua /absolute/path/to/your/documents abaixo pelo caminho absoluto do diretório.

O mcp-local-rag usa o protocolo MCP padrão por meio de um servidor stdio local, portanto funciona com ferramentas de codificação com IA e outros hosts MCP que suportam servidores MCP locais.

Use um dos exemplos abaixo ou registre npx -y mcp-local-rag e defina BASE_DIR usando o formato de configuração MCP do seu cliente.

Para Claude Code: Execute este comando:

claude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-rag

Para Codex: Adicione a ~/.codex/config.toml:

[mcp_servers.local-rag]
command = "npx"
args = ["-y", "mcp-local-rag"]

[mcp_servers.local-rag.env]
BASE_DIR = "/absolute/path/to/your/documents"

Para OpenCode: Adicione a ~/.config/opencode/opencode.json (ou opencode.jsonc):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "local-rag": {
      "type": "local",
      "command": ["npx", "-y", "mcp-local-rag"],
      "environment": {
        "BASE_DIR": "/absolute/path/to/your/documents"
      }
    }
  }
}

Para Cursor: Adicione a ~/.cursor/mcp.json:

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": ["-y", "mcp-local-rag"],
      "env": {
        "BASE_DIR": "/absolute/path/to/your/documents"
      }
    }
  }
}

Reinicie o cliente e peça a ele para construir o índice:

Sync all documents in the configured root and wait until it finishes.

A primeira sincronização baixa o modelo de embedding padrão (cerca de 90 MB) e pode levar de 1 a 2 minutos antes que a ingestão comece. Execuções posteriores usam o cache local.

Quando a sincronização for concluída:

What does the API documentation say about authentication?

Início Rápido com CLI

Para usar a CLI sem um cliente MCP:

npx mcp-local-rag ingest ./docs/
npx mcp-local-rag query "authentication API"

A CLI usa o diretório atual como raiz de documentos por padrão. Execute ambos os comandos no mesmo diretório para que usem o mesmo índice padrão, ou defina BASE_DIR e DB_PATH explicitamente.

Por Que Isso Existe

Alguns conjuntos de documentos não podem ser enviados a um serviço de embedding hospedado por questões de confidencialidade ou política organizacional. Manter o índice local torna esses documentos pesquisáveis sem adicionar um custo de API por consulta.

A busca semântica sozinha pode perder identificadores exatos que são importantes na documentação técnica. A reclassificação por palavras-chave mantém esses termos visíveis sem abrir mão da recuperação em linguagem natural.

Conteúdo Suportado

Entrada	Como ingerir
PDF, DOCX, TXT, Markdown	Ingestão de arquivo ou sincronização de diretório
HTML já obtido pelo cliente	`ingest_data`; limpo com Readability e convertido para Markdown
Texto simples ou Markdown mantido em memória	`ingest_data` com um identificador de origem estável

A obtenção de HTML não está integrada ao servidor. Um cliente MCP pode obter uma página e passar seu HTML para ingest_data.

Excel, PowerPoint, imagens avulsas e extensões de arquivos de código-fonte não são suportados pela ingestão de arquivos. PDFs podem opcionalmente usar um modelo de visão local para descrever figuras, mas isso não é OCR nem busca de imagens.

Ferramentas MCP

Ferramenta	Finalidade
`sync_start`	Reconciliar o índice com todas as raízes configuradas ou um caminho
`sync_status`	Consultar um trabalho de sincronização em execução
`ingest_file`	Ingerir ou substituir um arquivo
`ingest_data`	Ingerir texto, Markdown ou HTML já mantido pelo cliente
`query_documents`	Buscar com correspondência semântica e reforço de palavras-chave
`read_chunk_neighbors`	Ler fragmentos ao redor de um resultado de busca
`list_files`	Mostrar arquivos suportados e seu estado de ingestão
`delete_file`	Excluir um arquivo indexado ou um item `ingest_data`
`status`	Mostrar status do índice e da busca

Sincronizando uma Raiz de Documentos

sync_start ingere arquivos novos e alterados, ignora arquivos idênticos em bytes e remove entradas de índice para arquivos que não existem mais:

Sync everything under the configured document roots and wait for completion.

A ferramenta retorna um jobId imediatamente. Os clientes devem consultar sync_status até que seu estado se torne succeeded ou failed. Não há modo visual durante a sincronização; PDFs alterados são ingeridos como texto.

Apenas um trabalho de sincronização é retido pelo processo do servidor. Um trabalho mais recente substitui um registro concluído, e reiniciar o servidor o descarta.

Ingerindo um Arquivo

ingest_file aceita PDF, DOCX, TXT e Markdown. Os caminhos de arquivo MCP devem ser absolutos e permanecer dentro de uma raiz de documentos configurada:

Ingest the document at /Users/me/docs/api-spec.pdf.

Reingerir o mesmo caminho substitui seus fragmentos existentes.

Buscando e Lendo Mais Contexto

What does the API documentation say about authentication?
Find the documented behavior of ERR_CONNECTION_REFUSED.

Os resultados contêm o texto, o caminho de origem, o título, o índice do fragmento e a pontuação de relevância. Passe o chunkIndex e o filePath ou o source de um resultado para read_chunk_neighbors quando a resposta precisar de mais contexto:

Read the surrounding chunks for that authentication result.

Tanto query_documents quanto list_files aceitam um prefixo de caminho scope absoluto opcional, ou uma lista de prefixos. Um prefixo corresponde ao caminho exato e aos seus descendentes.

Ingerindo HTML

Use ingest_data depois que o cliente MCP obtiver uma página:

Fetch https://example.com/docs and ingest the HTML.

O servidor extrai o artigo principal, converte-o para Markdown e o armazena sob o identificador de origem fornecido. Reutilizar a mesma origem atualiza o conteúdo existente.

Respeite os termos e os direitos autorais do site de origem ao indexar conteúdo externo.

Figuras em PDF

O modo visual adiciona uma legenda gerada para páginas de PDF com muitas figuras. Ele é opcional e não carrega um modelo de visão durante a ingestão normal.

Ingest /Users/me/docs/research-paper.pdf with visual: true.

npx mcp-local-rag ingest ./docs/research-paper.pdf --visual

Perfil	Cache do modelo	Caso de uso
`fast` (padrão)	cerca de 250 MB	Indexação visual leve
`quality`	cerca de 2,9 GB	Figuras contendo rótulos, anotações ou outro texto dentro da imagem

Selecione o modelo maior com visualQuality: "quality" via MCP ou --visual-quality quality via CLI. A inferência medida em CPU foi cerca de duas vezes mais lenta que fast, embora os resultados dependam do hardware e das atualizações do modelo.

As legendas são texto auxiliar, não transcrições fiéis. Trate legendas recuperadas e texto de documentos como entrada não confiável, e não como instruções.

CLI

A CLI usa o mesmo analisador, embedder e armazenamento vetorial sem um cliente MCP:

npx mcp-local-rag ingest ./docs/
npx mcp-local-rag sync ./docs/
npx mcp-local-rag query "authentication API"
npx mcp-local-rag query "auth" --scope /docs/api --scope /docs/guide
npx mcp-local-rag read-neighbors --file-path /abs/path.md --chunk-index 5
npx mcp-local-rag list
npx mcp-local-rag status
npx mcp-local-rag delete ./docs/old.pdf
npx mcp-local-rag delete --source "https://example.com/docs"

Opções globais como --db-path, --cache-dir e --model-name vão antes do subcomando. As opções do subcomando vão depois dele:

npx mcp-local-rag --db-path ./my-db query "authentication"

Execute npx mcp-local-rag --help para a referência completa de comandos.

A CLI não lê a configuração do cliente MCP. Defina as mesmas variáveis de ambiente ou flags se ambas as interfaces devem compartilhar um índice. Em particular, MODEL_NAME e a --model-name da CLI devem corresponder para um banco de dados compartilhado.

Ajuste de Busca

O reforço de palavras-chave está habilitado por padrão. O agrupamento por lacuna de relevância e os filtros de distância e de arquivo são controles opcionais para corpora que precisam de uma seleção de resultados mais restrita.

Variável	Padrão	Descrição
`RAG_HYBRID_WEIGHT`	`0.6`	Fator de reforço de palavras-chave (0,0–1,0). 0 desativa a reclassificação por palavras-chave; 1 aplica o reforço máximo.
`RAG_GROUPING`	(não definido)	`similar` mantém o primeiro grupo de relevância; `related` mantém até dois, usando lacunas significativas de distância vetorial como limites.
`RAG_MAX_DISTANCE`	(não definido)	Filtrar resultados de baixa relevância (por exemplo, `0.5`).
`RAG_MAX_FILES`	(não definido)	Limitar resultados aos N principais arquivos (por exemplo, `1` para o melhor arquivo único).

Para especificações de API e outros documentos que contêm muitos identificadores, um peso de palavra-chave mais forte pode melhorar a classificação por termos exatos:

"env": {
  "RAG_HYBRID_WEIGHT": "0.7"
}

0.7: reclassificação por termos exatos ligeiramente mais forte que o padrão
1.0: reforço máximo de palavras-chave

Como Funciona

Durante a ingestão:

O analisador extrai texto para o formato de entrada.
O fragmentador semântico encontra limites de tópico e preserva blocos de código Markdown.
O Transformers.js cria embeddings localmente.
O LanceDB armazena os fragmentos, metadados, vetores e o índice de texto completo.

Durante a busca:

A consulta é incorporada com o mesmo modelo.
A busca vetorial recupera fragmentos semanticamente relacionados.
Filtros opcionais de distância e de grupo de relevância restringem os candidatos quando configurados.
Correspondências de texto completo reforçam os termos exatos da consulta.

Habilidades do Agente

Agent Skills fornecem orientação de consulta e ingestão para assistentes de IA:

npx mcp-local-rag skills install --claude-code
npx mcp-local-rag skills install --claude-code --global
npx mcp-local-rag skills install --codex

As habilidades instaladas cobrem formulação de consultas, refinamento de resultados e ingestão de HTML. Peça ao assistente para usar a habilidade mcp-local-rag explicitamente se ela não ativar automaticamente.

Configuração

O servidor MCP lê variáveis de ambiente. A CLI aceita as mesmas variáveis mais as flags listadas, com as flags da CLI tendo precedência.

Variável de Ambiente	Flag da CLI	Padrão	Descrição
`BASE_DIR`	`--base-dir`	Diretório atual	Uma raiz de documentos; a flag da CLI é repetível em `ingest`, `list` e `sync`
`BASE_DIRS`	N/A	(não definido)	Array JSON de raízes de documentos; tem precedência sobre `BASE_DIR`
`DB_PATH`	`--db-path`	`./lancedb/`	Localização do banco de dados vetorial
`CACHE_DIR`	`--cache-dir`	`./models/`	Diretório de cache do modelo
`MODEL_NAME`	`--model-name`	`Xenova/all-MiniLM-L6-v2`	Modelo de embedding Hugging Face
`MAX_FILE_SIZE`	`--max-file-size`	`104857600` (100MB)	Tamanho máximo de arquivo em bytes
`CHUNK_MIN_LENGTH`	`--chunk-min-length`	`50`	Comprimento mínimo do fragmento em caracteres (1–10000)
`RAG_DEVICE`	N/A	`cpu`	Dispositivo de execução do ONNX Runtime
`RAG_DTYPE`	N/A	`fp32`	Tipo de dados (dtype) de embedding fornecido pelo modelo selecionado

Raízes de Documentos (`BASE_DIR` e `BASE_DIRS`)

O mcp-local-rag só permite operações de arquivo dentro das raízes configuradas. Para múltiplas raízes, BASE_DIRS deve ser um array JSON de caminhos não vazios:

export BASE_DIRS='["/Users/me/Documents/work","/Users/me/Projects/specs"]'

A configuração de raízes é resolvida nesta ordem:

Flags --base-dir <path> da CLI (repetíveis em ingest, list e sync)
BASE_DIRS
BASE_DIR
Diretório atual

Cada fonte substitui a fonte de prioridade mais baixa em vez de se mesclar com ela. Uma configuração BASE_DIRS inválida falha em vez de recorrer a BASE_DIR ou ao diretório atual. status permanece disponível no MCP para que o cliente possa relatar o erro de configuração.

npx mcp-local-rag ingest --base-dir /Users/me/work --base-dir /Users/me/specs /Users/me/work/readme.md
npx mcp-local-rag list --base-dir /Users/me/work --base-dir /Users/me/specs
npx mcp-local-rag sync --base-dir /Users/me/work --base-dir /Users/me/specs
BASE_DIRS='["/Users/me/work","/Users/me/specs"]' npx mcp-local-rag list

Armazenamento e Modelos

DB_PATH e CACHE_DIR são relativos ao diretório de trabalho do processo por padrão. Defina caminhos absolutos quando o cliente MCP puder iniciar o servidor a partir de diretórios de projeto diferentes.

Alterar MODEL_NAME, RAG_DEVICE ou RAG_DTYPE pode tornar os vetores existentes incompatíveis. Use um novo DB_PATH ou exclua o índice existente e reingira após alterar a configuração de embedding.

Exemplos de modelos:

Documentos multilíngues: onnx-community/embeddinggemma-300m-ONNX
Artigos científicos: sentence-transformers/allenai-specter

Segurança e Operação

O acesso a arquivos é restrito às raízes BASE_DIR, BASE_DIRS ou --base-dir da CLI.
Links simbólicos que resolvem para fora de toda raiz configurada são rejeitados.
O processamento de documentos e a busca não fazem solicitações de rede após os modelos necessários serem armazenados em cache.
O servidor foi projetado para um único usuário local e não fornece autenticação ou controle de acesso.
Não execute vários gravadores CLI ou MCP contra o mesmo DB_PATH. Consultas somente leitura podem ser executadas enquanto uma sincronização está ativa.
Faça backup de um índice copiando seu diretório DB_PATH enquanto nenhum gravador estiver ativo.

Solução de problemas

"Nenhum resultado encontrado"

Os documentos devem ser carregados primeiro. Execute "List all ingested files" para verificar.

Falha no download do modelo

Verifique a conexão com a internet. Se estiver atrás de um proxy, configure as configurações de rede. O modelo também pode ser baixado manualmente.

"Arquivo muito grande"

O limite padrão é 100MB. Divida arquivos grandes ou aumente MAX_FILE_SIZE.

Consultas lentas

Verifique a contagem de chunks com status. Documentos grandes com muitos chunks podem tornar as consultas lentas. Considere dividir arquivos muito grandes.

"Caminho fora de BASE_DIR"

Garanta que os caminhos de arquivo estejam dentro de uma das raízes configuradas (BASE_DIR, qualquer entrada de BASE_DIRS ou qualquer --base-dir da CLI). Use caminhos absolutos.

"BASE_DIRS deve ser um array JSON..."

BASE_DIRS aceita um array JSON de uma ou mais strings de caminho não vazias:

Válido: BASE_DIRS='["/Users/me/work","/Users/me/specs"]'
Inválido: BASE_DIRS=/a:/b (sintaxe de delimitador não suportada)
Inválido: BASE_DIRS='[]' (array vazio)

O cliente MCP não vê as ferramentas

Verifique a sintaxe do arquivo de configuração
Reinicie o cliente completamente (Cmd+Q no Mac para Cursor)
Teste diretamente: npx mcp-local-rag deve ser executado sem erros

Contribuindo

Contribuições são bem-vindas! Veja CONTRIBUTING.md para configuração e diretrizes.

Licença

Licença MIT. Gratuita para uso pessoal e comercial.

Postagens do Blog

Construindo um Local RAG para Codificação Agentica: Análise técnica aprofundada do design de divisão semântica e busca híbrida.

Agradecimentos

Construído com Model Context Protocol da Anthropic, LanceDB e Transformers.js.