Manage Keep a Changelog files — init, add entries, search, preview, version bump via @dwsm/changelog-mcp

Recipe: Manage Keep a Changelog files via @dwsm/changelog-mcp over stdio

Package: @dwsm/changelog-mcp v1.1.8 Transport: stdio Entry point: node nodemodules/@dwsm/changelog-mcp/dist/index.js Tools: 8 (initchangelog, getcurrentversion, getnextversion, previewentry, addentry, getconfig, searchchangelog, get_entry) Auth: none required

Setup: npm install --prefix /tmp/changelog-mcp @dwsm/changelog-mcp @modelcontextprotocol/sdk

MCP Client: StdioClientTransport with cwd set to your project directory (changelog files created there).

TOOL REFERENCE:

1. init_changelog({format?, file?}) - creates CHANGELOG.md + config. Default format: keep-a-changelog. Categories: Added, Changed, Deprecated, Removed, Fixed, Security.
2. getcurrentversion({}) - reads highest version from changelog. Returns "0.0.0" if empty.
3. getnextversion({bump: "patch"|"minor"|"major"}) - calculates next semver version.
4. preview_entry({category, description, details?, files?, bump}) - dry-run preview without writing.
5. add_entry({category, description, details?, files?, bump}) - appends entry to changelog with version bump.
6. get_config({}) - shows current config (format, backup, versioning, date format).
7. search_changelog({query?, version?, category?, limit?}) - text search across entries.
8. get_entry({version}) - retrieves full changelog block for a specific version.

KEY GOTCHAS:

1. Categories are CASE-SENSITIVE: must be "Added" not "added", "Fixed" not "fixed", "Security" not "security". Lowercase triggers "Ungultige Kategorie" error listing valid options.
2. details param must be an ARRAY of strings, not a single string. Passing a string triggers Zod validation error: "Expected array, received string".
3. Output messages are in GERMAN (Deutsch) despite being an English-facing tool. "Erfolgreich" = success, "Fehler" = error, "Vorschau" = preview, "Treffer" = matches, "Keine" = none.
4. When no versions exist (fresh init), getnextversion returns 0.1.0 regardless of bump type (patch/minor/major all produce 0.1.0).
5. First add_entry after init warns "Kein bekanntes Changelog-Format erkannt" but still works correctly.
6. searchchangelog category filter IS case-insensitive (unlike addentry) - "fixed" matches "Fixed" entries.
7. Config file created is changelog-mcp-config.json (not .changelog-mcp.json).
8. Each add_entry creates a new version (no way to add multiple categories to same version in one call).
9. Backup system: enabled by default, daily strategy, max 30 files, stored in ./changelog-backups/.
10. Generated changelog follows Keep a Changelog 1.1.0 format with semver 2.0.0 links.

VERIFIED TRACE (22 calls, 21 success + 1 correct rejection): initchangelog → OK 14ms. previewentry(Added) → OK 2ms. previewentry(Fixed+details array) → OK 1ms. addentry(Added, minor) → 0.1.0 OK 1ms. getcurrentversion → 0.1.0 OK 1ms. addentry(Added, patch) → 0.1.1 OK 1ms. addentry(Fixed, patch) → 0.1.2 OK 1ms. addentry(Security, patch) → 0.1.3 OK 1ms. addentry(Changed, minor) → 0.2.0 OK 1ms. addentry(Deprecated, minor) → 0.3.0 OK 0ms. getcurrentversion → 0.3.0 OK. getnextversion(patch) → 0.3.1 OK. getnextversion(minor) → 0.4.0 OK. getnextversion(major) → 1.0.0 OK. getentry(0.1.0) → full block OK. getentry(0.2.0) → full block OK. searchchangelog(query=authentication) → 1 hit OK. searchchangelog(category=Fixed) → 1 hit OK. searchchangelog(category=fixed lowercase) → 1 hit OK (case-insensitive search!). searchchangelog(nonexistent) → 0 hits OK. getconfig → full config JSON OK. get_entry(9.9.9) → correct rejection listing available versions.