# WhkerDB MCP Server

[![npm version](https://img.shields.io/npm/v/@whkerdb/mcp.svg)](https://www.npmjs.com/package/@whkerdb/mcp)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-1.0.0-green.svg)](https://modelcontextprotocol.io/)

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

## ✨ 特性

- 🏠 **房间管理** - 创建、加入、管理协作房间
- 📝 **笔记树操作** - 完整的文件树结构管理
- 🎨 **标注功能** - 支持文本、路径、图片等多种标注类型
- 📄 **PDF 处理** - 上传、查看和管理 PDF 文件
- 🖼️ **图片管理** - 图片上传和列表功能
- 🔄 **实时同步** - 基于 Socket.IO 的实时数据同步
- 🔌 **多平台支持** - 支持 Claude Desktop、Claude Code、CodeX 等

## 📋 目录

- [WhkerDB MCP Server](#whkerdb-mcp-server)
  - [✨ 特性](#-特性)
  - [📋 目录](#-目录)
  - [🚀 安装](#-安装)
    - [前置要求](#前置要求)
    - [安装步骤](#安装步骤)
  - [🎯 快速开始](#-快速开始)
    - [命令行模式（stdio）](#命令行模式stdio)
    - [使用 MCP Inspector 测试](#使用-mcp-inspector-测试)
  - [🔌 集成指南](#-集成指南)
    - [Claude Desktop](#claude-desktop)
    - [Claude Code (CLI)](#claude-code-cli)
    - [CodeX (Codex CLI)](#codex-codex-cli)
    - [MCP Inspector 测试](#mcp-inspector-测试)
  - [📚 API 文档](#-api-文档)
    - [工具列表](#工具列表)
      - [房间管理](#房间管理)
      - [笔记树操作](#笔记树操作)
      - [标注对象](#标注对象)
      - [PDF 操作](#pdf-操作)
      - [图片操作](#图片操作)
    - [资源 URI](#资源-uri)
  - [💡 使用示例](#-使用示例)
    - [示例 1: 创建房间并添加内容](#示例-1-创建房间并添加内容)
    - [示例 2: 上传 PDF 并标注](#示例-2-上传-pdf-并标注)
  - [🛠️ 开发](#️-开发)
    - [项目结构](#项目结构)
    - [开发命令](#开发命令)
    - [技术栈](#技术栈)
  - [⚙️ 环境变量](#️-环境变量)
  - [⚠️ 注意事项](#️-注意事项)
  - [🤝 贡献](#-贡献)
  - [🔗 相关链接](#-相关链接)

## 🚀 安装

### 前置要求

- Node.js >= 18
- pnpm (推荐) 或 npm/yarn
- 运行中的讲了么（WhkerDB）服务器或访问在线服务

### 安装步骤

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

# 安装依赖
pnpm install

# 构建项目
pnpm build
```

## 🎯 快速开始

### 命令行模式（stdio）

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

# 启动 MCP 服务器
pnpm start
```

### 使用 MCP Inspector 测试

```bash
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`

```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`）：

```bash
# 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)

**命令行方式：**

```bash
# 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`）：

```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 进行交互式测试和调试：

```bash
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: 创建房间并添加内容

```javascript
// 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 并标注

```javascript
// 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
```

### 开发命令

```bash
# 开发模式（监听文件变化）
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！

## 🔗 相关链接

- [Model Context Protocol 文档](https://modelcontextprotocol.io/)
- [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)