release-notes-mcp

release-notes-mcp

複数のリポジトリの GitHub リリースを、1 つの製品リリースノートにまとめる、小規模で汎用的な MCP サーバーです。サーバーは生データを取得してまとめるだけで、最終的なノートは LLM が作成します。

特定のアーキテクチャには依存しません。

• provider — リリースを取得する forge：github（デフォルト）、gitlab、または gitea/Forgejo。リリースの取得には小さなアダプターを使用するため、forge の追加はリリース JSON の正規化だけで済みます。変更範囲も限定的です。
• repos — サーバーがリリースを読み取ることを許可されているリポジトリ。
• contextSources — 背景情報として読み込む任意の URL（スタイルガイド、バージョンファイル、機能名など、内容は問いません）。サーバーは意味を割り当てません。各ソースが何であるかは、URL の先に何を置くかによって決まります。

設定

設定にシークレットは含まれません。リポジトリの一覧とコンテキストのみです。プロバイダーと認証情報は環境変数で指定します。

// config.json — non-sensitive (required; the server errors if it's missing)
{
  "repos": [
    "myorg/auth-service",
    "myorg/web"
  ],
  "contextSources": [
    {
      "name": "release-info",
      "url": "https://example.github.io/whatever/release.json",
      "description": "Extra context to consult when assembling release notes"
    }
  ]
}

環境変数（プロバイダーに依存しません。.env またはシェルで設定します）：

Var	用途	デフォルト
TOKEN	プロバイダーの認証トークン — 設定には絶対に含めないでください	(空。公開リポジトリなら問題ありません)
PROVIDER	github | gitlab | gitea（設定を上書きします）	github
BASE_URL	API のベース URL — セルフホストの GitLab / Gitea の場合のみ	プロバイダーのデフォルト

• コンテキストソースの format は任意です。Content-Type／URL の拡張子／コンテンツの判定から自動検出されます。検出結果が正しくない場合にのみ上書きしてください。

トークンの権限

サーバーが行うのはリリースの読み取り（GET /repos/{owner}/{repo}/releases…）のみです。そのため、TOKEN には必要最小限の読み取りスコープを付与し、書き込み権限は決して与えないでください。

プロバイダー	公開リポジトリ	非公開リポジトリ
GitHub — fine-grained PAT	トークン不要	各リポジトリに対して Contents: Read-only（リリースは Contents 配下にあります）
GitHub — classic PAT	トークン不要（または public_repo）	repo スコープ
GitLab	トークン不要	read_api スコープ
Gitea / Forgejo	トークン不要	read:repository スコープ

GitHub では、config.json に記載したリポジトリだけを対象に、Contents → Read-only を設定した fine-grained PAT が最も権限を絞った方法であり、このサーバーに必要な権限はこれだけです。

設定（repos + contextSources）は、次の 2 つの場所のいずれかから指定する必要があります。どちらも設定されていない場合、サーバーは起動時にエラーになります。

ソース	用途
RELEASE_MCP_CONFIG_JSON	設定をインライン JSONで指定します。ファイルは不要です。すべてを環境変数で設定する uvx や MCP ハブに最適です。
RELEASE_MCP_CONFIG	config.json ファイルへのパス（デフォルトは ./config.json）。実際のファイルをマウントするコンテナーで使用します。

両方が設定されている場合は、インライン JSON が優先されます。ファイルを使用する場合は、config.example.json をコピーして始めてください。

ツール

ツール	用途
list_repos()	設定済みのリポジトリ
list_releases(repo, limit)	1 つのリポジトリの最近のリリース
get_latest_version(repo)	1 つのリポジトリの最新リリース
get_release(repo, tag)	指定したタグの完全なノート
compare_releases(repo, from_tag, to_tag)	2 つのバージョン間のすべてのリリース
gather_release_notes(selections[])	N 組の (repo, tag) から生のノートをまとめます（並行処理）
get_context(name?)	設定済みのコンテキスト URL を読み込みます（形式は自動検出）

選択は動的です。結合する (repo, tag) の組は、ユーザー（または Claude）が渡します。サーバーの instructions は、最初に get_context() を呼び出すよう Claude に指示します。

実行

サーバーはコンテナー内で HTTP transport を使用し、localhost:8000 で実行されます。まず設定ファイルと環境変数ファイルを作成してください（どちらの実行方法でも必要です）。

cp config.example.json config.json   # edit repos + contextSources (no secrets)
cp .env.example .env                  # set TOKEN (+ PROVIDER / BASE_URL if needed)

通常実行

docker compose up -d

ローカル開発 — docker compose watch

ローカル開発では、docker compose watch を使うと、編集しながらサーバーを起動したままにできます。

docker compose watch

変更	動作
server.py	同期＋再起動 — コンテナにコピーされ、プロセスが再起動します
requirements.txt、Dockerfile	再ビルド — イメージが自動的に再ビルドされます
config.json	バインドマウント（リアルタイム反映）です。再読み込みするには docker compose restart を実行してください

uvx で実行する（クローン不要、コンテナ不要）

サーバーは PyPI に公開されているため、クライアントは uvx を使って必要に応じて起動できます。チェックアウトも Docker も不要です。

uvx release-notes-mcp

uvx は stdio（デフォルトのトランスポート）経由でサーバーと通信します。 マウントするファイルがないため、RELEASE_MCP_CONFIG_JSON を使って設定を JSON としてインラインで渡してください （すべて環境変数のみで設定でき、MCP ハブに最適です）。

RELEASE_MCP_CONFIG_JSON='{"repos":["myorg/web"],"contextSources":[]}' \
  TOKEN=ghp_... uvx release-notes-mcp

ファイルを使用する場合は、代わりに RELEASE_MCP_CONFIG に絶対パスを指定してください （uvx は作業ディレクトリが不明な状態で実行されるため、相対パスでは解決できません）。

RELEASE_MCP_CONFIG=/abs/path/config.json TOKEN=ghp_... uvx release-notes-mcp

Claude Code に登録する

HTTP（コンテナ） — 実行中のサーバーの URL を Claude Code に指定します。

claude mcp add --transport http release-notes http://localhost:8000/mcp

stdio（uvx） — Claude Code にサブプロセスとしてサーバーを起動させます。

claude mcp add release-notes \
  --env RELEASE_MCP_CONFIG=/abs/path/config.json \
  --env TOKEN=ghp_... \
  -- uvx release-notes-mcp

次に Claude にこう依頼します。「auth-service と web の最新リリースをまとめて、プロダクトのリリースノートを作成してください。」