⚙️

ActVer の技術解説 — Cloudflare Workers + MCP + Claude Code スキル設計

2026/03/24に公開

GitHub Actions

Cloudflare

Model Context Protocol

Hono

Claude Code

tech

この記事は GitHub Actions の最新バージョン・SHA をサクッと引ける ActVer の技術解説です。使い方は 前回の記事 をどうぞ。
https://actver.dev

 全体アーキテクチャActVer は Cloudflare Workers 上で動作しています。各コンポーネントを順に見ていきましょう。

 REST API (Hono)API は Hono で構築しています。代表的なエンドポイントは 1 つだけです。
GET /v1/actions/{owner}/{repo}
リクエストが来ると、まず KV キャッシュを確認します。キャッシュヒットすればそのまま返し、ミスした場合は GitHub API にフォールバックして結果を KV に保存します。
エラーレスポンスは RFC 9457 Problem Details を参考にしたフォーマットで返しています。

 KV キャッシュ戦略
TTL: 15 分

CDN: stale-while-revalidate 1 時間
※ 2026 年 3 月時点の値です。今後変更する可能性があります。
GitHub API のレート制限を気にせず高速応答するために、2 段のキャッシュを設けています。KV の TTL が切れても CDN の stale-while-revalidate が効くため、ほとんどのリクエストはキャッシュから返ります。

 Cron Trigger によるプリフェッチ1 時間ごとに Cron Trigger が起動し、プリフェッチリストに登録されたアクションの最新情報を GitHub API から取得して KV に保存します。これにより、人気のあるアクション（actions/checkout, actions/setup-node など）は常にキャッシュが温まった状態になります。

 Analytics Engine による自動管理Cloudflare Analytics Engine でリクエスト数を計測しています。
1 週間のリクエスト数がしきい値以上: 自動的にプリフェッチリストに追加
1 週間のリクエスト数がしきい値未満: 自動的にプリフェッチリストから削除
手動でリストを管理する必要はありません。

 MCP サーバー
 StreamableHTTP を選んだ理由MCP のトランスポートには複数の選択肢がありますが、ActVer では StreamableHTTP を採用しました。
ActVer の MCP はバージョン情報を問い合わせて返すだけで、セッション状態を持つ必要がありません。ステートレスな HTTP リクエスト/レスポンスで完結するので、StreamableHTTP が最もシンプルな選択肢でした。


トランスポート
特徴


stdio
ローカルプロセスが必要。ユーザー側でインストールが必要

SSE
MCP SDK v2 でサーバー側は廃止。StreamableHTTP への移行が推奨

StreamableHTTP
ステートレス。Workers 上でそのまま動作。設定は URL だけ

ユーザー側はローカルプロセスを起動する必要がなく、.mcp.json に URL を追加するだけで使えます。後述しますが、プラグインに .mcp.json を同梱しているので、プラグインをインストールするだけで MCP サーバーへの接続も完了します。

 Workers 上での同居MCP サーバーは REST API と同じ Workers 上でパス (/mcp) を分けて動作しています。別途デプロイする必要がないため、運用コストを抑えられます。

 提供ツール

ツール
説明


get_action_version
指定アクションの最新バージョン・SHA を取得

list_action_versions
全メジャーバージョンの一覧を取得

この 2 つだけで、スキルが必要とする情報は揃います。

 Claude Code スキル設計
 3 スキルの補完関係audit（発見）→ pin（SHA 固定）→ upgrade（バージョン更新）
3 つのスキルは独立して使えますが、補完関係を持たせています。

audit-actions: ワークフローのセキュリティ問題を検出。タグ参照のアクションが見つかれば pin-actions へ、古いバージョンが見つかれば upgrade-actions へハンドオフ

pin-actions: ActVer の get_action_version で最新 SHA を取得し、ワークフローファイルを書き換え

upgrade-actions: ActVer の list_action_versions でメジャーバージョン一覧を取得し、最新版にアップグレード
たとえば audit-actions の SKILL.md には、問題を見つけたら pin-actions や upgrade-actions にハンドオフするよう記述してあります。

 SKILL.md の description 設計スキルが正しく発火するためには、description のトリガーフレーズが重要です。
---
name: pin-actions
description: This skill should be used when the user asks to pin GitHub Actions
  to commit SHAs, secure workflows against supply-chain attacks, replace action
  tags with SHAs, harden GitHub Actions, fix Scorecard pinned-dependencies
  findings, or lock action versions. Triggers on phrases like "pin actions",
  "SHA pin", "secure workflows", "harden workflows", "lock action versions",
  "replace tags with SHAs".
---
※ 上記は執筆時点の例です。最新の内容はリポジトリを参照してください。
意識したポイント：

三人称: "This skill should be used when..." で始める

5 つ以上のトリガーフレーズ: ユーザーが使いそうな表現を網羅

同義語のカバー: "pin"、"secure"、"harden"、"lock" など類似の表現を含める

具体的な文脈: "fix Scorecard pinned-dependencies findings" のように具体的なユースケースも記述
description の品質は anthropics/claude-plugins-official のプラグインを使ってチェック・修正しています。skill-creator で description の最適化やベンチマーク、plugin-dev の skill-reviewer エージェントでトリガーフレーズの網羅性やスキル間の重複チェックができるので便利です。

 プラグインとしての配布スキルは actver-dev/skills リポジトリで Claude Code プラグインとして配布しています。
actver-dev/skills/
├── .claude-plugin/
│   └── marketplace.json      # マーケットプレイス登録
├── plugins/actver/
│   ├── .claude-plugin/
│   │   └── plugin.json       # プラグインメタデータ
│   ├── .mcp.json              # MCP サーバー接続設定
│   ├── agents/actver.md       # エージェント定義
│   └── skills/ → ../../skills/  # シンボリックリンク
└── skills/
    ├── pin-actions/
    │   ├── SKILL.md
    │   └── references/
    ├── upgrade-actions/
    │   └── ...
    └── audit-actions/
        └── ...
plugins/actver/skills/ は skills/ へのシンボリックリンクになっています。これにより、Claude Code プラグインと skills.sh の両方でスキルを配布できます。
ポイントは .mcp.json をプラグインに同梱していることです。claude plugin install actver を実行すると、スキルのインストールと同時に ActVer の MCP サーバーへの接続設定も完了します。ユーザーが手動で .mcp.json を編集する必要はありません。この仕組みは sentry プラグインの実装を参考にしました。

 CI / 品質管理
 ルールベースバリデーションscripts/validate.sh で以下をチェックしています。
必須ファイルの存在確認
JSON バリデーション（marketplace.json, plugin.json, .mcp.json）
SKILL.md / Agent の frontmatter 検証（name, description 必須）
description の最低文字数（20 文字以上）
相対リンク切れチェック
ファイルマニフェスト一致確認

 LLM ベースの品質チェックルールベースでは判定しにくい「description のトリガー精度」や「スキル間のトリガー重複」を、Claude Sonnet によるレビューで補完しています。
pull_request_target + GitHub Actions の environment 保護ルールにより、fork PR でも承認制で LLM チェックを実行できます。

 SHA ピン留めの dogfoodingActVer 自身のワークフローでも、すべてのアクションを SHA ピン留めしています。
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- uses: anthropics/claude-code-action@6062f3709600659be5e47fcddf2cf76993c235c2 # v1.0.76
前回の記事で書いた「Allow を何度も押す」問題はもう発生しません🙌

 まとめActVer は「AI エージェントが GitHub Actions のバージョン情報を簡単に取得できる」というシンプルな課題に対して、以下の技術選択をしています。


技術
選択理由


Cloudflare Workers
エッジで低遅延、サーバーレス運用

Hono
Workers ネイティブ、軽量

KV + Cron
GitHub API レート制限を回避する 2 段キャッシュ

StreamableHTTP
Workers 上で MCP サーバーが動作、設定は URL だけ

Claude Code Skills
自然言語でのワークフロー操作


Web UI: actver.dev

プラグイン & スキル: actver-dev/skills
すべて無料で利用できます。もし気に入っていただけたら、サポートいただけると嬉しいです！
この記事にバッジを送る（Zenn）
Product Hunt で応援する
Buy Me a Coffee
GitHub Sponsors

トランスポート	特徴
stdio	ローカルプロセスが必要。ユーザー側でインストールが必要
SSE	MCP SDK v2 でサーバー側は廃止。StreamableHTTP への移行が推奨
StreamableHTTP	ステートレス。Workers 上でそのまま動作。設定は URL だけ

ツール	説明
`get_action_version`	指定アクションの最新バージョン・SHA を取得
`list_action_versions`	全メジャーバージョンの一覧を取得

技術	選択理由
Cloudflare Workers	エッジで低遅延、サーバーレス運用
Hono	Workers ネイティブ、軽量
KV + Cron	GitHub API レート制限を回避する 2 段キャッシュ
StreamableHTTP	Workers 上で MCP サーバーが動作、設定は URL だけ
Claude Code Skills	自然言語でのワークフロー操作

全体アーキテクチャ

REST API (Hono)

KV キャッシュ戦略

Cron Trigger によるプリフェッチ

Analytics Engine による自動管理

MCP サーバー

StreamableHTTP を選んだ理由

Workers 上での同居

提供ツール

Claude Code スキル設計

3 スキルの補完関係

SKILL.md の description 設計

プラグインとしての配布

CI / 品質管理

ルールベースバリデーション

LLM ベースの品質チェック

SHA ピン留めの dogfooding

まとめ

Discussion