Notionは会計ほど直接的な金銭影響がなくても、タスクの状態や期限を誤って変えると業務に影響します。freee連携で使ったprepareとwriteの分離を、Notionにも適用しました。
作成と更新を別々に扱う
公開したToolは、参照、作成準備、作成、更新準備、更新に分けました。
- 一覧・一件取得：副作用なし
- 作成準備：Notionへ送るプロパティを組み立て、確認コードを返す
- 作成：書き込み有効かつ確認コード一致で実行
- 更新準備：対象ページと変更差分を確認する
- 更新：同じ変更内容だけを実行
更新対象はNotionのpage_idまたはHermes側の安定IDで一意に特定します。タイトル検索の先頭一件を更新するような曖昧な方法は使いません。
変更差分を人が読める形にする
prepareの結果には、API payloadだけでなく、人が確認できる要約を含めます。
対象: TASK-EXAMPLE-001
変更前: In progress
変更後: Done
完了日時: 2026-07-30T10:00:00+09:00この表示を確認してから、同じ内容に対する確認コードを渡します。後から期限や状態が変更されればコードが一致せず、再度prepareが必要です。
APIのエラーを分類する
Notion APIでは、権限不足、共有漏れ、スキーマ不一致、rate limit、一時的な503などを分けて扱います。公式ドキュメントは503時に指数バックオフとジッター、page size削減、filterの絞り込みを案内しています。
何でも即時再試行すると、障害中にリクエストを増やします。401・403・404は設定確認、429・503は待って再試行、入力エラーは人へ返す、といった分類が必要です。
拒否されることをテストする
手元では、初期値が読み取り専用であること、書き込み無効時の作成拒否、間違った確認コードの更新拒否、必須列不足の検出、APIバージョンヘッダーの付与をテストしました。
「AIが正しく使うだろう」と期待せず、誤った呼び出しでも外部状態が変わらないようにします。
再現チェック
- [ ] 作成と更新を別Toolにした
- [ ] prepareはNotionを変更しない
- [ ] 対象を一意なIDで指定する
- [ ] 変更前後を人が読める形で表示する
- [ ] 書き込みの初期値はfalse
- [ ] 権限・rate limit・一時障害を分類した
次回は、PLAUD公式MCPをOAuthでつなぎ、録音と文字起こしを読み取ります。