Experiência do Usuário | Minha jornada criando o XMind-MCP com o TRAE

Este é o relato completo de uma jornada que começou com a frustração de receber arquivos corrompidos gerados por IA e terminou com a criação do XMind-MCP. Se você já tentou abrir um mapa mental feito por uma IA e deu de cara com um erro — ou se tem curiosidade sobre como estender as capacidades de um modelo de linguagem — aqui estão os meus erros, aprendizados e o código final (repositório no fim do post).

O Ponto de Virada: Uma tarde de arquivos corrompidos

Tudo começou numa tarde comum. Pedi ao TRAE que planejasse um roteiro de estudos para Playwright. Para facilitar a visualização, tive a ideia de pedir que ele exportasse o plano no formato de mapa mental do XMind.
A IA me entregou o arquivo rapidamente. Porém, ao tentar abri-lo, o XMind foi implacável: Erro de leitura.
Tentei colar o código do erro de volta no chat, esperando que a IA corrigisse a própria falha. Após várias tentativas frustradas, a ficha caiu: a IA simplesmente não possui a habilidade nativa de estruturar arquivos XMind corretamente.
Se ela não consegue fazer sozinha, eu daria as ferramentas para isso! Decidi criar um utilitário baseado no protocolo MCP (Model Context Protocol) para permitir que a IA manipule arquivos XMind de verdade.

Por que escolhi o formato MCP?

Minha decisão de transformar essa ferramenta em um MCP baseou-se em três pilares:

1. Reutilização e Portabilidade: Eu não queria um código que funcionasse apenas uma vez. Precisava de algo que pudesse ser usado em diferentes projetos e compartilhado com a comunidade para aumentar a produtividade de todos.

2. Baixa Barreira de Entrada: Empacotar a solução como um executável (jar ou npm) seria complexo e limitaria o uso dependendo da linguagem do projeto principal.

3. Integração Nativa com IA: O MCP é hoje o padrão ouro para conectar IAs a capacidades externas. Foi a escolha lógica para que o Agent pudesse "enxergar" e escrever arquivos XMind.

---

Do Zero ao Um: Notas de Desenvolvimento

A Escolha da Stack: O tropeço no Node e a virada para Python

Como era meu primeiro MCP, comecei tateando no escuro com a ajuda do TRAE. Inicialmente, tentei usar Node.js, já que muitos utilitários MCP rodam via npx. Testamos mais de dez pacotes npm diferentes e... nenhum funcionou.
Minha conclusão: Atualmente, não existe uma solução robusta em Node para gerar arquivos XMind que o software oficial reconheça como válidos. Por isso, mudei o foco para o Python.

O Desafio Técnico: Ensinando o "Caminho das Pedras" à IA

Mesmo no Python, o caminho não foi livre de obstáculos. Os primeiros arquivos gerados ainda travavam o XMind devido a problemas na estrutura do XML. No entanto, os logs de erro mudaram, o que indicava que eu estava no caminho certo, apenas pecando nos detalhes de formatação. O segredo seria dar à IA um modelo (template) infalível de como o XMind espera receber os dados.

Já que a IA não fazia ideia de como era a estrutura interna correta de um arquivo XMind, decidi fornecer a "resposta padrão".
Abri o XMind, criei um arquivo simples manualmente e o coloquei no diretório do projeto como um template. Entreguei esse modelo para a IA e pedi que ela analisasse a estrutura interna e o formato do XML para reescrever toda a lógica de geração do zero.
O resultado foi um divisor de águas: em apenas algumas rodadas de conversa, a IA gerou o código central capaz de criar arquivos XMind perfeitos, sem um único erro de leitura!
Essa experiência me deixou uma lição valiosa no desenvolvimento com IA: quando o modelo não sabe como executar uma tarefa específica, forneça um exemplo real. Isso soa familiar? É exatamente a filosofia por trás das Skills. Em vez de esperar que a IA adivinhe o padrão, você a "treina" com um contexto de alta qualidade para que ela execute a tarefa com precisão cirúrgica.

Encapsulamento MCP: O desvio pelo servidor e o caminho certo via PyPI
Com o núcleo da funcionalidade pronto, o desafio seguinte era transformá-lo em uma ferramenta MCP pronta para consumo por IA.
Pela falta de experiência prévia com o protocolo, recorri à própria IA em busca de diretrizes. A sugestão "padrão ouro" que recebi foi hospedar o XMind MCP em um servidor, expondo suas funções via interface HTTP. Convencido pela proposta, cheguei a analisar a fundo diversas opções de hospedagem gratuita, comparando prós e contras de cada arquitetura de servidor.

☁️ XMind MCP Server - Comparativo Detalhado de Soluções de Implantação em Nuvem

🎯 Visão Geral da Solução

Este comparativo abrange as principais soluções gratuitas de implantação em nuvem, ajudando você a escolher o método mais adequado.

📊 Tabela de Comparação Detalhada

Característica	GitHub Codespaces	Replit (Plano Gratuito)	Render (Plano Gratuito)	Fly.io (Plano Gratuito)	Railway (Plano Gratuito)
Execução Contínua	❌ Timeout de sessão (4h)	❌ Hiberna em 15 min	❌ Hiberna em 15 min	✅ "Always On" (Opcional)	✅ Execução contínua
Tempo de "Cold Start"	30-60 segundos	10-30 segundos	30-60 segundos	1-3 segundos	5-15 segundos
Despertar Automático	✅ Renovação de sessão	✅ Acionamento HTTP	✅ Acionamento HTTP	✅ Acionamento HTTP	✅ Acionamento HTTP
Cota Gratuita	60 horas/mês	Totalmente Gratuito	750 horas/mês	Crédito de $5/mês	Crédito de $5/mês
Limites de Recursos	2 Núcleos CPU + 4GB RAM + 32GB Armaz.	1GB Armaz. + CPU Compartilhada	512MB RAM + CPU Compartilhada	3 CPU + 256MB RAM + 3GB Armaz.	1 CPU + 512MB RAM + 1GB Armaz.
Qtd. de Aplicações	Ilimitado	Ilimitado	Ilimitado	10 por organização	Ilimitado
Tráfego de Rede	Sem limite explícito	Sem limite explícito	100GB/mês	100GB/mês	Sem limite explícito
Complexidade	⭐ Configuração Zero	⭐ Extremamente Simples	⭐⭐ Requer Configuração	⭐⭐⭐ Requer Configuração	⭐⭐ Configuração Simples
Índice de Recomendação	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐

Validei cada uma das opções de implantação em servidor, apenas para confirmar que o XMind MCP era incompatível com o modelo de serviços via HTTP. Diante do impasse, mudei de tática: fui ao marketplace do TRAE analisar o método de instalação dos MCPs mais populares para orientar a IA.
A constatação foi imediata: a maioria das ferramentas dispensa servidores remotos, privilegiando a instalação local. É o caso do Playwright, framework que venho estudando e que segue justamente essa arquitetura simplificada.

Paralelamente, debrucei-me sobre a documentação oficial do Model Context Protocol no portal do TRAE ：https://docs.trae.cn/ide/model-context-protocol.
A análise confirmou que a instalação e o empacotamento local fundamentam-se, essencialmente, em três modalidades distintas:
Configurar o Ambiente do Sistema
Para garantir a inicialização correta do MCP Server, você pode precisar instalar:

• npx: Depende do Node.js, a versão deve ser igual ou superior a 18.

• uvx: Uma ferramenta de execução rápida baseada em Python, requer instalação manual.

• (Opcional) Docker: Plataforma de conteinerização para isolar e executar aplicativos. Deve-se instalar a versão correspondente ao seu sistema. Caso utilize o GitHub MCP Server, o uso do Docker será necessário.

Como a linguagem de programação usada neste projeto é Python, a escolha óbvia é o uvx!
Se quisermos instalar via uvx, primeiro é necessário empacotar e publicar o projeto no PyPI.
Portanto, eu criei uma conta no PyPI e empacotei o projeto para publicá-lo na plataforma.

No momento em que consegui executar pip install XMind-mcp com sucesso, foi uma sensação incrível. Depois de tantos anos escrevendo código, finalmente consegui fazer com que outras pessoas instalassem meu pacote!
Após definir a forma de instalação do MCP, ainda era preciso decidir como conectar o MCP. As formas mais comuns de conexão são FastMCP e stdio, e eu optei pelo FastMCP.
Durante a configuração do FastMCP, enfrentei alguns desafios e percebi que modelos grandes diferentes têm desempenhos variados ao resolver o mesmo problema.

Para minha surpresa, modelos estrangeiros como GPT-5 não conseguiram me ajudar a resolver o problema de conexão do MCP, mas o Kimi K2 conseguiu.
Essa experiência me ensinou uma lição valiosa:
Quando você encontra um problema e várias tentativas de diálogo não resolvem, não insista cegamente. Experimente mudar de modelo ou buscar outra perspectiva. É como pedir a opinião de alguém quando você está travado — às vezes a solução aparece de repente.

Prática e iteração: de “funcional” para “bem utilizável”

Depois que a ferramenta MCP começou a rodar, surgiu um novo problema: onde o arquivo XMind gerado estava sendo salvo?
Percebi que, como o MCP é instalado via uvx no ambiente uv, o “diretório atual” que ele obtém durante a execução não é o diretório de trabalho do meu projeto, fazendo com que o arquivo gerado ficasse “desaparecido”.

Para resolver esse problema, adotei duas melhorias a partir de uma perspectiva de produto:

1. Definir o caminho de saída como parâmetro de entrada: adicionei um parâmetro obrigatório de caminho de saída, permitindo que o AI especifique onde salvar o arquivo gerado.

2. Retorno claro do caminho: após a execução bem-sucedida, o MCP deve retornar o caminho absoluto do arquivo gerado, facilitando para o usuário localizar o arquivo.

Depois de testar localmente com sucesso, convidei o Nolan da comunidade para ajudar nos testes. E como esperado, quando tudo parece certo, algo inesperado acontece. No projeto dele, parecia que o AI não entendeu completamente como chamar corretamente meu XMind MCP, resultando em uma estrutura XMind gerada incorreta.

Acredito que o problema esteja na “compreensão” da ferramenta pelo AI. Preciso fazer com que meu MCP “se apresente” de forma mais clara.
Então, recorri ao TRAE para perguntar ao AI se havia uma boa solução para isso.
O resultado foi exatamente como eu suspeitava: era necessário aperfeiçoar a auto-descrição do MCP.

Em seguida, usei o TRAE para otimizar as informações de auto-descrição do MCP, detalhando o propósito e a estrutura de dados de cada parâmetro em cada método, especialmente como o parâmetro principal data deve organizar a hierarquia dos dados.

O efeito dessa otimização foi notável. Após 4 dias e 21 versões de iteração, com a ajuda contínua do TRAE, a ferramenta XMind MCP finalmente alcançou um estado estável e fácil de usar. Agora, o AI já consegue gerar mapas mentais com estrutura clara e conteúdo correto de uma só vez.

Três passos para usar o XMind-MCP

Usar essa ferramenta é muito simples — afinal, uma ferramenta feita para o AI não deve complicar a vida do usuário humano.
Passo 1: Copie a configuração e vá até TRAE → Configurações → Aba “MCP”, clique em “Adicionar manualmente” e cole o seguinte JSON:

{
  "mcpServers": {
    "XMind": {
      "command": "uvx",
      "args": [
        "XMind-mcp",
        "--mode",
        "fastmcp"
      ]
    }
  }
}

Passo 2: se o seu computador ainda não tiver o Python ou o uv instalados, o TRAE vai te guiar durante a instalação. Para usuários do Windows, após instalar o uv, certifique-se de adicionar manualmente o caminho de instalação do uv (geralmente C:\Users\SeuNomeDeUsuario\.uv\bin) às variáveis de ambiente do sistema, na seção Path.

Passo 3: Após a instalação bem-sucedida, selecione o agente no qual você acabou de configurar o XMind-MCP. A partir daí, você já pode enviar comandos diretamente para a IA.

Por exemplo, você pode dizer: “Me ajude a gerar um arquivo XMind sobre aprendizado de agentes usando o XMind MCP.”

O que o XMind MCP pode fazer?

Atualmente, o XMind-MCP oferece as seguintes funcionalidades principais:

• Ler mapas mentais: acessar e extrair informações de cada nó de arquivos XMind.

• Criar mapas mentais: gerar novos arquivos XMind a partir de dados estruturados (como JSON).

• Conversão de formatos de arquivo: suporta converter conteúdos de TXT, Markdown, HTML, Word, Excel e outros formatos diretamente para mapas mentais XMind.

• Analisar a estrutura do mapa mental: avaliar o número de nós, a profundidade máxima e fornecer uma análise de “saúde” do mapa.

• Busca de arquivos: listar todos os arquivos XMind em um diretório específico.