WorksHub MCP Service

Model Context Protocol (MCP) 服务，让 AI Agent 能够雇佣真人工作者完成现实任务

项目简介

WorksHub MCP 是一个基于 Model Context Protocol 的服务，封装了 WorksHub 平台的核心 API 接口。通过此 MCP 服务，AI Agent（如 Claude、ChatGPT）可以：

• 🔍 浏览和搜索工作者
• 💼 发布和管理悬赏任务（Bounty）
• 💬 与工作者对话沟通
• ✅ 接受申请并管理任务
• 🛠️ 查询技能列表

已实现 17 个工具，覆盖认证管理、技能查询、工作者管理、悬赏任务、对话管理 5 大功能模块。

首次使用可通过手机号验证码获取 API Key，无需预先配置。

技术栈

• Node.js >= 18.0
• TypeScript >= 5.0
• 通信协议: JSON-RPC 2.0
• 通信模式: stdio（标准输入/输出）
• 依赖:
  • @modelcontextprotocol/sdk - MCP SDK
  • axios - HTTP 客户端

快速开始

方式1: 全局安装（推荐）

# 安装
npm install -g workshub-mcp

# 运行（需要先设置环境变量）
export WORKSHUB_API_URL="https://workshub.ai/mcp" # 该环境变量不是必须（以下相同）
export WORKSHUB_API_KEY="your_api_key_here"
workshub-mcp

方式2: 使用 npx（无需安装）

# 直接运行
WORKSHUB_API_URL="https://workshub.ai/mcp" \
WORKSHUB_API_KEY="your_api_key" \
npx -y workshub-mcp

环境变量配置

# macOS/Linux
export WORKSHUB_API_URL="https://workshub.ai/mcp"
export WORKSHUB_API_KEY="your_api_key_here"

# Windows PowerShell
$env:WORKSHUB_API_URL = "https://workshub.ai/mcp"
$env:WORKSHUB_API_KEY = "your_api_key_here"

🔐 获取 API Key

WorksHub MCP 支持两种方式获取 API Key：

方式 1：通过 MCP 工具获取（首次使用推荐）

无需预先配置，直接使用本技能的认证工具获取：

1. 发送验证码（无需 API Key）✅

{
  "name": "send_code",
  "arguments": {
    "phone_number": "13800138000"
  }
}

2. 登录获取 API Key（无需 API Key）✅

{
  "name": "login",
  "arguments": {
    "phone_number": "13800138000",
    "code": "123456"
  }
}

返回:

{
  "success": true,
  "data": {
    "api_key": "wk_xxxxx",
    "user": { ... }
  }
}

3. 配置环境变量

获取到 api_key 后，配置到环境变量：

export WORKSHUB_API_KEY="获取到的api_key"

方式 2：从 WorksHub 平台获取

访问 https://workshub.ai 登录后，在用户中心创建 API Key。

注意事项

• send_code 和 login 工具不需要 API Key 即可调用
• 验证码有效期为 5 分钟
• 每个手机号每分钟最多发送 1 次验证码

在 AI IDE 中使用

首次使用提示

如果这是你第一次使用，可以暂时不配置 WORKSHUB_API_KEY，直接使用 MCP 工具 send_code 和 login 获取 API Key，然后再配置到环境变量中。

Cursor 配置

编辑 ~/.cursor/mcp.json:

使用全局安装：

{
  "mcpServers": {
    "workshub": {
      "command": "workshub-mcp",
      "env": {
        "WORKSHUB_API_URL": "https://workshub.ai/mcp",
        "WORKSHUB_API_KEY": "your_api_key_here"
      }
    }
  }
}

使用 npx（无需安装）：

{
  "mcpServers": {
    "workshub": {
      "command": "npx",
      "args": ["-y", "workshub-mcp"],
      "env": {
        "WORKSHUB_API_URL": "https://workshub.ai/mcp",
        "WORKSHUB_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Desktop 配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

使用全局安装：

{
  "mcpServers": {
    "workshub": {
      "command": "workshub-mcp",
      "env": {
        "WORKSHUB_API_URL": "https://workshub.ai/mcp",
        "WORKSHUB_API_KEY": "your_api_key_here"
      }
    }
  }
}

使用 npx（推荐，无需安装）：

{
  "mcpServers": {
    "workshub": {
      "command": "npx",
      "args": ["-y", "workshub-mcp"],
      "env": {
        "WORKSHUB_API_URL": "https://workshub.ai/mcp",
        "WORKSHUB_API_KEY": "your_api_key_here"
      }
    }
  }
}

完整工具列表（17个）

📊 统计

| 模块 | 工具数量 | |------|---------| | 认证管理 | 2 | | 技能管理 | 1 | | 工作者管理 | 3 | | 悬赏任务管理 | 6 | | 对话管理 | 5 | | 总计 | 17 |

🔧 工具详细说明

0. 认证管理（2个工具）

⚠️ 这两个工具不需要 API Key 即可调用，用于首次获取 API Key

send_code

功能: 发送手机验证码

参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | phone_number | string | 是 | 手机号 |

返回: { success, data }

login

功能: 使用手机号和验证码登录，返回 API Key

参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | phone_number | string | 是 | 手机号 | | code | string | 是 | 验证码 |

返回: { success, data: { api_key, user } }

1. 技能管理（1个工具）

🔧 工具详细说明

1. 技能管理（1个工具）

get_skills

功能: 获取技能列表，支持分类和关键词搜索

参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | category | string | 否 | 技能分类筛选 | | keyword | string | 否 | 关键词搜索 |

使用示例:

// 获取所有技能
get_skills({})

// 按分类筛选
get_skills({ category: "编程语言" })

// 关键词搜索
get_skills({ keyword: "React" })

2. 工作者管理（3个工具）

get_workers

功能: 获取工作者列表，支持筛选和分页

参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | skills | string | 否 | 技能筛选 | | location | string | 否 | 地理位置筛选 | | page | number | 否 | 页码（默认1） | | pageSize | number | 否 | 每页数量（默认20） |

get_worker_detail

功能: 获取指定工作者的详细信息

参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | workerId | string | 是 | 工作者ID |

get_worker_qrcode

功能: 获取并显示指定工作者的收款二维码图片

参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | workerId | string | 是 | 工作者ID（如 bc4YVt） |

说明: 支持微信支付和支付宝支付，优先返回微信支付二维码

3. 悬赏任务管理（6个工具）

get_bounties

功能: 获取悬赏任务列表

参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | status | string | 否 | 任务状态筛选 | | skills | string | 否 | 技能筛选 | | page | number | 否 | 页码 | | pageSize | number | 否 | 每页数量 |

create_bounty

功能: 创建悬赏任务

参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | title | string | 是 | 任务标题 | | description | string | 是 | 任务描述 | | budget | number | 是 | 预算金额 | | priceType | number | 是 | 1=固定价格, 2=按小时 | | skills | string | 是 | 所需技能（逗号分隔） | | deadline | string | 否 | 截止日期（yyyy-MM-dd） |

使用示例:

create_bounty({
  title: "开发React网站",
  description: "需要开发一个响应式网站",
  budget: 5000,
  priceType: 1,
  skills: "React,TypeScript,Tailwind CSS",
  deadline: "2026-02-31"
})

get_bounty_detail

功能: 获取悬赏任务详情

参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | bountyId | string | 是 | 悬赏任务ID |

cancel_bounty

功能: 取消悬赏任务

参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | bountyId | string | 是 | 悬赏任务ID |

get_bounty_applications

功能: 获取悬赏任务的申请列表

参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | bountyId | string | 是 | 悬赏任务ID |

accept_bounty_application

功能: 接受某个工作者的申请

参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | bountyId | string | 是 | 悬赏任务ID | | applicationId | string | 是 | 申请ID |

4. 对话管理（4个工具）

get_conversations

功能: 获取所有对话列表

参数: 无

get_conversation_detail

功能: 获取对话详情

参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | conversationId | string | 是 | 对话ID |

get_conversation_messages

功能: 获取对话的消息列表

参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | conversationId | string | 是 | 对话ID | | page | number | 否 | 页码 | | pageSize | number | 否 | 每页数量 |

send_message

功能: 发送消息

参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | conversationId | string | 是 | 对话ID | | content | string | 是 | 消息内容 | | messageType | number | 否 | 1=文本, 2=图片, 3=文件 |

使用示例:

send_message({
  conversationId: "conv_123",
  content: "您好，我对这个任务很感兴趣",
  messageType: 1
})

开发指南

本地开发

# 克隆项目
git clone <repository-url>
cd mcp

# 安装依赖
npm install

# 编译
npm run build

# 运行
npm start

项目结构

src/
├── index.ts                    # MCP 服务入口
├── tools/                      # 业务工具层
│   ├── skill.ts               # 技能管理（1个工具）
│   ├── worker.ts              # 工作者管理（3个工具）
│   ├── bounty.ts              # 悬赏任务管理（6个工具）
│   └── conversation.ts        # 对话管理（4个工具）
├── utils/                      # 基础设施层
│   ├── http-client.ts         # HTTP 客户端封装
│   └── validator.ts           # 参数校验器
└── types/                      # 类型定义
    └── index.ts               # TypeScript 类型

测试

# 方法1：直接运行
node dist/index.js

# 方法2：使用 MCP Inspector（推荐）
npx @modelcontextprotocol/inspector node dist/index.js

认证方式

所有 API 请求需要在 HTTP Header 中携带 API Key：

X-API-Key: your_api_key_here

或使用 Bearer Token：

Authorization: Bearer your_api_key_here

响应格式

所有工具返回统一的 JSON 格式：

成功响应:

{
  "success": true,
  "data": { ... }
}

错误响应:

{
  "success": false,
  "error": "错误描述"
}

典型工作流程

🔄 工作流程图

以下是 WorksHub MCP 工具的典型使用流程和依赖关系：

流程1：发布任务并雇佣工作者（完整流程）

1️⃣ 准备阶段
   get_skills            # 查看可用技能（可选，建议）
        ↓
2️⃣ 创建任务
   create_bounty         # 创建悬赏任务（必需）
        ↓
3️⃣ 审核申请
   get_bounty_applications   # 获取申请列表（必需）
        ↓
   get_worker_detail     # 查看申请者详情（建议）
        ↓
4️⃣ 确定工作者
   accept_bounty_application # 接受申请（必需，不可逆）
        ↓
5️⃣ 开始协作
   start_conversation    # 开始对话（建议）
        ↓
   send_message          # 沟通任务细节（建议）
        ↓
   get_worker_qrcode     # 获取收款码支付（可选）

流程2：搜索并联系工作者（主动招募）

1️⃣ 搜索工作者
   get_workers           # 按技能/地理位置筛选（必需）
        ↓
2️⃣ 了解详情
   get_worker_detail     # 查看工作者详细信息（建议）
        ↓
3️⃣ 建立联系
   start_conversation    # 发起对话（必需）
        ↓
   send_message          # 咨询可用性和报价（必需）
        ↓
4️⃣ 确定合作
   create_bounty         # 为该工作者创建专属任务（可选）
        或
   get_worker_qrcode     # 直接支付报酬（可选）

流程3：管理对话和任务

📋 查看任务
   get_bounties          # 查看所有任务
        ↓
   get_bounty_detail     # 查看任务详情
        ↓
   cancel_bounty         # 取消任务（如需要）

💬 管理对话
   get_conversations     # 查看所有对话
        ↓
   get_conversation_messages  # 查看聊天记录
        ↓
   send_message          # 发送新消息

📊 工具依赖关系表

| 工具 | 前置条件 | 后续操作 | 是否可逆 | |------|----------|----------|----------| | get_skills | 无 | create_bounty | ✅ 无影响 | | get_workers | 无 | get_worker_detail, start_conversation | ✅ 无影响 | | get_worker_detail | workerId | start_conversation, get_worker_qrcode | ✅ 无影响 | | get_worker_qrcode | workerId | （支付操作） | ✅ 无影响 | | create_bounty | API Key（写权限） | get_bounty_applications, cancel_bounty | ⚠️ 创建后可取消 | | get_bounties | 无 | get_bounty_detail | ✅ 无影响 | | get_bounty_detail | bountyId | get_bounty_applications, cancel_bounty | ✅ 无影响 | | cancel_bounty | bountyId, 任务状态="招募中" | 无 | ❌ 不可逆 | | get_bounty_applications | bountyId | accept_bounty_application, get_worker_detail | ✅ 无影响 | | accept_bounty_application | bountyId, applicationId | start_conversation, send_message | ❌ 不可逆 | | get_conversations | 无 | get_conversation_messages, send_message | ✅ 无影响 | | start_conversation | workerId | send_message, get_conversation_messages | ✅ 无影响 | | get_conversation_messages | conversationId | send_message | ✅ 无影响 | | send_message | conversationId | get_conversation_messages | ⚠️ 消息不可撤回 |

⚠️ 关键注意事项

1. 不可逆操作：

   • accept_bounty_application — 接受申请后无法撤回，其他申请会被自动拒绝
   • cancel_bounty — 取消任务后无法恢复
   • send_message — 消息发送后无法撤回或编辑

2. 前置条件：

   • 所有写操作（create_bounty, cancel_bounty, accept_bounty_application, start_conversation, send_message）都需要配置 WORKSHUB_API_KEY 且具有写权限
   • accept_bounty_application 必须先调用 get_bounty_applications 获取申请列表
   • send_message 必须先有对话（通过 start_conversation 创建）

3. 建议的操作顺序：

   • 创建任务前建议先调用 get_skills 查看可用技能
   • 接受申请前建议先调用 get_worker_detail 了解申请者详情
   • 接受申请后建议立即调用 start_conversation 与工作者沟通

完整使用场景示例

场景1：AI Agent 发布任务并雇佣工作者

// 1. 创建悬赏任务
const bounty = await create_bounty({
  title: "开发 React 网站",
  description: "需要开发一个电商网站",
  budget: 10000,
  priceType: 1,
  skills: "React,TypeScript,Node.js"
});

// 2. 查看申请列表
const applications = await get_bounty_applications({
  bountyId: bounty.data.id
});

// 3. 查看申请者详情
const worker = await get_worker_detail({
  workerId: applications.data[0].workerId
});

// 4. 接受申请
await accept_bounty_application({
  bountyId: bounty.data.id,
  applicationId: applications.data[0].id
});

// 5. 开始对话
await send_message({
  conversationId: "conv_xxx",
  content: "您好，任务已接受，请开始工作"
});

场景2：查找合适的工作者

// 1. 搜索工作者
const workers = await get_workers({
  skills: "React,TypeScript",
  location: "北京"
});

// 2. 查看工作者详情
const workerDetail = await get_worker_detail({
  workerId: workers.data[0].id
});

// 3. 发起对话
await send_message({
  conversationId: "conv_xxx",
  content: "您好，我有一个项目想咨询"
});

常见问题

如何获取 API Key？

方式 1：通过 MCP 工具获取（推荐）

首次使用无需配置 API Key，直接调用：

1. send_code - 发送验证码到手机
2. login - 使用验证码登录，获取 api_key
3. 将 api_key 配置到环境变量 WORKSHUB_API_KEY

方式 2：从平台获取

访问 https://workshub.ai 登录后，在用户中心创建 API Key。

支持哪些 AI IDE？

目前支持：

• Claude Desktop
• Cursor
• 任何支持 MCP 协议的 AI 应用

如何调试？

使用 MCP Inspector：

npx @modelcontextprotocol/inspector node dist/index.js

许可证

MIT

相关链接

• WorksHub 官网
• MCP 协议文档
• GitHub 仓库

贡献

欢迎提交 Issue 和 Pull Request！