release-notes-mcp

release-notes-mcp

一个小巧、通用的 MCP 服务，可将多个仓库的 GitHub 发布记录合并为一份产品发布说明。服务只负责获取并打包原始数据；最终说明由大模型综合生成。

不依赖特定架构：

• provider — 要从哪个代码托管平台读取发布记录：github（默认）、gitlab 或 gitea/Forgejo。发布记录通过一个小型适配器获取，因此添加代码托管平台只需规范化其发布记录 JSON——改动范围有限。
• repos — 服务获准读取发布记录的仓库。
• contextSources — 用作背景上下文的任意 URL（风格指南、版本文件、功能名称等）。服务不会赋予它们任何含义；每个来源代表什么，取决于你在 URL 后提供的内容。

配置

配置中不包含任何密钥——只有仓库列表和上下文。Provider 和身份验证信息来自环境变量。

// 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"
    }
  ]
}

环境变量（与 provider 无关，在 .env 或 shell 中设置）：

变量	用途	默认值
TOKEN	Provider 的身份验证令牌——绝不能放在配置中	(空；公开仓库可用)
PROVIDER	github | gitlab | gitea（覆盖配置）	github
BASE_URL	API 基础 URL——仅用于可自托管的 GitLab / Gitea	provider 默认值

• 上下文来源中的 format 可选——会根据 Content-Type / URL 扩展名 / 内容嗅探自动检测。仅在检测结果错误时覆盖。

令牌权限

服务只会读取发布记录（GET /repos/{owner}/{repo}/releases…），因此请为 TOKEN 授予最低限度的读取权限——绝不能授予写入权限。

Provider	公开仓库	私有仓库
GitHub — 细粒度 PAT	无需令牌	Contents：只读（发布记录归属 Contents），需针对你列出的每个仓库
GitHub — 经典 PAT	无需令牌（或使用 public_repo）	repo scope
GitLab	无需令牌	read_api scope
Gitea / Forgejo	无需令牌	read:repository scope

对于 GitHub，使用一个仅限 config.json 中所列仓库且具有 Contents → 只读权限的细粒度 PAT，是权限最精简的配置，也是此服务所需的全部权限。

配置（repos + contextSources）必须来自以下两个来源之一——如果两者都未设置，服务会在启动时出错：

来源	用途
RELEASE_MCP_CONFIG_JSON	将配置作为内联 JSON提供。无需文件——适合所有内容都通过环境变量设置的 uvx / MCP Hub。
RELEASE_MCP_CONFIG	config.json 文件的路径（默认 ./config.json）。供挂载实际文件的容器使用。

两者都设置时，内联 JSON 优先。复制 config.example.json 即可开始使用文件配置方式。

工具

工具	用途
list_repos()	列出已配置的仓库
list_releases(repo, limit)	获取一个仓库的近期发布记录
get_latest_version(repo)	获取一个仓库的最新发布版本
get_release(repo, tag)	获取一个标签对应的完整说明
compare_releases(repo, from_tag, to_tag)	获取两个版本之间的所有发布记录
gather_release_notes(selections[])	汇总 N 个 (repo, tag) 对应的原始说明（并发）
get_context(name?)	加载已配置的上下文 URL（格式自动检测）

选择是动态的——你（或 Claude）可以传入要合并的 (repo, tag) 对。服务的 instructions 会告诉 Claude 首先调用 get_context()。

运行

服务通过容器在 localhost:8000 上使用 HTTP 传输运行。 首先创建配置文件和环境变量文件（两种运行方式都需要）：

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 hub）：

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 的最新发布内容合并成一份产品发布说明。"