Mcp Server

Inkdrop MCP 服务

一个用于 Inkdrop 本地 HTTP 服务 API 的 Model Context Protocol 服务。

安装

请阅读此处的文档。

组件

工具

1. read-note：根据 ID 从数据库中获取笔记的完整内容。
   • 必填输入：
     • noteId：要获取的笔记 ID。可在笔记文档中找到，字段为 _id。始终以 note: 开头。
   • 可选输入：
     • includeTemplate：当值为 true 且笔记具有 sourceTemplateId 时，同时获取该模板，并将其正文（填写说明和示例）作为额外文本块嵌入。默认值：false。
   • 注意：如果笔记是根据模板创建的，响应会包含指向其源模板的资源链接，模板正文中包含填写说明和示例。
2. read-backlinks：获取笔记的反向链接，即链接到该笔记的笔记。
   • 必填输入：
     • noteId：要查找反向链接的笔记 ID。始终以 note: 开头。
   • 注意：每个结果都会作为资源链接（inkdrop://note/<id>）返回，指向引用该笔记的笔记。反向链接通过在所有笔记正文中搜索该笔记的链接 URI 查找。
3. search-notes：列出包含指定关键词的所有笔记。
   • 必填输入：
     • keyword：要搜索的关键词。
   • 注意：结果包含截断后的笔记正文（200 个字符）。使用 read-note 获取完整内容。
   • 支持高级搜索限定符，例如 book:、tag:、status:、title: 等。
4. list-notes：根据指定条件列出所有笔记。
   • 必填输入：
     • bookId：笔记本 ID。始终以 'book:' 开头。
   • 可选输入：
     • tagIds：用于筛选的标签 ID 数组。每个 ID 都以 'tag:' 开头。
     • keyword：用于筛选笔记的关键词。
     • sort：排序字段（updatedAt、createdAt 或 title）。默认值：updatedAt。
     • descending：反转输出顺序。默认值：true。
   • 注意：结果包含截断后的笔记正文（200 个字符）。使用 read-note 获取完整内容。
5. list-templates：列出笔记模板，包括你的自定义模板，以及 Inkdrop 随附的官方模板。
   • 可选输入：
     • keyword：通过模糊匹配模板标题来筛选模板。
   • 注意：结果包含截断后的模板正文（200 个字符）。使用 read-note 获取完整内容。
6. create-note：在数据库中创建新笔记。
   • 必填输入：
     • bookId：笔记本 ID。必须以 'book:' 开头，或为 'trash' 或 'template'。指定 'template' 可创建自定义笔记模板。
     • title：笔记标题。
     • body：笔记的 Markdown 内容。
   • 可选输入：
     • status：笔记状态（none、active、onHold、completed、dropped）。
     • tags：要分配给笔记的标签 ID 数组。每个 ID 都必须以 'tag:' 开头。
7. update-note：更新数据库中的现有笔记。仅更新你提供的字段；未提供的字段保持不变。
   • 必填输入：
     • _id：笔记 ID。必须以 'note:' 开头。
     • _rev：修订 ID（CouchDB MVCC-token）。
   • 可选输入：
     • bookId：笔记本 ID。必须以 'book:' 开头，或为 'trash' 或 'template'。
     • title：笔记标题。
     • body：笔记的 Markdown 内容。
     • status：笔记状态（none、active、onHold、completed、dropped）。
     • tags：要分配给笔记的标签 ID 数组。每个 ID 都必须以 'tag:' 开头。
8. patch-note：通过执行精确的字符串替换来更新现有笔记正文。对于大型笔记的小幅编辑，此方法比 update-note 更高效，因为它可以节省 token。你必须先使用 read-note 读取笔记，以获取当前正文。
   • 必填输入：
     • _id：笔记 ID。必须以 'note:' 开头。
     • _rev：修订 ID（CouchDB MVCC-token）。
     • old_string：要在笔记正文中查找的精确文本。必须恰好匹配一次。请提供足够的上下文，确保匹配唯一。
     • new_string：用于替换 old_string 的文本。使用空字符串可删除匹配文本。
9. list-notebooks：获取所有笔记本的列表。
10. read-book：根据 ID 获取单个笔记本。
    • 必填输入：
      • bookId：笔记本 ID。必须以 'book:' 开头。
11. create-book：在数据库中创建新笔记本。
    • 必填输入：
      • name：笔记本名称。
    • 可选输入：
      • parentBookId：父笔记本的 ID。必须以 'book:' 开头。省略此项可在根级别创建笔记本。
12. update-book：更新数据库中的现有笔记本。仅更新你提供的字段；未提供的字段保持不变，因此无需先读取笔记本。
    • 必填输入：
      • _id：笔记本 ID。必须以 'book:' 开头。
    • 可选输入：
      • _rev：修订 ID（CouchDB MVCC-token）。仅在需要乐观并发保护时使用——传入此值可确保发生并发编辑冲突时更新失败。
      • name：笔记本名称。
      • parentBookId：父笔记本的 ID。传入 null 可将笔记本移至根级别。
13. list-tags：获取所有标签的列表。
14. read-tag：根据 ID 获取单个标签。
    • 必填输入：
      • tagId：标签 ID。必须以 'tag:' 开头。
15. create-tag：在数据库中创建新标签。
    • 必填输入：
      • name：标签名称。
    • 可选输入：
      • color：标签颜色类型（default、red、orange、yellow、olive、green、teal、blue、violet、purple、pink、brown、grey、black）。默认值：default。
16. update-tag：更新数据库中的现有标签。仅更新你提供的字段；未提供的字段保持不变，因此无需先读取标签。
    • 必填输入：
      • _id：标签 ID。必须以 'tag:' 开头。
    • 可选输入：
      • _rev：修订 ID（CouchDB MVCC-token）。仅在需要乐观并发保护时使用——传入此值可确保发生并发编辑冲突时更新失败。
      • name：标签名称。
      • color：标签颜色类型。省略此项可保留标签当前颜色。
17. create-file：使用本地图片文件或 Base64 图片数据在数据库中创建新的附件文件。返回用于在笔记正文中嵌入该附件的 Markdown。
    • 必填输入：以下选项必须且只能提供一个
      • filePath：要附加的本地图片文件的绝对路径。优先使用此项——这样图片字节不会进入对话。
      • data：Base64 编码的图片数据，不带 data: URI 前缀。
    • 可选输入：
      • name：文件名。默认为 filePath 的文件名；如果提供 data，则默认为 image.<ext>。
      • contentType：MIME 类型（image/png、image/jpeg、image/jpg、image/svg+xml、image/gif、image/heic、image/heif）。省略时会根据 filePath 扩展名推断；使用 data 时必须提供。
      • publicIn：包含该附件的笔记 ID 数组。每个 ID 都必须以 'note:' 开头。
    • 注意：附件大小上限为 10MB。
18. read-file：根据 ID 获取附件文件。返回文件元数据；如果文件是 PNG、JPEG 或 GIF，还会返回图片本身。
    • 必填输入：
      • fileId：附件 ID。必须以 'file:' 开头。
    • 可选输入：
      • outputPath：用于写入附件的绝对路径。提供此项后，文件会保存到该路径，且其字节不会以内联形式返回。获取 SVG、HEIC 和 HEIF 附件时必须提供此项，因为这些格式无法以内联形式显示。
      • includeImage：是否在元数据旁返回图片。默认值：true。对于较大的附件，设为 false 可只获取元数据。

调试

由于 MCP 服务通过 stdio 运行，调试可能颇具挑战。为了获得最佳调试体验，我们强烈建议使用 MCP Inspector。

你可以通过 npm 使用此命令启动 MCP Inspector：

npx @modelcontextprotocol/inspector "./dist/index.js"

请确保已正确配置环境变量。

启动后，Inspector 会显示一个 URL，你可以在浏览器中访问该 URL 开始调试。

你也可以使用此命令查看服务日志：

tail -n 20 -f ~/Library/Logs/Claude/mcp-server-inkdrop.log