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 incorporação (embedding).

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

Recursos

Execução local: Análise de documentos, incorporações, armazenamento e pesquisa são executados na sua máquina. Após o download inicial do modelo, a ingestão de texto e a pesquisa funcionam offline.
Pesquisa híbrida: A recuperação semântica encontra conceitos relacionados, enquanto a correspondência de palavras-chave reforça termos técnicos exatos.
Incorporações configuráveis: Escolha um modelo de incorporação da Hugging Face que se ajuste ao idioma e ao domínio dos seus documentos.
Fragmentação semântica: Os documentos são divididos em limites de tópicos, 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.

Não é necessária chave de API, Docker, Python ou banco de dados externo.

Início Rápido

Requisitos

Node.js 22 ou posterior
Acesso à internet no primeiro uso para baixar o pacote npm e o modelo de incorporação
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 em 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 para ele construir o índice:

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

A primeira sincronização baixa o modelo de incorporação 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 incorporação hospedado devido a confidencialidade ou política organizacional. Manter o índice local os torna pesquisáveis sem adicionar custo de API por consulta.

Somente a pesquisa semântica pode perder identificadores exatos que importam 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á embutida no servidor. Um cliente MCP pode buscar uma página e passar seu HTML para ingest_data.

Excel, PowerPoint, imagens independentes 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 pesquisa 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`	Pesquisar com correspondência semântica e reforço de palavras-chave
`read_chunk_neighbors`	Ler fragmentos ao redor de um resultado de pesquisa
`list_files`	Mostrar arquivos suportados e seu estado de ingestão
`delete_file`	Excluir um arquivo indexado ou um item de `ingest_data`
`status`	Mostrar status do índice e da pesquisa

Sincronizando uma Raiz de Documentos

sync_start ingere arquivos novos e alterados, ignora arquivos idênticos em bytes e remove entradas do í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. Um PDF alterado mantém o perfil visual com o qual foi indexado; sync_start não pode alterá-lo. Defina STORE_IMAGES=true no ambiente do servidor MCP para armazenar imagens de PDF e DOCX suportadas para arquivos novos ou alterados selecionados pela sincronização; arquivos inalterados permanecem ignorados.

Apenas um trabalho de sincronização é retido pelo processo do servidor. Um trabalho mais novo 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 devem 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.

Pesquisando 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, a pontuação de relevância e quaisquer imagens armazenadas nesse fragmento. O MCP retorna cada imagem como um bloco de conteúdo de imagem emparelhado com sua identidade de resultado; a CLI query inclui um array images de { imageIndex, mimeType, data } em cada resultado. Passe o chunkIndex e filePath ou 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 absoluto opcional scope, 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 buscar uma página:

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

O servidor extrai o artigo principal, converte 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.

Legendas Visuais de PDF e Imagens Armazenadas

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

O armazenamento de imagens é independente das legendas visuais. Defina STORE_IMAGES=true para o servidor MCP, ou passe --images para a ingestão e sincronização da CLI:

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

O armazenamento de PDF usa regiões detectadas de figuras/tabelas. O armazenamento de DOCX inclui apenas imagens PNG/JPEG que a conversão existente do Mammoth emite como <img>; gráficos, SmartArt e formas não são renderizados separadamente. As imagens armazenadas seguem seu texto ao redor para o fragmento semântico final e não alteram a classificação, as pontuações ou a contagem de resultados.

`visual` / `--visual`	`STORE_IMAGES` / `--images`	Comportamento do PDF
false	false	Somente texto; sem legendas visuais ou imagens retornadas.
true	false	Legendas geradas tornam-se texto pesquisável; nenhuma imagem é armazenada ou retornada.
true	true	Legendas geradas tornam-se texto pesquisável, e imagens de fragmentos correspondentes são retornadas inline.
false	true	Imagens são anexadas ao texto de PDF retido próximo e retornadas inline para fragmentos correspondentes; o VLM não é importado, carregado ou executado.

Perfil	Cache do modelo	Caso de uso
`fast` (padrão)	cerca de 250 MB	Indexação visual leve
`quality`	cerca de 1,7 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 três vezes mais lenta que fast, embora os resultados dependam do hardware e das atualizações do modelo.

Atualizando Legendas `quality` Existentes

A partir de 0.18.4, quality executa Qwen3.5-2B; versões anteriores executavam Qwen2.5-VL-3B. Legendas já indexadas mantêm a redação que o modelo antigo produziu, e sync não as refará, então reingira os arquivos que você deseja atualizar:

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

Adicione --images se o arquivo foi ingerido com ele, porque uma execução sem ele substitui as imagens armazenadas. O modelo antigo permanece no disco. Quando nada mais o usar, exclua onnx-community/Qwen2.5-VL-3B-Instruct-ONNX/ do diretório de cache do modelo — <cache-dir>, que padrão é ./models/.

Modo Visual Entre Sincronizações

O perfil com o qual um PDF foi indexado é registrado, e sync o reutiliza: um PDF indexado com fast ou quality é reingerido com esse mesmo perfil, e um PDF sem perfil registrado é ingerido como texto.

npx mcp-local-rag sync ./docs/                      # keep each PDF's recorded profile
npx mcp-local-rag sync ./docs/ --visual             # request fast for every PDF in scope
npx mcp-local-rag sync ./docs/ --visual --visual-quality quality

--visual substitui perfis registrados, portanto também adiciona legendas a PDFs que foram indexados como texto. Alterar um perfil reingere o PDF mesmo quando o arquivo em si não mudou; executar o mesmo comando novamente não faz nada e não carrega modelo. As configurações de imagem nunca são registradas, então --images e STORE_IMAGES nunca causam uma reingestão.

Para desativar legendas para um caminho, execute ingest nele: uma ingestão normal bem-sucedida limpa o perfil registrado. Para tentar novamente uma página cuja legenda falhou, execute ingest <path> --visual --visual-quality <profile> with the profile you want — a plain ingest a limpa em vez disso. Se as linhas indexadas de um PDF discordarem sobre o perfil, a sincronização para antes de alterar qualquer coisa e nomeia o arquivo; execute novamente com --visual para resolver o perfil.

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

Em limites altos, fragmentos correspondentes e seus anexos podem se aproximar do teto de contexto do modelo/cliente; escolha o limite de consulta considerando o contexto disponível do modelo chamador.

CLI

A CLI usa o mesmo analisador, incorporador 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. Opções de 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 sinalizadores se ambas as interfaces devem compartilhar um índice. Em particular, MODEL_NAME e a CLI --model-name devem corresponder para um banco de dados compartilhado, e o mesmo vale para EMBED_TITLE_PREFIX.

query escreve seus resultados em stdout como JSON, melhor correspondência primeiro, para que possa ser canalizado para outra ferramenta. O contrato campo por campo está em docs/schema/query-output.schema.json.

Ajuste de Pesquisa

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 arquivo são controles opcionais para corpora que precisam de seleção de resultados mais rigorosa. Todos os quatro se aplicam ao servidor MCP e à CLI query igualmente.

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 reordenaçã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)	Filtra resultados de baixa relevância (ex.: `0.5`).
`RAG_MAX_FILES`	(não definido)	Limita os resultados aos N principais arquivos (ex.: `1` para o melhor arquivo único).
`RAG_RERANK_CMD`	(não definido)	Somente servidor MCP: modelo de comando externo que reordena resultados. O texto correspondido é enviado via stdin; `{query}` passa a consulta.
`RAG_RERANK_TIMEOUT_MS`	`10000`	Orçamento de tempo por chamada de reordenação em milissegundos (100–600000).

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

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

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

Reordenação Externa (`RAG_RERANK_CMD`)

O servidor envia cada conjunto de resultados de busca, incluindo o texto do trecho correspondido, para o comando via stdin. Ele passa a consulta de busca somente onde o modelo contém {query}. Um comando que chama um serviço remoto pode enviar o conteúdo que recebe desta máquina.

Forneça o executável e seu modelo completo de argumentos. Coloque {query} e {top} onde o comando espera a consulta e a contagem de resultados. Aspas simples ou duplas agrupam caminhos ou argumentos contendo espaços, e barras invertidas permanecem literais. O servidor executa o executável sem um shell, portanto um shim .cmd instalado via npm no Windows não será iniciado.

"env": {
  "RAG_RERANK_CMD": "/path/to/reranker --query {query} --top {top}",
  "RAG_RERANK_TIMEOUT_MS": "10000"
}

O comando recebe cada resultado na forma publicada em docs/schema/query-output.schema.json e deve responder nessa mesma forma. Dentro dele, o comando decide tudo: o que manter, como ordenar e o que o texto diz. O que ele retornar é o que você vê.

Os resultados mantêm sua ordem original se o comando falhar, expirar ou responder com algo que não esteja nessa forma.

Como Funciona

Durante a ingestão:

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

Durante a busca:

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

Habilidades do Agente

Habilidades do Agente 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 variáveis de ambiente globais listadas e flags; o armazenamento de imagens na ingestão e sincronização da CLI é habilitado somente com --images.

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)	Matriz 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
`HF_ENDPOINT`	N/A	`https://huggingface.co`	Endpoint de download de modelos Hugging Face; use uma URL de espelho quando downloads diretos forem bloqueados
`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 em caracteres (1–10000) para trechos comuns; um fragmento de conteúdo dividido para caber no limite de tokens do modelo pode ser mais curto
`EMBED_TITLE_PREFIX`	N/A	`false`	Incorpora cada trecho atrás de uma linha `Title:` com seu título de documento. O texto do trecho retornado permanece inalterado. Reingira após alterá-lo
`STORE_IMAGES`	N/A	`false`	Somente servidor MCP: armazena imagens PDF/DOCX suportadas e as retorna com os trechos correspondidos. A CLI usa `--images`.
`RAG_DEVICE`	N/A	`cpu`	Dispositivo de execução do ONNX Runtime
`RAG_DTYPE`	N/A	`fp32`	Tipo de dados de embedding passado ao modelo selecionado

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

mcp-local-rag só permite operações de arquivo dentro das raízes configuradas. Para múltiplas raízes, BASE_DIRS deve ser uma matriz 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 mesclar com ela. 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 diferentes diretórios de projeto.

Defina MODEL_NAME ou passe --model-name para escolher um modelo de embedding Hugging Face que se ajuste ao idioma e domínio dos seus documentos.

mcp-local-rag gera embeddings com pooling médio e normalização L2. Ao escolher um modelo, verifique se essas configurações correspondem à configuração de inferência recomendada, pois o método de pooling pode afetar a qualidade da recuperação.

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

Um exemplo de modelo para documentos em inglês é Xenova/bge-small-en-v1.5.

Segurança e Operação

O acesso a arquivos é restrito a raízes BASE_DIR, BASE_DIRS ou --base-dir da CLI.
Links simbólicos que resolvem 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, a menos que RAG_RERANK_CMD nomeie um comando que as faça.
O servidor é projetado para um único usuário local e não fornece autenticação ou controle de acesso.
Não execute múltiplos 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 ingeridos 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 trechos com status. Documentos grandes com muitos trechos 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 BASE_DIRS ou qualquer --base-dir da CLI). Use caminhos absolutos.

"BASE_DIRS deve ser uma matriz JSON..."

BASE_DIRS aceita uma matriz 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='[]' (matriz vazia)

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. Gratuito para uso pessoal e comercial.

Postagens no Blog

Construindo um Local RAG para Codificação Agêntica: Aprofundamento técnico no design de divisão semântica e busca híbrida.

Agradecimentos

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