MarsDawn

marsdawn-mcp

一个 MCP 服务，可让 AI agent 在 macOS 上将 Markdown 导出为 PDF，并在 MarsDawn 应用中打开 Markdown 文件。它通过运行你已有的 marsdawn 命令行工具来实现。对于没有自带 Shell 的客户端，这是一个调用渠道；如果能使用 Shell，直接运行 marsdawn 会更简单。

首个版本 0.1.0 是一个 MCP Bundle，marsdawn.mcpb 已附加在该版本的发布页中。

最新版本 0.2.4 已列入 MCP Registry，条目为 dev.southern-light.mcp/marsdawn。

功能

提供两个工具。

export_markdown_to_pdf

运行 marsdawn export <input> --json，并将 CLI 的 JSON 结果作为结构化内容返回，因此生成的 PDF 与从命令行导出的效果一致：按照 MarsDawn 的预览效果渲染，并包含 Mermaid 图表。

参数
input	Markdown 文件的绝对路径，必须位于允许的文件夹内。必填。
output	PDF 的绝对路径，必须位于允许的文件夹内，并以 .pdf 结尾。默认为输入文件路径，扩展名为 .pdf。
theme	dawn、classic、modern 或 vivid。
paper	a4 或 letter。
force	替换已有的 PDF。不启用此项时，会保留已有 PDF，并由工具提示这一情况。
allowRemoteImages	渲染时加载网络图片。默认关闭。

open_in_marsdawn

运行 marsdawn open <path>[:line] --json，并返回 CLI 的 JSON 结果。需要安装 MarsDawn 应用，可从 Mac App Store 获取；每个文件只需调用一次，因为打开的窗口会自动跟随该文件后续的编辑，无需再次调用。

参数
path	已存在的 Markdown 文件的绝对路径，不能是文件夹，且必须位于允许的文件夹内。必填。
line	要定位到的行号，范围为 1 到 999999999。
background	在不将 MarsDawn 切换到前台的情况下打开。

目前还没有 folder：首个版本的 marsdawn open --folder 会在应用中弹出错误对话框，因此此工具不提供该选项。待应用 1.1 支持文件夹，且网站发布对应的 open.v3.json 后，此功能才会提供。

任一工具调用失败时，都会返回错误，其中包含 CLI 的错误消息和后续操作建议。如果未安装 MarsDawn 应用（仅适用于 open_in_marsdawn），也会以同样的方式返回错误，而不会抛出异常。

它可以读取和写入的位置

两个工具只能在你允许的文件夹内工作。指定文件夹有两种方式，服务会同时使用这两种方式：

• 扩展程序的设置。“允许的文件夹”是一个多值设置，没有预设值：添加你需要的文件夹，例如“文稿”文件夹，然后保存。每个文件夹都会成为传给服务的一个参数。在添加文件夹之前，每次调用都会被拒绝，并显示相应消息。（设置预设值也没有用：Claude Desktop 不会展开文件夹设置默认值中的 ${DOCUMENTS} 这类占位符，而必填设置会使服务在保存之前完全无法启动。）
• **MCP 根目录。**如果客户端提供 roots 能力，服务会在每次工具调用时向客户端请求当前根目录（只有客户端承诺会通知变更时，才会缓存根目录）。根目录是客户端对你工作区的声明，并非由此服务控制：沙箱范围取决于最宽泛的来源，因此，如果 Agent 可以自行扩大工作区，客户端也就能扩大自身的限制范围。Claude Desktop 不会发送根目录；Claude Code 会。

从源代码运行时，文件夹是位置参数：

node /absolute/path/to/marsdawn-mcp/server/index.js /Users/me/Documents /Users/me/Projects

**既没有文件夹也没有根目录时，所有调用都会被拒绝。**服务无法检查的调用也会被拒绝：如果客户端的 roots/list 返回错误、格式不正确的结果或空结果，该调用会被视为没有根目录，而不是拥有所有根目录。

在启动 marsdawn 之前，会应用以下规则：

• 每个路径都必须是纯绝对路径——不能包含 . 或 .. 路径组件，不能包含 //，也不能以斜杠结尾——这样服务检查的字符串就是 CLI 收到的字符串。
• 通过符号链接解析后的路径所在文件夹必须位于某个允许的文件夹内，文件本身也必须如此。指向文件夹树之外的符号链接，无论从哪一端访问都会被拒绝。
• output 必须指定一个 .pdf 文件，不能是符号链接，也不能是常规文件以外的任何类型。缺少 output 时，会将 <input without its extension>.pdf 作为输出路径，并按相同方式检查，然后作为 --output 传给 CLI。
• 任何位于允许文件夹之外的路径都会收到一条拒绝消息，其中会列出允许的文件夹，无论该路径是否存在，这样两个工具都不会透露该位置有什么内容。该消息确实会向模型透露你的文件夹路径；这是刻意的权衡，让 Agent 能选择有效路径，而不是盲目重试。
• 允许文件夹内不存在的文件会继续传递给 CLI，因此 CLI 仍会返回 input_not_found 及后续操作说明。符号链接目标无法解析时，不会被视为文件缺失：它会收到与指向文件夹之外的符号链接相同的拒绝消息。

此机制不会做的事：在允许的文件夹内，force 仍会替换已有的 PDF，与命令行行为完全相同。如果目标位置是硬链接，PDF 会替换目录项，而不是文件内容——CLI 会在目标文件旁渲染到临时文件，再将其替换到目标位置——因此其他链接仍会保留旧内容。这两种情况都是 CLI 原有的行为，未作更改。

要求

• macOS，以及 marsdawn 0.5.0 或更高版本：brew install redtear1115/tap/marsdawn。
• Node.js 20 或更高版本。

服务会先查找 MARSDAWN_PATH 指定的 marsdawn 路径（如果已设置），然后在 PATH 中查找，最后检查 /opt/homebrew/bin 和 /usr/local/bin。

从源代码运行

git clone https://github.com/redtear1115/marsdawn-mcp.git
cd marsdawn-mcp
npm ci --omit=dev

然后，将 MCP 客户端配置为通过 stdio 运行 node /absolute/path/to/marsdawn-mcp/server/index.js，并将它可以操作的文件夹作为参数传入（参见 它可以读取和写入的位置）。

开发

npm ci
npm test               # unit and stdio tests, against a fake marsdawn
npm run check-schemas  # the vendored schemas match the ones the site publishes
npx mcpb validate manifest.json
node scripts/check-server-json.js   # server.json's fileSha256 matches the release asset

schemas/ 存放的是从 https://marsdawn.southern-light.dev/schemas/cli/ 发布的 JSON Schemas 副本。网站是这些文件的发布源；更新时请复制已发布的文件，不要在此处编辑。

许可证

Apache License 2.0。请参阅 LICENSE。