feat(oauth): device flow UX — auto-browser + auth-required tool response (mcp-server, local-mcp)

docs/0-requirements.ja.md

@@ -158,6 +158,8 @@ Worker は OAuth 2.1 Device Authorization Grant を自前実装する（`@cloudf
 | F7.6 | 旧 `GET /oauth/authorize` および `GET /oauth/callback` は **HTTP 410 Gone** を返す（localhost callback flow は v0.11.0 で廃止） |
 | F7.7 | 保護対象 API ルート（`/mcp`, `/events`）は `Authorization: Bearer <access_token>` ヘッダによる独自 token 検証 middleware で認可する |
 | F7.8 | KV schema は自前設計: `client:{client_id}` / `device:{device_code}` / `user_code:{user_code}` / `token:{access_token}` / `refresh:{refresh_token}` / `grant:{grant_id}` |
+| F7.9 | ローカルブリッジは device authorization 応答受信直後に `verification_uri_complete`（なければ `verification_uri`）を platform 既定のブラウザで自動オープンする。Windows は `cmd /c start`、macOS は `open`、Linux は `xdg-open` を使う。オープン失敗は fatal にしない（stderr に警告を残し、URL は応答と stderr で伝える） |
+| F7.10 | ローカルブリッジは初回ツール呼び出しで device flow が完了していない場合、polling をバックグラウンドに維持したまま、`user_code` / `verification_uri_complete` / `verification_uri` / 残り有効秒数を本文に含む `isError: true` の構造化ツール応答を即座に返す。2 回目以降の同一ツール呼び出しは、承認完了なら通常処理、未完了なら同じ auth-required 応答を返す（ポーリングは 1 本に serialize） |
 
 **GitHub App 前提条件:**
 

docs/0-requirements.md

@@ -158,6 +158,8 @@ Worker は OAuth 2.1 Device Authorization Grant を自前実装する（`@cloudf
 | F7.6 | 旧 `GET /oauth/authorize` および `GET /oauth/callback` は **HTTP 410 Gone** を返す（localhost callback flow は v0.11.0 で廃止） |
 | F7.7 | 保護対象 API ルート（`/mcp`, `/events`）は `Authorization: Bearer <access_token>` ヘッダによる独自 token 検証 middleware で認可する |
 | F7.8 | KV schema は自前設計: `client:{client_id}` / `device:{device_code}` / `user_code:{user_code}` / `token:{access_token}` / `refresh:{refresh_token}` / `grant:{grant_id}` |
+| F7.9 | ローカルブリッジは device authorization 応答受信直後に `verification_uri_complete`（なければ `verification_uri`）を platform 既定のブラウザで自動オープンする。Windows は `cmd /c start`、macOS は `open`、Linux は `xdg-open` を使う。オープン失敗は fatal にしない（stderr に警告を残し、URL は応答と stderr で伝える） |
+| F7.10 | ローカルブリッジは初回ツール呼び出しで device flow が完了していない場合、polling をバックグラウンドに維持したまま、`user_code` / `verification_uri_complete` / `verification_uri` / 残り有効秒数を本文に含む `isError: true` の構造化ツール応答を即座に返す。2 回目以降の同一ツール呼び出しは、承認完了なら通常処理、未完了なら同じ auth-required 応答を返す（ポーリングは 1 本に serialize） |
 
 **GitHub App 前提条件:**
 

docs/installation.ja.md

@@ -17,17 +17,40 @@
 
 ### 初回認証（OAuth Device Flow）
 
-v0.11.0 以降、MCP クライアントは **OAuth 2.1 Device Authorization Grant (RFC 8628)** で認証します。初回接続時に以下のメッセージが Claude Code の stderr ログに出力されます:
+v0.11.0 以降、MCP クライアントは **OAuth 2.1 Device Authorization Grant (RFC 8628)** で認証します。v0.11.1 以降は初回のツール呼び出し時に以下が同時に起きます:
+
+1. **ブラウザが自動で開きます**（`verification_uri_complete`、コード事前入力済み URL）
+2. **ツール呼び出しの応答として `user_code` と URL が即座に返ります**（600 秒待たされません）
+
+Claude Code / Claude Desktop のチャット上には、おおよそ次のような応答が表示されます:
+
+```
+OAuth device authorization required.
+
+Open (code pre-filled): https://github.com/login/device?user_code=WDJB-MJHT
+
+Or visit https://github.com/login/device and enter the code:
+  WDJB-MJHT
+
+Code expires in about 10 minutes.
+A browser window should have opened automatically. Retry the same tool call
+after approving — subsequent calls will succeed once authorization completes.
+```
+
+ブラウザで承認するとバックグラウンドのポーリングが完了し、`~/.github-webhook-mcp/oauth-tokens.json` にトークンが保存されます。その後同じツールを呼び直すと通常どおり結果が返ります。以降の起動では保存済みトークンが再利用され、期限切れ前に自動でリフレッシュされます。
+
+並行して、stderr ログにも同じ情報が出力されます（ログを見たい場合のフォールバック）:
 
 ```
 [github-webhook-mcp] OAuth device authorization required.
 [github-webhook-mcp] Visit: https://github.com/login/device
 [github-webhook-mcp] Enter code: WDJB-MJHT
 [github-webhook-mcp] Or open directly: https://github.com/login/device?user_code=WDJB-MJHT
+[github-webhook-mcp] Opening browser for authentication...
 [github-webhook-mcp] Waiting for approval (expires in 600s)...
 ```
 
-ブラウザで `https://github.com/login/device` を開き、表示された 8 文字の `user_code` を入力してください。承認後、自動的にトークンが発行され、`~/.github-webhook-mcp/oauth-tokens.json` に保存されます。以降の起動では保存済みトークンが再利用され、期限切れ前に自動でリフレッシュされます。
+> **ブラウザ自動オープンが失敗した場合:** 応答と stderr ログに URL がそのまま残るので、手動でコピーしてブラウザに貼り付けてください。Windows では `start`、macOS では `open`、Linux では `xdg-open` を使用します。
 
 > **旧バージョンからの移行:** v0.10.x 以前の localhost callback flow を使っていた場合、初回起動時に旧トークンファイルが自動削除され、migration 通知が stderr に出力されます。表示される device code を入力して一度だけ再認証してください。
 

docs/installation.md

@@ -17,17 +17,40 @@
 
 ### 初回認証（OAuth Device Flow）
 
-v0.11.0 以降、MCP クライアントは **OAuth 2.1 Device Authorization Grant (RFC 8628)** で認証します。初回接続時に以下のメッセージが Claude Code の stderr ログに出力されます:
+v0.11.0 以降、MCP クライアントは **OAuth 2.1 Device Authorization Grant (RFC 8628)** で認証します。v0.11.1 以降は初回のツール呼び出し時に以下が同時に起きます:
+
+1. **ブラウザが自動で開きます**（`verification_uri_complete`、コード事前入力済み URL）
+2. **ツール呼び出しの応答として `user_code` と URL が即座に返ります**（600 秒待たされません）
+
+Claude Code / Claude Desktop のチャット上には、おおよそ次のような応答が表示されます:
+
+```
+OAuth device authorization required.
+
+Open (code pre-filled): https://github.com/login/device?user_code=WDJB-MJHT
+
+Or visit https://github.com/login/device and enter the code:
+  WDJB-MJHT
+
+Code expires in about 10 minutes.
+A browser window should have opened automatically. Retry the same tool call
+after approving — subsequent calls will succeed once authorization completes.
+```
+
+ブラウザで承認するとバックグラウンドのポーリングが完了し、`~/.github-webhook-mcp/oauth-tokens.json` にトークンが保存されます。その後同じツールを呼び直すと通常どおり結果が返ります。以降の起動では保存済みトークンが再利用され、期限切れ前に自動でリフレッシュされます。
+
+並行して、stderr ログにも同じ情報が出力されます（ログを見たい場合のフォールバック）:
 
 ```
 [github-webhook-mcp] OAuth device authorization required.
 [github-webhook-mcp] Visit: https://github.com/login/device
 [github-webhook-mcp] Enter code: WDJB-MJHT
 [github-webhook-mcp] Or open directly: https://github.com/login/device?user_code=WDJB-MJHT
+[github-webhook-mcp] Opening browser for authentication...
 [github-webhook-mcp] Waiting for approval (expires in 600s)...
 ```
 
-ブラウザで `https://github.com/login/device` を開き、表示された 8 文字の `user_code` を入力してください。承認後、自動的にトークンが発行され、`~/.github-webhook-mcp/oauth-tokens.json` に保存されます。以降の起動では保存済みトークンが再利用され、期限切れ前に自動でリフレッシュされます。
+> **ブラウザ自動オープンが失敗した場合:** 応答と stderr ログに URL がそのまま残るので、手動でコピーしてブラウザに貼り付けてください。Windows では `start`、macOS では `open`、Linux では `xdg-open` を使用します。
 
 > **旧バージョンからの移行:** v0.10.x 以前の localhost callback flow を使っていた場合、初回起動時に旧トークンファイルが自動削除され、migration 通知が stderr に出力されます。表示される device code を入力して一度だけ再認証してください。