# github-changelog-mcp

An [MCP](https://modelcontextprotocol.io) server that turns raw GitHub commit
history into a categorized, human-readable changelog — directly inside
Claude (or any MCP-compatible client).

```
You: "Generate a changelog for expressjs/express between v4.18.0 and v4.19.0"

Claude: [calls generate_changelog tool]

## expressjs/express: v4.18.0 → v4.19.0

### Features
- add support for X-Forwarded-Host header (`a1b2c3d`) — @wesleytodd

### Bug Fixes
- prevent ReDoS in query parser (`b2c3d4e`) — @cdoublev

### Chores
- bump path-to-regexp to 0.1.10 (`c3d4e5f`) — @dependabot
```

No paid APIs. No API keys required to get started (an optional free GitHub
token just raises the rate limit).

## Why this exists

Writing release notes by hand is tedious and usually done by skimming
`git log` and manually sorting commits into categories. This tool automates
that: it fetches the commit diff between two refs via GitHub's public REST
API, classifies each commit ([Conventional Commits](https://www.conventionalcommits.org/)
prefix first, keyword heuristics as a fallback), filters out merge-commit
noise, and renders clean grouped Markdown — as a tool Claude can call
directly in conversation.

## Tools

| Tool                 | Description                                                                                        |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| `list_tags`          | List recent tags for a public repo (use this to find valid ref names)                              |
| `compare_refs`       | Raw commit diff between two refs, uncategorized                                                    |
| `generate_changelog` | The main tool — categorized Markdown changelog between two refs, with optional contributor summary |

## Setup

```bash
git clone https://github.com/SiwarKhalfaoui/github-changelog-mcp.git
cd github-changelog-mcp
npm install
npm run build
```

Optional — raise the GitHub API rate limit from 60/hr to 5,000/hr:

```bash
cp .env.example .env
# add a free token from https://github.com/settings/tokens (no scopes needed)
```

## Connect it to Claude Desktop

Add this to your Claude Desktop config
(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
`%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "github-changelog": {
      "command": "node",
      "args": ["/absolute/path/to/github-changelog-mcp/build/index.js"],
      "env": {
        "GITHUB_TOKEN": "optional-token-here"
      }
    }
  }
}
```

Restart Claude Desktop. You should see a 🔨 tools icon confirming the server
connected — then just ask Claude to generate a changelog for any public repo.

## Development

```bash
npm run dev              # run directly with tsx, no build step
npm run test:changelog   # run the categorization logic test suite
```

## Architecture notes

- `src/github.ts` — thin GitHub REST API wrapper. No SDK dependency, just
  `fetch` + a shared header builder. Handles rate-limit errors explicitly
  and surfaces an actionable message (which token to add, when the limit
  resets) rather than a raw HTTP error.
- `src/changelog.ts` — the actual logic: Conventional Commits parsing with
  a keyword-based fallback for repos that don't use that convention, merge
  commit filtering, and Markdown rendering.
- `src/index.ts` — MCP server wiring (tool registration, schemas via `zod`,
  stdio transport).

Kept intentionally dependency-light — GitHub's REST API and MCP's official
SDK are the only two runtime dependencies. No frameworks, no ORMs, no
unnecessary abstraction for a tool this size.

## Possible extensions

- Group changelog entries by scope (`feat(auth): ...` → group under "Auth")
  in addition to type
- Compare against **unreleased** commits (`to_ref` = default branch) and
  suggest the next semver bump based on commit types present
- Cache `compareRefs` responses per (owner, repo, base, head) to reduce
  API calls on repeated queries in the same session

## License

MIT