# mindmapio-mcp

> **Tip:** Give this README to your agent and ask it to install the MCP.

Give your AI agent a place to build and keep what it learns. Connect it to [mindmap.io](https://mindmap.io) and it turns research, plans, and conversations into a real map you can open, grow, and share. Your agent reads existing maps, adds and edits nodes, runs prompts on them, and fans any topic out into follow-up questions, all through your own mindmap.io account.

Three ways to set it up:

1. **Claude plugin.** One install command and one masked prompt for your token.
2. **MCP server.** One line in your MCP client config (Claude Desktop, Cursor, and other MCP clients).
3. **Agent skill.** Install it with `npx skills` so your agent works with mindmap.io directly, no MCP client needed.

## Get a token

Every call uses a personal access token from your account.

1. Open mindmap.io, go to settings, then API access.
2. Generate a token and copy it. You only see it once.
3. Save it as `MINDMAP_API_TOKEN`, or paste it into the plugin's token prompt.

The token acts as you. Regenerate it any time and the old one stops working instantly.

## Option 1: Claude plugin

```
/plugin marketplace add MohGanji/mindmapio-mcp
/plugin install mindmapio@mindmap-io
```

Claude Code prompts for your API token, masks it, and stores it in your OS keychain. Restart, and the tools are live. [`SETUP.md`](SETUP.md) walks Claude through the same steps, and through what to check when something does not connect.

The plugin ships the MCP server, a skill on how to shape a map well, and the direct-HTTP skill below. No slash commands and no sub-agents.

## Option 2: MCP server

Add this to your MCP client config. `npx` fetches and runs the package for you:

```json
{
  "mcpServers": {
    "mindmapio": {
      "command": "npx",
      "args": ["-y", "github:MohGanji/mindmapio-mcp"],
      "env": {
        "MINDMAP_API_TOKEN": "<your personal access token>"
      }
    }
  }
}
```

With the Claude Code CLI, the same thing in one line:

```bash
claude mcp add mindmapio --env MINDMAP_API_TOKEN=<your token> -- npx -y github:MohGanji/mindmapio-mcp
```

The first run builds from source, so it takes a few extra seconds. Later runs are cached.

### Settings

| Env var | Required | Default | What it does |
| --- | --- | --- | --- |
| `MINDMAP_API_TOKEN` | yes | — | Your personal access token. Sent as `Authorization: Bearer <token>`. Never logged. |
| `MINDMAP_API_BASE_URL` | no | `https://mindmap.io` | API base URL. |

### What your agent can do

Seventeen tools, one per operation in the [Mindmap.io node API](https://mindmap.io/api/openapi.json).

| Tool | What it does |
| --- | --- |
| `list_maps` | List your maps, newest first. |
| `get_map` | Read a whole map and its node tree. |
| `get_node` | Read one node. |
| `get_subtree` | Read a node and its children, as deep as you want. |
| `create_map` | Start a new map. |
| `delete_map` | Delete a map and everything in it. |
| `publish_map` | Publish a map and get its shareable + embed links. |
| `unpublish_map` | Make a published map private again. |
| `create_node` | Add a node under a parent. |
| `update_node` | Edit a node's content, note, type, or model. |
| `delete_node` | Remove a node and its children. |
| `submit_node` | Run a node through the model and get the answer back. |
| `auto_expand` | Turn a node into follow-up questions for your agent to run. |
| `retry_node` | Re-run a node that failed. |
| `interrupt_node` | Stop a node that is still running. |
| `upload_attachment` | Upload an image or PDF from this machine to attach to a node. |
| `read_attachment` | Save an uploaded file back to this machine. |

`create_node` mints a node id for you when you leave it out, so your agent can lay out a whole branch in one pass.

Each tool's description and its `title` / `readOnlyHint` / `destructiveHint` annotations are generated from the OpenAPI document rather than written here, so what your agent reads is the contract the API enforces. See [Regenerating the tool list](#regenerating-the-tool-list).

## Option 3: agent skills

Install the skills with one command:

```bash
npx skills add MohGanji/mindmapio-mcp
```

This works with Claude Code and other agents that support skills (browse them at [skills.sh](https://www.skills.sh)). Two skills ship here:

- [`skills/mindmapio/SKILL.md`](skills/mindmapio/SKILL.md) teaches the same actions over plain HTTP, no MCP client required.
- [`skills/map-shaping/SKILL.md`](skills/map-shaping/SKILL.md) teaches how to shape a map: what belongs in the root node, when to branch versus append, and when to fan out.

Set your token first:

```bash
export MINDMAP_API_TOKEN="<your personal access token>"
```

## Hello world

Create a map, add a question, run it, and read the answer. Node content is sent as `messages`, a UIMessage array (`{ role, parts: [{ type: "text", text }] }`). With the MCP server, call the tools in order:

```jsonc
// 1. Create a map with a root node.
create_map   { "title": "Hello", "data": { "rootId": "root", "nodes": { "root": {
               "id": "root",
               "messages": [{ "role": "user", "parts": [{ "type": "text", "text": "Hello" }] }],
               "children": [] } } } }
//   -> { "id": "MAP_ID" }

// 2. Add a question under the root.
create_node  { "mapId": "MAP_ID", "nodeId": "q1", "parentId": "root", "nodeType": "prompt",
               "messages": [{ "role": "user", "parts": [{ "type": "text", "text": "Say hi in one word." }] }] }

// 3. Run it. The call waits until the answer is ready.
submit_node  { "mapId": "MAP_ID", "nodeId": "q1" }
//   -> { "nodeId": "q1", "status": "complete", "messages": [ ... ] }

// 4. Read it back.
get_node     { "mapId": "MAP_ID", "nodeId": "q1" }
```

The API also still accepts a legacy `text` field for node content, but `messages` is the canonical shape.

The skill at [`skills/mindmapio/SKILL.md`](skills/mindmapio/SKILL.md) shows the same flow as curl commands.

## Keep your token safe

- Never commit your token. Keep it in the plugin's token prompt, your MCP client config, or an environment variable.
- It is sent only as the `Authorization` header and is never logged. Config and error messages carry no secret.
- Treat it like a password. If it leaks, regenerate it in settings and the old one stops working right away.

## Layout

```
.claude-plugin/   plugin.json and the self-hosted marketplace manifest
.mcp.json         the plugin's connector: the stdio server below, token from userConfig
skills/           the agent skills, also what `npx skills add` installs
server/           the stdio MCP server (src, tests, and the vendored OpenAPI document)
SETUP.md          first-install instructions for Claude
```

The root `package.json` is the server's, so `npx -y github:MohGanji/mindmapio-mcp` still resolves: it builds `server/dist` and runs it.

## Develop

```bash
npm install
npm test        # vitest against a mocked HTTP layer, no live backend needed
npm run build   # tsc -> server/dist/
```

### Regenerating the tool list

Tool descriptions and annotations come from `server/spec/openapi.json`, a vendored mirror of the published [`https://mindmap.io/api/openapi.json`](https://mindmap.io/api/openapi.json). Refresh it with:

```bash
npm run sync:openapi
```

Drift is checkable in one line:

```bash
npm run sync:openapi && git diff --exit-code server/spec
```

It fetches the published document on purpose, never a local checkout of the API repo, which can hold unpushed edits that would ship a tool list nobody can reach. It refuses to write a document whose operations are missing their `x-mcp` annotations (`title`, `readOnlyHint`, `destructiveHint`), because a tool without them is a rejection criterion for Anthropic's directories, and leaves the vendored copy untouched in that case.

### The skill is held to the same document

`buildTools` joins the tool list to that document in both directions, and `server/test/skill-parity.test.ts` joins [`skills/mindmapio/SKILL.md`](skills/mindmapio/SKILL.md) to it the same way: every documented operation has to be named, called in a worked example, and taught with the query or header inputs and the operation-specific failures (a `409`, a `413`, a `429`) the document declares for it — and a section teaching an endpoint the document does not describe fails too. That is the third leg of [ADR 0029](https://github.com/MohGanji/mindmap/blob/main/docs/adr/0029-agent-discovery-surfaces.md)'s parity invariant, unenforced until the skill had quietly drifted to 15 of 17 operations.

Editing that skill is half a change: mindmap.io serves a mirror of it with a SHA-256 digest, so `marketing/scripts/sync-agent-skills.mjs` has to be re-run there once the edit is pushed here.

## License

[MIT](LICENSE)