own-rag-cli 0.0.1-snapshot

package/MCP_USAGE.md

@@ -0,0 +1,315 @@
+# MCP RAG Server — Como Usar
+
+Este documento explica como usar o MCP Server RAG para buscar código, atualizar índices e trabalhar com a codebase de forma semântica.
+
+## Setup Rápido
+
+O servidor MCP já deve estar configurado em `~/.claude.json`. Se não estiver:
+
+```json
+"mcpServers": {
+  "rag-codebase": {
+    "command": "~/.local/bin/mcp-rag-server",
+    "args": [],
+    "env": {
+      "CHROMA_HOST": "localhost",
+      "CHROMA_PORT": "8000"
+    }
+  }
+}
+```
+
+**Pré-requisitos:**
+- Docker rodando (`docker ps` deve mostrar o container chromadb)
+- ChromaDB inicializado com dados indexados (`~/.rag_db`)
+- mcp-rag-server instalado em `~/.local/bin/`
+
+---
+
+## Ferramentas Disponíveis
+
+### 1. **semantic_search_code** — Busca Semântica
+
+Encontra trechos de código relevantes usando busca vetorial. Funciona com descrições em linguagem natural.
+
+**Parâmetros:**
+- `query` (string): O que você está procurando — pode ser uma descrição vaga
+- `top_k` (int, opcional): Quantos resultados retornar (padrão: 7, máximo: 20)
+
+**Exemplos de uso:**
+
+```
+semantic_search_code("função que valida email")
+semantic_search_code("como fazer requisição HTTP com retry", top_k=5)
+semantic_search_code("integração com banco de dados", top_k=10)
+```
+
+**Resultado:**
+```
+# Resultados para: 'função que valida email'
+
+## [1] /home/<usuario>/projeto/src/validators.py
+**Similaridade:** 92.3%
+
+```
+def validate_email(email: str) -> bool:
+    return "@" in email and "." in email.split("@")[1]
+```
+```
+
+**Dicas:**
+- Use descrições em português ou inglês (o modelo entende bem)
+- Seja específico: "função de autenticação" é melhor que "função"
+- Se poucos resultados úteis, tente reformular a query
+- Resultados acima de 85% geralmente são muito relevantes
+
+---
+
+### 2. **update_file_index** — Atualizar Índice de Arquivo
+
+Após editar um arquivo, use isto para manter o índice RAG sincronizado.
+
+**Parâmetros:**
+- `file_path` (string): Caminho absoluto ou relativo do arquivo
+
+**Exemplos:**
+
+```
+update_file_index("/home/<usuario>/projeto/src/auth.py")
+update_file_index("src/validators.py")
+update_file_index("<PROJECT_ROOT>/bin/mcp_server.py")
+```
+
+**Resultado:**
+```
+Arquivo reindexado com sucesso.
+  Arquivo  : /home/<usuario>/projeto/src/auth.py
+  Chunks antigos removidos: 5
+  Novos chunks inseridos  : 6
+```
+
+**Quando usar:**
+- Depois de editar um arquivo no projeto
+- Depois de criar um novo arquivo
+- Quando a IA faz mudanças no código que deveriam ser searchable
+
+**Nota:** O arquivo é dividido em chunks (~2400 caracteres cada). Alterações pequenas podem afetar múltiplos chunks.
+
+---
+
+### 3. **delete_file_index** — Remover Arquivo do Índice
+
+Remove um arquivo completamente do banco de dados vetorial.
+
+**Parâmetros:**
+- `file_path` (string): Caminho absoluto ou relativo
+
+**Exemplos:**
+
+```
+delete_file_index("/home/<usuario>/projeto/src/old_module.py")
+delete_file_index("temp/debug.py")
+```
+
+**Quando usar:**
+- Quando um arquivo é deletado do projeto
+- Quando você quer excluir um arquivo dos resultados de busca
+
+---
+
+### 4. **index_specific_folder** — Reindexar Pasta
+
+Indexa ou reindexar todos os arquivos de um diretório.
+
+**Parâmetros:**
+- `folder_path` (string): Caminho da pasta a indexar recursivamente
+
+**Exemplos:**
+
+```
+index_specific_folder("/home/<usuario>/projeto/src")
+index_specific_folder("./src/auth")
+```
+
+**Resultado:**
+```
+Indexação da pasta concluída.
+  Pasta    : /home/<usuario>/projeto/src
+  Arquivos processados: 12/12
+  Total de chunks     : 145
+```
+
+**Quando usar:**
+- Depois de criar vários arquivos novos em uma pasta
+- Para reindexar uma seção do projeto após alterações em massa
+- Quando o índice está desatualizado para um diretório
+
+---
+
+## Fluxo Típico de Uso
+
+### Buscar código existente
+```
+1. semantic_search_code("descrição do que procura")
+2. Analisa os resultados
+3. Navega para os arquivos mencionados
+```
+
+### Editar código
+```
+1. Lê o arquivo (Read tool)
+2. Edita o arquivo (Edit tool)
+3. update_file_index(file_path) — IMPORTANTE!
+4. Próximas buscas já veem a versão nova
+```
+
+### Criar novo arquivo
+```
+1. Escreve o arquivo (Write tool)
+2. index_specific_folder(folder_path) OU update_file_index(file_path)
+3. Agora está pronto para ser encontrado em buscas
+```
+
+---
+
+## Entendendo os Resultados
+
+Cada resultado de busca inclui:
+
+- **Número e rank** (ex: [1], [2], etc.)
+- **Arquivo** — caminho completo para localizar o código
+- **Similaridade %** — confiança da correspondência (70-100%)
+- **Snippet** — até 800 caracteres do trecho mais relevante
+
+**Como interpretar similaridade:**
+- 90-100% → Muito relevante, provavelmente exatamente o que procura
+- 80-89%  → Bastante relevante, confira o contexto completo
+- 70-79%  → Relevante, mas pode precisar revisar mais contexto
+- <70%   → Pode ser relevante apenas parcialmente
+
+---
+
+## Limitações e Comportamento
+
+**O que o RAG sabe:**
+- Código-fonte de linguagens de programação
+- Documentação e markdown
+- Configurações (JSON, YAML, etc.)
+- Comentários no código
+
+**O que ignora automaticamente:**
+- Binários (`*.exe`, `*.so`, `*.dll`)
+- Imagens (`*.png`, `*.jpg`)
+- Mídia (`*.mp4`, `*.mp3`)
+- Pacotes (`node_modules/`, `venv/`, `.git/`)
+- Arquivos muito grandes (>500KB)
+
+**Precisão:**
+- O RAG é baseado em similaridade vetorial, não busca literal
+- Reformule a query se os resultados não forem úteis
+- A primeira chamada aquece o modelo (pode levar 1-2s)
+
+---
+
+## Troubleshooting
+
+### "Erro de conexão: Não foi possível conectar ao ChromaDB"
+```bash
+# Verifique se Docker está rodando
+docker ps | grep chromadb
+
+# Se não estiver, inicie
+docker compose -f "$HOME/docker-chromadb/docker-compose.yml" up -d
+```
+
+### "Nenhum resultado encontrado"
+- O índice pode estar vazio — rode `python3 indexer_full.py /seu/projeto`
+- Tente uma query mais simples
+- Verifique se os arquivos estão indexados com `./chroma_monitor.sh chunks`
+
+### Busca retorna resultados muito antigos
+- Arquivo pode ter sido editado mas não atualizado no índice
+- Use `update_file_index(file_path)` para sincronizar
+- Ou `index_specific_folder(folder_path)` para toda a pasta
+
+### Arquivo editado não aparece nos resultados
+1. Confirme que o arquivo foi salvo
+2. Use `update_file_index(file_path)` imediatamente após editar
+3. Aguarde a próxima busca (o modelo está aquecido)
+
+---
+
+## Configuração Avançada
+
+Todas as configurações são definidas em `~/.rag_venv/bin/mcp_server.py`:
+
+```python
+CHUNK_SIZE = 2400        # Caracteres por chunk (~600 tokens)
+CHUNK_OVERLAP = 400      # Sobreposição entre chunks
+EMBEDDING_MODEL = "jinaai/jina-embeddings-v3"  # Modelo de embeddings
+TOP_K_RESULTS = 7        # Resultados padrão por busca
+MAX_FILE_SIZE = 500KB    # Limite de tamanho de arquivo
+```
+
+Para alterar:
+1. Edite `~/.rag_venv/bin/mcp_server.py`
+2. Reinicie o servidor (reinicie o Claude Code)
+3. Reindexe os dados: `python3 indexer_full.py /seu/projeto`
+
+---
+
+## Performance
+
+- **Primeira busca:** 1-2 segundos (aquecimento do modelo)
+- **Buscas subsequentes:** <1 segundo
+- **Indexação de 1 arquivo:** <1 segundo
+- **Indexação de pasta com 100 arquivos:** 10-30 segundos
+
+---
+
+## Exemplos Práticos
+
+### Encontrar tratamento de erros
+```
+semantic_search_code("como fazer try catch ou exception handling")
+```
+
+### Localizar função de login
+```
+semantic_search_code("autenticação de usuário login", top_k=5)
+```
+
+### Buscar integração com API
+```
+semantic_search_code("chamada a API externa requests HTTP")
+```
+
+### Encontrar testes
+```
+semantic_search_code("testes unitários pytest")
+```
+
+### Procurar por padrões de cache
+```
+semantic_search_code("cache memoização performance")
+```
+
+---
+
+## Integração com Claude Code
+
+O MCP Server é automaticamente chamado pelo Claude Code quando você:
+
+1. **Usa a ferramenta de busca** — procura por "semantic_search_code"
+2. **Edita um arquivo** — sincroniza automaticamente com `update_file_index`
+3. **Pede recomendações de código** — busca contexto relevante antes de responder
+
+A IA pode usar todas as 4 ferramentas para:
+- Entender o projeto antes de fazer mudanças
+- Encontrar padrões existentes e seguir convenções
+- Manter o índice atualizado enquanto trabalha
+- Evitar duplicação de código ao sugerir novos
+
+---
+
+**Último update:** 2026-03-05 — Documentação para mcp-rag-server v1.0

package/README.md

@@ -0,0 +1,133 @@
+# MCP binary checksum (SHA-256, payload without shebang): `3246eeb57f901742d915e0bce37fa96f059e149a57bbce73095ff4e5ea51d8d4`
+
+# own-rag
+
+Local RAG for codebases with:
+- ChromaDB (Docker)
+- MCP server (`mcp-rag-server`)
+- CPU embeddings (`jina`, `bge`, `hybrid`)
+- Cross-platform setup (`Linux` and `macOS`)
+
+## Why this repo
+
+`own-rag` lets you index local projects and query them from MCP-compatible tools (Claude/Cursor).
+
+It includes:
+- installers: `rag-setup.run`, `rag-setup-macos.run`
+- MCP server source: `bin/mcp_server.py`
+- indexer source: `bin/indexer_full.py`
+- monitor and wrapper scripts
+
+## Source vs Artifact
+
+This repo is fully auditable:
+- source of logic: `bin/*.py` and `bin/*.sh`
+- generated artifacts: `rag-setup.run`, `rag-setup-macos.run`
+
+To refresh embedded payloads from source files:
+
+```bash
+./bin/build_run.sh
+./bin/build_run_macos.sh
+```
+
+## Quick Start
+
+### Linux
+
+```bash
+chmod +x rag-setup.run
+./rag-setup.run /path/to/project
+```
+
+### macOS
+
+```bash
+chmod +x rag-setup-macos.run
+./rag-setup-macos.run /path/to/project
+```
+
+### NPM wrapper
+
+```bash
+rag run /path/to/project
+rag monitor
+rag remove
+```
+
+## What setup does
+
+1. Creates `~/.rag_venv` and installs dependencies.
+2. Starts ChromaDB in Docker with persistent volume (`~/.rag_db`).
+3. Installs `mcp-rag-server` in `~/.local/bin`.
+4. Optionally updates MCP config files (`.claude.json`, Cursor config).
+5. Indexes the project.
+
+## ChromaDB Port Behavior
+
+- Default host port is `8000`.
+- During ChromaDB install/reinstall, setup asks for the port.
+- The installer checks if the chosen port is already in use using native tools:
+  - Linux: `ss` (fallback: `lsof` / `netstat`)
+  - macOS: `lsof` (fallback: `netstat`)
+- If the port is busy, it asks for another one.
+- In non-interactive runs, it auto-selects the next free port.
+- Selected port is propagated to:
+  - Docker Compose mapping
+  - health checks
+  - MCP config (`CHROMA_PORT`)
+  - indexer runtime (`MCP_CHROMA_PORT`)
+
+## Performance Profiles
+
+Available in indexer/setup:
+- `autotune` (recommended): uses local machine metrics and short benchmark.
+- `max-performance`: higher throughput and higher memory usage risk.
+
+`max-performance` warning shown by setup:
+
+```text
+Este modo pode elevar consideravelmente o consumo de memória e causar encerramento por OOM (exit 137).
+```
+
+## Key Environment Variables
+
+- `MCP_EMBEDDING_MODEL=jina|bge|hybrid`
+- `MCP_JINA_QUANTIZATION=default|dynamic-int8`
+- `MCP_PERF_PROFILE=autotune|max-performance`
+- `MCP_CHROMA_PORT=8000`
+- `MCP_CHUNK_SIZE`
+- `MCP_CHUNK_OVERLAP`
+- `MCP_EMBEDDING_BATCH_SIZE`
+
+## Useful Commands
+
+```bash
+# only index (infra already installed)
+./rag-setup.run /path/to/project --only-index
+
+# skip indexing
+./rag-setup.run /path/to/project --skip-index
+
+# force reinstall
+./rag-setup.run /path/to/project --reinstall
+
+# force model change flow
+./rag-setup.run --change-model /path/to/project
+```
+
+## Development
+
+- Edit source files in `bin/`.
+- Rebuild payloads with `./bin/build_run.sh` and `./bin/build_run_macos.sh`.
+- Validate before commit:
+
+```bash
+bash -n rag-setup.run
+bash -n rag-setup-macos.run
+python3 -m py_compile bin/indexer_full.py
+```
+
+## License
+
+MIT (or your preferred OSS license file in this repo).

package/bin/docker-compose.yml

@@ -0,0 +1,21 @@
+services:
+  chromadb:
+    image: chromadb/chroma:latest
+    container_name: chromadb-rag
+    ports:
+      - "8000:8000"
+    volumes:
+      # Persiste o banco diretamente na pasta do usuário no host
+      - ${HOME}/.rag_db:/chroma/chroma
+    environment:
+      # Habilita autenticação anônima (sem token) para uso local
+      - ANONYMIZED_TELEMETRY=false
+      - CHROMA_SERVER_AUTHN_CREDENTIALS_FILE=""
+      - CHROMA_SERVER_AUTHN_PROVIDER=""
+    restart: always
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/heartbeat"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s

package/bin/download_model_from_hugginface.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+"""
+download_model_from_hugginface.py
+
+Camada de download de modelos com prioridade de provedores e fallback de modelo.
+Fluxo padrão:
+1) tenta baixar o modelo preferido via Hugging Face;
+2) se falhar, tenta provedores alternativos (quando disponíveis);
+3) se o modelo preferido falhar em todos os provedores, tenta modelo fallback.
+"""
+
+from dataclasses import dataclass
+import getpass
+import os
+from pathlib import Path
+import shutil
+import sys
+from typing import Protocol
+
+
+class ModelDownloadStrategy(Protocol):
+    name: str
+
+    def download(self, model_id: str, local_dir: Path) -> None:
+        """Baixa model_id para local_dir ou levanta exceção."""
+
+
+class HuggingFaceDownloadStrategy:
+    name = "huggingface"
+
+    def download(self, model_id: str, local_dir: Path) -> None:
+        from huggingface_hub import snapshot_download
+
+        hf_token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+        _download_with_hf_token_recovery(
+            repo_id=model_id,
+            local_dir=local_dir,
+            hf_token=hf_token,
+            snapshot_download=snapshot_download,
+        )
+
+
+@dataclass(frozen=True)
+class DownloadSelection:
+    model_id: str
+    provider: str
+    local_dir: Path
+
+
+def _load_optional_strategies() -> list[ModelDownloadStrategy]:
+    strategies: list[ModelDownloadStrategy] = []
+
+    try:
+        from download_model_from_modelscope import ModelScopeDownloadStrategy
+
+        strategies.append(ModelScopeDownloadStrategy())
+    except Exception:
+        # Provider opcional: ignora se não estiver disponível no ambiente.
+        pass
+
+    return strategies
+
+
+def build_default_strategies() -> list[ModelDownloadStrategy]:
+    """Factory simples: ordem de prioridade de provedores de download."""
+    return [HuggingFaceDownloadStrategy(), *_load_optional_strategies()]
+
+
+_MODEL_READY_MARKER = ".download_complete"
+
+
+def _prepare_destination(local_dir: Path, *, clean: bool) -> None:
+    if clean and local_dir.exists():
+        shutil.rmtree(local_dir)
+    local_dir.mkdir(parents=True, exist_ok=True)
+
+
+def _model_cache_dir(base_dir: Path, model_id: str) -> Path:
+    # Evita colisão de nomes e mantém diretório seguro em qualquer SO.
+    safe_name = model_id.replace("/", "__").replace(":", "_")
+    return base_dir / safe_name
+
+
+def _cache_ready(local_dir: Path) -> bool:
+    marker = local_dir / _MODEL_READY_MARKER
+    if not marker.exists() or not local_dir.exists():
+        return False
+    return any(p.name != _MODEL_READY_MARKER for p in local_dir.iterdir())
+
+
+def _mark_cache_ready(local_dir: Path) -> None:
+    (local_dir / _MODEL_READY_MARKER).write_text("ok\n", encoding="utf-8")
+
+
+def _status_code_from_error(exc: Exception) -> int | None:
+    response = getattr(exc, "response", None)
+    if response is None:
+        return None
+    status_code = getattr(response, "status_code", None)
+    if isinstance(status_code, int):
+        return status_code
+    return None
+
+
+def _is_invalid_hf_token_error(exc: Exception) -> bool:
+    message = str(exc).lower()
+    status_code = _status_code_from_error(exc)
+    token_keywords = ("invalid token", "token is invalid", "unauthorized", "401")
+    if status_code == 401:
+        return True
+    return any(keyword in message for keyword in token_keywords)
+
+
+def _prompt_recover_invalid_hf_token() -> tuple[str, str | None]:
+    if not sys.stdin.isatty():
+        return ("no-token", None)
+
+    while True:
+        print(
+            "[!] O token do HuggingFace parece inválido. Escolha: "
+            "[1] informar novo token, [2] continuar sem token.",
+            file=sys.stderr,
+        )
+        answer = input("> Escolha [1/2]: ").strip().lower()
+        if answer in {"1", "novo", "new"}:
+            new_token = getpass.getpass("Cole o novo HF_TOKEN: ").strip()
+            if new_token:
+                return ("new-token", new_token)
+            print("[!] Token vazio. Tente novamente.", file=sys.stderr)
+            continue
+        if answer in {"2", "", "sem", "no"}:
+            return ("no-token", None)
+        print("[!] Opção inválida. Digite 1 ou 2.", file=sys.stderr)
+
+
+def _download_with_hf_token_recovery(
+    *,
+    repo_id: str,
+    local_dir: Path,
+    hf_token: str | None,
+    snapshot_download,
+) -> None:
+    attempt_token = hf_token
+
+    while True:
+        try:
+            snapshot_download(
+                repo_id=repo_id,
+                local_dir=str(local_dir),
+                token=attempt_token,
+            )
+            if attempt_token:
+                os.environ["HF_TOKEN"] = attempt_token
+            else:
+                os.environ.pop("HF_TOKEN", None)
+            return
+        except Exception as exc:
+            if attempt_token and _is_invalid_hf_token_error(exc):
+                print(
+                    "[!] Falha de autenticação no HuggingFace com o token atual. "
+                    "Você pode informar outro token ou seguir sem token.",
+                    file=sys.stderr,
+                )
+                action, replacement = _prompt_recover_invalid_hf_token()
+                if action == "new-token" and replacement:
+                    attempt_token = replacement
+                    continue
+                attempt_token = None
+                continue
+            raise
+
+
+def download_model_with_fallback(
+    preferred_model_id: str,
+    fallback_model_id: str,
+    local_dir: Path,
+    strategies: list[ModelDownloadStrategy] | None = None,
+) -> DownloadSelection:
+    """
+    Tenta baixar `preferred_model_id`; se falhar em todos os provedores,
+    tenta `fallback_model_id`.
+    """
+    base_dir = local_dir.expanduser()
+    base_dir.mkdir(parents=True, exist_ok=True)
+    providers = strategies or build_default_strategies()
+    errors: list[str] = []
+
+    for model_id in (preferred_model_id, fallback_model_id):
+        model_local_dir = _model_cache_dir(base_dir, model_id)
+        if _cache_ready(model_local_dir):
+            return DownloadSelection(
+                model_id=model_id,
+                provider="local-cache",
+                local_dir=model_local_dir,
+            )
+
+        for strategy in providers:
+            try:
+                print(
+                    f"[+] Iniciando download do modelo '{model_id}' via {strategy.name} em: {model_local_dir}",
+                    file=sys.stderr,
+                )
+                _prepare_destination(model_local_dir, clean=True)
+                strategy.download(model_id=model_id, local_dir=model_local_dir)
+                _mark_cache_ready(model_local_dir)
+                return DownloadSelection(
+                    model_id=model_id,
+                    provider=strategy.name,
+                    local_dir=model_local_dir,
+                )
+            except Exception as exc:
+                errors.append(f"{strategy.name}:{model_id}: {exc}")
+
+    raise RuntimeError(
+        "Falha no download dos modelos em todos os provedores configurados. "
+        + " | ".join(errors)
+    )

package/bin/download_model_from_modelscope.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+"""
+Provider opcional de download via ModelScope.
+Usado apenas se o pacote `modelscope` estiver instalado.
+"""
+
+from pathlib import Path
+
+
+class ModelScopeDownloadStrategy:
+    name = "modelscope"
+
+    def download(self, model_id: str, local_dir: Path) -> None:
+        try:
+            from modelscope.hub.snapshot_download import snapshot_download
+        except Exception as exc:
+            raise RuntimeError(
+                "Pacote `modelscope` indisponível para provider alternativo"
+            ) from exc
+
+        snapshot_download(
+            model_id=model_id,
+            local_dir=str(local_dir),
+        )