From 0f3778e3e8c845283b139da0b038eff06133383b Mon Sep 17 00:00:00 2001 From: rodolpho Date: Thu, 7 May 2026 18:52:03 -0300 Subject: [PATCH] docs: finalize comprehensive documentation and MCP guide --- MCP_GUIDE.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++ index.md | 38 ++++++++++++++++++++++++----------- 2 files changed, 83 insertions(+), 11 deletions(-) create mode 100644 MCP_GUIDE.md diff --git a/MCP_GUIDE.md b/MCP_GUIDE.md new file mode 100644 index 0000000..813b7f0 --- /dev/null +++ b/MCP_GUIDE.md @@ -0,0 +1,56 @@ +# 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`. + +## 1. Pré-requisitos +* Python 3.9 ou superior. +* Dependências instaladas: + ```bash + 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` + +```json +{ + "mcpServers": { + "fluig-wiki": { + "command": "python", + "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 +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 +``` +*(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` + +Isso garantirá que o servidor MCP sempre forneça as informações mais recentes para a sua IA. diff --git a/index.md b/index.md index e8d8525..bcd4020 100644 --- a/index.md +++ b/index.md @@ -1,16 +1,32 @@ -# Bem-vindo à sua Wiki Técnica Fluig Offline +# Wiki Técnica Fluig Offline & MCP Server -Esta base de dados contém toda a documentação técnica extraída do TDN, otimizada para consulta rápida e uso em modelos de IA locais. +Esta é uma base de conhecimento técnica completa da plataforma TOTVS Fluig, extraída automaticamente do TDN e otimizada para desenvolvedores e sistemas de IA. -### Atalhos Rápidos -* [Desenvolvimento de Datasets](Plataforma Documentação técnica/Desenvolvimento sobre a plataforma/Desenvolvimento de Datasets/Construção do Dataset Avançado.md) -* [Eventos de Processo (BPM)](Plataforma Documentação técnica/Recurso de Processos (BPM).md) -* [Guia de Estilos (Style Guide)](Plataforma Documentação técnica/Desenvolvimento sobre a plataforma/Guia de Estilos.md) +## 🚀 Funcionalidades Principais +* **Extração Inteligente:** Motor assíncrono que mantém a documentação sempre atualizada com o TDN. +* **Wiki Offline:** Interface visual moderna via MkDocs para consulta rápida sem internet. +* **Biblioteca de Snippets:** Todos os exemplos de código (JS, Java, SQL) extraídos e categorizados. +* **Pronto para IA (RAG):** Documentação dividida em chunks semânticos para alimentar modelos de linguagem. +* **Servidor MCP:** Interface nativa para integrar o conhecimento do Fluig diretamente no seu chat de IA. -### Recursos Offline e IA -* **Biblioteca de Snippets:** Veja exemplos de [JS](Biblioteca de Snippets/Snippets JAVASCRIPT.md), [Java](Biblioteca de Snippets/Snippets JAVA.md) e [SQL](Biblioteca de Snippets/Snippets SQL.md). -* **RAG Ready:** Use o `rag_processor.py` para gerar chunks para sua IA local. -* **Manutenção:** Rode `link_validator.py` para garantir que nada esteja quebrado. +## 📂 Estrutura do Projeto +* `fluig_extractor.py`: O motor de extração (Async + Incremental). +* `fluig_rag_docs/`: A base de arquivos Markdown e imagens. +* `mcp_server.py`: O servidor para conexão com IAs. +* `rag_processor.py`: Gerador de chunks para sistemas RAG. +* `snippet_generator.py`: Extrator de exemplos de código. +* `Dockerfile`: Ambiente pronto para deploy da Wiki. + +## 🛠️ Como Começar +1. **Instalação:** `pip install -r requirements.txt` +2. **Ver a Wiki:** `mkdocs serve` e acesse `http://localhost:8000` +3. **Configurar MCP:** Veja o [Guia do MCP](MCP_GUIDE.md). --- -*Gerado automaticamente para uso via Tailscale.* +### 🔗 Atalhos Rápidos +* [Desenvolvimento de Datasets](Plataforma Documentação técnica/Desenvolvimento sobre a plataforma/Desenvolvimento de Datasets/Construção do Dataset Avançado.md) +* [Eventos de Processo (BPM)](Plataforma Documentação técnica/Recurso de Processos (BPM).md) +* [Biblioteca de Snippets JS](Biblioteca de Snippets/Snippets JAVASCRIPT.md) + +--- +*Este projeto visa acelerar o desenvolvimento na plataforma Fluig através de engenharia de conhecimento avançada.*