# kiuwo-mcp

A Model Context Protocol (MCP) server exposing Kiuwo's mind map APIs as MCP tools.

### Introduction

This MCP server lets AI clients (e.g., Cursor) create, search, expand, and fetch mind maps via Kiuwo's HTTP APIs. The server communicates over stdio and requires an API key.

### Installation

1. Ensure Node.js 18+ and Yarn are installed.
2. Install dependencies:

```bash
yarn install
```

3. Build the server:

```bash
yarn build
```

### Usage

Set the required environment variable and run the server binary:

```bash
export KIUWO_API_KEY=<api-key>
export KIUWO_BASE_URL=${KIUWO_BASE_URL:-https://kiuwo.com}
export KIUWO_TIMEOUT_MS=${KIUWO_TIMEOUT_MS:-30000}
node build/index.js
```

Available tools:

- `create_mind_map` (input: `{ text: string }`)
- `search_mind_maps` (input: `{ query: string }`)
- `expand_node` (input: `{ mindMapId: string, nodeName: string }`)
- `get_mind_map` (input: `{ mindMapId: string }`)

All responses follow the APIResponse shape described in `documentation/api.md`.

### How to use the MCP server with Cursor

Add a server entry to Cursor's MCP config (e.g., `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "kiuwo": {
      "command": "node",
      "args": ["/absolute/path/to/kiuwo-mcp/build/index.js"],
      "env": {
        "KIUWO_API_KEY": "${KIUWO_API_KEY}",
        "KIUWO_BASE_URL": "https://kiuwo.com",
        "KIUWO_TIMEOUT_MS": "90000"
      }
    }
  }
}
```

### API reference

The server wraps Kiuwo HTTP APIs defined in `documentation/api.md` and expects a header `X-API-key` set via the environment.

Environment variables:

- `KIUWO_API_KEY` (required)
- `KIUWO_BASE_URL` (default: `https://kiuwo.com`)
- `KIUWO_TIMEOUT_MS` (default: `90000`)