42min

42min 開発者向け

42min の公開パッケージと契約です。会議スケジュールプラットフォームの 42min 上で開発したり、AI エージェントを接続したりするために必要なものを、このリポジトリにまとめています。製品自体はクローズドソースです。

REST API	https://api.42min.us/v1
MCP サーバー	https://api.42min.us/mcp
ドキュメント	42min.us/help/api
ステータス	OAuth 2.1、Dynamic Client Registration、個人用アクセストークン

内容

plugins/42min

Cursor 用の 42min プラグインです。エディターのエージェントを OAuth 経由で 42min アカウントに接続し、43 個のスケジュール管理ツールを提供します。詳しくはREADMEをご覧ください。

このプラグインを使わなくても、任意の MCP クライアントから https://api.42min.us/mcp を指定して接続できます。サーバーは OAuth 保護リソースのメタデータを公開しているため、準拠クライアントであれば、残りの情報はすべて自動で検出できます。

openapi/42min.v1.yaml

公開 REST API の OpenAPI 3.1 仕様です。クライアントの生成、Postman や Bruno へのインポート、コーディングエージェントへの入力に使用できます。

この仕様は手作業で作成されており、すべてのドキュメント記載エンドポイントを実行して、実際のレスポンス、ヘッダー、エラーボディをこれらのスキーマと照合する契約テストスイートによって、稼働中の API と突き合わせて検証されています。こうして初稿にあった 7 つの誤りが見つかりました。そのうち 2 つは、予約の書き込みのたびに、生成されたすべてのクライアントが動作しなくなるものでした。エンドポイントが存在するのに文書化されていない場合、またはその逆の場合は、ルートの網羅性チェックによってビルドが失敗します。

これらのチェックは、実際のデータベースを使って API を起動する必要があり、ここでは実行できないため、非公開リポジトリで実行しています。このリポジトリの CI で保証しているのは、このファイルが有効な OpenAPI 3.1 ドキュメントであることです。そのため、不正な仕様が皆さんの手元に届くことはありません。

このファイルと API の内容に食い違いを見つけた場合、誤っている可能性が高いのはファイルのほうです。issue を作成してください。

server.json

公式 MCP Registry のエントリーです。https://api.42min.us/mcp でストリーミング可能な HTTP を使うリモートサーバーとして登録しているため、レジストリと連携するディレクトリでは、誰かが手作業でフォームに入力しなくても一覧に掲載できます。

mcp/tools.json

MCP の契約を機械可読なスナップショットとしてまとめたものです。引数の JSON Schema、必要なスコープ、書き込みを行うかどうか、呼び出し前にユーザーへの確認を求めるタイミングをクライアントが判断するためのアノテーションを、すべてのツールについて記載しています。手作業で管理するのではなく、稼働中のツールレジストリから生成され、両者に食い違いがあるとテストが失敗する仕組みになっています。

クライアントを構築する場合は内容を確認するか、コーディングエージェントに入力してください。プラグインの READMEにある表は、同じ内容を人間向けにまとめたものです。

examples/webhook-receiver

依存関係なしで約 120 行で動作するレシーバーと、verify.js のみを対象にした 10 個のテストです。インテグレーションが失敗する原因になりやすいのは署名の検証です。よくある原因は、再シリアライズしたボディを検証してしまうことです。ドキュメントをいくら読んでも気付きにくい問題なので、verify.js をコピーして先に進んでください。

この API を利用したプロジェクト

• n8n community node（n8n-nodes-42min）。 予約、イベントタイプ、空き枠、現在のユーザーに加え、署名検証機能を内蔵したすべての webhook イベント用トリガーを提供します。ご自身の n8n 内で実行されるため、予約データは 42min からお使いのサーバーに送られ、それ以外の場所には送信されません。

認証を簡単に説明すると

認証方式は2つあります。ユーザーに代わって動作するアプリケーション向けの、PKCEを使用したOAuth 2.1です。Dynamic Client Registrationに対応しているため、クライアントはサポートへの問い合わせなしで自身を登録できます。もう1つは、個人として動作するスクリプト向けのパーソナルアクセストークンです。どちらにもスコープが設定され、APIはトークンのスコープで許可されていない操作を拒否します。トークンはそのユーザーとして動作します。つまり、42minでそのメンバーが閲覧・変更できる内容とまったく同じものにアクセスできます。そのため、通常のユーザーが接続したアプリはそのユーザーの予約にアクセスし、管理者が接続したアプリは組織全体にアクセスできます。ディスカバリードキュメントは /.well-known/oauth-authorization-server と /.well-known/oauth-protected-resource にあります。

詳細：認証。

構築を始める前に知っておくべきこと

• 予約を変更するAPI呼び出しでは Idempotency-Key を指定できます。 同じキーで再試行してください。新しいキーを使うと、2件目の予約が作成されます。キーはトークンに紐づくユーザーと、1つのエンドポイントに紐づきます。
• PATCH /v1/bookings/{uid} はETagを使用します。 ETagを読み取り、If-Match として送り返してください。同時に編集が行われた場合は、上書きが黙って行われるのではなく、エラーが明示されます。
• 現時点ではテスト環境がありません。 書き込み操作は本番環境に対して実行され、実際のメールを送信し、実際のカレンダーイベントを作成します。ご自身が所有するイベントタイプでテストし、終了後は後片付けをしてください。（ヘルプページで使われている「sandbox」は別のもの、つまりWebhookサブスクリプションの認証情報ごとの分離を指します。）
• レスポンスに未知のフィールドがあっても無視してください。 通知なしにフィールドが追加されることがあります。完全なバージョニングポリシーと6か月の廃止予告保証については、CHANGELOG.md をご覧ください。

サポート

APIのバグ、仕様の誤り、プラグインの問題については、issue を作成してください。セキュリティに関する報告は、issueトラッカーではなく [email protected] までお寄せください。SECURITY.md をご覧ください。

ライセンス

MITです。LICENSE をご覧ください。