MCP 工具参考

HumanAPI 通过单一的 POST /api/mcp 入口分派 12 个工具。请求使用 { tool, arguments } 包络,认证与限流与 REST 完全一致。

入口 POST /api/mcp 工具数量 12 参数风格 snake_case 认证 Bearer / x-api-key

调用方式

每次调用都是一个 POST 请求,body 为 { "tool": "<工具名>", "arguments": { ... } }。arguments 可省略(默认空对象),但 tool 必须是已声明的工具名,且请求体不接受额外字段。

请求示例

javascript · fetch
const response = await fetch("http://localhost:3000/api/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    tool: "search_humans",
    arguments: {
      skills: ["现场调研"],
      location: { lat: 31.2304, lon: 121.4737 },
      max_distance: 5000,
      rating_min: 4,
    },
  }),
});

const result = await response.json();

读取工具清单

GET /api/mcp 返回工具名称列表、版本与本地基础 URL,同样需要认证:

json · 200
{
  "name": "HumanAPI MCP Server",
  "version": "2.0.0",
  "description": "MCP server for AI agents to book human experts for physical-world tasks",
  "tools": [
    "search_humans",
    "get_human",
    "book_human",
    "get_booking",
    "update_booking",
    "list_skills",
    "create_review",
    "send_message",
    "create_dispute",
    "get_dispute",
    "list_disputes",
    "resolve_dispute"
  ],
  "baseUrl": "http://localhost:3000/api/mcp"
}
命名差异:MCP 工具参数使用 snake_case(如 human_id、rating_min),REST 端点使用 camelCase(如 humanId、ratingMin);两者操作同一份数据与同一套状态机。

工具清单

#工具说明
01search_humans按技能、位置、费率与评分搜索专家
02get_human读取单个专家档案与能力信息
03book_human创建任务记录与待处理预约
04get_booking读取预约、支付字段与执行时间
05update_booking更新预约状态与完成凭据字段
06list_skills列出技能分类与技能条目
07create_review对已完成预约提交评价
08send_message在预约双方之间发送消息
09create_dispute对预约创建争议
10get_dispute读取争议详情
11list_disputes按状态或预约列出争议
12resolve_dispute以 RESOLVED / REJECTED 结案争议

发现与检索

TOOL search_humans

按技能、位置、费率与评分搜索可用专家,返回与 REST GET /api/humans 相同结构的档案列表。

参数

参数类型必填说明
skillsstring[]否技能标签,最多 50 个
locationobject否{ lat, lon },用于距离匹配
max_distancenumber否最大距离(米),默认 10000
rate_minnumber否最低时薪
rate_maxnumber否最高时薪
rating_minnumber否最低评分(0–5)
available_nowboolean否仅当前可接单,默认 true

请求示例

javascript · fetch
const response = await fetch("/api/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    tool: "search_humans",
    arguments: {
      skills: ["现场调研", "摄影"],
      location: { lat: 31.2304, lon: 121.4737 },
      max_distance: 8000,
      rate_max: 250,
      rating_min: 4,
      available_now: true,
    },
  }),
});

响应示例 · 200

json
{
  "success": true,
  "data": [
    {
      "id": "hp_9k2f71xa",
      "name": "林晓",
      "avatar": null,
      "rating": 4.8,
      "totalReviews": 126,
      "skills": [{ "name": "现场调研", "verified": true }],
      "hourlyRate": 150,
      "currency": "CNY",
      "available": true,
      "location": { "lat": 31.2304, "lon": 121.4737, "city": "上海" }
    }
  ],
  "count": 1
}
TOOL get_human

读取单个专家档案,含简介、认证与统计字段。

参数

参数类型必填说明
idstring是HumanProfile.id

请求示例

javascript · fetch
const response = await fetch("/api/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    tool: "get_human",
    arguments: { id: "hp_9k2f71xa" },
  }),
});

响应示例 · 200

json
{
  "success": true,
  "data": {
    "id": "hp_9k2f71xa",
    "name": "林晓",
    "rating": 4.8,
    "totalReviews": 126,
    "bio": "十年市场调研经验,可承接线下访谈与数据收集。",
    "skills": [{ "name": "现场调研", "verified": true }],
    "hourlyRate": 150,
    "currency": "CNY",
    "available": true,
    "verified": true,
    "totalTasks": 87,
    "successRate": 0.97,
    "location": { "lat": 31.2304, "lon": 121.4737, "city": "上海" },
    "certifications": []
  }
}
TOOL list_skills

列出全部技能分类与技能条目,无需参数。

请求示例

javascript · fetch
const response = await fetch("/api/mcp", {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.HUMANAPI_API_KEY}` },
  body: JSON.stringify({ tool: "list_skills", arguments: {} }),
});

响应示例 · 200

json
{
  "success": true,
  "data": {
    "categories": [
      { "id": "cat_field", "name": "实地服务", "nameEn": "Field Service", "nameZh": "实地服务" }
    ],
    "skills": [
      {
        "id": "skl_survey",
        "name": "现场调研",
        "name_en": "Field Survey",
        "name_zh": "现场调研",
        "category": "实地服务",
        "description": "线下访谈、观察与数据收集"
      }
    ],
    "total": 1
  }
}

预约与执行

TOOL book_human

一步创建任务与预约:任务直接置为 ASSIGNED,预约置为 PENDING。专家必须 verified 且 available,否则 409。

参数

参数类型必填说明
human_idstring是HumanProfile.id
task_descriptionstring是任务描述,≤ 10000 字符(前 100 字符作为标题)
task_locationobject是{ lat, lon, address?, city?, country? }
scheduled_timestring是计划执行时间(ISO 8601,含时区偏移)
estimated_durationnumber是预计时长(分钟),最大 10080
payment_amountnumber是报酬金额
agent_idstring是发起方 User.id(role 须为 AGENT)
payment_methodstring否支付方式标注

请求示例

javascript · fetch
const response = await fetch("/api/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    tool: "book_human",
    arguments: {
      human_id: "hp_9k2f71xa",
      task_description: "拍摄三家门店的陈列照片并填写检查表。",
      task_location: { lat: 31.2304, lon: 121.4737, city: "上海" },
      scheduled_time: "2026-11-05T02:00:00.000Z",
      estimated_duration: 120,
      payment_amount: 300,
      agent_id: "usr_2b71de04",
      payment_method: "credit",
    },
  }),
});

const { booking_id, task_id } = (await response.json()).data;

响应示例 · 201

json
{
  "success": true,
  "data": {
    "booking_id": "bkg_5t8wa31q",
    "task_id": "tsk_7h3kd92m",
    "human_id": "hp_9k2f71xa",
    "agent_id": "usr_2b71de04",
    "scheduled_time": "2026-11-05T02:00:00.000Z",
    "estimated_duration": 120,
    "payment_amount": 300,
    "currency": "CNY",
    "status": "PENDING",
    "human_name": "林晓"
  }
}
TOOL get_booking

读取预约状态、支付字段与执行时间。human_id 在返回中解析为 HumanProfile.id。

参数

参数类型必填说明
idstring是Booking.id

请求示例

javascript · fetch
const response = await fetch("/api/mcp", {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.HUMANAPI_API_KEY}` },
  body: JSON.stringify({
    tool: "get_booking",
    arguments: { id: "bkg_5t8wa31q" },
  }),
});

响应示例 · 200

json
{
  "success": true,
  "data": {
    "id": "bkg_5t8wa31q",
    "task_id": "tsk_7h3kd92m",
    "agent_id": "usr_2b71de04",
    "human_id": "hp_9k2f71xa",
    "scheduled_time": "2026-11-05T02:00:00.000Z",
    "estimated_duration": 120,
    "actual_duration": null,
    "payment_amount": 300,
    "currency": "CNY",
    "status": "IN_PROGRESS",
    "payment_status": "PENDING",
    "agent_name": "ResearchBot",
    "human_name": "林晓",
    "completion_proof": null,
    "started_at": "2026-11-05T02:05:00.000Z",
    "completed_at": null,
    "created_at": "2026-10-29T09:00:00.000Z"
  }
}
TOOL update_booking

更新预约状态。状态机与 REST 一致:PENDING → CONFIRMED → IN_PROGRESS → COMPLETED,CANCELLED 可从任意非终态进入。非法迁移或并发冲突返回 409。

参数

参数类型必填说明
idstring是Booking.id
statusenum是CONFIRMED / IN_PROGRESS / COMPLETED / CANCELLED
proofstring否完成凭据,写入 completionProof

请求示例

javascript · fetch
const response = await fetch("/api/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    tool: "update_booking",
    arguments: {
      id: "bkg_5t8wa31q",
      status: "COMPLETED",
      proof: "https://files.example.com/reports/bkg_5t8wa31q.pdf",
    },
  }),
});

响应示例 · 200

json
{
  "success": true,
  "data": {
    "id": "bkg_5t8wa31q",
    "status": "COMPLETED",
    "updated_at": "2026-11-05T05:15:00.000Z"
  }
}

协作

TOOL create_review

对已完成预约提交评价。仅 COMPLETED 预约可评;reviewer 须为预约双方之一;同一预约同一 reviewer 只能评一次。

参数

参数类型必填说明
booking_idstring是Booking.id,须已 COMPLETED
reviewer_idstring是User.id,预约的 agent 或 human
ratingnumber是1–5 的整数
commentstring否评价内容

请求示例

javascript · fetch
const response = await fetch("/api/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    tool: "create_review",
    arguments: {
      booking_id: "bkg_5t8wa31q",
      reviewer_id: "usr_2b71de04",
      rating: 5,
      comment: "照片与检查表齐全,沟通顺畅。",
    },
  }),
});

响应示例 · 201

json
{
  "success": true,
  "data": {
    "id": "rev_5m2ka91x",
    "bookingId": "bkg_5t8wa31q",
    "reviewerId": "usr_2b71de04",
    "revieweeId": "usr_4c8d10be",
    "rating": 5,
    "comment": "照片与检查表齐全,沟通顺畅。",
    "createdAt": "2026-11-05T06:00:00.000Z"
  }
}
TOOL send_message

在预约双方之间发送消息。sender 与 recipient 必须是该预约的 agent 或 human,且不能相同。

参数

参数类型必填说明
booking_idstring是Booking.id
sender_idstring是发送方 User.id
recipient_idstring是接收方 User.id
contentstring是消息内容

请求示例

javascript · fetch
const response = await fetch("/api/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    tool: "send_message",
    arguments: {
      booking_id: "bkg_5t8wa31q",
      sender_id: "usr_2b71de04",
      recipient_id: "usr_4c8d10be",
      content: "巡查时请顺便拍摄冰柜温度显示。",
    },
  }),
});

响应示例 · 201

json
{
  "success": true,
  "data": {
    "id": "msg_03",
    "bookingId": "bkg_5t8wa31q",
    "senderId": "usr_2b71de04",
    "recipientId": "usr_4c8d10be",
    "content": "巡查时请顺便拍摄冰柜温度显示。",
    "createdAt": "2026-11-05T02:20:00.000Z"
  }
}

争议

TOOL create_dispute

对预约创建争议,提交后预约置 DISPUTED。预约不能已 COMPLETED / CANCELLED;已存在 OPEN 争议时返回 409。

参数

参数类型必填说明
booking_idstring是Booking.id
reporter_idstring是发起人 User.id
reasonstring是争议原因,≤ 200 字符
descriptionstring是详细说明,≤ 5000 字符
evidencestring否证据链接

请求示例

javascript · fetch
const response = await fetch("/api/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    tool: "create_dispute",
    arguments: {
      booking_id: "bkg_5t8wa31q",
      reporter_id: "usr_2b71de04",
      reason: "未按约定时间到达",
      description: "约定 14:00 开始,专家 16:30 才到场且未提前告知。",
      evidence: "https://files.example.com/evidence/chat-log.pdf",
    },
  }),
});

响应示例 · 201

json
{
  "success": true,
  "data": {
    "id": "dsp_6m1qz84e",
    "bookingId": "bkg_5t8wa31q",
    "reporterId": "usr_2b71de04",
    "reason": "未按约定时间到达",
    "status": "OPEN",
    "createdAt": "2026-11-05T03:05:00.000Z"
  }
}
TOOL get_dispute

读取争议详情,含预约摘要与处理结论。

参数

参数类型必填说明
idstring是Dispute.id

请求示例

javascript · fetch
const response = await fetch("/api/mcp", {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.HUMANAPI_API_KEY}` },
  body: JSON.stringify({
    tool: "get_dispute",
    arguments: { id: "dsp_6m1qz84e" },
  }),
});

响应示例 · 200

json
{
  "success": true,
  "data": {
    "id": "dsp_6m1qz84e",
    "bookingId": "bkg_5t8wa31q",
    "reporterId": "usr_2b71de04",
    "reason": "未按约定时间到达",
    "description": "约定 14:00 开始,专家 16:30 才到场且未提前告知。",
    "evidence": "https://files.example.com/evidence/chat-log.pdf",
    "status": "OPEN",
    "aiResolution": null,
    "humanResolution": null,
    "resolvedAt": null,
    "createdAt": "2026-11-05T03:05:00.000Z"
  }
}
TOOL list_disputes

按状态或预约列出争议。

参数

参数类型必填说明
statusenum否OPEN / INVESTIGATING / RESOLVED / REJECTED
booking_idstring否按预约过滤

请求示例

javascript · fetch
const response = await fetch("/api/mcp", {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.HUMANAPI_API_KEY}` },
  body: JSON.stringify({
    tool: "list_disputes",
    arguments: { status: "OPEN" },
  }),
});

响应示例 · 200

json
{
  "success": true,
  "data": [
    {
      "id": "dsp_6m1qz84e",
      "bookingId": "bkg_5t8wa31q",
      "reason": "未按约定时间到达",
      "status": "OPEN",
      "createdAt": "2026-11-05T03:05:00.000Z"
    }
  ],
  "count": 1
}
TOOL resolve_dispute

以 RESOLVED 或 REJECTED 结案争议,并记录 resolvedAt。

参数

参数类型必填说明
idstring是Dispute.id
statusenum是RESOLVED / REJECTED
resolutionstring否处理结论

请求示例

javascript · fetch
const response = await fetch("/api/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    tool: "resolve_dispute",
    arguments: {
      id: "dsp_6m1qz84e",
      status: "RESOLVED",
      resolution: "扣除 20% 报酬作为补偿,双方确认结案。",
    },
  }),
});

响应示例 · 200

json
{
  "success": true,
  "data": {
    "id": "dsp_6m1qz84e",
    "status": "RESOLVED",
    "resolution": "扣除 20% 报酬作为补偿,双方确认结案。",
    "resolvedAt": "2026-11-06T10:00:00.000Z"
  }
}

错误与状态码

MCP 路由复用 REST 的认证、限流与错误包络。包络校验失败(未知工具、多余字段、参数类型错误)返回 400,details 使用点分路径定位问题字段。

状态码error常见场景
400Invalid MCP request未知工具名、多余字段或参数校验失败
401Authentication required缺少或无效 API Key
404Human / Booking / Dispute not found引用的资源不存在
409Invalid agent / not verified and available / Cannot transition…状态冲突或资源不可用
429Rate limit exceeded超过每 Key 限额,带 Retry-After
500Internal server error未处理的内部异常

错误响应示例 · 400

json
{
  "success": false,
  "error": "Invalid MCP request",
  "details": [
    { "path": "arguments.rating_min", "message": "Number must be less than or equal to 5" }
  ]
}

客户端配置

仓库内置独立的 MCP stdio Server(mcp-server/)。构建后,在 MCP 客户端中添加如下配置,客户端会通过 stdio 调用本地进程,再由它请求 /api/mcp:

json · mcp client config
{
  "mcpServers": {
    "humanapi": {
      "command": "node",
      "args": ["/absolute/path/to/HumanAPI/mcp-server/dist/index.js"],
      "env": {
        "HUMANAPI_API_URL": "http://localhost:3000/api/mcp",
        "HUMANAPI_API_KEY": "与 API_KEY 相同的值"
      }
    }
  }
}
HUMANAPI_API_KEY 必须与服务端 API_KEY 一致;args 中的路径需为绝对路径。完整步骤见 快速开始 · MCP 客户端。