Skip to main content
Glama
A-Quark2005

WhkerDB MCP Server

by A-Quark2005
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

WhkerDB MCP Server

npm version TypeScript MCP

讲了么（WhkerDB）的 MCP（Model Context Protocol）服务器实现，为 AI 助手和第三方应用提供讲了么共享 PDF 编辑器的完整功能访问能力。

✨ 特性

  • 🏠 房间管理 - 创建、加入、管理协作房间

  • 📝 笔记树操作 - 完整的文件树结构管理

  • 🎨 标注功能 - 支持文本、路径、图片等多种标注类型

  • 📄 PDF 处理 - 上传、查看和管理 PDF 文件

  • 🖼️ 图片管理 - 图片上传和列表功能

  • 🔄 实时同步 - 基于 Socket.IO 的实时数据同步

  • 🔌 多平台支持 - 支持 Claude Desktop、Claude Code、CodeX 等

📋 目录

🚀 安装

前置要求

  • Node.js >= 18

  • pnpm (推荐) 或 npm/yarn

  • 运行中的讲了么（WhkerDB）服务器或访问在线服务

安装步骤

# 克隆仓库
git clone https://github.com/A-Quark2005/whkerdb-mcp.git
cd whkerdb-mcp

# 安装依赖
pnpm install

# 构建项目
pnpm build

🎯 快速开始

命令行模式（stdio）

# 设置服务器地址（可选，默认 https://share.whkerdb.top）
export WHKERDB_SERVER_URL=https://share.whkerdb.top

# 启动 MCP 服务器
pnpm start

使用 MCP Inspector 测试

npx @modelcontextprotocol/inspector stdio node dist/index.js

🔌 集成指南

Claude Desktop

在 Claude Desktop 配置文件中添加以下配置：

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "whkerdb": {
      "command": "node",
      "args": ["/absolute/path/to/whkerdb-mcp/dist/index.js"],
      "env": {
        "WHKERDB_SERVER_URL": "https://share.whkerdb.top"
      }
    }
  }
}

Claude Code (CLI)

使用命令行添加项目级配置（配置会写入项目根目录的 .mcp.json）：

# Windows PowerShell
claude mcp add -s project whkerdb node C:\path\to\whkerdb-mcp\dist\index.js -e WHKERDB_SERVER_URL=https://share.whkerdb.top

# macOS/Linux
claude mcp add -s project whkerdb node /path/to/whkerdb-mcp/dist/index.js -e WHKERDB_SERVER_URL=https://share.whkerdb.top

CodeX (Codex CLI)

命令行方式：

# Windows PowerShell
codex mcp add whkerdb --env WHKERDB_SERVER_URL=https://share.whkerdb.top -- node C:\path\to\whkerdb-mcp\dist\index.js

# macOS/Linux
codex mcp add whkerdb --env WHKERDB_SERVER_URL=https://share.whkerdb.top -- node /path/to/whkerdb-mcp/dist/index.js

配置文件方式（~/.codex/config.toml）：

[mcp_servers.whkerdb]
command = "node"
args = ['/path/to/whkerdb-mcp/dist/index.js']

[mcp_servers.whkerdb.env]
WHKERDB_SERVER_URL = "https://share.whkerdb.top"

MCP Inspector 测试

使用 MCP Inspector 进行交互式测试和调试：

npx @modelcontextprotocol/inspector stdio node dist/index.js

📚 API 文档

工具列表

房间管理

工具

描述

whkerdb_create_room

创建新房间

whkerdb_join_room

加入房间（支持房间 ID 或邀请码）

whkerdb_get_room_info

获取房间信息

whkerdb_list_rooms

列出已加入的房间

whkerdb_export_snapshot

导出房间快照

whkerdb_leave_room

离开房间

笔记树操作

工具

描述

whkerdb_get_note_tree

获取笔记树结构

whkerdb_add_file

添加文件节点

whkerdb_add_page

添加页面节点

whkerdb_delete_node

删除节点

whkerdb_move_node

移动节点

whkerdb_update_node

更新节点属性

whkerdb_get_node

获取节点详情

标注对象

工具

描述

whkerdb_get_page_objects

获取页面对象

whkerdb_add_text

添加文本标注

whkerdb_add_path

添加路径（画笔/高亮笔）

whkerdb_add_image

添加图片

whkerdb_update_object

更新对象属性

whkerdb_delete_object

删除对象

PDF 操作

工具

描述

whkerdb_upload_pdf

上传 PDF 文件

whkerdb_list_pdfs

列出房间内 PDF

whkerdb_get_pdf_info

获取 PDF 信息

图片操作

工具

描述

whkerdb_upload_image

上传图片

whkerdb_list_images

列出房间内图片

资源 URI

说明：带 {} 的为资源模板（resources/templates/list）；加入房间后也可以通过 resources/list 获取当前房间的实际资源 URI。

URI

描述

whkerdb://rooms

房间列表

whkerdb://rooms/{roomId}

房间详情

whkerdb://rooms/{roomId}/tree

笔记树结构

whkerdb://rooms/{roomId}/pages/{nodeId}

页面内容

whkerdb://pdfs/{pdfId}/info

PDF 信息

💡 使用示例

示例 1: 创建房间并添加内容

// 1. 创建房间
whkerdb_create_room({ name: "我的项目" })

// 2. 加入房间
whkerdb_join_room({ roomId: "room-id" })

// 3. 创建文件节点
whkerdb_add_file({ 
  parentId: "root", 
  name: "文档.pdf" 
})

// 4. 添加页面
whkerdb_add_page({ 
  parentId: "file-id", 
  name: "第1页" 
})

// 5. 添加文本标注
whkerdb_add_text({
  pageId: "page-id",
  content: "这是重要注释",
  x: 100,
  y: 200
})

示例 2: 上传 PDF 并标注

// 1. 加入房间
whkerdb_join_room({ roomId: "room-id" })

// 2. 上传 PDF（自动创建节点）
whkerdb_upload_pdf({
  filePath: "/path/to/document.pdf",
  name: "文档.pdf"
})

// 3. 查看树结构
whkerdb_get_note_tree({ roomId: "room-id" })

// 4. 在页面上添加标注
whkerdb_add_text({
  pageId: "page-id",
  content: "需要重点注意",
  x: 150,
  y: 300
})

🛠️ 开发

项目结构

whkerdb-mcp/
├── src/
│   ├── client/          # 讲了么MCP客户端实现
│   ├── resources/       # MCP 资源定义
│   ├── tools/           # MCP 工具实现
│   │   ├── roomTools.ts
│   │   ├── treeTools.ts
│   │   ├── objectTools.ts
│   │   ├── pdfTools.ts
│   │   └── imageTools.ts
│   ├── server.ts        # MCP 服务器配置
│   └── index.ts         # 入口文件
├── dist/                # 编译输出
├── bin/                 # 可执行文件
└── package.json

开发命令

# 开发模式（监听文件变化）
pnpm dev

# 构建项目
pnpm build

# 启动服务器
pnpm start

# 启动 stdio 模式
pnpm start:stdio

技术栈

  • TypeScript - 类型安全

  • @modelcontextprotocol/sdk - MCP 协议实现

  • Socket.IO Client - 实时通信

  • tsup - 构建工具

⚙️ 环境变量

变量

描述

默认值

WHKERDB_SERVER_URL

讲了么（WhkerDB）服务器地址

https://share.whkerdb.top

⚠️ 注意事项

  1. 服务器要求: 使用工具前需要确保讲了么（WhkerDB）服务器可访问（默认使用在线服务 https://share.whkerdb.top，也可配置本地服务器）

  2. 房间上下文: 大部分工具需要先加入房间（使用 whkerdb_join_room）

  3. 文件上传: 支持本地文件路径或 Base64 编码

  4. 实时同步: 所有操作会通过 Socket.IO 实时同步到其他连接的客户端

  5. 路径配置: 在配置文件中使用绝对路径，避免相对路径问题

🤝 贡献

欢迎提交 Issue 和 Pull Request！

🔗 相关链接

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/A-Quark2005/whkerdb-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server