From c857c7bee4487e29e7feb4ff1b7d0bf344acf929 Mon Sep 17 00:00:00 2001 From: Claude Lin & Lay Date: Mon, 3 Aug 2026 10:40:02 +0900 Subject: [PATCH 1/2] docs: document the client restart as the last stage of the release delivery chain MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A release that reaches the npm registry has not reached a running client yet. npx resolves the package version once, at process start, so an already-running MCP client keeps the version it launched with regardless of what the registry serves. That stage sits outside CD and was documented nowhere, so a release report ending at "the registry returns the new version" reports an undelivered change as delivered -- which inverts the verdict for releases whose whole point is a proxy static-schema change. - README.md / docs/Home.md / mcp-server/README.md: an Updating section stating that the MCP client (Claude Desktop, Claude Code, Codex) has to be restarted to pick up a new release, and that `npm view --prefer-online` is the check to use because the npm CLI caches registry metadata and can report the previous version right after a publish. - docs/0-requirements.md / docs/0-requirements.ja.md: a "配送鎖と完了条件" subsection under CI/CD carrying the full chain (merge -> gh release create -> CD npm-publish -> registry latest -> client restart -> npx resolve) and the completion criterion that registry update is not where release completion is judged. - docs/0-requirements.ja.md: its CD trigger table and release flow still described the retired `v*` tag-push trigger. Aligned with cd.yml (release published, attach-mcpb, gh release create) so the file does not contradict the subsection added below it. 書けるのは「再起動が要る」という事実と確認手段までとし、npx のキャッシュ解決挙動そのものは 本リポジトリの管理外として規定しない。根拠は v0.11.9 リリース直後の実測（registry は 0.11.9、 npx キャッシュの実体は 3 ディレクトリすべて 0.11.8、Claude Desktop 再起動後に新規ディレクトリ へ 0.11.9 取得）で、これを本文に残した。 Closes #247 --- README.md | 16 ++++++++++++++++ docs/0-requirements.ja.md | 39 +++++++++++++++++++++++++++++++++------ docs/0-requirements.md | 27 +++++++++++++++++++++++++++ docs/Home.md | 10 ++++++++++ mcp-server/README.md | 20 ++++++++++++++++++++ 5 files changed, 106 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index f13ca86..b9d1c6f 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,22 @@ 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.** On +restart, npx fetches the new version into a fresh cache directory; the old cache directories stay +behind on the previous 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 index 5ce38a5..e6234d8 100644 --- 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、npx キャッシュ内の実体は 3 ディレクトリすべて 0.11.8 のまま。Claude Desktop +再起動後、新規ディレクトリに 0.11.9 が取得された）。 + +したがって **「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 index a90ed74..1aa8528 100644 --- 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、npx キャッシュ内の実体は 3 ディレクトリすべて 0.11.8 のまま。Claude Desktop +再起動後、新規ディレクトリに 0.11.9 が取得された）。 + +したがって **「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 index 0e80a4c..e247808 100644 --- 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）を再起動してください。** 再起動すると npx が新しいバージョンを新規のキャッシュディレクトリに取得します（以前のキャッシュディレクトリは旧バージョンのまま残り、選択されなくなるだけです）。 + +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 index e6c2fb9..462934c 100644 --- a/mcp-server/README.md +++ b/mcp-server/README.md @@ -51,6 +51,26 @@ 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:///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.** On restart npx fetches the new version into a fresh +cache directory; the cache directories used before keep the old version and are simply no longer +selected. + +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 From 2e1d05b516e900e03b16490001b9f891078a1067 Mon Sep 17 00:00:00 2001 From: Claude Lin & Lay Date: Mon, 3 Aug 2026 10:44:20 +0900 Subject: [PATCH 2/2] docs: drop the npx cache-directory mechanics from the delivery-chain section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Self-review found the claim false. Every surface said a restart fetches the new version into a *fresh* cache directory while the old directories stay behind on the previous version. Before/after measurement on the same machine shows the same three directories in both states: none was created, and the live one (70bf1377065b9d0a) was updated in place with an mtime at the restart moment. The other two are untouched leftovers from mid-July that were never the live directory, so "the old directories are no longer selected" describes a selection event that did not happen. Removed rather than corrected, on two grounds. The section's own stated boundary puts npx cache resolution outside this repository's scope, so describing the mechanics contradicted the paragraph three lines below it. And it is not load-bearing: a reader needs "restart to pick up a new release" and "check the registry with --prefer-online", and the mechanism by which npx stores the package changes neither instruction. - README.md / mcp-server/README.md / docs/Home.md: the cache-directory sentence is replaced by the fact it was there to support -- the restart is what moves the client onto the new version. - docs/0-requirements.md / docs/0-requirements.ja.md: the parenthetical measurement now states only what was observed at the delivery level (the registry served 0.11.9 while the running client stayed on 0.11.8, and the restart is what changed it). npm CLI が registry メタデータをキャッシュする件（`--prefer-online` を付ける理由）は 別軸の実測であり、そのまま残している。誤りはパッケージ格納側の機構についての記述に 限られる。 Refs #247 --- README.md | 5 ++--- docs/0-requirements.ja.md | 4 ++-- docs/0-requirements.md | 4 ++-- docs/Home.md | 2 +- mcp-server/README.md | 5 ++--- 5 files changed, 9 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index b9d1c6f..c27ca7f 100644 --- a/README.md +++ b/README.md @@ -59,9 +59,8 @@ See the [Installation wiki page](https://github.com/Liplus-Project/github-webhoo 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.** On -restart, npx fetches the new version into a fresh cache directory; the old cache directories stay -behind on the previous version. +**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: diff --git a/docs/0-requirements.ja.md b/docs/0-requirements.ja.md index e6234d8..59a72f8 100644 --- a/docs/0-requirements.ja.md +++ b/docs/0-requirements.ja.md @@ -257,8 +257,8 @@ merge → gh release create → CD (npm-publish) → registry の latest 更新 後半 2 段は CD の外側にあり、リポジトリ側からは実行できない。npx がパッケージのバージョンを解決するの はプロセス起動時の一度きりであり（クライアント設定で `@latest` を指定していても同じ）、すでに起動して いるプロセスは registry がどう変わっても起動時のバージョンを保持し続ける（v0.11.9 のリリース直後に実 -測: registry は 0.11.9、npx キャッシュ内の実体は 3 ディレクトリすべて 0.11.8 のまま。Claude Desktop -再起動後、新規ディレクトリに 0.11.9 が取得された）。 +測: registry が 0.11.9 を返している間、稼働中のクライアントは 0.11.8 のままだった。0.11.9 に移ったの +は Claude Desktop を再起動した時点である）。 したがって **「registry が新版を返す」はリリース完了の判定基準にならない**。特にプロキシの静的ツール スキーマを変更したリリースは、利用側プロセスが再起動して初めて成果が現れる。リリース完了報告を diff --git a/docs/0-requirements.md b/docs/0-requirements.md index 1aa8528..de6ea15 100644 --- a/docs/0-requirements.md +++ b/docs/0-requirements.md @@ -297,8 +297,8 @@ merge → gh release create → CD (npm-publish) → registry の latest 更新 後半 2 段は CD の外側にあり、リポジトリ側からは実行できない。npx がパッケージのバージョンを解決するの はプロセス起動時の一度きりであり（クライアント設定で `@latest` を指定していても同じ）、すでに起動して いるプロセスは registry がどう変わっても起動時のバージョンを保持し続ける（v0.11.9 のリリース直後に実 -測: registry は 0.11.9、npx キャッシュ内の実体は 3 ディレクトリすべて 0.11.8 のまま。Claude Desktop -再起動後、新規ディレクトリに 0.11.9 が取得された）。 +測: registry が 0.11.9 を返している間、稼働中のクライアントは 0.11.8 のままだった。0.11.9 に移ったの +は Claude Desktop を再起動した時点である）。 したがって **「registry が新版を返す」はリリース完了の判定基準にならない**。特にプロキシの静的ツール スキーマを変更したリリースは、利用側プロセスが再起動して初めて成果が現れる。リリース完了報告を diff --git a/docs/Home.md b/docs/Home.md index e247808..160fba4 100644 --- a/docs/Home.md +++ b/docs/Home.md @@ -49,7 +49,7 @@ GitHub --POST--> Cloudflare Worker --> Durable Object (SQLite) ## 更新 -公開されたリリースは、稼働中のクライアントに自動では届きません。npx がパッケージのバージョンを解決するのはプロセス起動時の一度きりで（クライアント設定で `@latest` を指定していても同じです）、すでに起動しているクライアントは registry が何を返すようになっても起動時のバージョンを保持し続けます。**新しいリリースを反映するには MCP クライアント（Claude Desktop / Claude Code / Codex）を再起動してください。** 再起動すると npx が新しいバージョンを新規のキャッシュディレクトリに取得します（以前のキャッシュディレクトリは旧バージョンのまま残り、選択されなくなるだけです）。 +公開されたリリースは、稼働中のクライアントに自動では届きません。npx がパッケージのバージョンを解決するのはプロセス起動時の一度きりで（クライアント設定で `@latest` を指定していても同じです）、すでに起動しているクライアントは registry が何を返すようになっても起動時のバージョンを保持し続けます。**新しいリリースを反映するには MCP クライアント（Claude Desktop / Claude Code / Codex）を再起動してください。** クライアントが新しいバージョンに移るのは、この再起動によってです。 registry 側の確認には `--prefer-online` を付けてください。npm CLI は registry のメタデータをキャッシュするため、publish 直後の `npm view` は旧バージョンを返すことがあります。 diff --git a/mcp-server/README.md b/mcp-server/README.md index 462934c..6d1cfa5 100644 --- a/mcp-server/README.md +++ b/mcp-server/README.md @@ -56,9 +56,8 @@ Sign in on GitHub (2FA works as usual), approve access, and close the tab when t 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.** On restart npx fetches the new version into a fresh -cache directory; the cache directories used before keep the old version and are simply no longer -selected. +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