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

New MCP Servers

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