TheBrain MCP Server

Interaja com o sistema de gerenciamento de conhecimento do TheBrain usando sua API.

GitHub
16
Experimente este MCPPatrocinado

Documentação

Servidor MCP TheBrain

Um servidor MCP (Model Context Protocol) que permite que assistentes de IA interajam com o sistema de gerenciamento de conhecimento do TheBrain. Este servidor fornece acesso abrangente à API do TheBrain, com foco na interação em linguagem natural com os poderosos recursos de gerenciamento de conhecimento do TheBrain.

🔧 O que é um servidor MCP?

MCP (Model Context Protocol) é um padrão que permite que assistentes de IA como o Claude se conectem a ferramentas e serviços externos. Pense nele como um tradutor entre linguagem natural e APIs de software.

Como funciona:

You → Claude → MCP Server → TheBrain API → Your Brain
  1. Você diz: "Crie um projeto com três fases"
  2. O Claude entende o que você deseja realizar
  3. O servidor MCP traduz isso em chamadas específicas da API do TheBrain
  4. A API do TheBrain cria os pensamentos e conexões
  5. Seu cérebro é atualizado com a nova estrutura

A mágica é que você não precisa saber nenhum detalhe técnico — basta descrever o que deseja em linguagem simples!

🚀 O que realmente funciona

✅ Funcionalidade principal (funcionando)

  • Gerenciamento de conteúdo: Criar, atualizar e excluir pensamentos e notas
  • Anexos de arquivos: Enviar imagens, PDFs e documentos para pensamentos
  • Referências da web: Anexos de URL com extração automática de título
  • Notas ricas: Suporte completo a Markdown com conteúdo incorporado
  • Mapeamento de relacionamentos: Conectar pensamentos com relacionamentos significativos
  • Busca: Pesquisa de texto completo em pensamentos, notas e anexos
  • Gerenciamento de cérebros: Alternar entre vários cérebros sem interrupções
  • Interface em linguagem natural: Descreva o que deseja, o Claude cuida dos detalhes

❌ Problemas e limitações atuais

🚨 Principais problemas de estilo visual

A maior limitação: As propriedades visuais não são aplicadas, apesar das respostas de sucesso da API.

  • ❌ Cores dos pensamentos: A API aceita cores, mas elas não aparecem no TheBrain
  • ❌ Cores dos links: Problema semelhante — aceitas, mas não aplicadas
  • ❌ Espessura dos links: A API relata sucesso, mas a espessura não muda
  • ❌ Formatação visual: Todos os recursos de estilo visual estão atualmente não funcionais

🐛 Outros problemas conhecidos

  • Problemas de conexão intermitentes: Erros de "Campo obrigatório" após operações bem-sucedidas
  • Limitações de notas longas: Problemas com conteúdo Markdown muito extenso (mantenha abaixo de 10 mil caracteres)
  • Sensibilidade ao caminho do arquivo: Requer caminhos de arquivo absolutos; caminhos relativos podem falhar
  • Tempo de conexão: Condição de corrida na inicialização do MCP causando falhas esporádicas
  • Restrições de memória: Anexos de arquivos grandes podem causar tempos limite
  • Limitações de busca: Consultas complexas às vezes retornam resultados incompletos

📋 Dependências e restrições da API

  • Operações de usuário único: Sem recursos de colaboração em tempo real
  • Sem operações em lote: Não é possível importar/exportar grandes conjuntos de dados com eficiência
  • Conectividade com a API necessária: Não há modo offline disponível
  • Limitações da API do TheBrain: Limitado pelos recursos existentes da API
  • Autenticação necessária: Deve ter uma chave de API válida do TheBrain

🛠 Soluções alternativas atuais

Até que o estilo visual seja corrigido, use estas alternativas:

  • Emojis para distinção: 🟢🟡🔴⚪🔵 em vez de cores
  • Nomes descritivos: "🔴 Tarefa urgente" em vez de pensamentos coloridos
  • Notas Markdown ricas: Use formatação dentro das notas para organização visual
  • Estrutura hierárquica: Dependa de relacionamentos pai/filho para organização

Instalação

  1. Clone este repositório:
git clone https://github.com/redmorestudio/thebrain-mcp.git
cd thebrain-mcp
  1. Instale as dependências:
npm install
  1. Crie um arquivo .env com sua chave de API:
THEBRAIN_API_KEY=your_api_key_here
THEBRAIN_DEFAULT_BRAIN_ID=optional_default_brain_id

Configuração

Para o Claude Desktop

Adicione à configuração do seu Claude Desktop:

{
  "mcpServers": {
    "thebrain": {
      "command": "node",
      "args": ["/absolute/path/to/thebrain-mcp/index.js"],
      "env": {
        "THEBRAIN_API_KEY": "your_api_key_here"
      }
    }
  }
}

⚠️ Importante: Use caminhos de arquivo absolutos na configuração e para anexos de arquivos.

Depuração e solução de problemas

Problemas comuns e soluções

Erros de "Campo obrigatório":

  • Reinicie o Claude Desktop
  • Verifique se o arquivo .env tem a chave de API correta
  • Sempre defina o cérebro ativo primeiro: "Defina meu cérebro ativo como [nome]"

Falhas no envio de arquivos:

  • Use caminhos de arquivo absolutos: /Users/username/Documents/file.pdf
  • Verifique as permissões e a existência do arquivo
  • Mantenha tamanhos de arquivo razoáveis (< 50 MB)

Problemas com notas longas:

  • Mantenha as notas abaixo de 10.000 caracteres
  • Divida conteúdo grande em vários pensamentos
  • Use anexos para documentos extensos

Modo de depuração:

VERBOSE=true node index.js

Ferramentas disponíveis (mais de 25 funções)

Gerenciamento de cérebros

  • list_brains - Listar todos os cérebros disponíveis
  • get_brain - Obter detalhes do cérebro
  • set_active_brain - Definir o cérebro ativo para operações
  • get_brain_stats - Obter estatísticas abrangentes do cérebro

Operações de pensamento

  • create_thought - Criar pensamentos (propriedades visuais não funcionam)
  • get_thought - Recuperar detalhes do pensamento
  • update_thought - Atualizar propriedades do pensamento
  • delete_thought - Excluir um pensamento
  • search_thoughts - Buscar no cérebro
  • get_thought_graph - Obter pensamento com todas as conexões
  • get_types - Listar todos os tipos de pensamento
  • get_tags - Listar todas as tags

Operações de links

  • create_link - Criar links entre pensamentos (estilo não funciona)
  • update_link - Modificar propriedades do link
  • get_link - Obter detalhes do link
  • delete_link - Remover um link

Operações de anexos

  • add_file_attachment - Anexar arquivos/imagens a pensamentos ✅
  • add_url_attachment - Anexar URLs da web ✅
  • get_attachment - Obter metadados do anexo
  • get_attachment_content - Baixar conteúdo do anexo
  • delete_attachment - Remover anexos
  • list_attachments - Listar anexos do pensamento

Operações de notas

  • get_note - Recuperar notas em markdown/html/texto ✅
  • create_or_update_note - Criar ou atualizar notas ✅
  • append_to_note - Adicionar conteúdo a notas existentes ✅

Recursos avançados

  • get_modifications - Visualizar histórico de modificações do cérebro

Exemplos de uso (o que realmente funciona)

Organização de projetos

You: "Create a project called 'Kitchen Renovation'"
Claude: Creates central project thought

You: "Add phases for planning, demolition, and installation"  
Claude: Creates connected sub-thoughts for each phase

You: "Attach my contractor quotes to the planning phase"
Claude: Uploads files to the planning thought

You: "Add a detailed note about the timeline to the project"
Claude: Creates rich markdown note with your timeline

Pesquisa e gerenciamento de conhecimento

You: "Create a research topic about sustainable energy"
Claude: Sets up main research thought

You: "Add sub-topics for solar, wind, and hydro power"
Claude: Creates organized thought hierarchy

You: "Attach relevant papers and web articles"
Claude: Adds file and URL attachments

You: "Search for everything related to efficiency"
Claude: Finds all relevant thoughts and content

🔮 Roteiro e desenvolvimento futuro

Prioridades imediatas (v1.2.0)

  • 🚨 Corrigir estilo visual: Investigar por que cores/espessuras não são aplicadas
  • 🔧 Estabilidade da conexão: Resolver problemas de tempo/condição de corrida do MCP
  • 📝 Suporte a notas longas: Melhor tratamento de conteúdo Markdown extenso
  • 🛡️ Tratamento de erros: Falhas e recuperação mais elegantes

Melhorias futuras

  • Operações em lote para organização em grande escala
  • Modelos aprimorados para fluxos de trabalho comuns
  • Otimizações de desempenho para cérebros complexos
  • Recursos offline e cache

Arquitetura técnica

O que torna este servidor especial

  • Interface em linguagem natural: Nenhum conhecimento técnico necessário
  • Cobertura completa da API: Mais de 25 ferramentas abrangendo todas as operações do TheBrain
  • Tratamento robusto de erros: Falhas elegantes e mensagens de erro claras
  • Design modular: Arquitetura de código limpa e sustentável
  • Pronto para produção: Registro, testes e documentação adequados

Status atual

  • Versão: 1.1.0 (junho de 2025)
  • Funcionalidade principal: ✅ Completa e funcionando
  • Propriedades visuais: ❌ Problemas importantes precisam de investigação
  • Estabilidade: 🟡 Geralmente estável com problemas de conexão intermitentes

Contribuição

Contribuições são bem-vindas! Áreas onde a ajuda é especialmente necessária:

  • Investigação de estilo visual: Por que cores/espessuras não são aplicadas?
  • Estabilidade da conexão: Depuração de condições de corrida do MCP
  • Otimização de desempenho: Tratamento de cérebros grandes
  • Documentação: Mais exemplos de uso e tutoriais

Sinta-se à vontade para enviar problemas ou solicitações de pull.

Licença

Licença MIT — consulte o arquivo LICENSE para obter detalhes.

Suporte

⚠️ Recomendação atual: Use este servidor para gerenciamento de conteúdo e organização com interação em linguagem natural. Não dependa dos recursos de estilo visual até que sejam corrigidos. A funcionalidade principal é sólida e muito útil para gerenciar conteúdo do TheBrain por meio de conversa!