feat: add remote mcp proxy and update guide for zero-download access
This commit is contained in:
rodolpho
+33
-39
@@ -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
|
||||
---
|
||||
**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.
|
||||
|
||||
@@ -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
|
||||
+4
-7
@@ -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")
|
||||
|
||||
Reference in New Issue
Block a user