diff --git a/MCP_GUIDE.md b/MCP_GUIDE.md index 0f072a3..6923776 100644 --- a/MCP_GUIDE.md +++ b/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. -* Dependências instaladas: - ```bash - pip install -r requirements.txt - ``` +* Python 3.9+ e `pip install -r requirements.txt` -## 2. Arquitetura do MCP -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` +## 2. Modos de Operação +### 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"], - "env": { - "PYTHONPATH": "C:/dev/apitdn" - } + "args": ["C:/dev/apitdn/mcp_server.py"] } } } ``` -*Substitua `C:/dev/apitdn` pelo caminho absoluto do seu repositório.* -## 5. Como Testar -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: -```bash -python mcp_server.py +### B. Uso Remoto Sem Download (Para sua Equipe via Tailscale) +O usuário NÃO precisa baixar a Wiki ou os dados. Ele se conecta ao seu servidor `dietpi`. + +**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 -Sempre que novos documentos forem extraídos do TDN via `fluig_extractor.py`, lembre-se de rodar: -1. `python rag_processor.py` (para atualizar o `fluig_chunks.json`). -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` +## 3. Ferramentas Disponíveis +* `search_docs(query)`: Busca semântica na Wiki. +* `get_code_snippets(language)`: Retorna exemplos de código JS/Java/SQL. -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 \ No newline at end of file +--- +**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. diff --git a/mcp_remote_proxy.py b/mcp_remote_proxy.py new file mode 100644 index 0000000..b1a7305 --- /dev/null +++ b/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 diff --git a/mcp_server.py b/mcp_server.py index e7f7457..79357da 100644 --- a/mcp_server.py +++ b/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("--port", type=int, default=8001, help="Porta para o modo SSE (padrão: 8001)") - + parser.add_argument("--mode", choices=["stdio", "sse"], default="stdio") + 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")