# mindmap-mcp

**Browser mind map + local TypeScript server + MCP.**  
No Tauri, no Rust, no desktop installer — just **Node.js**.

[![npm](https://img.shields.io/npm/v/@ewigmidori/mindmap-mcp.svg)](https://www.npmjs.com/package/@ewigmidori/mindmap-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)

中文说明见下方 [中文](#中文)。

---

## What you get

| URL | Purpose |
|-----|---------|
| `http://127.0.0.1:17381/` | Mind map UI |
| `http://127.0.0.1:17381/mcp` | MCP (Streamable HTTP) |
| `http://127.0.0.1:17381/health` | Health check |

- Multi-session isolation: each browser tab and each MCP connection has its own document by default.
- Agents edit structure via `mindmap_apply_op` (`update_node`, `insert_child`, `remove_node`, `move_node`, `reorder_children`).
- Optimistic concurrency with `document_epoch`.

---

## Quick start (everyone)

### Option A — npx (recommended)

Requires [Node.js 20+](https://nodejs.org). Opens the UI and starts MCP on port `17381`.

> npm package: **`@ewigmidori/mindmap-mcp`** (org scope; unscoped `mindmap-mcp` is blocked as too similar to `mind-map-mcp`).  
> CLI binary is still `mindmap-mcp`.

```bash
npx @ewigmidori/mindmap-mcp
```

Or install globally:

```bash
npm install -g @ewigmidori/mindmap-mcp
mindmap-mcp
```

Useful flags / env:

```bash
npx @ewigmidori/mindmap-mcp --no-open          # start without opening a browser
npx @ewigmidori/mindmap-mcp --check            # exit 0 if already healthy
npx @ewigmidori/mindmap-mcp --lan              # bind 0.0.0.0 + print LAN URLs (remote machine)
npx @ewigmidori/mindmap-mcp --lan --public-host 192.168.1.20
# MINDMAP_MCP_PORT=17381 MINDMAP_HOST=127.0.0.1 MINDMAP_LAN=1 MINDMAP_NO_OPEN=1
```

Then wire MCP (or run the write-mcp scripts from a clone) and **open a new chat** so the client reconnects.

### Remote Linux → host browser (LAN)

When the skill/server runs on a **remote Linux** box (SSH, no display), loopback URLs only work on that box. Use **LAN mode** so your laptop browser can open the map:

```bash
# on the remote machine
npx @ewigmidori/mindmap-mcp --lan --no-open
# or from a git clone:
MINDMAP_LAN=1 ./scripts/ensure-running.sh --lan
```

Then open the printed **LAN UI** on your **host** browser, e.g. `http://192.168.1.20:17381/`.

| Need | How |
|------|-----|
| Force public hostname/IP | `--public-host 10.0.0.5` or `MINDMAP_PUBLIC_HOST` |
| Full public base URL | `MINDMAP_PUBLIC_URL=http://box.local:17381` |
| Discover URLs | `GET http://127.0.0.1:17381/health` → `lan_ui`, `lan_mcp`, `ui` |
| MCP on the same remote host | keep `http://127.0.0.1:17381/mcp` |
| MCP client on your laptop | use `lan_mcp` (and open firewall for TCP 17381 on LAN/VPN only) |

Headless SSH sessions skip `xdg-open` and print the host-browser link instead.

### Option B — clone & one-shot scripts

```bash
git clone https://github.com/EwigMidori/mindmap-mcp.git
cd mindmap-mcp
```

**Windows (PowerShell):**

```powershell
powershell -ExecutionPolicy Bypass -File scripts/ensure-running.ps1
powershell -ExecutionPolicy Bypass -File scripts/write-workbuddy-mcp.ps1
```

**macOS / Linux:**

```bash
chmod +x scripts/ensure-running.sh scripts/write-mcp.sh
./scripts/ensure-running.sh
./scripts/write-mcp.sh
```

### Option C — develop from source

```bash
pnpm install   # or: npm install -g pnpm@9 && pnpm install
pnpm build
pnpm start     # same as: node bin/mindmap-mcp.mjs
```

### Wire MCP manually

```json
{
  "mcpServers": {
    "mindmap": { "url": "http://127.0.0.1:17381/mcp" }
  }
}
```

| Client | Config |
|--------|--------|
| WorkBuddy | `~/.workbuddy/mcp.json` |
| Cursor | `~/.cursor/mcp.json` |
| Grok | `~/.grok/config.toml` → `[mcp_servers.mindmap]` `url = "…"` `enabled = true` |

---

## Security

- Default bind is **`127.0.0.1` only** — other machines cannot reach your map.
- `--lan` / `MINDMAP_HOST=0.0.0.0` listens on **all interfaces** (LAN/VPN). There is **no auth** on the API — only use on trusted networks, never expose `17381` to the public internet.
- Prefer VPN or private LAN; restrict with host firewall when possible.

---

## MCP tools (summary)

| Tool | Role |
|------|------|
| `mindmap_list_sessions` / `mindmap_use_session` | Multi-session focus |
| `mindmap_status` / `mindmap_get_outline` / `mindmap_get_document` | Read |
| `mindmap_apply_op` | Tree edit (one op) |
| `mindmap_new` / `mindmap_open` / `mindmap_save` | Lifecycle |

**Default MCP session is a private AI document**, not the browser tab you are looking at.  
To edit the visible tab: `list_sessions` → `use_session` → then ops.

Agent skill (for AI operators): [`skills/mindmap-mcp/SKILL.md`](skills/mindmap-mcp/SKILL.md).

---

## Develop

```bash
pnpm install
pnpm dev          # server :17381 + Vite :1420
pnpm build        # UI → dist/ + bundle/server.mjs
pnpm start        # production single process
pnpm typecheck
```

```
server/           control plane (REST + WS + MCP) — only write path for agents
src/              React UI
packages/mindmap  domain + canvas
bin/              CLI entry
scripts/          ensure-running / write MCP (Win + Unix)
bundle/           esbuild output (generated by pnpm build)
```

---

## Env

| Variable | Default | Meaning |
|----------|---------|---------|
| `MINDMAP_MCP_PORT` | `17381` | HTTP port |
| `MINDMAP_HOST` | `127.0.0.1` | Bind address (`0.0.0.0` for LAN) |
| `MINDMAP_LAN` | — | `1` = same as bind `0.0.0.0` + advertise LAN URLs |
| `MINDMAP_PUBLIC_HOST` | auto | Host printed in UI/MCP URLs (never `0.0.0.0`) |
| `MINDMAP_PUBLIC_URL` | — | Full public base, e.g. `http://box.local:17381` |
| `MINDMAP_NO_OPEN` | — | `1` = do not open browser |
| `MINDMAP_REPO_ROOT` | auto | Package root (UI `dist/`) |
| `MINDMAP_DEV` | — | `1` = proxy UI to Vite |

---

## Publishing (maintainers)

npm name: **`@ewigmidori/mindmap-mcp`** (public scoped).

Releases use **npm Trusted Publishing** (OIDC from GitHub Actions) — no long-lived `NPM_TOKEN`.

1. On [npmjs.com](https://www.npmjs.com) → package **@ewigmidori/mindmap-mcp** → **Settings** → **Trusted Publisher**  
   - GitHub user: `EwigMidori`  
   - Repository: `mindmap-mcp`  
   - Workflow filename: `publish.yml` (name only, not the path)  
   - Ensure the publisher account can publish under the **ewigmidori** org
2. Bump `version` in `package.json`, push, create a GitHub **Release** (or run workflow **Publish npm** manually).
3. Workflow: [`.github/workflows/publish.yml`](.github/workflows/publish.yml) — `id-token: write`, `npm publish --access public --provenance`.

## License

[MIT](LICENSE) © 2026 EwigMidori

---

## 中文

**浏览器思维导图 + 本机 TypeScript 服务 + MCP。** 不需要 Tauri / Rust / 桌面安装包，只要 Node。

### 最快上手（推荐 npx）

```bash
npx @ewigmidori/mindmap-mcp
```

**远程 Linux（要在自己电脑浏览器里看）：**

```bash
npx @ewigmidori/mindmap-mcp --lan --no-open
# 日志 / health 里的 lan_ui → 在宿主浏览器打开
```

全局安装：

```bash
npm install -g @ewigmidori/mindmap-mcp
mindmap-mcp --lan
```

也可用仓库脚本：

```bash
git clone https://github.com/EwigMidori/mindmap-mcp.git
cd mindmap-mcp
```

- Windows：`scripts/ensure-running.ps1` + `scripts/write-workbuddy-mcp.ps1`
- macOS/Linux：`./scripts/ensure-running.sh`（远程加 `--lan`）+ `./scripts/write-mcp.sh`
- 开发：`pnpm install && pnpm build && pnpm start`

默认只监听本机 `127.0.0.1`；`--lan` 会监听全网卡，**仅限受信局域网/VPN**，不要暴露到公网。

对 AI 说「帮我打开思维导图」时，助手应 `npx @ewigmidori/mindmap-mcp`（远程则加 `--lan`）并写入 MCP，而不是甩一长串终端命令给你。

MCP 默认连的是**独立 AI 会话**；要改你正在看的浏览器标签，必须先 `mindmap_list_sessions` → `mindmap_use_session`。