human-dispatch-mcp

human-dispatch-mcp

🌐 humandispatch.ai — 主页和服务提供方文档

AI Agent 到人工任务路由的通用调度层 — 任何企业（律师事务所、虚拟助理服务、自由职业者、代理机构）都可以通过 webhook 接入，并在几分钟内开始接收由 AI 调度的任务。

将任务路由到已注册的 webhook 服务提供方，并支持智能匹配、备用链和完成凭证跟踪。任何服务提供方都可以注册 webhook，路由器会根据能力、地区和预算将任务匹配给服务提供方。

快速开始

# Clone and install
git clone https://github.com/zyntarasystems/human-dispatch-mcp.git
cd human-dispatch-mcp
npm install

# Configure (optional — works out of the box with manual fallback)
cp .env.example .env

# Build and run
npm run build
node dist/index.js

使用 MCP Inspector 测试

验证服务是否正常工作的最简单方法：

npx @modelcontextprotocol/inspector node dist/index.js

打开 http://localhost:5173，输入终端中显示的代理会话令牌，然后点击 连接。

测试步骤：

1. 列出后端 — 调用 human_list_backends，查看 webhook_provider 和 manual

2. 注册服务提供方 — 调用 human_register_provider：

{
  "name": "Test Provider",
  "webhook_url": "https://webhook.site/your-uuid",
  "webhook_secret": "a-secret-that-is-at-least-32-chars-long!",
  "categories": ["digital_micro"],
  "task_types": ["digital"],
  "regions": ["*"],
  "min_budget_usd": 0,
  "max_budget_usd": 500,
  "max_concurrent_tasks": 10
}

3. 调度任务 — 使用 原始 JSON 输入模式调用 human_dispatch_task：

{
  "description": "Test task — verify the MCP server is routing correctly",
  "category": "digital_micro",
  "task_type": "digital",
  "budget": { "max_usd": 5, "currency": "USD" },
  "deadline": {
    "complete_by": "2026-04-10T18:00:00Z",
    "urgency": "low"
  },
  "proof_required": ["text_report"],
  "quality_sla": "low",
  "callback_url": null
}

任务应路由到已注册的服务提供方。如果没有匹配的服务提供方，任务会转到手动后端。

MCP 客户端配置

Claude Desktop / Cursor / 任意 MCP 客户端

{
  "mcpServers": {
    "human-dispatch": {
      "command": "npx",
      "args": ["human-dispatch-mcp"]
    }
  }
}

HTTP 传输

注意： HTTP 传输仅绑定到 127.0.0.1。如需远程访问，请在服务前放置一个负责 TLS 终止的反向代理（例如 nginx、Caddy）。切勿直接暴露端口。

必需： 未设置 MCP_AUTH_TOKEN 时，HTTP 传输会拒绝启动。所有 POST /mcp 请求都必须包含 Authorization: Bearer <MCP_AUTH_TOKEN>。/callbacks/task/:taskId 端点使用 HMAC 签名进行身份验证，因此服务提供方不会看到 Bearer 令牌。

{
  "mcpServers": {
    "human-dispatch": {
      "command": "npx",
      "args": ["human-dispatch-mcp"],
      "env": {
        "TRANSPORT": "http",
        "PORT": "3000",
        "MCP_AUTH_TOKEN": "a-long-random-string-32-chars-or-more"
      }
    }
  }
}

工具参考

工具	说明
human_dispatch_task	将任务提交给最匹配的服务提供方，由人工工作者完成
human_get_task_status	查询任务当前状态、工作者信息和完成凭证提交情况
human_cancel_task	取消待处理或进行中的任务
human_list_tasks	使用筛选条件（状态、后端、类别）和分页列出任务
human_list_backends	显示可用后端、其配置状态和能力
human_register_provider	注册 webhook 服务提供方以接收调度的任务
human_list_providers	使用统计信息和筛选条件列出已注册的服务提供方
human_remove_provider	注销 webhook 服务提供方

架构

┌─────────────┐
│   AI Agent   │
│ (Claude, etc)│
└──────┬───────┘
       │ MCP Protocol (stdio or HTTP)
       ▼
┌──────────────────────────────────────┐
│     human-dispatch-mcp Server        │
│                                      │
│  ┌────────────┐  ┌────────────────┐  │
│  │ Task Store │  │ Provider       │  │
│  │ (in-memory)│  │ Registry       │  │
│  └────────────┘  └───────┬────────┘  │
│                          │           │
│  ┌────────────┐  ┌───────▼────────┐  │
│  │   Router   │──│  Webhook       │  │
│  │  (scoring) │  │  Provider      │  │
│  └──────┬─────┘  │  Adapter       │  │
│         │        └───────┬────────┘  │
│         │                │           │
│         │    ┌───────────▼─────────┐ │
│         │    │ Provider A (law)    │ │
│         │    │ Provider B (VA)     │ │
│         │    │ Provider C (photos) │ │
│         │    └─────────────────────┘ │
│         ▼                            │
│  ┌────────────┐                      │
│  │   Manual   │ (always-on fallback) │
│  │  Adapter   │                      │
│  └────────────┘                      │
└──────────────────────────────────────┘

面向服务提供方

任何企业都可以注册为服务提供方，以接收由 AI 调度的任务。操作方法如下：

1. 设置 webhook 端点

你的端点会收到包含以下标头的 POST 请求：

标头	说明
x-dispatch-signature	sha256=<hmac_hex> — 使用共享密钥对请求正文计算的 HMAC-SHA256
X-Dispatch-Event	事件类型：task.new、task.cancel 或 provider.verify
X-Dispatch-TaskId	任务的 UUID

2. 处理 task.new 事件

请求正文：

{
  "payload_version": 1,
  "event": "task.new",
  "task_id": "uuid",
  "description": "What needs to be done",
  "category": "photo_video",
  "task_type": "physical",
  "location": { "address": "123 Main St", "region": "US" },
  "budget": { "max_usd": 25, "currency": "USD" },
  "deadline": { "complete_by": "2026-04-10T18:00:00Z", "urgency": "medium" },
  "proof_required": ["photo", "gps_checkin"],
  "quality_sla": "medium"
}

payload_version 是请求格式的版本；请将解析器固定为已知版本，并拒绝未知版本。目前仅发送 1。

响应：

{ "accepted": true, "external_id": "your-internal-id" }

或者拒绝：

{ "accepted": false, "reason": "Outside service area" }

处理 provider.verify 事件

注册服务提供方时，服务器会立即 POST 一个 provider.verify 事件，以确认端点可访问且愿意接收任务。仅返回 200 还不够——你的端点必须在 JSON 正文中返回 { "verified": true }。其他任何情况（字段缺失、值为 false、非 JSON）都会将验证标记为不可访问。这样一来，注册就需要端点明确同意，而不仅仅是 URL 可访问。

3. 报告完成情况（仅限 HTTP 传输）

使用以下标头向 http://<server>/callbacks/task/<task_id> 发送 POST 请求：

• x-provider-id：你的服务提供方 UUID
• x-dispatch-signature：正文的 sha256=<hmac_hex>

{
  "status": "completed",
  "proof": [
    { "type": "photo", "url": "https://...", "submitted_at": "2026-04-10T12:00:00Z" }
  ],
  "actual_cost_usd": 20,
  "notes": "Task completed successfully"
}

4. 验证 HMAC 签名

始终使用共享密钥验证传入的 Webhook：

const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));

HMAC 规范化约定（至关重要）：签名是基于请求 POST 时使用的确切字节计算的，而不是基于重新序列化的 JSON 对象计算的。发送回调时，应对实际发送到网络上的字节串进行签名——不要解析请求正文，再将其重新序列化后签名，因为键的顺序或空白可能不同。使用一次 JSON.stringify(payload)，保存生成的字符串，对该字符串签名，并发送该字符串。服务端接收时也遵循相同规则：在任何 JSON 解析器处理请求正文之前，先捕获原始请求正文缓冲区。

智能路由

路由器会根据以下因素自动选择最佳后端：

1. Agent 偏好 — 优先遵循 preferred_backends 和 fallback_chain
2. 提供方匹配 — 类别、任务类型、区域和预算兼容性
3. 可靠性 — 优先尝试完成率较高的提供方
4. 速度 — 速度更快的提供方得分更高
5. 回退 — manual 后端始终可用，作为最终回退选项

Agent 使用示例

使用 LangGraph 的 Python

import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient

async def dispatch_photo_task():
    async with MultiServerMCPClient({
        "human": {
            "command": "node",
            "args": ["path/to/human-dispatch-mcp/dist/index.js"],
            "transport": "stdio",
        }
    }) as client:
        tools = client.get_tools()

        # Register a provider first
        await client.call_tool("human_register_provider", {
            "name": "Photo Service Co",
            "webhook_url": "https://photos.example.com/webhook",
            "webhook_secret": "your-secret-that-is-at-least-32-characters",
            "categories": ["photo_video"],
            "task_types": ["physical"],
            "regions": ["US"],
            "min_budget_usd": 5,
            "max_budget_usd": 100,
            "max_concurrent_tasks": 20
        })

        # Dispatch a task
        result = await client.call_tool("human_dispatch_task", {
            "description": "Take a photo of the menu board at Starbucks on 5th Ave, NYC",
            "category": "photo_video",
            "task_type": "physical",
            "location": {
                "address": "5th Ave & 42nd St, New York, NY",
                "region": "US"
            },
            "budget": {"max_usd": 15, "currency": "USD"},
            "deadline": {
                "complete_by": "2026-01-15T18:00:00Z",
                "urgency": "medium"
            },
            "proof_required": ["photo", "gps_checkin"],
            "quality_sla": "medium"
        })
        print(result)

asyncio.run(dispatch_photo_task())

环境变量

变量	默认值	说明
TRANSPORT	stdio	传输模式：stdio 或 http
PORT	3000	HTTP 端口（当 TRANSPORT=http 时）
MCP_AUTH_TOKEN	—	当 TRANSPORT=http 时，每个 POST /mcp 请求都必须提供的 Bearer 令牌。未设置时，HTTP 传输不会启动。
MANUAL_WEBHOOK_URL	—	用于手动任务通知的 Webhook URL
PROVIDERS_CONFIG	—	用于在启动时预先填充提供方的 JSON 对象数组

安全性

此服务代表调用方处理出站 HTTP 请求，旨在可信的基础设施中运行。相关保障如下：

• HTTP 传输需要身份验证。 MCP_AUTH_TOKEN 为必填项；未设置时，服务不会启动。Bearer 令牌比较采用恒定时间算法（timingSafeEqual）。
• 已在 POST /mcp 上启用 DNS 重绑定防护。 如果请求的 Host 标头指向的不是配置的回环地址，传输层会拒绝该请求。
• 出站 URL 防护。 服务获取的每个 Webhook URL（提供方注册、MANUAL_WEBHOOK_URL、callback_url、证明 URL）都会经过结构化验证：仅允许 HTTPS，不允许回环地址、RFC1918 / 链路本地 / 唯一本地地址主机，并在获取时进行 DNS 解析检查，以防范最后一刻的重绑定。无法禁用此防护 — 本地测试请使用公共隧道（ngrok、cloudflared）。
• 入站回调通过 HMAC 而非 IP 进行身份验证。 每个提供方都会注册自己的 Webhook 密钥。服务会在解析 JSON 之前，基于原始请求字节验证 x-dispatch-signature。每个提供方都受令牌桶限流，限制回调洪泛（突发 30 次，持续每秒 5 次）。
• 终态保护。 任务进入 completed、failed 或 cancelled 状态后，针对该任务的回调都会被拒绝，并返回 409。这可阻止重放、提供方的延迟重试以及提供方驱动的状态变更。
• Webhook 负载版本控制。 所有出站正文都带有 payload_version 和 event 判别字段。请固定解析器版本，并拒绝未知版本。
• Webhook 密钥不会离开服务端。 MCP 工具返回的提供方数据经过清理，不包含 webhook_secret。该字段也绝不会出现在日志中。
• 不持久化。 任务、提供方和每个任务的状态都保存在内存中。重启服务会丢弃所有状态。如果在生产环境中运行此服务，请妥善终止，以便进行中的任务能够快速失败，而不是一直卡在提供方处。

如果发现安全问题，请在 GitHub 上私下提交安全公告，而不要创建公开问题。

路线图

• 持久化提供方注册表（SQLite / PostgreSQL）
• 任务过期和自动重试
• 提供方质量评分和反馈循环
• 调度前估算成本
• 批量提交任务
• 提供方仪表板 / 管理界面
• 基于 OAuth 的提供方身份验证

参与贡献

添加新的后端适配器

1. 在 src/services/backends/ 中创建一个新文件
2. 扩展 BaseBackendAdapter
3. 实现 BackendAdapter 接口中的所有方法
4. 在 src/types.ts 的 BackendId 枚举中添加后端 ID
5. 在 src/index.ts 中注册该适配器

许可证

MIT