Bear MCP Server

Fornece acesso direto ao seu banco de notas do Bear para gerenciamento completo de notas, contornando as limitações da API padrão.

GitHub
32
Experimente este MCPPatrocinado

Documentação

Bear MCP Server

Um servidor Model Context Protocol (MCP) que fornece ao Claude acesso abrangente às suas notas do Bear usando uma abordagem híbrida segura para sincronização - combinando leituras diretas do banco de dados com a API do Bear para gravações.

🔄 Modo Híbrido Seguro para Sincronização: Todas as operações agora funcionam com segurança com a sincronização do iCloud!

⚠️ Aviso

Esta ferramenta usa uma abordagem híbrida: leituras diretas do banco de dados + gravações via API do Bear. Embora medidas abrangentes de segurança sejam implementadas:

  • Operações de leitura acessam o banco de dados do Bear diretamente (somente leitura, seguro)
  • Operações de gravação usam a API oficial do Bear (seguro para sincronização)
  • A ferramenta não é afiliada aos desenvolvedores do Bear
  • Sempre mantenha backups regulares do Bear como boa prática

🚀 Início Rápido (5 minutos)

Pré-requisitos

  • Aplicativo Bear instalado no macOS
  • Aplicativo Claude Desktop
  • Node.js 18+ instalado

Instalação

  1. Clone e configure:
git clone <repository-url>
cd bear-notes-mcp
npm install
npm run build
  1. Adicione à configuração do Claude Desktop: Edite ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "bear": {
      "command": "node",
      "args": ["/path/to/bear-notes-mcp/dist/index.js"],
      "env": {}
    }
  }
}
  1. Comece a usar:
  • Reinicie o Claude Desktop
  • Pergunte ao Claude: "Quais notas do Bear eu tenho?"
  • Comece a gerenciar suas notas com linguagem natural!

✨ O Que Você Pode Fazer

📖 Operações de Leitura (26 ferramentas) - ✅ ATIVAS

  • Busca e Descoberta: Pesquisa de texto completo, encontrar notas semelhantes, obter sugestões
  • Organização: Navegar por tags, analisar relações entre notas, obter estatísticas
  • Análise de Conteúdo: Extrair metadados, analisar anexos, encontrar padrões
  • Consultas Avançadas: Filtragem complexa, intervalos de datas, critérios de conteúdo

✏️ Operações de Gravação (6 ferramentas) - ✅ ATIVAS (Seguro para Sincronização)

  • Criar Notas: ✅ Via API do Bear (seguro para sincronização)
  • Editar Notas: ✅ Via API do Bear (seguro para sincronização)
  • Organizar: ✅ Via API do Bear (seguro para sincronização)
  • Gerenciamento de Tags: ✅ Via API do Bear (seguro para sincronização)
  • Análise de Hashtags: ✅ Via API do Bear (seguro para sincronização)

Como funciona: Usa a API x-callback-url do Bear para gravações e o banco de dados para leituras!

🛡️ Recursos de Segurança

  • Arquitetura Híbrida: Leituras do banco de dados + gravações via API para máxima segurança
  • Seguro para Sincronização do iCloud: Todas as operações de gravação usam a API do Bear
  • Detecção de Conflitos: Evita sobrescrever alterações concorrentes
  • Validação de Tags: Sanitização automática de tags com avisos
  • Tratamento de Erros: Gerenciamento robusto de erros para todas as operações

📊 Visão Geral das Capacidades

CategoriaFerramentasStatusPrincipais Recursos
Operações Básicas6✅ AtivasObter notas, buscar, navegar por tags, estatísticas do banco de dados
Busca Avançada8✅ AtivasPesquisa de texto completo, correspondência de similaridade, consultas complexas
Análises6✅ AtivasAnálise de conteúdo, mapeamento de relações, padrões de uso
Metadados6✅ AtivasAnexos de arquivos, estrutura de conteúdo, insights de organização
Operações de Gravação6✅ AtivasSeguro para sincronização via API do Bear - capacidade total de gravação restaurada!

🔧 Configuração

Localização do Banco de Dados

O servidor encontra automaticamente seu banco de dados do Bear em:

~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite

Variáveis de Ambiente

  • BEAR_DB_PATH: Substitui a localização padrão do banco de dados (para leituras)
  • NODE_ENV: Defina como 'development' para registro de depuração

📚 Exemplos de Uso

Gerenciamento Básico de Notas

"Show me my recent notes"
"Find all notes tagged with 'project'"  
"Create a new note about today's meeting"
"Search for notes containing 'API documentation'"
"Update my project notes with the latest status"

Operações Avançadas

"Analyze my note-taking patterns this month"
"Find notes similar to my current project"
"Show me notes with attachments"
"What are my most-used tags?"

Organização e Limpeza

"Archive old notes from last year"
"Find duplicate or similar notes"
"Show me notes that might need better tags"
"Duplicate this note with a new title"
"Add tags to organize my notes better"

🛡️ Segurança e Boas Práticas

⚠️ Diretrizes de Segurança

  1. O Bear pode estar em execução durante as operações - As operações de gravação usam a API do Bear com segurança
  2. Validação automática de tags - As tags são sanitizadas com avisos
  3. Compatível com sincronização do iCloud - Sem conflitos ou problemas de sincronização
  4. Mantenha o Bear atualizado - Garanta a compatibilidade da API

💡 Boas Práticas

  • Operações de leitura são instantâneas - acesso direto ao banco de dados
  • Operações de gravação funcionam com o Bear em execução ou fechado
  • Avisos de tags são exibidos quando as tags são corrigidas automaticamente
  • Use termos de busca específicos para melhores resultados
  • Arquive notas em vez de excluir quando possível

🏷️ Diretrizes de Formatação de Tags

✅ FORMATOS DE TAGS RECOMENDADOS:

  • Tags simples: work, personal, urgent, meeting
  • Categorias aninhadas: work/projects, personal/health, study/math
  • Baseadas em tempo: 2024, january, q1
  • Códigos de projeto: proj001, alpha, beta

❌ EVITE ESTES FORMATOS (corrigidos automaticamente):

  • Hífens: project-alpha → torna-se projectalpha
  • Espaços: work meeting → torna-se workmeeting
  • Maiúsculas e minúsculas misturadas: ProjectAlpha → torna-se projectalpha

🔧 Sanitização Automática de Tags: O servidor valida e sanitiza automaticamente todas as tags:

  • Somente minúsculas: Project → project
  • Sem espaços: tag name → tagname
  • Sem hífens: project-alpha → projectalpha
  • Sem vírgulas: tag,name → tagname
  • ✅ Barras preservadas: project/alpha → project/alpha (para tags aninhadas)

Avisos de tags são retornados quando as tags são modificadas, para que você saiba exatamente quais alterações foram feitas.

🏗️ ARQUITETURA DE SERVIÇOS REFATORADA

✅ Totalmente refatorado de monolítico para arquitetura moderna orientada a serviços!

Visão Geral da Transformação

Reconstruímos completamente o sistema de um BearService monolítico de 2.589 linhas para uma arquitetura moderna, testável e orientada a serviços:

🔧 Design Baseado em Serviços

  • 7 serviços especializados com responsabilidades claras
  • Injeção de dependências para testabilidade e flexibilidade
  • Desenvolvimento orientado por interfaces para manutenibilidade
  • 384 testes abrangentes em todos os serviços

🛡️ Arquitetura Híbrida Segura para Sincronização

  • Operações de Leitura: Acesso direto ao banco de dados SQLite para máximo desempenho
  • Operações de Gravação: API x-callback-url do Bear para segurança de sincronização
  • Coordenação perfeita usando a ponte ZUNIQUEIDENTIFIER

📊 Qualidade e Desempenho

  • 100% TypeScript com verificação estrita de tipos
  • Tratamento de erros abrangente e validação
  • Cache em múltiplos níveis para otimização de desempenho
  • Registro estruturado e monitoramento de saúde

Arquitetura de Serviços

ServiceContainer (Dependency Injection)
├── DatabaseService      (SQLite operations & connection management)
├── CacheService        (Performance optimization & intelligent caching)
├── LoggingService      (Structured logging with Winston)
├── HealthService       (System monitoring & health checks)
├── ValidationService   (Input validation & data sanitization)
├── NoteService         (Note CRUD & lifecycle management)
├── SearchService       (Advanced search & content discovery)
└── TagService          (Tag management & organization)

Por Que Esta Arquitetura Funciona

O Problema: O código monolítico era difícil de testar, manter e estender.

A Solução: Arquitetura orientada a serviços com separação clara de responsabilidades.

O Resultado:

  • ✅ Código mantível - Limites e responsabilidades de serviços claros
  • ✅ 100% de cobertura de testes - 384 testes em todos os serviços
  • ✅ Segurança de tipos - Eliminados 50+ tipos any
  • ✅ Desempenho otimizado - Cache em múltiplos níveis e otimização de consultas
  • ✅ Pronto para produção - Registro, monitoramento e tratamento de erros abrangentes
  • ✅ Operações seguras para sincronização - Abordagem híbrida elimina conflitos do iCloud

Status Atual

  • ✅ Todas as operações de leitura - Acesso direto ao banco de dados (26 ferramentas)
  • ✅ Todas as operações de gravação - API do Bear segura para sincronização (6 ferramentas)
  • ✅ Paridade total de recursos - Tudo funciona como projetado
  • ✅ Compatível com sincronização do iCloud - Sem conflitos ou problemas
  • ✅ Correção de títulos duplicados - As notas exibem títulos corretamente (sem duplicação)

🙏 Agradecimentos à Equipe do Bear

Agradecimento especial a Danilo, da equipe do Bear, que forneceu a percepção fundamental que levou a esta solução!

🤝 Contribuição e Comunidade

O desafio da sincronização do iCloud foi resolvido! 🎉 Agora estamos focados em tornar esta a melhor integração possível com o Bear. Seja você:

  • Desenvolvedor macOS/iOS com experiência em API
  • Especialista em banco de dados familiarizado com otimização de SQLite
  • Usuário avançado do Bear com insights de fluxo de trabalho
  • Desenvolvedor que deseja contribuir com o ecossistema MCP

Sua contribuição pode ajudar milhares de usuários do Bear a obter ainda mais de seus assistentes de IA!

Prioridades Atuais

  1. 🚀 Adicionar novos recursos - Mais maneiras de analisar e trabalhar com notas
  2. 📖 Melhorar a documentação - Ajudar outros a entender e contribuir
  3. 🧪 Expandir a cobertura de testes - Garantir confiabilidade em todas as versões do Bear
  4. ⚡ Otimização de desempenho - Tornar as operações ainda mais rápidas

Maneiras Rápidas de Ajudar

  • ⭐ Dê uma estrela no repositório se achar útil
  • 🐛 Relate problemas que encontrar
  • 💡 Compartilhe ideias para novos recursos ou soluções
  • 🔗 Divulgue para desenvolvedores que possam ajudar
  • 📝 Contribua com melhorias na documentação

Juntos, podemos construir a integração mais poderosa do Bear para assistentes de IA!

🔍 Todas as Ferramentas Disponíveis

📖 Operações de Leitura (26 ferramentas) - ✅ ATIVAS

Operações Básicas (6 ferramentas)

  • get_database_stats - Visão geral do seu banco de dados do Bear
  • get_notes - Listar notas com opções de filtragem
  • get_note_by_id - Obter nota específica por ID
  • get_note_by_title - Encontrar nota por título exato
  • get_tags - Listar todas as tags com contagens de uso
  • get_notes_by_tag - Encontrar notas com tag específica

Busca Avançada (8 ferramentas)

  • get_notes_advanced - Filtragem e ordenação complexas
  • get_notes_with_criteria - Busca com múltiplos critérios
  • search_notes_fulltext - Pesquisa de texto completo com pontuação de relevância
  • get_search_suggestions - Autocompletar para buscas
  • find_similar_notes - Correspondência de similaridade de conteúdo
  • get_related_notes - Encontrar notas relacionadas por tags e conteúdo
  • get_recent_notes - Notas criadas ou modificadas recentemente
  • get_note_counts_by_status - Estatísticas por status da nota

Análises e Insights (6 ferramentas)

  • get_note_analytics - Estatísticas abrangentes de notas
  • analyze_note_metadata - Análise de padrões de conteúdo
  • get_notes_with_metadata - Filtrar por características de conteúdo
  • get_file_attachments - Gerenciamento de anexos de arquivos
  • get_tag_hierarchy - Análise de relações entre tags
  • get_tag_analytics - Padrões de uso de tags

Análise de Conteúdo (6 ferramentas)

  • analyze_tag_relationships - Sugestões de otimização de tags
  • get_tag_usage_trends - Uso de tags ao longo do tempo
  • search_notes_regex - Correspondência de padrões (quando disponível)
  • Categorização avançada de conteúdo
  • Análise de links e referências
  • Insights de padrões de escrita
✏️ Operações de Gravação (6 ferramentas) - ✅ ATIVAS (Seguro para Sincronização)

Gerenciamento de Notas - SEGURO PARA SINCRONIZAÇÃO VIA API DO BEAR

  • create_note - ✅ Criar novas notas com tags e conteúdo
  • update_note - ✅ Atualizar notas existentes com segurança
  • duplicate_note - ✅ Criar cópias de notas existentes
  • archive_note - ✅ Arquivar/desarquivar notas
  • trigger_hashtag_parsing - ✅ Forçar reprocessamento de hashtags
  • batch_trigger_hashtag_parsing - ✅ Processamento em lote de hashtags

✅ Todas as operações agora são seguras para sincronização:

  • Usa a API x-callback-url do Bear para todas as gravações
  • Sem conflitos de sincronização do iCloud ou corrupção de dados
  • Respeita a coordenação interna de sincronização do Bear
  • Funcionalidade completa de gravação restaurada

Integração perfeita entre leituras do banco de dados e gravações via API!

🔧 Solução de Problemas

Problemas Comuns

Erro "Banco de dados não encontrado":

  • Verifique se o Bear está instalado e foi aberto pelo menos uma vez
  • Verifique o caminho do banco de dados: ~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/

Erro "Permissão negada":

  • Garanta que o Claude Desktop tenha as permissões de sistema de arquivos necessárias
  • Verifique se o arquivo do banco de dados é legível

Operações de gravação não funcionando:

  • Garanta que o aplicativo Bear esteja instalado e tenha sido aberto pelo menos uma vez
  • Verifique se a funcionalidade x-callback-url do Bear está habilitada
  • Tente abrir o Bear manualmente para verificar se está funcionando

Desempenho lento:

  • Bancos de dados grandes (10.000+ notas) podem demorar mais para leituras
  • Use termos de busca específicos em vez de consultas amplas
  • Considere usar paginação com parâmetros limit

Obtendo Ajuda

  1. Consulte o guia de solução de problemas
  2. Revise os padrões de uso comuns
  3. Habilite o registro de depuração com NODE_ENV=development
  4. Teste a API do Bear diretamente: open "bear://x-callback-url/create?title=Test"

📈 Desempenho

  • Operações de leitura: Instantâneas (acesso direto ao banco de dados)
  • Operações de gravação: 1-2 segundos (processamento da API do Bear)
  • Bancos de dados grandes: Testado com 10.000+ notas
  • Uso de memória: ~50MB típico, ~100MB para operações complexas
  • Operações concorrentes: Operações de leitura podem ser executadas simultaneamente
  • Operações de API: Processadas através do esquema de URL do Bear

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Feito com ❤️ para a comunidade Bear