使用说明

• 项目简介 该仓库实现了一个本地 MCP 服务器（Bear Notes MCP 服务器捆绑包），用于在 Claude Desktop 对话中以标准化的方式访问和操作 Bear Notes。本服务器在本地读取 Bear Notes 的数据库，提供阅读、搜索、增加文本以及附加文件等工具，通过 MCP 客户端进行请求与响应，确保数据不离开本机。

• 主要功能点

  • MCP 服务器核心：使用 Model Context Protocol (MCP) 提供可扩展的资源、工具和提示渲染能力，返回标准化的 JSON-RPC 响应。
  • 工具集成：注册多种工具，例如 bear-open-note、bear-create-note、bear-search-notes、bear-add-text-append、bear-add-text-prepend、bear-add-file，用于读取、创建、修改 Bear Notes。
  • 本地数据处理：直接读取 Bear Notes 的 SQLite 数据库，或通过 Bear 的 x-callback-url API 完成写操作，所有操作均在本地完成，无网络传输。
  • 日志与错误处理：完善的日志记录和错误处理，便于排错与运维。
  • 本地化传输：通过 Stdio Server Transport 与 MCP 客户端进行通信，适配 Claude Desktop 的扩展场景。

• 安装步骤

  1. 确保 Bear Notes 应用已安装并至少打开过一次，以便生成并准备数据库。
  2. 确保 Claude Desktop 已安装并处于运行状态，用于加载并启动该 MCP 服务。
  3. 将本仓库的代码打包成可在目标环境执行的扩展包（通常包括将 TypeScript 编译为 JavaScript，输出到 dist 目录，并确保可执行入口 main.js/ dist/main.js 可被 Node 直接执行）。
  4. 在 Claude Desktop 的扩展/服务器配置中加载该扩展，或者按照扩展打包后放置的位置运行。
  5. 查看日志确认服务器已就绪（例如 Bear Notes MCP 服务器日志位于 ~/Library/Logs/Claude/ 等路径，具体以实际运行环境为准）。

• 服务器配置（MCP 客户端需要在启动前了解的参数信息，这里给出示例描述） 说明：MCP 客户端需知道服务器的名称、启动命令及参数，以便建立连接。以下信息用于配置客户端的启动项（以 JSON 形式表示，不作为代码块呈现）： { "name": "bear-notes-mcp", "command": "node", "args": ["dist/main.js"] } 注释：

  • name: MCP 服务器在本实现中的名称，与代码中创建的服务器对象 name 字段一致。
  • command: 启动服务器所需的命令，此处采用 Node.js 运行打包后的入口。
  • args: 命令参数，dist/main.js 为编译输出入口，请确保实际打包产物路径与入口名称一致。服务器通过标准输入/输出（Stdio）与 MCP 客户端通信，因此保持工作目录及依赖就绪即可。

• 基本使用方法

  • 通过 Claude Desktop 与 Bear Notes 的对话场景直接调用工具，如“查找 Bear Notes”、“打开笔记”、“创建笔记”等。
  • 使用 Bear Notes 的搜索功能进行定位后，通过对应的工具 ID 调用了解和修改笔记内容。
  • 遇到需要附加文件时，先将文件内容编码为 Base64，调用 Bear 文件附加工具完成操作。
  • 如遇到问题，可通过查看本地日志文件（如 Bear Notes MCP 的日志）进行排错。

• 其他信息

  • 本实现默认 macOS 平台相关的 Bear Notes API 调用方式，若要在其他平台使用，请相应调整 Bear 的 URL 调用逻辑与数据库访问方式。
  • 服务器版本与应用版本参见配置，确保与 Claude Desktop 版本兼容。