# Wolai MCP 服务器

一个用于访问 Wolai 工作空间内容的 Model Context Protocol (MCP) 服务器,让 AI 助手能够读取并交互你的 Wolai 数据库和块。

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

简体中文 | [English](README.en.md)

## Vibe Coding 声明

本项目采用 vibe coding 工作流，由人与 AI 协同共创完成，强调沉浸式节奏与即时反馈，而非完全"古法手敲"模式。代码、文档与测试均在这种协作环境下迭代生成，请在贡献或审阅时充分考虑这一创作背景。

## 功能特性

- 🔐 **身份认证**: 自动管理 Wolai Open API Token
- 📊 **数据库访问**: 读取数据库结构、行数据,并转换为 Markdown 表格
- 📝 **块操作**: 访问块及其子节点,支持层级导航
- 📄 **Markdown 导出**: 将 Wolai 内容转换为 Obsidian 友好的 Markdown 格式
- ✍️ **安全写入**: 通过提示与文件落地机制提供创建块/插入行的写操作
- 🔄 **分页支持**: 使用游标分页处理大型数据集
- 🛠️ **MCP 工具**: 提供 7 个常用 Wolai 操作工具
- 📦 **MCP 资源**: 2 个资源模板,支持基于 URI 的直接访问

## 安装

### 通过 npm 安装(推荐)

```bash
npm install -g wolai-mcp
```

### 从源码安装

```bash
git clone https://github.com/yourusername/wolai-mcp.git
cd wolai-mcp
npm install
npm run build
```

## 配置

### 环境变量

在项目根目录创建 `.env` 文件:

```env
WOLAI_APP_ID=你的应用ID
WOLAI_APP_SECRET=你的应用密钥
WOLAI_ROOT_BLOCK_ID=你的根块ID(可选，用于默认操作)
WOLAI_API_BASE_URL=https://openapi.wolai.com/v1(可选)
```

获取 Wolai API 凭证:
1. 访问 [Wolai 开放平台](https://www.wolai.com/wolai/eseF6yB4VzfwxM3M6xWfb2)
2. 创建新应用
3. 复制你的 App ID 和 App Secret

### MCP 客户端配置

添加到你的 MCP 客户端配置中(例如 Claude Desktop):

```json
{
  "mcpServers": {
    "wolai": {
      "command": "npx",
      "args": ["wolai-mcp"],
      "env": {
        "WOLAI_APP_ID": "你的应用ID",
        "WOLAI_APP_SECRET": "你的应用密钥",
        "WOLAI_ROOT_BLOCK_ID": "你的根块ID"
      }
    }
  }
}
```

或者使用全局安装:

```json
{
  "mcpServers": {
    "wolai": {
      "command": "node",
      "args": ["/全局路径/node_modules/wolai-mcp/dist/index.js"],
      "env": {
        "WOLAI_APP_ID": "你的应用ID",
        "WOLAI_APP_SECRET": "你的应用密钥"
      }
    }
  }
}
```

## MCP 工具

| 工具 | 描述 | 参数 |
| --- | --- | --- |
| `wolai_refresh_token` | 刷新 Wolai 访问令牌 | 无 |
| `wolai_list_databases` | 列出父块下的数据库 | `parentBlockId` (可选) |
| `wolai_get_database` | 获取数据库结构与行数据，大表自动写入本地文件 | `databaseId`, `sampleSize`, `includeMeta`, `outputMode` |
| `wolai_get_block` | 获取块详情和 JSON 快照 | `blockId` |
| `wolai_list_block_children` | 列出块的子节点 | `blockId`, `page_size`, `start_cursor`, `includeTypes` |
| `wolai_create_block` | 在父块下创建新块（写操作） | `parentId`, `block`, `extra` |
| `wolai_insert_database_row` | 向数据库插入一行或多行（写操作） | `databaseId`, `row`/`rows`, `extra` |

> ⚠️ **写操作提示**：调用 `wolai_create_block` 与 `wolai_insert_database_row` 会直接修改 Wolai 数据。请先在小范围验证 payload，并确保 MCP 应用已获得目标页面/数据库的权限。

## MCP 资源

| 资源 URI | 描述 |
| --- | --- |
| `wolai://database/{databaseId}` | 访问数据库结构和行数据 |
| `wolai://block/{blockId}` | 访问块内容和元数据 |

## 使用示例

### 在 Claude Desktop 中使用

配置完成后,你可以自然地与 Wolai 工作空间交互:

```
用户: 显示我工作空间中的所有数据库
Claude: [使用 wolai_list_databases 工具]

用户: 获取数据库 XYZ123 的内容
Claude: [使用 wolai://database/XYZ123 资源]

用户: 列出块 ABC456 的子节点
Claude: [使用 wolai_list_block_children 工具]
```

### 输出格式

每个工具返回两种格式:
1. **JSON**: 包含完整信息的结构化数据
2. **Markdown**: 格式化的表格,可直接复制到 Obsidian/Notion

示例输出:
````
```json
{
  "schema": {...},
  "rows": [...]
}
```

# 数据库: 项目任务

| ID | 标题 | 状态 | 优先级 |
| --- | --- | --- | --- |
| 1 | 任务 1 | 已完成 | 高 |
| 2 | 任务 2 | 进行中 | 中 |
````

## 开发

### 运行测试

```bash
npm test
```

### 本地开发

```bash
npm run dev
```

### 构建

```bash
npm run build
```

## 项目结构

```
wolai-mcp/
├── src/
│   ├── lib/
│   │   ├── wolaiClient.ts          # Wolai API 客户端
│   │   ├── runtimeConfig.ts        # 配置管理
│   │   └── renderers/
│   │       └── markdownRenderer.ts # Markdown 转换
│   ├── server/
│   │   ├── mcpServer.ts            # MCP 服务器设置
│   │   ├── databaseResource.ts     # 数据库操作
│   │   └── blockResource.ts        # 块操作
│   └── index.ts                    # 入口文件
├── tests/                          # 单元测试
├── docs/                           # 文档
└── dist/                           # 编译输出
```

## 故障排除

### "Missing WOLAI_APP_ID or WOLAI_APP_SECRET"

确保你的环境变量在 MCP 客户端配置中正确设置。

### "Path matcher not found" 错误

确保使用最新版本(已修复数据库行端点问题)。更新后重启 MCP 客户端。

### Token 过期

遇到认证错误时,使用 `wolai_refresh_token` 工具手动刷新。

### 性能优化和大数据集处理

插件包含多种性能优化来处理大型数据库:

- **自动分页**: 大型数据集自动分页(默认每页100行)
- **超时保护**: 30秒超时防止请求卡死
- **智能采样**: 使用 `sampleSize` 参数预览大型数据库
- **游标支持**: 使用响应中的 `cursor` 获取更多行

大型数据库使用示例:
```javascript
// 获取前50行
wolai_get_database({ databaseId: "xxx", limit: 50 })

// 使用游标获���下一页
wolai_get_database({ databaseId: "xxx", limit: 50, cursor: "来自上次响应的游标" })

// 使用采样预览
wolai_get_database({ databaseId: "xxx", sampleSize: 10 })
```

## 贡献

欢迎贡献!请随时提交 Pull Request。

## 许可证

MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

## 相关链接

- [Wolai 开放平台](https://www.wolai.com/wolai/eseF6yB4VzfwxM3M6xWfb2)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [GitHub 仓库](https://github.com/yourusername/wolai-mcp)

## 路线图

- [ ] CLI 命令行工具
- [ ] 批量导出多个数据库
- [ ] 附件下载支持
- [ ] 缓存层以减少 API 调用
- [ ] 速率限制策略