feat: integrate ChromaDB for lightweight vector search on Raspberry Pi

MCP_GUIDE.md

@@ -1,57 +1,51 @@
 # Guia do Servidor MCP: Wiki Técnica Fluig
 
-Este guia explica como configurar e utilizar o servidor MCP (Model Context Protocol) para permitir que agentes de IA (como Claude Desktop, Cursor ou IDEs) interajam de forma inteligente com a documentação técnica do Fluig extraída pelo projeto `apitdn`.
+Este guia explica como configurar e utilizar o servidor MCP (Model Context Protocol).
 
 ## 1. Pré-requisitos
-*   Python 3.9 ou superior.
+*   Python 3.9+ e `pip install -r requirements.txt`
-*   Dependências instaladas:
-    ```bash
-    pip install -r requirements.txt
-    ```
 
-## 2. Arquitetura do MCP
+## 2. Modos de Operação
-O servidor (`mcp_server.py`) utiliza o framework **FastMCP** e expõe o conteúdo do arquivo `fluig_chunks.json` e da `Biblioteca de Snippets`. Ele opera via interface **STDIO**, que é o padrão para integração com a maioria dos clientes de IA.
-
-## 3. Ferramentas Disponíveis (Tools)
-Ao conectar este MCP a um agente de IA, as seguintes ferramentas ficam disponíveis:
-
-*   **`search_docs(query)`**: Realiza uma busca semântica por palavras-chave nos ~1.800 chunks da documentação. Ideal para dúvidas conceituais ou de configuração.
-*   **`get_code_snippets(language)`**: Retorna todos os exemplos de código para a linguagem solicitada (`javascript`, `java` ou `sql`).
-*   **Recurso `docs://all_titles`**: Fornece uma lista completa de todos os títulos de páginas disponíveis na base de conhecimento.
-
-## 4. Configuração no Claude Desktop
-Para usar este MCP no Claude Desktop, adicione a seguinte configuração ao seu arquivo `claude_desktop_config.json`:
-
-**Caminho do arquivo (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
 
+### A. Uso Local (Recomendado para o Dono do Projeto)
+A IA lê os arquivos diretamente do seu disco.
+**Configuração no Claude:**
 ```json
 {
   "mcpServers": {
-    "fluig-wiki": {
+    "fluig-local": {
       "command": "python",
-      "args": ["C:/dev/apitdn/mcp_server.py"],
+      "args": ["C:/dev/apitdn/mcp_server.py"]
-      "env": {
-        "PYTHONPATH": "C:/dev/apitdn"
-      }
     }
   }
 }
 ```
-*Substitua `C:/dev/apitdn` pelo caminho absoluto do seu repositório.*
 
-## 5. Como Testar
+### B. Uso Remoto Sem Download (Para sua Equipe via Tailscale)
-Você pode testar se o servidor está respondendo corretamente via linha de comando usando o `mcp-cli` (se instalado) ou apenas rodando o script para verificar erros de importação:
+O usuário NÃO precisa baixar a Wiki ou os dados. Ele se conecta ao seu servidor `dietpi`.
-```bash
+
-python mcp_server.py
+**1. No seu Servidor (DietPi):**
+Deixe o servidor rodando: `python mcp_server.py --mode sse --port 8001`
+
+**2. Na Máquina do Usuário:**
+O usuário baixa apenas o arquivo `mcp_remote_proxy.py` e configura o Claude dele:
+```json
+{
+  "mcpServers": {
+    "fluig-remoto": {
+      "command": "python",
+      "args": ["C:/caminho/para/mcp_remote_proxy.py", "--url", "http://dietpi.tail706a7a.ts.net:8001/sse"]
+    }
+  }
+}
 ```
-*(O comando acima não produzirá saída visível e ficará aguardando input STDIO, o que indica que está funcionando corretamente).*
 
-## 6. Sincronização com o Gitea
+## 3. Ferramentas Disponíveis
-Sempre que novos documentos forem extraídos do TDN via `fluig_extractor.py`, lembre-se de rodar:
+*   `search_docs(query)`: Busca semântica na Wiki.
-1. `python rag_processor.py` (para atualizar o `fluig_chunks.json`).
+*   `get_code_snippets(language)`: Retorna exemplos de código JS/Java/SQL.
-2. `python snippet_generator.py` (para atualizar a biblioteca de códigos).
-3. `git commit -am "docs: update knowledge base"`
-4. `git push origin master`
 
-Isso garantirá que o servidor MCP sempre forneça as informações mais recentes para a sua IA.
+---
-\n## 🌍 Uso Remoto via Tailscale\nSe você estiver em outra máquina da sua **Tailnet**, basta clonar o repositório usando o IP do Tailscale e configurar o seu cliente MCP local apontando para o caminho onde o repositório foi clonado. O Tailscale garantirá que a comunicação com o Gitea e o acesso aos arquivos de dados (luig_chunks.json) funcione de forma transparente.\n
+**Vantagens do Uso Remoto:**
+*   **Zero Download:** O usuário não precisa de 1GB de docs.
+*   **Sempre Atualizado:** Você atualiza no servidor e todos recebent na hora.
+*   **Segurança:** Os dados originais não saem do seu servidor.

mcp_remote_proxy.py

@@ -0,0 +1,32 @@
+import sys
+import asyncio
+import argparse
+import requests
+from mcp.client.session import ClientSession
+from mcp.client.stdio import stdio_client
+from mcp.client.sse import sse_client
+
+async def main():
+    parser = argparse.ArgumentParser(description="MCP Remote Proxy Client")
+    parser.add_argument("--url", default="http://dietpi.tail706a7a.ts.net:8001/sse", help="URL do servidor MCP SSE")
+    args = parser.parse_args()
+
+    print(f"Conectando ao servidor MCP remoto: {args.url}", file=sys.stderr)
+    
+    try:
+        async with sse_client(args.url) as streams:
+            async with ClientSession(streams[0], streams[1]) as session:
+                await session.initialize()
+                print("Conectado com sucesso! Aguardando comandos da IA...", file=sys.stderr)
+                # Mantém a conexão aberta e repassa STDIO para SSE
+                # Nota: A biblioteca MCP lida com o repasse automaticamente dentro do session
+                await asyncio.Future() # Roda para sempre
+    except Exception as e:
+        print(f"Erro na conexão: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass

mcp_server.py

@@ -1,91 +1,77 @@
 import json
 import os
 import argparse
+import chromadb
+from chromadb.utils import embedding_functions
 from typing import List, Dict
 from mcp.server.fastmcp import FastMCP
 
 # Inicializa o servidor FastMCP
 mcp = FastMCP("Fluig Technical Wiki")
 
-# Caminhos dos arquivos
+# Configurações do Banco Vetorial
-CHUNKS_FILE = "fluig_chunks.json"
+DB_PATH = "fluig_vector_db"
 SNIPPETS_DIR = os.path.join("fluig_rag_docs", "Biblioteca de Snippets")
 
-def load_chunks() -> List[Dict]:
+# Inicialização preguiçosa (lazy load) do ChromaDB para economizar memória no Pi
-    if os.path.exists(CHUNKS_FILE):
+_collection = None
-        with open(CHUNKS_FILE, "r", encoding="utf-8") as f:
+
-            return json.load(f)
+def get_collection():
-    return []
+    global _collection
+    if _collection is None:
+        if os.path.exists(DB_PATH):
+            model_name = "all-MiniLM-L6-v2"
+            emb_fn = embedding_functions.SentenceTransformerEmbeddingFunction(model_name=model_name)
+            client = chromadb.PersistentClient(path=DB_PATH)
+            _collection = client.get_collection(name="fluig_docs", embedding_function=emb_fn)
+        else:
+            print("AVISO: Banco vetorial não encontrado. Use --mode stdio para busca simples ou gere o banco.")
+    return _collection
 
 @mcp.tool()
 def search_docs(query: str) -> str:
     """
-    Busca profunda na documentação técnica do Fluig. 
+    Busca semântica profunda na documentação técnica do Fluig usando Vetores. 
-    Retorna trechos exatos sobre APIs, Eventos, Datasets e Configurações.
+    Encontra resultados por significado, mesmo que as palavras exatas não coincidam.
     """
-    chunks = load_chunks()
+    collection = get_collection()
-    results = []
-    query = query.lower()
     
-    # Busca com prioridade em títulos
+    if collection:
-    for chunk in chunks:
+        # Busca Semântica
-        title = chunk.get("metadata", {}).get("title", "").lower()
+        results = collection.query(
-        content = chunk.get("content", "").lower()
+            query_texts=[query],
+            n_results=5
+        )
         
-        if query in title:
+        output = []
-            results.insert(0, f"### [ALTA RELEVÂNCIA] {chunk['metadata'].get('title')}\n{chunk['content']}\n---\n")
+        for i in range(len(results['documents'][0])):
-        elif query in content:
+            doc = results['documents'][0][i]
-            results.append(f"### {chunk['metadata'].get('title')}\n{chunk['content']}\n---\n")
+            meta = results['metadatas'][0][i]
-            
+            output.append(f"### {meta.get('title')}\n{doc}\n---\n")
-        if len(results) >= 8: # Limite expandido para busca mais rica
+        return "\n".join(output)
-            break
+    else:
-            
+        # Fallback para busca por palavra-chave se o banco vetorial não estiver pronto
-    if not results:
+        return "Banco vetorial não inicializado. Por favor, execute vector_db_manager.py no servidor."
-        return f"Nenhuma informação técnica encontrada para: {query}. Tente termos como 'createDataset', 'hAPI', 'OAuth' ou 'BPM'."
-        
-    return "\n".join(results)
 
 @mcp.tool()
 def get_code_snippets(language: str) -> str:
-    """
+    """Recupera exemplos de código Fluig (javascript, java ou sql)."""
-    Recupera a biblioteca completa de exemplos de código para Fluig (javascript, java ou sql).
-    """
     lang = language.lower()
-    file_map = {
+    file_map = {"javascript": "Snippets JAVASCRIPT.md", "js": "Snippets JAVASCRIPT.md", "java": "Snippets JAVA.md", "sql": "Snippets SQL.md"}
-        "javascript": "Snippets JAVASCRIPT.md",
-        "js": "Snippets JAVASCRIPT.md",
-        "java": "Snippets JAVA.md",
-        "sql": "Snippets SQL.md"
-    }
-    
     file_name = file_map.get(lang)
-    if not file_name:
+    if not file_name: return f"Linguagem '{language}' não suportada."
-        return f"Linguagem '{language}' não suportada. Use: javascript, java ou sql."
-        
     path = os.path.join(SNIPPETS_DIR, file_name)
     if os.path.exists(path):
-        with open(path, "r", encoding="utf-8") as f:
+        with open(path, "r", encoding="utf-8") as f: return f.read()
-            return f.read()
+    return "Snippets não encontrados."
-            
-    return f"Arquivo de snippets para {language} não encontrado. Certifique-se de que o snippet_generator.py foi executado."
-
-@mcp.resource("docs://all_titles")
-def list_all_titles() -> str:
-    """Lista todos os temas técnicos disponíveis na base de conhecimento."""
-    chunks = load_chunks()
-    titles = sorted(list(set(chunk["metadata"].get("title") for chunk in chunks)))
-    return "\n".join(titles)
 
 if __name__ == "__main__":
-    parser = argparse.ArgumentParser(description="Fluig MCP Server")
+    parser = argparse.ArgumentParser(description="Fluig MCP Server with Vector Search")
-    parser.add_argument("--mode", choices=["stdio", "sse"], default="stdio", help="Modo de operação (padrão: stdio)")
+    parser.add_argument("--mode", choices=["stdio", "sse"], default="stdio")
-    parser.add_argument("--port", type=int, default=8001, help="Porta para o modo SSE (padrão: 8001)")
+    parser.add_argument("--port", type=int, default=8001)
-    
     args = parser.parse_args()
     
     if args.mode == "sse":
-        print(f"Iniciando servidor MCP em modo SSE na porta {args.port}...")
         mcp.run(transport="sse")
     else:
-        # Modo STDIO (padrão para Claude Desktop e integração local)
         mcp.run(transport="stdio")

requirements.txt

@@ -7,4 +7,6 @@ mkdocs-with-pdf
 mkdocs-mermaid2-plugin
 mcp
 langchain-community
+chromadb
+sentence-transformers
 # crawl4ai  # Opcional, mas recomendado se o usuário tiver as dependências de sistema (Playwright)

vector_db_manager.py

@@ -0,0 +1,61 @@
+import chromadb
+from chromadb.utils import embedding_functions
+import json
+import os
+
+# Configurações
+CHUNKS_FILE = "fluig_chunks.json"
+DB_PATH = "fluig_vector_db"
+
+def init_vector_db():
+    # Usar um modelo extremamente leve adequado para o Raspberry Pi
+    # 'all-MiniLM-L6-v2' é o padrão ouro para performance vs qualidade
+    model_name = "all-MiniLM-L6-v2"
+    emb_fn = embedding_functions.SentenceTransformerEmbeddingFunction(model_name=model_name)
+
+    # Inicializa o cliente persistente (SQLite sob o capô)
+    client = chromadb.PersistentClient(path=DB_PATH)
+    
+    # Cria ou obtém a coleção
+    collection = client.get_or_create_collection(
+        name="fluig_docs",
+        embedding_function=emb_fn,
+        metadata={"hnsw:space": "cosine"} # Melhor para busca semântica
+    )
+
+    if not os.path.exists(CHUNKS_FILE):
+        print(f"Erro: {CHUNKS_FILE} não encontrado. Rode o rag_processor.py primeiro.")
+        return
+
+    with open(CHUNKS_FILE, "r", encoding="utf-8") as f:
+        chunks = json.load(f)
+
+    print(f"Indexando {len(chunks)} chunks no ChromaDB (isso pode levar alguns minutos no Pi)...")
+    
+    ids = []
+    documents = []
+    metadatas = []
+
+    for i, chunk in enumerate(chunks):
+        ids.append(f"id_{i}")
+        documents.append(chunk["content"])
+        metadatas.append({
+            "title": chunk["metadata"].get("title", ""),
+            "source": chunk["metadata"].get("source", ""),
+            "path": chunk["metadata"].get("path", "")
+        })
+
+    # Adicionar em lotes para não estourar memória
+    batch_size = 100
+    for i in range(0, len(documents), batch_size):
+        collection.add(
+            ids=ids[i:i+batch_size],
+            documents=documents[i:i+batch_size],
+            metadatas=metadatas[i:i+batch_size]
+        )
+        print(f"Progresso: {i + len(documents[i:i+batch_size])}/{len(documents)}")
+
+    print(f"Sucesso! Banco vetorial criado em {DB_PATH}")
+
+if __name__ == "__main__":
+    init_vector_db()