Bear MCP 服务器

一个模型上下文协议（MCP）服务器，通过混合同步安全方法提供Claude对您的Bear笔记的全面访问——结合直接数据库读取与Bear API写入。

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

⚠️ 免责声明

此工具采用混合方法：直接数据库读取 + Bear API 写入。虽然已实施全面的安全措施：

• 读操作直接访问Bear的数据库（只读，安全）
• 写操作使用Bear的官方API（同步安全）
• 此工具与Bear开发者无关
• 建议定期备份Bear以确保数据安全

🚀 快速开始（5分钟）

预备条件

• 已安装在macOS上的Bear应用
• Claude桌面应用
• 安装了Node.js 18+

安装

1. 克隆并设置：

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

2. 添加到Claude桌面配置： 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

3. 开始使用：

• 重启Claude桌面应用
• 询问Claude：“我有哪些Bear笔记？”
• 开始用自然语言管理您的笔记！

✨ 您可以做什么

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

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

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

• 创建笔记：✅ 通过Bear API（同步安全）
• 编辑笔记：✅ 通过Bear API（同步安全）
• 组织：✅ 通过Bear API（同步安全）
• 标签管理：✅ 通过Bear API（同步安全）
• 解析标签：✅ 通过Bear API（同步安全）

如何工作：写入操作使用Bear的x-callback-url API，读取操作使用数据库！

🛡️ 安全特性

• 混合架构：数据库读取 + API写入以实现最大安全性
• iCloud同步安全：所有写入操作均使用Bear的API
• 冲突检测：防止覆盖并发更改
• 标签验证：自动标签净化并带有警告
• 错误处理：所有操作的健壮错误管理

📊 能力概览

类别	工具	状态	关键特性
基本操作	6	✅ 活跃	获取笔记，搜索，浏览标签，数据库统计
高级搜索	8	✅ 活跃	全文搜索，相似匹配，复杂查询
分析	6	✅ 活跃	内容分析，关系映射，使用模式
元数据	6	✅ 活跃	文件附件，内容结构，组织洞察
写操作	6	✅ 活跃	通过Bear API同步安全 - 恢复全部写入能力！

🔧 配置

数据库位置

服务器会自动找到您的Bear数据库位于：

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

环境变量

• BEAR_DB_PATH：覆盖默认数据库位置（用于读取）
• NODE_ENV：设置为'development'以启用调试日志

📚 使用示例

基本笔记管理

“显示我的最近笔记”
“查找所有标记为‘项目’的笔记”
“创建关于今天会议的新笔记”
“搜索包含‘API文档’的笔记”
“更新我的项目笔记以反映最新状态”

高级操作

“分析我这个月的笔记记录模式”
“查找与我当前项目相似的笔记”
“显示有附件的笔记”
“我最常用的标签是什么？”

组织与清理

“归档去年的旧笔记”
“查找重复或相似的笔记”
“显示可能需要更好标签的笔记”
“复制此笔记并赋予新标题”
“添加标签以更好地组织我的笔记”

🛡️ 安全与最佳实践

⚠️ 安全指南

1. Bear可以在操作期间运行 - 写操作使用Bear的API安全地进行
2. 自动标签验证 - 标签被净化并带有警告
3. 兼容iCloud同步 - 没有冲突或同步问题
4. 保持Bear更新 - 确保API兼容性

💡 最佳实践

• 读操作是即时的 - 直接数据库访问
• 写操作可以在Bear运行或关闭时进行
• 标签警告会在标签被自动修正时显示
• 使用特定搜索词以获得更好的结果
• 尽可能归档笔记而不是删除

🏷️ 标签格式指南

✅ 推荐标签格式：

• 简单标签：工作，个人，紧急，会议
• 嵌套类别：工作/项目，个人/健康，学习/数学
• 时间基础：2024，一月，一季度
• 项目代码：proj001，alpha，beta

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

• 连字符：项目-alpha → 变成 项目alpha
• 空格：工作会议 → 变成 工作会议
• 大小写混合：ProjectAlpha → 变成 projectalpha

🔧 自动标签净化： 服务器会自动验证和净化所有标签：

• 仅小写：Project → project
• 无空格：标签 名称 → 标签名称
• 无连字符：项目-alpha → 项目alpha
• 无逗号：标签,名称 → 标签名称
• ✅ 斜杠保留：项目/alpha → 项目/alpha（用于嵌套标签）

当标签被修改时，会返回标签警告，这样您就会知道发生了哪些更改。

🏗️ 重构服务架构

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

转型概述

我们完全重建了系统，从一个2,589行的单体BearService转变为一个现代、可测试的服务导向架构：

🔧 服务导向设计

• 7个专业服务，职责明确
• 依赖注入，提高可测试性和灵活性
• 接口驱动开发，提高可维护性
• 384项全面测试，涵盖所有服务

🛡️ 混合同步安全架构

• 读操作：直接SQLite数据库访问以实现最大性能
• 写操作：Bear的x-callback-url API以实现同步安全
• 完美协调，使用ZUNIQUEIDENTIFIER桥接

📊 质量与性能

• 100% TypeScript，严格类型检查
• 全面错误处理和验证
• 多层缓存，优化性能
• 结构化日志和健康监控

服务架构

ServiceContainer（依赖注入）
├── DatabaseService      （SQLite操作及连接管理）
├── CacheService        （性能优化及智能缓存）
├── LoggingService      （Winston结构化日志）
├── HealthService       （系统监控及健康检查）
├── ValidationService   （输入验证及数据净化）
├── NoteService         （笔记CRUD及生命周期管理）
├── SearchService       （高级搜索及内容发现）
└── TagService          （标签管理和组织）

为什么这种架构有效

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

解决方案：具有清晰关注点分离的服务导向架构。

结果：

• ✅ 可维护代码 - 清晰的服务边界和职责
• ✅ 100%测试覆盖率 - 所有服务的384项测试
• ✅ 类型安全 - 消除了50多个any类型
• ✅ 性能优化 - 多层缓存和查询优化
• ✅ 生产就绪 - 全面的日志记录、监控和错误处理
• ✅ 同步安全操作 - 混合方法消除了iCloud冲突

当前状态

• ✅ 所有读操作 - 直接数据库访问（26个工具）
• ✅ 所有写操作 - 同步安全Bear API（6个工具）
• ✅ 完整功能一致性 - 所有功能按设计运行
• ✅ 兼容iCloud同步 - 没有冲突或问题
• ✅ 标题重复修复 - 笔记正确显示标题（无重复）

🙏 感谢Bear团队

特别感谢来自Bear团队的Danilo，他提供了关键见解，促成了这一解决方案！

---

🤝 贡献与社区

**iCloud同步挑战已被解决！**🎉 现在我们的重点是让这成为最好的Bear集成。无论您是：

• macOS/iOS开发者，拥有API经验
• 数据库专家，熟悉SQLite优化
• Bear重度用户，了解工作流程
• 开发者，希望为MCP生态系统做出贡献

您的贡献可以帮助数千名Bear用户从他们的AI助手获得更多！

当前优先事项

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

快速帮助方式

• ⭐ 如果觉得有用，请给仓库点赞
• 🐛 报告遇到的问题
• 💡 分享新功能或解决方案的想法
• 🔗 向可能提供帮助的开发者传播消息
• 📝 贡献文档改进

让我们一起构建最强大的Bear集成，为AI助手服务！

🔍 所有可用工具

<details> <summary><strong>📖 读操作（26个工具） - ✅ 活跃</strong></summary>

基本操作（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 - 模式匹配（当可用时）
• 高级内容分类
• 链接和参考分析
• 写作模式洞察

</details> <details> <summary><strong>✏️ 写操作（6个工具） - ✅ 活跃（同步安全）</strong></summary>

笔记管理 - 通过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写入之间的完美集成！

</details>

🔧 故障排除

常见问题

“未找到数据库”错误：

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

“权限被拒绝”错误：

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

写操作不工作：

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

性能缓慢：

• 大型数据库（10,000+笔记）可能会花费更长时间进行读取
• 使用具体搜索词而不是广泛查询
• 考虑使用分页参数limit

获取帮助

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

📈 性能

• 读操作：即时（直接数据库访问）
• 写操作：1-2秒（Bear API处理）
• 大型数据库：测试了10,000+笔记
• 内存使用：~50MB典型，~100MB用于复杂操作
• 并发操作：读操作可以同时运行
• API操作：通过Bear的URL方案处理

📄 许可证

MIT许可证 - 详情见LICENSE文件。

---

为Bear社区制作 ❤️