crontap-schedule-http-job

用途

本技能用于创建、更新和验证周期性的 Crontap HTTP 请求。当用户希望按计划自动调用某个 HTTP 接口时使用，支持用 cron 表达式或自然语言描述调度节奏，并可配置时区、请求头和 JSON 请求体。

前置条件

使用所需工具前，先检查其是否可用。若缺失，应停止并让用户在以下两项中明确选择其一：

连接 Crontap MCP：https://mcp.crontap.com/mcp 。MCP 访问在所有 Crontap 套餐中均可用。
为原始 API 配置 $CRONTAP_CLIENT_ID 和 $CRONTAP_API_KEY。原始 API 访问需要 Ultra 套餐。

在用户做出选择前，不要静默选择某条路径或继续执行。

主要能力

用自然语言或 cron 表达式预览调度节奏。
创建定时 HTTP 请求，可指定 URL、方法、时区、请求头、JSON 请求体和幂等键。
部分更新已有调度，仅发送变更字段；省略的字段会保留原有配置（包括隐藏的请求密钥）；空的 headers 对象会替换并清空请求头。
读取最近的运行历史，并可使用返回的游标原样请求下一页。
在执行后检查保留的历史记录，验证接口调用结果。

使用方式

确认信息

确认绝对的 HTTP 或 HTTPS 端点、方法、调度节奏和 IANA 时区。询问端点是否需要请求头、JSON 请求体或幂等键。凭据不要放入 URL 和日志，应从安全存储中引用。

工作流

预览自然语言描述的调度节奏，并解决所有需要澄清的问题。
向用户展示解析后的 cron、时区和接下来的运行时间。
使用 text 或 cron 中的恰好一个来创建调度。
如需修改，先定位已有调度，仅发送变更字段。
执行后检查保留的历史记录，验证端点结果。

MCP 示例

不保存的预览：

{
  "tool": "preview_schedule",
  "arguments": {
    "text": "every weekday at 09:15",
    "timezone": "Europe/Copenhagen"
  }
}

创建带保护的 JSON 请求：

{
  "tool": "create_schedule",
  "arguments": {
    "url": "https://app.example.com/api/daily-report",
    "text": "every weekday at 09:15",
    "timezone": "Europe/Copenhagen",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer <secret-from-secure-store>",
      "Content-Type": "application/json"
    },
    "body": {
      "source": "crontap"
    },
    "label": "Daily report"
  }
}

部分更新调度：

{
  "tool": "update_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "cron": "30 9 * * 1-5",
    "timezone": "Europe/Copenhagen"
  }
}

读取最近运行记录：

{
  "tool": "get_schedule_history",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "limit": 20
  }
}

REST 回退

仅在 MCP 不可用且账户具有 Ultra API 访问权限时使用 REST。REST 使用 interval、verb 和 data，而非 MCP 的别名。

curl --fail-with-body https://api.crontap.com/v1/schedule \
  -X POST \
  -H "ClientId: $CRONTAP_CLIENT_ID" \
  -H "ApiKey: $CRONTAP_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://app.example.com/api/daily-report",
    "interval": "30 9 * * 1-5",
    "timezone": "Europe/Copenhagen",
    "verb": "POST",
    "headers": {
      "Authorization": "Bearer <secret-from-secure-store>",
      "Content-Type": "application/json"
    },
    "data": {"source": "crontap"},
    "label": "Daily report"
  }'

验证

确认保存的 URL、方法、cron、时区和接下来的运行时间。
验证端点能处理所选方法并返回成功状态。
首次运行后检查历史记录中的状态、耗时、超时和重试证据。

适用场景

适用于需要按计划自动调用 HTTP/HTTPS 接口的任务，例如定时触发报表生成、数据同步、周期性调用某个 API 等。

限制与安全

创建前先预览本地时间调度，尤其是在夏令时切换前后。
在无关的部分更新中，不要覆盖请求头或集成配置。
当可能发生重试或重叠调用时，使写入端点具备幂等性。
若套餐上限或调度频率下限阻止创建，应说明结构化的四选项升级阶梯及其最小可行选项。

故障排查

澄清响应不是失败。应提出返回的问题，然后再次预览。
目标返回 401 或 403 通常表示端点凭据过期或格式错误。
超时表示 Crontap 未及时收到响应。在增加重试前，先检查端点运行时间和下游调用。
MCP 返回 404 表示调度 ID 已失效。重试前先列出调度。