English | 简体中文 | Deutsch | Español | Português (Brasil) | Français
Pesquise documentos privados usando um cliente MCP ou o terminal sem enviá-los a uma API de embeddings. O mcp-local-rag indexa arquivos PDF, DOCX, Markdown e texto no seu computador. A busca combina similaridade semântica e correspondência por palavras-chave. Assim, leva em conta tanto o sentido da consulta quanto termos técnicos exatos, como nomes de APIs, classes e códigos de erro. ## Recursos - **Execução local:** O processamento dos documentos, os embeddings, o armazenamento e a busca acontecem no seu computador. Depois do primeiro download do modelo, a importação de texto e as buscas funcionam offline. - **Busca híbrida:** A recuperação semântica encontra conceitos relacionados, enquanto a correspondência por palavras-chave dá mais peso a termos técnicos exatos. - **Embeddings configuráveis:** Escolha um modelo de embeddings do Hugging Face adequado ao idioma e à área dos seus documentos. - **Divisão semântica:** Os documentos são divididos nas mudanças de assunto, não por uma quantidade fixa de caracteres. Blocos de código Markdown permanecem intactos. - **MCP e CLI:** Use o mesmo índice em uma ferramenta de programação com IA ou diretamente no terminal. Não é necessário ter chave de API, Docker, Python nem banco de dados externo. ## Início rápido ### Requisitos - Node.js 22 ou mais recente - Acesso à internet no primeiro uso para baixar o pacote npm e o modelo de embeddings - Um diretório com os documentos que você quer pesquisar Defina `BASE_DIR` com o caminho desse diretório. Ele também funciona como limite de segurança para as operações com arquivos. Substitua `/absolute/path/to/your/documents` nos exemplos pelo caminho absoluto do diretório. O mcp-local-rag usa o protocolo MCP padrão por meio de um servidor stdio local. Assim, ele funciona com ferramentas de programação com IA e outros hosts MCP compatíveis com servidores MCP locais. Use um dos exemplos abaixo ou registre `npx -y mcp-local-rag` e defina `BASE_DIR` no formato de configuração MCP do seu cliente. **Claude Code:** Execute este comando: ```bash claude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-rag ``` **Codex:** Adicione a `~/.codex/config.toml`: ```toml [mcp_servers.local-rag] command = "npx" args = ["-y", "mcp-local-rag"] [mcp_servers.local-rag.env] BASE_DIR = "/absolute/path/to/your/documents" ``` **OpenCode:** Adicione a `~/.config/opencode/opencode.json` (ou `opencode.jsonc`): ```json { "$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" } } } } ``` **Cursor:** Adicione a `~/.cursor/mcp.json`: ```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 criar o índice: ```text Sincronize todos os documentos do diretório raiz configurado e aguarde a conclusão. ``` A primeira sincronização baixa o modelo de embeddings padrão (cerca de 90 MB). O início da importação pode levar de 1 a 2 minutos. Nas próximas execuções, o cache local será usado. Quando a sincronização terminar, faça uma pergunta: ```text O que a documentação da API diz sobre autenticação? ``` ### Início rápido pela CLI Para usar a CLI sem um cliente MCP: ```bash npx mcp-local-rag ingest ./docs/ npx mcp-local-rag query "API de autenticação" ``` Por padrão, a CLI usa o diretório atual como raiz dos documentos. Execute os dois comandos no mesmo diretório para que usem o mesmo índice padrão ou defina `BASE_DIR` e `DB_PATH` explicitamente. ## Por que este projeto existe Alguns conjuntos de documentos não podem ser enviados a um serviço de embeddings hospedado devido a requisitos de confidencialidade ou políticas da organização. Mantendo o índice local, esses documentos continuam pesquisáveis sem gerar custo de API por consulta. Uma busca puramente semântica pode ignorar identificadores exatos que são importantes na documentação técnica. O reordenamento por palavras-chave mantém esses termos visíveis sem abrir mão das consultas em linguagem natural. ## Conteúdo compatível | Entrada | Como importar | |---|---| | PDF, DOCX, TXT, Markdown | Importaçã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 em memória | `ingest_data` com um identificador de origem estável | O servidor não busca HTML por conta própria. Um cliente MCP pode obter uma página e enviar o HTML para `ingest_data`. A importação de arquivos não aceita Excel, PowerPoint, imagens avulsas nem extensões de código-fonte. Opcionalmente, arquivos PDF podem usar um modelo visual local para descrever figuras, mas esse recurso não é OCR nem busca de imagens. ## Ferramentas MCP | Ferramenta | Finalidade | |---|---| | `sync_start` | Sincronizar o índice com todos os diretórios raiz configurados ou com um caminho | | `sync_status` | Consultar uma sincronização em andamento | | `ingest_file` | Importar ou substituir um arquivo | | `ingest_data` | Importar texto, Markdown ou HTML que já esteja disponível no cliente | | `query_documents` | Pesquisar com correspondência semântica e reforço por palavras-chave | | `read_chunk_neighbors` | Ler os fragmentos próximos a um resultado de busca | | `list_files` | Mostrar os arquivos compatíveis e o estado de importação | | `delete_file` | Excluir um arquivo indexado ou um item de `ingest_data` | | `status` | Mostrar o estado do índice e da busca | ### Sincronizar um diretório raiz `sync_start` importa arquivos novos e alterados, ignora os que são idênticos byte a byte e remove do índice os arquivos que deixaram de existir: ```text Sincronize todo o conteúdo dos diretórios raiz configurados e aguarde a conclusão. ``` A ferramenta retorna um `jobId` imediatamente. O cliente deve consultar `sync_status` até o estado mudar para `succeeded` ou `failed`. Não há modo visual durante a sincronização; arquivos PDF alterados são importados como texto. O processo do servidor mantém apenas o registro de um job de sincronização. Um novo job substitui o registro de outro já concluído, e o registro é descartado quando o servidor reinicia. ### Importar um arquivo `ingest_file` aceita PDF, DOCX, TXT e Markdown. Os caminhos enviados via MCP devem ser absolutos e permanecer dentro de um diretório raiz configurado: ```text Importe o documento /Users/me/docs/api-spec.pdf. ``` Importar novamente o mesmo caminho substitui os fragmentos existentes. ### Pesquisar e ler mais contexto ```text O que a documentação da API diz sobre autenticação? Encontre o comportamento documentado de 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. Se precisar de mais contexto, envie a `read_chunk_neighbors` o `chunkIndex` e o `filePath` ou `source` do resultado: ```text Leia os fragmentos próximos a esse resultado sobre autenticação. ``` Tanto `query_documents` quanto `list_files` aceitam um prefixo de caminho absoluto opcional em `scope`, ou uma lista de prefixos. Cada prefixo corresponde ao caminho exato e a todos os caminhos abaixo dele. ### Importar HTML Use `ingest_data` depois que o cliente MCP buscar a página: ```text Busque https://example.com/docs e importe o HTML. ``` O servidor extrai o artigo principal, converte o conteúdo para Markdown e o armazena com 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 descrição gerada às páginas de PDF com muitas figuras. Ele é opcional e não carrega um modelo visual durante a importação normal. ```text Importe /Users/me/docs/research-paper.pdf com visual: true. ``` ```bash npx mcp-local-rag ingest ./docs/research-paper.pdf --visual ``` | Perfil | Cache do modelo | Indicação | |---|---:|---| | `fast` (padrão) | cerca de 250 MB | Indexação visual leve | | `quality` | cerca de 2,9 GB | Figuras com rótulos, anotações ou outros textos dentro da imagem | Selecione o modelo maior com `visualQuality: "quality"` via MCP ou com `--visual-quality quality` pela CLI. Em testes com CPU, a inferência levou cerca do dobro do tempo de `fast`, mas o resultado depende do hardware e das atualizações do modelo. As descrições são textos auxiliares, não transcrições fiéis. Trate as descrições e o texto recuperado dos documentos como entradas não confiáveis, não como instruções. ## CLI A CLI usa o mesmo analisador, gerador de embeddings e banco vetorial sem precisar de um cliente MCP: ```bash npx mcp-local-rag ingest ./docs/ npx mcp-local-rag sync ./docs/ npx mcp-local-rag query "API de autenticação" npx mcp-local-rag query "autenticação" --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êm antes do subcomando. As opções próprias do subcomando vêm depois: ```bash npx mcp-local-rag --db-path ./my-db query "autenticação" ``` Execute `npx mcp-local-rag --help` para consultar a referência completa dos comandos. A CLI não lê a configuração do cliente MCP. Defina as mesmas variáveis de ambiente ou opções se as duas interfaces precisarem compartilhar um índice. Em particular, `MODEL_NAME` e a opção `--model-name` da CLI devem ser iguais quando usam o mesmo banco de dados. ## Ajuste da busca O reforço por palavras-chave é ativado por padrão. Para acervos que exigem uma seleção mais restrita, também é possível configurar o agrupamento por saltos de relevância e os filtros de distância e de arquivos. | Variável | Padrão | Descrição | |----------|---------|-------------| | `RAG_HYBRID_WEIGHT` | `0.6` | Fator de reforço por palavras-chave (0.0–1.0). 0 desativa o reordenamento por palavras-chave e 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 e usa saltos relevantes na distância vetorial como limites. | | `RAG_MAX_DISTANCE` | não definido | Descarta resultados pouco relevantes, por exemplo, com `0.5`. | | `RAG_MAX_FILES` | não definido | Limita os resultados aos N arquivos mais bem classificados, por exemplo, `1` para apenas o melhor arquivo. | Em especificações de API e outros documentos com muitos identificadores, um peso maior para palavras-chave pode melhorar a classificação de termos exatos: ```json "env": { "RAG_HYBRID_WEIGHT": "0.7" } ``` - `0.7`: reordenamento de termos exatos um pouco mais forte que o padrão - `1.0`: reforço máximo por palavras-chave ## Como funciona Durante a importação: 1. O analisador extrai o texto do formato de entrada. 2. O divisor semântico encontra as mudanças de assunto e preserva os blocos de código Markdown. 3. O Transformers.js cria os embeddings localmente. 4. O LanceDB armazena os fragmentos, metadados, vetores e o índice de texto completo. Durante a busca: 1. A consulta é convertida em embedding pelo mesmo modelo. 2. A busca vetorial recupera fragmentos relacionados pelo significado. 3. Quando configurados, os filtros opcionais de distância e os grupos de relevância reduzem os candidatos. 4. As correspondências de texto completo reforçam os termos exatos da consulta. ## Agent Skills As [Agent Skills](https://agentskills.io/) orientam assistentes de IA na formulação de consultas e na importação de conteúdo: ```bash 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 skills instaladas cobrem formulação de consultas, refinamento de resultados e importação de HTML. Se uma skill não for ativada automaticamente, peça ao assistente para usar a skill mcp-local-rag de forma explícita. ## Configuração O servidor MCP lê variáveis de ambiente. A CLI aceita as mesmas variáveis e as opções listadas na tabela; as opções da CLI têm prioridade. | Variável de ambiente | Opção da CLI | Padrão | Descrição | |---------------------|----------|---------|-------------| | `BASE_DIR` | `--base-dir` | Diretório atual | Um diretório raiz; a opção da CLI pode ser repetida em `ingest`, `list` e `sync` | | `BASE_DIRS` | N/D | não definido | Array JSON de diretórios raiz; tem prioridade sobre `BASE_DIR` | | `DB_PATH` | `--db-path` | `./lancedb/` | Local do banco de dados vetorial | | `CACHE_DIR` | `--cache-dir` | `./models/` | Diretório de cache dos modelos | | `MODEL_NAME` | `--model-name` | `Xenova/all-MiniLM-L6-v2` | Modelo de embeddings do Hugging Face | | `MAX_FILE_SIZE` | `--max-file-size` | `104857600` (100 MB) | Tamanho máximo do arquivo em bytes | | `CHUNK_MIN_LENGTH` | `--chunk-min-length` | `50` | Tamanho mínimo de um fragmento em caracteres (1–10000) | | `RAG_DEVICE` | N/D | `cpu` | Dispositivo de execução do ONNX Runtime | | `RAG_DTYPE` | N/D | `fp32` | Tipo de dados dos embeddings enviado ao modelo selecionado | ### Diretórios raiz (`BASE_DIR` e `BASE_DIRS`) O mcp-local-rag só permite operações com arquivos dentro dos diretórios raiz configurados. Para usar vários diretórios, `BASE_DIRS` deve ser um array JSON de caminhos não vazios: ```bash export BASE_DIRS='["/Users/me/Documents/work","/Users/me/Projects/specs"]' ``` A configuração é resolvida nesta ordem: 1. Opções `--base-dir