crontap-replace-vercel-cron

Vercel Cron を置き換える

ランタイムは Vercel のままにして、スケジュールだけを移行します。Crontap はデプロイ済みのルートを HTTPS で呼び出します。

前提条件

必須ツールを使用する前に、利用可能かどうかを確認してください。利用できないツールがある場合は、そこで中断し、ユーザーに次の 2 つの選択肢を提示してください。

1. https://mcp.crontap.com/mcp で Crontap MCP に接続します。MCP アクセスは Crontap のすべてのプランで利用できます。
2. 生の API を使う場合は、$CRONTAP_CLIENT_ID と $CRONTAP_API_KEY を設定します。生の API へのアクセスには Ultra が必要です。

どちらかをユーザーが選択するまで、勝手に方法を選んだり、先に進んだりしないでください。

• 既存の vercel.json にある Cron のパスと式を確認します。
• 本番環境のホスト名とルートのメソッドを確認します。
• 専用のシークレットヘッダーでルートを保護します。
• 切り替える前に、ハンドラーを冪等にします。

切り替えのワークフロー

1. Vercel アプリケーションでルート認証を追加するか、既に設定されていることを確認します。
2. 制御されたリクエストで、保護された本番ルートをテストします。
3. 切り替え時刻を決め、一時的な重複実行または実行漏れのリスクを説明します。
4. vercel.json のスケジュールを削除するか、無効にします。
5. 直ちに同じ内容の Crontap スケジュールを作成します。
6. 解決されたタイムゾーン、次回の実行時刻、最初の履歴エントリーを確認します。
7. ロールバック手順を用意します。Crontap を一時停止し、Vercel Cron を復元してからデプロイします。

両方のスケジューラーを有効なままにしないでください。どちらも正常に動作していても、2 つのスケジューラーが副作用を重複して発生させる可能性があります。

MCP の例

置き換え用のスケジュールを作成します。

{
  "tool": "create_schedule",
  "arguments": {
    "url": "https://app.example.com/api/cron/daily-report",
    "cron": "0 9 * * 1-5",
    "timezone": "UTC",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer <secret-from-secure-store>"
    },
    "label": "Vercel daily report"
  }
}

ロールバックまたはメンテナンスのために一時停止します。

{
  "tool": "pause_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}

同じ設定を再開します。

{
  "tool": "resume_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}

一時停止または再開する前に、選択した ID を確認してください。

保護されたルートのパターン

リクエストの認証ヘッダーを、サーバー専用の環境変数と比較します。一致しない場合は、処理を実行する前に 401 を返します。クエリ文字列やルートパスにシークレットを含めないでください。

ルートが処理をキューに追加する場合は、キューへの追加前に、論理的なスケジュール期間を冪等性キーとして保存します。キューがジョブを受け付けた後にのみ成功を返します。

REST による代替手段

REST での作成には Ultra API アクセスが必要です。

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/cron/daily-report",
    "interval": "0 9 * * 1-5",
    "timezone": "UTC",
    "verb": "GET",
    "headers": {
      "Authorization": "Bearer <secret-from-secure-store>"
    },
    "label": "Vercel daily report"
  }'

Ultra 以外のアカウントでは MCP を使用してください。

検証

• デプロイ済みの設定から古い Vercel スケジュールが削除されていることを確認します。
• そのルートを対象とする Crontap スケジュールが 1 つだけであることを確認します。
• シークレットなしで 401 が返され、シークレットありで成功することを確認します。
• 最初の実行と、アプリケーションレベルの副作用を調べます。

安全性とプランの制限

• 本番ルートのシークレットをスキル、リポジトリ、チャットに貼り付けないでください。
• ロールバックで古いスケジューラーを復元する前に、一時停止してください。
• ユーザーがローカルの IANA タイムゾーンを明示的に選択しない限り、元の実行間隔が持つ UTC の意味を維持してください。
• 上限または実行間隔のエラーが発生した場合は、返された 4 つの選択肢と、実行可能な最小の選択肢を提示してください。

トラブルシューティング

• Vercel の 401 は、設定されたスケジュールヘッダーとルートシークレットが一致していないことを意味します。
• 404 は、呼び出し先のホスト名にルートがデプロイされていない場合によく発生します。
• 出力の重複は、両方のスケジューラーが有効になっているか、エンドポイントの冪等性に問題があることを意味します。
• タイムアウトが発生する場合は、同期処理を長時間行う代わりに、永続キューが必要となることがあります。

参考資料

• Crontap エージェントスキルのカタログ
• Vercel Cron の制限と代替手段
• Vercel Cron の代替手段
• Cron のトラブルシューティング
• Cron ジョブの監視