Drafta

drafta-mcp

一个 Model Context Protocol 服务，可向 AI 助手（Claude Code、Zed，或任何通过 stdio 启动服务的其他 MCP 客户端）开放 Drafta 笔记库。

助手可以搜索和阅读笔记；（除非你使用 --read-only 启动服务）还可以创建笔记、追加内容、添加标签、设置状态，以及将笔记归档到笔记本中。它写入的所有内容都会保存在 Drafta 应用读取的同一 Markdown 文件中，因此，从聊天中创建的笔记与手动输入的笔记别无二致。

隐私

创建此仓库，是为了让你可以自行检查笔记会被发送到哪里。答案是：哪里都不会。

• 仅使用 stdio。 服务通过 stdin 和 stdout 与启动它的客户端通信。它不会打开套接字，也不会监听任何端口。
• 仅访问本地文件。 它只会读取和写入笔记库目录下的文件，不做其他操作。它绝不会访问应用的设置、钥匙串项目或同步状态。
• 不连接网络。 此软件包中的代码不会发起网络请求。Sources/ 中没有 URLSession、Network 框架或任何套接字；唯一的依赖项是官方 MCP Swift SDK，仅用于其 stdio 传输。
• 没有账户、许可证检查或遥测。

笔记会暴露给谁，取决于 MCP 客户端如何处理读取到的文本——这由你连接的客户端决定。

构建

需要 macOS 13 或更高版本，以及 Swift 6（Xcode 16 或更新版本）。

swift build -c release

二进制文件位于 .build/release/drafta-mcp。

swift test   # the test suite

安装

将二进制文件复制到稳定的位置，例如：

install -m 755 .build/release/drafta-mcp /usr/local/bin/drafta-mcp

用法

usage: drafta-mcp [--library <path>] [--read-only]

  -l, --library <path>  library root (default: ~/Library/Application Support/Drafta/Library)
  -r, --read-only       publish read tools only
  -h, --help            print this help and exit

如果未指定 --library，服务会打开 Drafta 应用使用的笔记库。由于客户端配置是 JSON，且不会经过 shell 处理，服务会展开路径中的 ~。未知标志会导致错误：--readonly（拼写错误）不会启动可写服务。

Claude Code

claude mcp add drafta -- /usr/local/bin/drafta-mcp --library "~/Library/Application Support/Drafta/Library"

在末尾添加 --read-only，即可仅授予助手读取权限。

Claude Code 插件

此仓库也是 Claude Code 插件市场。插件会启动 Drafta.app 内附带的 drafta-mcp 辅助程序，因此需要将 Drafta.app 安装在 /Applications 中。

/plugin marketplace add rpegorov/drafta-mcp
/plugin install drafta@drafta

插件会使用默认设置（应用的笔记库，具有读写权限）运行服务。如需只读访问，或 Drafta.app 位于 ~/Applications 中，请使用 claude mcp add 自行注册辅助程序，并传入 --read-only 或完整路径；请参阅 plugins/drafta/README.md。

Claude Desktop（MCPB）

从 Releases 页面下载 drafta-mcp.mcpb，然后双击。此软件包不包含二进制文件：它会启动 Drafta.app 内附带的 drafta-mcp 辅助程序，因此需要将 Drafta.app 安装在 /Applications 中。使用 scripts/build-mcpb.sh 从源代码构建。

Codex

codex plugin marketplace add rpegorov/drafta-mcp
codex plugin add drafta@drafta

插件会启动 Drafta.app 内的辅助程序，因此需要将 Drafta.app 安装在 /Applications 中。

DeepSeek Harness（DSH）

plugins/dsh-drafta 会为 Drafta 辅助程序添加一个 @deepseek-ai/dsh-mcp-client 条目（dsh-drafta-mcp）。像添加任何本地插件一样，使用 link: 依赖项将软件包添加到配置文件的 package.json 中，并在 dsh.profile.bundles 下列出：

{
  "dependencies": { "dsh-drafta": "link:/path/to/drafta-mcp/plugins/dsh-drafta" },
  "dsh": { "profile": { "bundles": ["dsh-drafta"] } }
}

如果你之前已手动将 Drafta 添加到 DSH，请移除其中一个：两者都会注册一个名为 drafta 的服务。

Zed

在 settings.json 中：

{
  "context_servers": {
    "drafta": {
      "command": "/usr/local/bin/drafta-mcp",
      "args": ["--library", "~/Library/Application Support/Drafta/Library"]
    }
  }
}

工具

读取工具（始终发布）：

工具	功能
search_notes	按 tag、status、notebook 筛选标题、正文和标签的全文搜索；按最新优先排序，limit 最高为 100。查询为空时，会列出最近的笔记。
read_note	按 ID 或确切标题读取一篇完整笔记。
list_notebooks	列出笔记本及其层级。
list_tags	列出所有正在使用的标签。
formatting_guide	Drafta 支持渲染的 Markdown 格式：提示框、mermaid、任务列表、标签、维基链接、数学公式。

写入工具（使用 --read-only 时不发布）：

工具	功能
create_note	新建笔记；除非指定笔记本，否则会放入收件箱。可选设置 tags 和 status。
append_to_note	在末尾添加文本；先前文本会作为一个修订版本保留。
update_note	替换正文；先前文本会作为一个修订版本保留。
set_note_status	设置为 active、onHold、completed、dropped 或 none。
tag_note	添加标签（数组或逗号分隔的字符串）。
create_notebook	创建笔记本，或返回同名的现有笔记本。
trash_note	将笔记移至废纸篓；文件会保留。

笔记也会作为 MCP 资源发布（drafta://note/<uuid>，最近的 200 篇），因此客户端无需调用工具即可将笔记附加为上下文。

资料库格式

资料库是一个普通目录：

Library/
  library.json              notebooks (pretty-printed, sorted JSON)
  notes/<UUID>.md           one note: YAML front matter + Markdown body
  revisions/<UUID>/<ms>.md  previous bodies of a note, one file per revision
  editor-hold.json          written by the app while it holds unsaved text

如果你要自行读取或写入这些文件，以下几点值得了解：

• 标签不会存储。 每次读取时，都会根据正文中的 #tags 提取标签；只有单独添加的标签会保存在 front-matter 字段 extraTags 中。
• 标题是正文的第一行。 如果正文中没有标题，create_note 会将标题写成 # heading。
• 没有笔记本的笔记是孤立笔记，只能在“所有笔记”中查看，因此新笔记会归入收件箱（如果不存在则会创建）。
• 编辑会保留历史记录。 update_note 和 append_to_note 会将替换的文本保存在 revisions/ 下（每篇笔记最多 30 个版本），应用会将其显示为历史记录。
• 打开的笔记受保护。 Drafta 应用为笔记保留未保存文本时，会在 editor-hold.json 中列出该笔记；update_note 和 append_to_note 会拒绝写入该笔记正文并说明原因，而不是报告成功后又被应用片刻后覆盖。
• library.json 的编辑会进行文件协调，因此应用同时添加的笔记本不会丢失。

无论应用是否运行，服务都可以工作。应用运行时，其文件监视器会检测到服务写入的内容。

与 Drafta.app 的关系

Drafta.app 在应用包内附带了自己的 drafta-mcp 副本。**此仓库并非该二进制文件。**它是同一服务的独立、可由社区编辑的快照：工具名称、参数和磁盘格式相同，但移除了应用的许可证检查——这里的写入操作仅由 --read-only 控制。两者分别开发，可能会逐渐不同步；如果应用更改了资料库格式，此快照不会自动跟进。

欢迎贡献。

许可证

Apache License 2.0 — 参见 LICENSE 和 NOTICE。

---

俄语简介

drafta-mcp 是一个用于 Drafta 笔记资料库的 MCP 服务。它仅通过 stdio 工作，只读取和写入资料库目录中的文件，不会发起任何网络请求。构建方式：swift build -c release。连接到 Claude Code： claude mcp add drafta -- /путь/к/drafta-mcp --library <путь к библиотеке>。 --read-only 标志仅保留读取工具。这是该服务的独立快照，并非 Drafta.app 内附带的二进制文件。

---