crontap-natural-language-schedules

自然言語によるスケジュールをプレビューする

別のスキルでスケジュールを作成または更新する前に、このスキルを使って実行タイミングを確定します。プレビューは読み取り専用です。

前提条件

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

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

ユーザーがどちらかを選ぶまで、どちらかの方法を黙って選択したり、先に進んだりしないでください。

• ユーザーが意図するローカルタイムゾーンを特定します。
• 営業日の表現が平日を指すのか、祝日を考慮したカレンダーを指すのかを確認します。
• 開始日や月末日など、境界に関する要件を確認します。

スケジュールを明確に表現する

頻度、ローカル時刻、カレンダーの範囲を含む表現を優先します。

• every weekday at 09:15
• every 6 hours
• at 02:30 every Sunday
• on the first day of every month at 08:00

in the morning、twice a month、month end、タイムゾーンの指定がない weekdays のような表現は避けてください。5フィールドの cron では、祝日を考慮するルールや最終営業日のルールをすべて表現できるわけではありません。

ワークフロー

1. ユーザーと正確な IANA タイムゾーンを確定します。
2. 元の頻度指定とタイムゾーンを指定して preview_schedule を呼び出します。
3. レスポンスで確認が必要な場合は、質問と選択肢を提示します。
4. ユーザーの回答を使って再度プレビューします。
5. 確定した cron、タイムゾーン、返された次回実行日時をすべて報告します。
6. 別途作成または更新する前に、ユーザーに確認を求めます。

MCP の例

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

レスポンスのステータスが needs_clarification または rejected の場合、推測した cron を保存しないでください。返された選択肢は候補として扱い、ユーザーに代わって選んでよいという許可とは見なさないでください。

DST とカレンダーの確認

• 近い将来の夏時間への移行の前後で、次回実行日時を確認します。
• 名前付きタイムゾーンを使うと、ローカルの壁時計時刻が維持されます。UTC スケジュールでは、UTC の固定時刻が維持されます。
• weekday が土曜日と日曜日だけを除外するのか確認します。
• 最終営業日のロジックでは、安全な候補頻度をスケジュールし、冪等なエンドポイント内で最終的なカレンダー確認を行います。
• 1回限りの処理では、正確なタイムスタンプとクリーンアップの動作を確認してから、1回限りのスケジュールを使います。

REST による代替手段

公開 API の代替手段を使うには、Ultra API へのアクセスが必要です。

curl --fail-with-body https://api.crontap.com/v1/schedule/preview \
  -X POST \
  -H "ClientId: $CRONTAP_CLIENT_ID" \
  -H "ApiKey: $CRONTAP_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"text":"every weekday at 09:15","timezone":"America/New_York"}'

MCP は Ultra がなくても利用できます。接続済みの場合は MCP を優先してください。

安全性とプランの制限

• プレビューによってリソース容量は消費されません。
• 有効なプレビューでも、アカウントで作成可能な下限を下回る頻度が示される場合があります。権限の最終確認は作成時に行われます。
• 作成時にプラン制限のレスポンスが返された場合は、4つの選択肢からなる段階的な選択肢をそのまま提示し、実行可能な最小プランを明示します。
• 読み取り専用のプレビューから、ユーザーが作成に同意したと推測してはいけません。

トラブルシューティング

• 表現が拒否された場合は、頻度を1つ、ローカル時刻を1つに絞って簡潔にしてください。
• cron は正しく見えるのに次回実行日時が誤っている場合は、まずタイムゾーンを確認してください。
• 希望するカレンダールールを表現できない場合は、その条件をエンドポイントに移し、エンドポイントを冪等に保ちます。

参考資料

• Crontap Agent Skills カタログ
• 英語から cron への変換
• Cron 構文リファレンス
• Cron のトラブルシューティング
• 機械可読な製品リファレンス