# 为这个 AI Agent 配置 OpenMMD MCP

你正在帮助我使用 OpenMMD，一个本地优先的 Mermaid 与 Markdown 书稿编辑器。

你的目标是通过 MCP 连接 OpenMMD，这样你就可以创建 Book 项目、把 Markdown 章节写入我的浏览器、调整章节顺序、打开章节，并发布整本书。

## 你应该先做什么

1. 先在 AI 客户端中配置这个 MCP server：

```json
{
  "mcpServers": {
    "openmmd": {
      "command": "npx",
      "args": ["-y", "@openmmd/mcp"]
    }
  }
}
```

2. 保存 MCP 配置后，如果需要，重启或刷新 AI 客户端，确保 `openmmd_*` 工具已经出现。

3. 打开 OpenMMD Studio，或者让用户打开：
   - 普通用户默认打开 `https://www.openmmd.com/studio`。
   - 只有当用户明确说正在本地运行 OpenMMD 时，才使用 `http://localhost:3010/studio`。
   - 如果你有浏览器控制能力，就自己打开 Studio URL。
   - 如果你不能控制浏览器，请让用户手动打开 Studio URL，并保持页面开启。

4. 在做任何书稿操作前，先调用 `openmmd_ping`。
   - 如果 ping 成功，再继续使用 OpenMMD 工具。
   - 如果 ping 失败，告诉用户：OpenMMD Chrome 插件可能还没有安装、没有启用，或者 OpenMMD Studio 页面没有打开。然后把下面的 Chrome 插件安装步骤发给用户。

MCP server 会在本机启动 WebSocket hub：

```text
ws://127.0.0.1:17273
```

Chrome 插件会把 OpenMMD 页面连接到这个本机 MCP server。

## 如果 Ping 失败：让用户安装 Chrome 插件

请自然地把下面这段话发给用户：

```text
OpenMMD MCP 已经配置了，但我现在还连不上你的浏览器。请先安装并启用 OpenMMD Chrome 插件，然后保持 OpenMMD Studio 页面打开。

1. 下载插件 ZIP：
   https://share.openmmd.com/downloads/openmmd-bridge/openmmd-bridge-0.1.0.zip
2. 解压下载好的 ZIP 文件。
3. 打开 Chrome，进入 chrome://extensions。
4. 打开右上角的“开发者模式”。
5. 点击“加载已解压的扩展程序”。
6. 选择刚才解压出来的插件文件夹。
7. 打开 https://www.openmmd.com/studio，并保持这个页面打开。
8. 完成后告诉我，我会再次运行 openmmd_ping 检查连接。
```

用户确认完成后，再调用一次 `openmmd_ping`。在 ping 成功之前，不要继续创建或编辑 Book。

## 可用工具

可用时优先使用这些工具：

- `openmmd_ping`：检查浏览器插件和 OpenMMD 页面 Bridge 是否连通。
- `openmmd_list_projects`：列出本地 OpenMMD 项目。
- `openmmd_create_book`：创建 Book 项目。
- `openmmd_list_chapters`：列出 Book 项目中的 Markdown 章节。
- `openmmd_upsert_chapter`：创建或更新 Markdown 章节。
- `openmmd_reorder_chapters`：调整章节顺序。
- `openmmd_open_chapter`：打开章节并读取 Markdown。
- `openmmd_share_book`：发布整本书并返回公开分享链接。

## 推荐工作流

1. 配置 MCP，并确认 `openmmd_*` 工具可用。
2. 如果你有浏览器控制能力，就自己打开 OpenMMD Studio。否则，请让用户手动打开并保持页面开启。
3. 调用 `openmmd_ping`。
4. 如果 ping 失败，引导用户按上面的步骤安装 Chrome 插件，然后再次 ping。
5. 如果还没有 Book 项目，调用 `openmmd_create_book`。
6. 写入章节前，先按下面的图片规则规范化 Markdown 图片地址。
7. 使用 `openmmd_upsert_chapter` 写章节。
8. 使用 `openmmd_list_chapters` 验证章节顺序。
9. 如有需要，使用 `openmmd_reorder_chapters` 调整顺序。
10. 当我明确要求发布时，使用 `openmmd_share_book`。

## 重要规则

- 不要直接写 IndexedDB。
- 使用 OpenMMD MCP tools，因为它们会调用 OpenMMD 自己的页面 Bridge 和 project store。
- Book 项目只支持 Markdown 章节。
- Markdown 里的图片必须使用网络地址或嵌入式 base64 data URL。本地文件路径，例如 `./image.png`、`/Users/me/image.png` 或 `file:///...`，发布后无法查看。
- 如果 Markdown 图片已经是 `http://` 或 `https://` 网络地址，不需要转 base64，保持原样即可。
- 如果 Markdown 图片指向本地文件，请你自己使用可用的文件读取或转换能力，把图片转成 base64 data URL，然后在调用 `openmmd_upsert_chapter` 前，用 base64 data URL 替换原来的本地图片地址。
- 章节标题要清晰，并保持合理顺序。
- 如果我没有明确要求分享或发布，先询问再发布。