Bear MCP Server

Bear MCP Server

Un servidor de Model Context Protocol (MCP) que proporciona a Claude acceso integral a tus notas de Bear mediante un enfoque híbrido seguro para sincronización — combinando lecturas directas de la base de datos con la API de Bear para escrituras.

🔄 Modo Híbrido Seguro para Sincronización: ¡Todas las operaciones ahora funcionan de forma segura con la sincronización de iCloud!

⚠️ Aviso Legal

Esta herramienta utiliza un enfoque híbrido: lecturas directas de la base de datos + escrituras mediante la API de Bear. Aunque se implementan medidas de seguridad integrales:

• Las operaciones de lectura acceden directamente a la base de datos de Bear (solo lectura, seguro)
• Las operaciones de escritura utilizan la API oficial de Bear (seguro para sincronización)
• La herramienta no está afiliada con los desarrolladores de Bear
• Mantén siempre copias de seguridad regulares de Bear como buena práctica

🚀 Inicio Rápido (5 minutos)

Requisitos Previos

• Aplicación Bear instalada en macOS
• Aplicación Claude Desktop
• Node.js 18+ instalado

Instalación

1. Clonar y configurar:

git clone <repository-url>
cd bear-notes-mcp
npm install
npm run build

2. Agregar a la configuración de Claude Desktop: Edita ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bear": {
      "command": "node",
      "args": ["/path/to/bear-notes-mcp/dist/index.js"],
      "env": {}
    }
  }
}

3. Comenzar a usar:

• Reinicia Claude Desktop
• Pregunta a Claude: "¿Qué notas de Bear tengo?"
• ¡Comienza a gestionar tus notas con lenguaje natural!

✨ Lo Que Puedes Hacer

📖 Operaciones de Lectura (26 herramientas) - ✅ ACTIVAS

• Búsqueda y Descubrimiento: Búsqueda de texto completo, encontrar notas similares, obtener sugerencias
• Organización: Explorar por etiquetas, analizar relaciones entre notas, obtener estadísticas
• Análisis de Contenido: Extraer metadatos, analizar archivos adjuntos, encontrar patrones
• Consultas Avanzadas: Filtrado complejo, rangos de fechas, criterios de contenido

✏️ Operaciones de Escritura (6 herramientas) - ✅ ACTIVAS (Seguras para Sincronización)

• Crear Notas: ✅ Mediante la API de Bear (seguro para sincronización)
• Editar Notas: ✅ Mediante la API de Bear (seguro para sincronización)
• Organizar: ✅ Mediante la API de Bear (seguro para sincronización)
• Gestión de Etiquetas: ✅ Mediante la API de Bear (seguro para sincronización)
• Análisis de Hashtags: ✅ Mediante la API de Bear (seguro para sincronización)

Cómo funciona: ¡Utiliza la API x-callback-url de Bear para escrituras y la base de datos para lecturas!

🛡️ Características de Seguridad

• Arquitectura Híbrida: Lecturas de base de datos + escrituras mediante API para máxima seguridad
• Seguro para Sincronización de iCloud: Todas las operaciones de escritura utilizan la API de Bear
• Detección de Conflictos: Evita sobrescribir cambios concurrentes
• Validación de Etiquetas: Saneamiento automático de etiquetas con advertencias
• Manejo de Errores: Gestión robusta de errores para todas las operaciones

📊 Resumen de Capacidades

Categoría	Herramientas	Estado	Características Clave
Operaciones Básicas	6	✅ Activas	Obtener notas, buscar, explorar etiquetas, estadísticas de base de datos
Búsqueda Avanzada	8	✅ Activas	Búsqueda de texto completo, coincidencia de similitud, consultas complejas
Analítica	6	✅ Activas	Análisis de contenido, mapeo de relaciones, patrones de uso
Metadatos	6	✅ Activas	Archivos adjuntos, estructura de contenido, información de organización
Operaciones de Escritura	6	✅ Activas	Seguro para sincronización mediante la API de Bear: ¡capacidad completa de escritura restaurada!

🔧 Configuración

Ubicación de la Base de Datos

El servidor encuentra automáticamente tu base de datos de Bear en:

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

Variables de Entorno

• BEAR_DB_PATH: Sobrescribir la ubicación predeterminada de la base de datos (para lecturas)
• NODE_ENV: Establecer en 'development' para registro de depuración

📚 Ejemplos de Uso

Gestión Básica 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"

Operaciones Avanzadas

"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?"

Organización y Limpieza

"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"

🛡️ Seguridad y Buenas Prácticas

⚠️ Directrices de Seguridad

1. Bear puede ejecutarse durante las operaciones - Las operaciones de escritura utilizan la API de Bear de forma segura
2. Validación automática de etiquetas - Las etiquetas se sanean con advertencias
3. Compatible con sincronización de iCloud - Sin conflictos ni problemas de sincronización
4. Mantén Bear actualizado - Asegura la compatibilidad de la API

💡 Buenas Prácticas

• Las operaciones de lectura son instantáneas - acceso directo a la base de datos
• Las operaciones de escritura funcionan con Bear abierto o cerrado
• Las advertencias de etiquetas se muestran cuando las etiquetas se corrigen automáticamente
• Usa términos de búsqueda específicos para mejores resultados
• Archiva notas en lugar de eliminarlas cuando sea posible

🏷️ Directrices de Formato de Etiquetas

✅ FORMATOS DE ETIQUETAS RECOMENDADOS:

• Etiquetas simples: work, personal, urgent, meeting
• Categorías anidadas: work/projects, personal/health, study/math
• Basadas en tiempo: 2024, january, q1
• Códigos de proyecto: proj001, alpha, beta

❌ EVITA ESTOS FORMATOS (se corrigen automáticamente):

• Guiones: project-alpha → se convierte en projectalpha
• Espacios: work meeting → se convierte en workmeeting
• Mayúsculas y minúsculas mezcladas: ProjectAlpha → se convierte en projectalpha

🔧 Saneamiento Automático de Etiquetas: El servidor valida y sane automáticamente todas las etiquetas:

• Solo minúsculas: Project → project
• Sin espacios: tag name → tagname
• Sin guiones: project-alpha → projectalpha
• Sin comas: tag,name → tagname
• ✅ Barras diagonales preservadas: project/alpha → project/alpha (para etiquetas anidadas)

Las advertencias de etiquetas se devuelven cuando se modifican las etiquetas, para que sepas exactamente qué cambios se realizaron.

🏗️ ARQUITECTURA DE SERVICIOS REFACTORIZADA

✅ ¡Completamente refactorizada de monolito a arquitectura moderna orientada a servicios!

Resumen de la Transformación

Hemos reconstruido completamente el sistema de un BearService monolítico de 2,589 líneas a una arquitectura moderna, testeable y orientada a servicios:

🔧 Diseño Basado en Servicios

• 7 servicios especializados con responsabilidades claras
• Inyección de dependencias para testabilidad y flexibilidad
• Desarrollo dirigido por interfaces para mantenibilidad
• 384 pruebas integrales en todos los servicios

🛡️ Arquitectura Híbrida Segura para Sincronización

• Operaciones de Lectura: Acceso directo a la base de datos SQLite para máximo rendimiento
• Operaciones de Escritura: API x-callback-url de Bear para seguridad de sincronización
• Coordinación perfecta utilizando el puente ZUNIQUEIDENTIFIER

📊 Calidad y Rendimiento

• 100% TypeScript con verificación estricta de tipos
• Manejo integral de errores y validación
• Caché multinivel para optimización del rendimiento
• Registro estructurado y monitoreo de salud

Arquitectura de Servicios

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 Qué Esta Arquitectura Funciona

El Problema: El código monolítico era difícil de probar, mantener y extender.

La Solución: Arquitectura orientada a servicios con separación clara de responsabilidades.

El Resultado:

• ✅ Código mantenible - Límites y responsabilidades de servicios claros
• ✅ 100% de cobertura de pruebas - 384 pruebas en todos los servicios
• ✅ Seguridad de tipos - Eliminados más de 50 tipos any
• ✅ Rendimiento optimizado - Caché multinivel y optimización de consultas
• ✅ Listo para producción - Registro, monitoreo y manejo de errores integrales
• ✅ Operaciones seguras para sincronización - El enfoque híbrido elimina conflictos de iCloud

Estado Actual

• ✅ Todas las operaciones de lectura - Acceso directo a la base de datos (26 herramientas)
• ✅ Todas las operaciones de escritura - API de Bear segura para sincronización (6 herramientas)
• ✅ Paridad completa de funciones - Todo funciona como está diseñado
• ✅ Compatible con sincronización de iCloud - Sin conflictos ni problemas
• ✅ Corrección de títulos duplicados - Las notas muestran los títulos correctamente (sin duplicación)

🙏 Agradecimientos al Equipo de Bear

Agradecimiento especial a Danilo del equipo de Bear quien proporcionó la información clave que condujo a esta solución.

---

🤝 Contribución y Comunidad

¡El desafío de la sincronización de iCloud ha sido resuelto! 🎉 Ahora nos enfocamos en hacer de esta la mejor integración de Bear posible. Ya seas:

• Desarrollador de macOS/iOS con experiencia en API
• Experto en bases de datos familiarizado con la optimización de SQLite
• Usuario avanzado de Bear con conocimientos de flujos de trabajo
• Desarrollador que desea contribuir al ecosistema MCP

¡Tu contribución puede ayudar a miles de usuarios de Bear a obtener aún más de sus asistentes de IA!

Prioridades Actuales

1. 🚀 Agregar nuevas funciones - Más formas de analizar y trabajar con notas
2. 📖 Mejorar la documentación - Ayudar a otros a entender y contribuir
3. 🧪 Expandir la cobertura de pruebas - Asegurar la confiabilidad en todas las versiones de Bear
4. ⚡ Optimización del rendimiento - Hacer las operaciones aún más rápidas

Formas Rápidas de Ayudar

• ⭐ Marca el repositorio con una estrella si lo encuentras útil
• 🐛 Reporta problemas que encuentres
• 💡 Comparte ideas para nuevas funciones o soluciones
• 🔗 Corre la voz a desarrolladores que puedan ayudar
• 📝 Contribuye mejoras a la documentación

¡Juntos, podemos construir la integración de Bear más potente para asistentes de IA!

🔍 Todas las Herramientas Disponibles

📖 Operaciones de Lectura (26 herramientas) - ✅ ACTIVAS

Operaciones Básicas (6 herramientas)

• get_database_stats - Resumen de tu base de datos de Bear
• get_notes - Listar notas con opciones de filtrado
• get_note_by_id - Obtener nota específica por ID
• get_note_by_title - Encontrar nota por título exacto
• get_tags - Listar todas las etiquetas con conteos de uso
• get_notes_by_tag - Encontrar notas con etiqueta específica

Búsqueda Avanzada (8 herramientas)

• get_notes_advanced - Filtrado y ordenamiento complejos
• get_notes_with_criteria - Búsqueda multicriterio
• search_notes_fulltext - Búsqueda de texto completo con puntuación de relevancia
• get_search_suggestions - Autocompletado para búsquedas
• find_similar_notes - Coincidencia de similitud de contenido
• get_related_notes - Encontrar notas relacionadas por etiquetas y contenido
• get_recent_notes - Notas creadas o modificadas recientemente
• get_note_counts_by_status - Estadísticas por estado de nota

Analítica e Información (6 herramientas)

• get_note_analytics - Estadísticas integrales de notas
• analyze_note_metadata - Análisis de patrones de contenido
• get_notes_with_metadata - Filtrar por características de contenido
• get_file_attachments - Gestión de archivos adjuntos
• get_tag_hierarchy - Análisis de relaciones entre etiquetas
• get_tag_analytics - Patrones de uso de etiquetas

Análisis de Contenido (6 herramientas)

• analyze_tag_relationships - Sugerencias de optimización de etiquetas
• get_tag_usage_trends - Uso de etiquetas a lo largo del tiempo
• search_notes_regex - Coincidencia de patrones (cuando esté disponible)
• Categorización avanzada de contenido
• Análisis de enlaces y referencias
• Información sobre patrones de escritura

✏️ Operaciones de Escritura (6 herramientas) - ✅ ACTIVAS (Seguras para Sincronización)

Gestión de Notas - SEGURO PARA SINCRONIZACIÓN MEDIANTE LA API DE BEAR

• create_note - ✅ Crear nuevas notas con etiquetas y contenido
• update_note - ✅ Actualizar notas existentes de forma segura
• duplicate_note - ✅ Crear copias de notas existentes
• archive_note - ✅ Archivar/desarchivar notas
• trigger_hashtag_parsing - ✅ Forzar reprocesamiento de hashtags
• batch_trigger_hashtag_parsing - ✅ Procesamiento masivo de hashtags

✅ Todas las operaciones ahora son seguras para sincronización:

• Utiliza la API x-callback-url de Bear para todas las escrituras
• Sin conflictos de sincronización de iCloud ni corrupción de datos
• Respeta la coordinación interna de sincronización de Bear
• Funcionalidad completa de escritura restaurada

¡Integración perfecta entre lecturas de base de datos y escrituras mediante API!

🔧 Solución de Problemas

Problemas Comunes

Error de "Base de datos no encontrada":

• Verifica que Bear esté instalado y se haya abierto al menos una vez
• Comprueba la ruta de la base de datos: ~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/

Error de "Permiso denegado":

• Asegúrate de que Claude Desktop tenga los permisos necesarios del sistema de archivos
• Comprueba que el archivo de la base de datos sea legible

Las operaciones de escritura no funcionan:

• Asegúrate de que la aplicación Bear esté instalada y se haya abierto al menos una vez
• Comprueba que la funcionalidad x-callback-url de Bear esté habilitada
• Intenta abrir Bear manualmente para verificar que funcione

Rendimiento lento:

• Las bases de datos grandes (10,000+ notas) pueden tardar más en las lecturas
• Usa términos de búsqueda específicos en lugar de consultas amplias
• Considera usar paginación con los parámetros limit

Obtener Ayuda

1. Consulta la guía de solución de problemas
2. Revisa los patrones de uso comunes
3. Habilita el registro de depuración con NODE_ENV=development
4. Prueba la API de Bear directamente: open "bear://x-callback-url/create?title=Test"

📈 Rendimiento

• Operaciones de lectura: Instantáneas (acceso directo a la base de datos)
• Operaciones de escritura: 1-2 segundos (procesamiento mediante la API de Bear)
• Bases de datos grandes: Probadas con 10,000+ notas
• Uso de memoria: ~50MB típico, ~100MB para operaciones complejas
• Operaciones concurrentes: Las operaciones de lectura pueden ejecutarse simultáneamente
• Operaciones de API: Procesadas mediante el esquema de URL de Bear

📄 Licencia

Licencia MIT - consulta el archivo LICENCIA para más detalles.

---

Hecho con ❤️ para la comunidad de Bear