Liplus-Project · liplus-lin-lay · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026
diff --git a/README.md b/README.md
@@ -54,6 +54,21 @@ See the [Installation wiki page](https://github.com/Liplus-Project/github-webhoo
 - **MCP Client Setup** for Claude Desktop, Claude Code CLI, and Codex
 - **Self-Hosting Guide** for Cloudflare Workers deployment
 
+## Updating
+
+A published release does not reach a running client on its own. npx resolves the package version
+once, when the process starts — including when the client config pins `@latest` — so an MCP client
+that is already running keeps the version it started with no matter what the registry serves.
+**Restart the MCP client (Claude Desktop, Claude Code, Codex) to pick up a new release.** The
+restart is what moves the client onto the new version.
+
+Check what the registry actually has with `--prefer-online`. The npm CLI caches registry metadata,
+so a bare `npm view` can still report the previous version shortly after a publish:
+
+```bash
+npm view github-webhook-mcp version --prefer-online
+```
+
 ## Usage Examples
 
 ### Example 1: Check pending webhook status

diff --git a/docs/0-requirements.ja.md b/docs/0-requirements.ja.md
@@ -237,16 +237,43 @@ Worker は GitHub の web OAuth flow をホストする独自実装を備える
 
 | トリガー | ジョブ | 内容 |
 |---------|--------|------|
-| `v*` タグ push | build-mcpb | `mcpb pack` で .mcpb 生成 |
-| `v*` タグ push | release | GitHub Release 作成 + .mcpb 添付 |
-| `v*` タグ push | npm-publish | npm レジストリに公開 |
+| release published | build-mcpb | `mcpb pack` で .mcpb 生成 |
+| release published | attach-mcpb | `gh release upload` で .mcpb をリリースに添付（build-mcpb 後） |
+| release published | npm-publish | npm レジストリに公開 |
 
 リリースフロー:
-1. `v*` タグを push する
-2. CD が自動実行: .mcpb 生成 → release 作成 → .mcpb 添付 → npm publish
-3. npm publish 時にタグ名から自動でバージョンを同期する（package.json の手動更新不要）
+1. AI が `gh release create` でリリースを作成する（PAT 経由で release イベントが発火する）
+2. Release published イベントで CD ワークフローが発火: .mcpb 生成 → .mcpb リリース添付 → npm publish
+3. npm publish 時にリリースタグ名から自動でバージョンを同期する（package.json の手動更新不要）
 4. プレリリースタグ（`-` を含む）は `next` dist-tag で公開、正式リリースは `latest` で公開
 
+### 配送鎖と完了条件
+
+```
+merge → gh release create → CD (npm-publish) → registry の latest 更新
+      → 利用側 MCP クライアントの再起動 → npx が新版を解決 → 利用側に到達
+```
+
+後半 2 段は CD の外側にあり、リポジトリ側からは実行できない。npx がパッケージのバージョンを解決するの
+はプロセス起動時の一度きりであり（クライアント設定で `@latest` を指定していても同じ）、すでに起動して
+いるプロセスは registry がどう変わっても起動時のバージョンを保持し続ける（v0.11.9 のリリース直後に実
+測: registry が 0.11.9 を返している間、稼働中のクライアントは 0.11.8 のままだった。0.11.9 に移ったの
+は Claude Desktop を再起動した時点である）。
+
+したがって **「registry が新版を返す」はリリース完了の判定基準にならない**。特にプロキシの静的ツール
+スキーマを変更したリリースは、利用側プロセスが再起動して初めて成果が現れる。リリース完了報告を
+registry の確認で締めると、届いていない状態を届いたと報告することになる。
+
+registry の確認には `--prefer-online` を付ける。npm CLI は registry のメタデータをキャッシュするため、
+publish 直後の `npm view github-webhook-mcp version` は旧版を返しうる（同じく v0.11.9 で実測）。
+
+```bash
+npm view github-webhook-mcp version --prefer-online
+```
+
+npx のキャッシュ解決挙動そのものは本リポジトリの管理外であり、規定できるのは
+「再起動が要る」という事実と上記の確認手段までとする。
+
 ## 依存関係
 
 ### Cloudflare Worker

diff --git a/docs/0-requirements.md b/docs/0-requirements.md
@@ -287,6 +287,33 @@ Node.js >= 18.0.0 が必要。
 
 manifest.json のバージョンも一致させる。
 
+### 配送鎖と完了条件
+
+```
+merge → gh release create → CD (npm-publish) → registry の latest 更新
+      → 利用側 MCP クライアントの再起動 → npx が新版を解決 → 利用側に到達
+```
+
+後半 2 段は CD の外側にあり、リポジトリ側からは実行できない。npx がパッケージのバージョンを解決するの
+はプロセス起動時の一度きりであり（クライアント設定で `@latest` を指定していても同じ）、すでに起動して
+いるプロセスは registry がどう変わっても起動時のバージョンを保持し続ける（v0.11.9 のリリース直後に実
+測: registry が 0.11.9 を返している間、稼働中のクライアントは 0.11.8 のままだった。0.11.9 に移ったの
+は Claude Desktop を再起動した時点である）。
+
+したがって **「registry が新版を返す」はリリース完了の判定基準にならない**。特にプロキシの静的ツール
+スキーマを変更したリリースは、利用側プロセスが再起動して初めて成果が現れる。リリース完了報告を
+registry の確認で締めると、届いていない状態を届いたと報告することになる。
+
+registry の確認には `--prefer-online` を付ける。npm CLI は registry のメタデータをキャッシュするため、
+publish 直後の `npm view github-webhook-mcp version` は旧版を返しうる（同じく v0.11.9 で実測）。
+
+```bash
+npm view github-webhook-mcp version --prefer-online
+```
+
+npx のキャッシュ解決挙動そのものは本リポジトリの管理外であり、規定できるのは
+「再起動が要る」という事実と上記の確認手段までとする。
+
 ## Distribution Channels
 
 | チャネル | 用途 | ステータス | 要件 |

diff --git a/docs/Home.md b/docs/Home.md
@@ -47,6 +47,16 @@ GitHub --POST--> Cloudflare Worker --> Durable Object (SQLite)
 - **MCP クライアント設定** — Claude Desktop、Claude Code CLI、Codex 向け
 - **セルフホスティングガイド** — Cloudflare Workers デプロイ
 
+## 更新
+
+公開されたリリースは、稼働中のクライアントに自動では届きません。npx がパッケージのバージョンを解決するのはプロセス起動時の一度きりで（クライアント設定で `@latest` を指定していても同じです）、すでに起動しているクライアントは registry が何を返すようになっても起動時のバージョンを保持し続けます。**新しいリリースを反映するには MCP クライアント（Claude Desktop / Claude Code / Codex）を再起動してください。** クライアントが新しいバージョンに移るのは、この再起動によってです。
+
+registry 側の確認には `--prefer-online` を付けてください。npm CLI は registry のメタデータをキャッシュするため、publish 直後の `npm view` は旧バージョンを返すことがあります。
+
+```bash
+npm view github-webhook-mcp version --prefer-online
+```
+
 ## MCP ツール
 
 | ツール | 説明 |

diff --git a/mcp-server/README.md b/mcp-server/README.md
@@ -51,6 +51,25 @@ Sign in on GitHub (2FA works as usual), approve access, and close the tab when t
 
 > **Configure the Callback URL on self-hosted GitHub Apps.** If you self-host the Worker with your own GitHub App, register `https://<your-worker>/oauth/callback` as the **Callback URL**. Without it, the Worker's `/oauth/callback` step fails with "Authorization failed" because GitHub will reject the redirect. **Device Flow** is not used and can stay off. See the [self-hosting guide](https://github.com/Liplus-Project/github-webhook-mcp/blob/main/docs/installation.md) for step-by-step instructions.
 
+## Updating
+
+npx resolves the package version once, at process start — including when the client config pins
+`@latest`. A client that is already running keeps the version it launched with, so a new npm
+release does not reach it until that process is replaced: **restart the MCP client (Claude Desktop,
+Claude Code, Codex) to pick up a new version.** The restart is what moves the client onto the new
+version.
+
+This matters most for releases that change the tool schemas the proxy advertises, because those
+schemas are served from the proxy's own code rather than fetched from the Worker — until the
+process restarts, the client keeps seeing the old tool definitions.
+
+Verify what the registry holds with `--prefer-online`. The npm CLI caches registry metadata, so a
+bare `npm view` can report the previous version shortly after a publish:
+
+```bash
+npm view github-webhook-mcp version --prefer-online
+```
+
 ## Client configuration
 
 ### Claude Desktop / Claude Code