feat: add remote mcp proxy and update guide for zero-download access

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,8 +1,8 @@
 import json
 import os
-import argparse
 from typing import List, Dict
 from mcp.server.fastmcp import FastMCP
+import argparse
 
 # Inicializa o servidor FastMCP
 mcp = FastMCP("Fluig Technical Wiki")
@@ -67,7 +67,7 @@ def get_code_snippets(language: str) -> str:
         with open(path, "r", encoding="utf-8") as f:
             return f.read()
             
-    return f"Arquivo de snippets para {language} não encontrado. Certifique-se de que o snippet_generator.py foi executado."
+    return f"Arquivo de snippets para {language} não encontrado."
 
 @mcp.resource("docs://all_titles")
 def list_all_titles() -> str:
@@ -78,14 +78,11 @@ def list_all_titles() -> str:
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(description="Fluig MCP Server")
-    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")