Bear Notes MCP

Bear MCP服务器

一个模型上下文协议（MCP）服务器，使用 混合同步安全方法 -将直接数据库读取与Bear的API进行写入相结合。

🔄 同步安全混合模式：所有操作现在都可以通过iCloud同步安全运行！

⚠️ 免责声明

该工具使用一种混合方法：直接数据库读取+Bear API写入。在实施综合安全措施的同时：

• 读取操作直接访问Bear的数据库（只读，安全）
• 编写操作使用Bear的官方API（sync-safe）
• 该工具与Bear的开发人员无关
• 始终保持定期Bear备份作为良好做法

🚀 快速入门（5分钟）

先决条件

• 安装在macOS上的Bear应用程序
• 克劳德桌面应用程序
• 已安装Node.js 18+

安装

1. 克隆和设置：

git clone 
cd bear-notes-mcp
npm install
npm run build

1. 添加到Claude桌面配置：

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

1. 开始使用：

• 重新启动克劳德桌面
• 问克劳德：“我有什么熊的笔记？”
• 开始用自然语言管理你的笔记！

✨ 你能做什么

📖 读取操作（26个工具）-✅ 活跃的

• 搜索与发现：全文搜索，查找类似笔记，获取建议
• 组织：按标签浏览，分析笔记关系，获取统计数据
• 内容分析：提取元数据、分析附件、查找模式
• 高级查询：复杂的筛选、日期范围、内容标准

✏️ 写入操作（6个工具）-✅ 活动（同步安全）

• 创建笔记: ✅ 通过Bear API（sync-safe）
• 编辑笔记: ✅ 通过Bear API（sync-safe）
• 组织: ✅ 通过Bear API（sync-safe）
• 标签管理: ✅ 通过Bear API（sync-safe）
• 标签解析: ✅ 通过Bear API（sync-safe）

运作原理：使用Bear的x-callback-url API进行写入，使用数据库进行读取！

🛡️ 安全功能

• 混合式结构：数据库读取+API写入以实现最大安全性
• iCloud同步保险箱：所有写入操作都使用Bear的API
• 冲突检测：防止覆盖并发更改
• 标签验证：带有警告的自动标签消毒
• 错误处理：对所有操作进行强大的错误管理

📊 能力概述

🔧 配置

数据库位置

服务器会自动在以下位置找到您的Bear数据库：

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

环境变量

• BEAR_DB_PATH：覆盖默认数据库位置（用于读取）
• NODE_ENV：设置为“development”进行调试日志记录

📚 使用示例

基本笔记管理

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

高级操作

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

组织与清理

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

🛡️ 安全与最佳实践

⚠️ 安全指南

1. 熊可以在行动中奔跑 -安全地使用Bear的API编写操作
2. 自动标签验证 -标签用警告进行消毒
3. iCloud同步兼容 -无冲突或同步问题
4. 让Bear保持更新 -确保API兼容性

💡 最佳实践

• 读取操作 是即时直接数据库访问
• 写入操作 与熊一起跑步或闭馆
• 标记警告 显示标签何时自动更正
• 使用特定的搜索词以获得更好的结果
• 尽可能将笔记存档，而不是删除

🏷️ 标签格式指南

✅ 推荐的标签格式：

• 简单标签： work, personal, urgent, meeting
• 嵌套类别： work/projects, personal/health, study/math
• 基于时间： 2024, january, q1
• 项目代码： proj001, alpha, beta

❌ 避免这些格式（自动更正）：

• 连字符: project-alpha → 成为 projectalpha
• 空间: work meeting → 成为 workmeeting
• 混合情况: ProjectAlpha → 成为 projectalpha

🔧 自动标签消毒： 服务器会自动验证和清理所有标签：

• 仅限低卡: Project → project
• 没有空格: tag name → tagname
• 无连字符: project-alpha → projectalpha
• 没有逗号: tag,name → tagname
• ✅ 保留正斜杠: project/alpha → project/alpha （适用于嵌套标签）

标记警告 在修改标签时返回，因此您将确切地知道所做的更改。

🏗️ 重构服务架构

✅ 从单体架构完全重构为现代面向服务的架构！

转型概述

我们已经完全重建了系统 2589线路单片承载服务 进入a 现代、可测试、面向服务的体系结构:

🔧 基于服务的设计

• 7专业服务 责任明确
• 依赖注入 可测试性和灵活性
• 界面驱动开发 可维护性
• 384项综合测试 所有服务

🛡️ 混合同步安全架构

• 读取操作：直接访问SQLite数据库以获得最佳性能
• 写入操作：Bear的x-callback-url API用于同步安全
• 完美协调 使用 ZUNIQUEIDENTIFIER 桥

📊 质量与性能

• 100%TypeScript 严格的类型检查
• 全面的错误处理 和验证
• 多级缓存 用于性能优化
• 结构化日志记录 健康监测

服务体系结构

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)

为什么这种架构有效

问题：单片代码很难测试、维护和扩展。

解决方案：具有明确关注点分离的面向服务的架构。

结果:

• ✅ 可维护代码 -明确的服务边界和责任
• ✅ 100%测试覆盖率 -在所有服务中进行384次测试
• ✅ 类型安全性 -淘汰50+ any 类型
• ✅ 性能优化 -多级缓存和查询优化
• ✅ 生产就绪 -全面的日志记录、监控和错误处理
• ✅ 同步安全操作 -混合方法消除了iCloud冲突

当前状态

• ✅ 所有读取操作 -直接数据库访问（26个工具）
• ✅ 所有写入操作 -Sync-safe Bear API（6个工具）
• ✅ 全功能奇偶校验 -一切按设计工作
• ✅ iCloud同步兼容 -无冲突或问题
• ✅ 重复标题修复 -注释正确显示标题（无重复）

🙏 感谢熊队

特别感谢 熊队的达尼洛 谁提供了导致这一解决方案的关键见解！

______________________________________________________________________

🤝 贡献与社区

这 iCloud同步挑战已解决！ 🎉 现在我们专注于使这成为最好的Bear整合。无论你是：

• macOS/iOS开发人员 具有API经验
• 数据库专家 熟悉SQLite优化
• 熊电力用户 具有工作流洞察力
• 开发者 希望为MCP生态系统做出贡献

你的贡献可以帮助成千上万的Bear用户从他们的AI助手那里获得更多！

当前优先事项

1. 🚀 添加新功能 -更多分析和处理笔记的方法
2. 📖 改进文档 -帮助他人理解并做出贡献
3. 🧪 扩大测试覆盖范围 -确保Bear版本的可靠性
4. ⚡ 性能优化 -使操作更快

快速帮助方式

• ⭐ 标记回购 如果你觉得它有用
• 🐛 报告问题 你遇到
• 💡 分享想法 获取新功能或解决方案
• 🔗 传话 对于可能提供帮助的开发人员
• 📝 提供文档 改进

我们可以一起为AI助手构建最强大的Bear集成！

🔍 所有可用工具

📖 Read Operations (26 tools) - ✅ ACTIVE

基本操作（6个工具）

• get_database_stats -Bear数据库概述
• get_notes -列出带有过滤选项的注释
• get_note_by_id -按ID获取特定注释
• get_note_by_title -按确切标题查找注释
• get_tags -列出所有带有使用次数的标签
• get_notes_by_tag -查找带有特定标签的笔记

高级搜索（8个工具）

• get_notes_advanced -复杂的过滤和排序
• get_notes_with_criteria -多条件搜索
• search_notes_fulltext -带有相关性评分的全文搜索
• get_search_suggestions -自动完成搜索
• find_similar_notes -内容相似性匹配
• get_related_notes -按标签和内容查找相关笔记
• get_recent_notes -最近创建或修改的笔记
• get_note_counts_by_status -按钞票状态统计

分析与洞察（6个工具）

• get_note_analytics -综合票据统计
• analyze_note_metadata -内容模式分析
• get_notes_with_metadata -按内容特征过滤
• get_file_attachments -文件附件管理
• get_tag_hierarchy -标签关系分析
• get_tag_analytics -标签使用模式

内容分析（6个工具）

• analyze_tag_relationships -标签优化建议
• get_tag_usage_trends -标签使用随时间变化
• search_notes_regex -图案匹配（如果可用）
• 高级内容分类
• 链接和参考分析
• 写作模式见解

✏️ Write Operations (6 tools) - ✅ ACTIVE (Sync-Safe)

票据管理-SYNC-SAFE VIA BEAR API

• create_note - ✅ 创建带有标签和内容的新笔记
• update_note - ✅ 安全更新现有笔记
• duplicate_note - ✅ 创建现有笔记的副本
• archive_note - ✅ 存档/取消存档笔记
• trigger_hashtag_parsing - ✅ 强制重新处理标签
• batch_trigger_hashtag_parsing - ✅ 批量标签处理

✅ 所有操作现在都是同步安全的：

• 所有写入都使用Bear的x-callback-url API
• 没有iCloud同步冲突或数据损坏
• 尊重Bear的内部同步协调
• 完全写入功能已恢复

数据库读取和API写入之间的完美集成！

🔧 故障排除

常见问题

“找不到数据库”错误：

• 验证Bear是否已安装并至少打开过一次
• 检查数据库路径： ~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/

“权限被拒绝”错误：

• 确保Claude Desktop具有必要的文件系统权限
• 检查数据库文件是否可读

写入操作不起作用：

• 确保Bear应用程序已安装并已打开至少一次
• 检查Bear的x-callback-url功能是否已启用
• 尝试手动打开Bear以验证其是否正常工作

性能缓慢：

• 大型数据库（10000多条笔记）的读取可能需要更长的时间
• 使用特定的搜索词而不是宽泛的查询
• 考虑使用分页 limit 参数

获取帮助

1. 检查 故障排除指南
2. 审查 常见使用模式
3. 使用启用调试日志记录 NODE_ENV=development
4. 直接测试Bear的API： open "bear://x-callback-url/create?title=Test"

📈 演出

• 读取操作：即时（直接访问数据库）
• 写入操作：1-2秒（Bear API处理）
• 大型数据库：测试了10000多个音符
• 内存使用：典型约50MB，复杂操作约100MB
• 并行操作：读取操作可以同时运行
• API操作：通过Bear的URL方案处理

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

由以下材料制成❤️ 为了熊社区