# Wolai MCP Server 🐺

**English** | [中文](./README_CN.md)

[![PyPI](https://img.shields.io/npm/v/wolai-mcp)](https://www.npmjs.com/package/wolai-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Connect AI agents to your [Wolai](https://www.wolai.com) knowledge base** via the Model Context Protocol (MCP).

Read, write, search, and navigate your Wolai pages — all from Claude, Cursor, OpenCode, or any MCP-compatible AI agent.

---

## ✨ Features

| Category | Tools | Description |
|----------|-------|-------------|
| 📖 Read | `get_block`, `get_block_children`, `get_breadcrumbs` | Read pages, list children, navigate hierarchy |
| ✏️ Write | `create_block`, `update_block`, `delete_block` | Create, update, and delete blocks |
| 📊 Database | `get_database`, `create_database_row`, `query_database_rows` | Query and modify database tables |
| 🔍 Search | `search_pages` | Fuzzy title search across page tree |
| 📎 Upload | `upload_file` | Upload file attachments to pages |
| 🔑 Token | `create_token`, `refresh_token` | Manage API authentication tokens |
| ⚙️ Config | `get_config`, `update_config` | Runtime configuration management |

**16 tools total** — covering read, write, database, search, upload, token, and configuration.

---

## 🚀 Quick Start

### Install

```bash
npm install -g wolai-mcp
# or
npx wolai-mcp
```

### Get Credentials

1. Go to [Wolai Developer Console](https://www.wolai.com/dev)
2. Create an application → get **App ID** and **App Secret**
3. Find the **Root Page ID** from your Wolai page URL (the part after `wolai.com/`)

### Interactive Setup

```bash
npx wolai-mcp init
```

Follow the prompts to enter your credentials. They will be saved to `~/.wolai-mcp/config.json`.

### Environment Variables

Alternatively, set environment variables:

```bash
export WOLAI_APP_ID="your_app_id"
export WOLAI_APP_SECRET="your_app_secret"
export WOLAI_ROOT_ID="your_root_page_id"  # optional, for search
```

---

## 📋 Platform Configuration

### OpenCode

Add to your `opencode.json`:

```json
{
  "mcp": {
    "wolai-mcp": {
      "command": "npx",
      "args": ["wolai-mcp"],
      "env": {
        "WOLAI_APP_ID": "your_app_id",
        "WOLAI_APP_SECRET": "your_app_secret",
        "WOLAI_ROOT_ID": "your_root_page_id"
      }
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "wolai-mcp": {
      "command": "npx",
      "args": ["wolai-mcp"],
      "env": {
        "WOLAI_APP_ID": "your_app_id",
        "WOLAI_APP_SECRET": "your_app_secret",
        "WOLAI_ROOT_ID": "your_root_page_id"
      }
    }
  }
}
```

### Cursor / CherryStudio / Other MCP Clients

```json
{
  "wolai-mcp": {
    "command": "npx",
    "args": ["wolai-mcp"],
    "env": {
      "WOLAI_APP_ID": "your_app_id",
      "WOLAI_APP_SECRET": "your_app_secret",
      "WOLAI_ROOT_ID": "your_root_page_id"
    }
  }
}
```

---

## 💡 Usage Examples

Once configured, ask your AI agent:

- *"读取我 Wolai 知识库的首页内容"*
- *"搜索标题包含'项目计划'的页面"*
- *"在指定页面下创建一个新页面叫'会议纪要'"*
- *"往指定页面添加一段代码"*
- *"查询我的数据表格内容"*
- *"显示当前 Wolai 配置状态"*

---

## 🔧 Tool Reference

### Token Management

#### `create_token`
Create a new API token.
- `app_id` (string): Wolai Application ID
- `app_secret` (string): Wolai Application Secret

#### `refresh_token`
Refresh the current API token.

### Block Operations

#### `get_block`
Get details of a specific block or page.
- `id` (string): Block ID or Page ID

#### `get_block_children`
Get child blocks of a given block or page.
- `id` (string): Parent block ID
- `cursor` (string, optional): Pagination cursor
- `page_size` (number, optional): Results per page (default: 100)

#### `create_block`
Create a new block under a parent.
- `parent_id` (string): Parent block or page ID
- `type` (string): Block type (text, heading, bullet, code, etc.)
- `content` (string, optional): Block content text
- `text_alignment` (string, optional): left, center, or right
- `level` (number, optional): Heading level 1-3
- `language` (string, optional): Code language for code blocks

#### `update_block`
Update an existing block.
- `id` (string): Block ID
- `content` (string, optional): New content
- `text_alignment` (string, optional): New alignment
- `level` (number, optional): New heading level

#### `delete_block`
Delete a block.
- `id` (string): Block ID

#### `get_breadcrumbs`
Get the breadcrumb path for a block.
- `id` (string): Block ID

### Database Operations

#### `get_database`
Get database structure and data.
- `id` (string): Database ID

#### `create_database_row`
Add rows to a database.
- `database_id` (string): Database ID
- `cells` (string): JSON string of cell data

#### `query_database_rows`
Query database rows with pagination.
- `database_id` (string): Database ID
- `cursor` (string, optional): Pagination cursor
- `page_size` (number, optional): Results per page

### Search

#### `search_pages`
Search pages by title keyword.
- `query` (string): Search keyword
- `root_id` (string, optional): Root page to start search from

### Upload

#### `upload_file`
Upload a file attachment.
- `parent_id` (string): Parent block or page ID
- `file_path` (string): Local file path

### Configuration

#### `get_config`
Get current configuration (hides secret).

#### `update_config`
Update configuration.
- `app_id` (string, optional): New App ID
- `app_secret` (string, optional): New App Secret
- `root_id` (string, optional): New root page ID

---

## 📄 License

MIT License — see [LICENSE](./LICENSE) for details.