Wolai MCP 服务器

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

简体中文 | English

Vibe Coding 声明

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

功能特性

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

安装

通过 npm 安装(推荐)

npm install -g wolai-mcp

从源码安装

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

配置

环境变量

在项目根目录创建 .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 开放平台
2. 创建新应用
3. 复制你的 App ID 和 App Secret

MCP 客户端配置

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

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

或者使用全局安装:

{
  "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 | 进行中 | 中 |

开发

运行测试

npm test

本地开发

npm run dev

构建

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 获取更多行

大型数据库使用示例:

// 获取前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 文件

相关链接

• Wolai 开放平台
• Model Context Protocol
• GitHub 仓库

路线图

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