# Configure OpenMMD MCP for This AI Agent

You are helping me use OpenMMD, a local-first Mermaid and Markdown book editor.

Your goal is to connect to OpenMMD through MCP so you can create Book projects, write Markdown chapters into my browser, reorder chapters, open chapters, and publish the book.

## What You Should Do First

1. Configure this MCP server in the AI client:

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

2. After the MCP config is saved, restart or reload the AI client if needed so the `openmmd_*` tools appear.

3. Open OpenMMD Studio, or ask the user to open it:
   - For normal users, open `https://www.openmmd.com/studio`.
   - Only use `http://localhost:3010/studio` if the user explicitly says they are running OpenMMD locally.
   - If you have browser-control capability, open the Studio URL yourself.
   - If you cannot control the browser, ask the user to open the Studio URL manually and keep the tab open.

4. Call `openmmd_ping` before doing any book work.
   - If ping succeeds, continue with the OpenMMD tools.
   - If ping fails, tell the user that the OpenMMD Chrome extension is probably not installed, not enabled, or the OpenMMD Studio tab is not open. Then give them the Chrome extension setup steps below.

The MCP server starts a local WebSocket hub at:

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

The Chrome extension connects the OpenMMD page to this local MCP server.

## If Ping Fails: Tell the User to Install the Chrome Extension

Use this message, adapted naturally:

```text
OpenMMD MCP is configured, but I cannot reach your browser yet. Please install and enable the OpenMMD Chrome extension, then keep OpenMMD Studio open.

1. Download the extension ZIP:
   https://share.openmmd.com/downloads/openmmd-bridge/openmmd-bridge-0.1.0.zip
2. Unzip the downloaded file.
3. Open Chrome and go to chrome://extensions.
4. Turn on Developer mode in the top-right corner.
5. Click "Load unpacked".
6. Select the unzipped extension folder.
7. Open https://www.openmmd.com/studio and keep that tab open.
8. Tell me when this is done, and I will run openmmd_ping again.
```

After the user confirms, call `openmmd_ping` again. Do not proceed to create or edit books until ping succeeds.

## Available Tools

Use these tools when available:

- `openmmd_ping`: Check that the browser extension and OpenMMD page bridge are connected.
- `openmmd_list_projects`: List local OpenMMD projects.
- `openmmd_create_book`: Create a Book project.
- `openmmd_list_chapters`: List Markdown chapters in a Book project.
- `openmmd_upsert_chapter`: Create or update a Markdown chapter.
- `openmmd_reorder_chapters`: Reorder chapters.
- `openmmd_open_chapter`: Open a chapter and read its Markdown.
- `openmmd_share_book`: Publish the whole book and return the public share URL.

## Recommended Workflow

1. Configure MCP and make sure the `openmmd_*` tools are available.
2. Open OpenMMD Studio yourself if you have browser-control capability. Otherwise, ask the user to open it manually and keep the tab open.
3. Call `openmmd_ping`.
4. If ping fails, guide the user through the Chrome extension installation steps and retry ping.
5. If I do not already have a Book project, call `openmmd_create_book`.
6. Before writing chapters, normalize Markdown image URLs using the image rules below.
7. Write chapters with `openmmd_upsert_chapter`.
8. Use `openmmd_list_chapters` to verify chapter order.
9. Use `openmmd_reorder_chapters` if needed.
10. Use `openmmd_share_book` when I ask you to publish.

## Important Rules

- Do not write IndexedDB directly.
- Use the OpenMMD MCP tools, because they call OpenMMD's own page bridge and project store.
- Book projects only support Markdown chapters.
- Markdown images must use network URLs or embedded base64 data URLs. Local file paths such as `./image.png`, `/Users/me/image.png`, or `file:///...` will not be viewable after publishing.
- If a Markdown image already uses an `http://` or `https://` URL, keep it as-is.
- If a Markdown image points to a local file, convert that image to a base64 data URL yourself using whatever file-reading or conversion capability you have, then replace the original local image path in the Markdown before calling `openmmd_upsert_chapter`.
- Keep chapter titles clear and ordered.
- Ask before publishing if I did not explicitly request sharing.