# nodeland-mcp

**NodeLand is the persistent destination where agent output becomes an editable map** — not a one-shot Mermaid render that dies with the chat.

This MCP server talks to the [NodeLand](https://nodeland.io) Maps API. Agents emit `concepts` + `relations`; NodeLand stores the map, runs layout, and returns a URL the human can open, share, embed, and keep editing.

## Demo maps (open these)

Replace these with maps you create during a real agent session before publishing:

- [Example concept map](https://nodeland.io/maps/0b395e9a-23a0-4a1a-90d1-332f9fd3e832?presentationMode=true)
- Create your own with Claude/Cursor below, then paste the live URL here — the artifact *is* the demo.

<!-- Record 3 short GIFs (agent prompt → tool call → map in browser) into docs/ before npm publish:
![Create a map](docs/demo-create.gif)
![Add over time](docs/demo-add.gif)
![Open the link](docs/demo-open.gif)
-->

## What you get

| Tool | When to use |
|------|-------------|
| `create_map` | Turn a topic into a shareable map (returns `url` + `embedUrl`) |
| `add_to_map` | Keep writing into the same map across a conversation |
| `get_map` | Read concepts/relations summary (not raw Cytoscape JSON) |
| `list_maps` | Find an existing map id |

Resource: `nodeland://templates` — named layouts (`StandardMindMapTemplate`, `TonyBuzzanTemplate`, `Tree TD` / `Tree LR`, …).

**Maps are public by default** so the link works without login. Pass `isPublic: false` only when the user asks for private.

## 1. Get an API key (the real onboarding step)

1. Sign up / log in at [nodeland.io](https://nodeland.io)
2. Open **Settings → API Keys**
3. Generate a key with `maps:read` and `maps:write`
4. Copy it once — it is shown only at creation time

## 2. Install in your agent

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "nodeland": {
      "command": "npx",
      "args": ["-y", "nodeland-mcp"],
      "env": {
        "NODELAND_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add nodeland --env NODELAND_API_KEY=YOUR_API_KEY -- npx -y nodeland-mcp
```

### Cursor

Cursor Settings → MCP → add server:

```json
{
  "mcpServers": {
    "nodeland": {
      "command": "npx",
      "args": ["-y", "nodeland-mcp"],
      "env": {
        "NODELAND_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

Optional staging:

```json
"NODELAND_BASE_URL": "https://staging.nodeland.io"
```

## 3. Try it

Ask the agent:

> Map the central concepts of [topic], put a short markdown description on each node, and give me the NodeLand link.

Then open the URL in a private/incognito window — it should render without signing in.

## Config

| Env | Required | Default |
|-----|----------|---------|
| `NODELAND_API_KEY` | yes | — |
| `NODELAND_BASE_URL` | no | `https://nodeland.io` |

The key is never logged. Missing key fails fast with a readable message.

## Local development

```bash
git clone https://github.com/nodeland/nodeland-mcp.git
cd nodeland-mcp
npm install
npm run build
NODELAND_API_KEY=... npm start
```

Smoke test (creates a public map and fetches the URL without credentials):

```bash
NODELAND_API_KEY=... NODELAND_BASE_URL=https://staging.nodeland.io npm run smoke
```

Inspector:

```bash
npx @modelcontextprotocol/inspector npx nodeland-mcp
```

## License

MIT