AI-github-changelog-generator-cli-mcp by idominikosgr - MCP Server

🚀 AI Changelog Generator

Generate professional changelogs from git commits using AI
Works as a standalone CLI tool or MCP server for AI assistants

🚀 TL;DR - Quick Start

What it does: AI-powered changelog generation from git commits + working directory changes + MCP server for AI assistants

# Install
npm install -g ai-github-changelog-generator-cli-mcp

# Generate changelog
ai-changelog

# Key options
ai-changelog --interactive        # Interactive commit selection
ai-changelog --detailed          # Comprehensive analysis  
ai-changelog --model gpt-4.1      # Force specific AI model
ai-changelog --since v1.0.0      # Generate since version/commit
ai-changelog --no-attribution    # Disable attribution footer
ai-changelog --help              # All options

# Start MCP server for Claude Desktop
ai-changelog-mcp

Requirements: Node.js 18+, Git repository, OpenAI/Azure API key (optional)
Works: Standalone CLI + MCP server for AI assistants
Models: GPT-4.1 series, o3/o4 reasoning models with smart auto-selection

🎉 NEW in v2.5.1: Enhanced Reliability & Repository Health - Added comprehensive repository health assessment, commit message quality scoring, improved error handling, and cleaner user experience!

🔥 NEW in v2.4.0: Complete MCP Feature Parity - MCP server now has 100% feature parity with CLI, including working directory changelog generation and file writing behavior!

✨ Features

🤖 AI-Powered: Uses GPT-4.1 series, o3/o4 reasoning models with intelligent selection
🏥 Repository Health: Comprehensive health assessment with commit quality scoring and hygiene recommendations
🔧 Dual Mode: Works as standalone CLI or MCP server with complete feature parity
📊 Comprehensive Analysis: Git commits + working directory changes + branches + dangling commits + untracked files
📁 File Generation: Creates AI_CHANGELOG.md files with proper attribution in both CLI and MCP modes
🎯 Model Override: Force specific models when needed (--model gpt-4.1, --model o4)
🎮 Interactive Mode: Professional commit selection and analysis interface
⚡ Zero Config: Works out of the box with intelligent fallbacks and enhanced error handling
🔐 Multi-Provider: Supports both OpenAI and Azure OpenAI with auto-detection

🚀 Quick Start

Installation

# Install globally for CLI use
npm install -g ai-github-changelog-generator-cli-mcp

# Or locally in your project
npm install ai-github-changelog-generator-cli-mcp

Basic Usage

# Generate changelog (if installed globally)
ai-changelog

# Or using npm scripts (if installed locally)
npm run changelog

# Start MCP server for AI assistants (if installed globally)
ai-changelog-mcp

# Or using npm scripts (if installed locally)
npm run mcp

MCP Server Integration

Add to your Claude Desktop config:

{
  "mcpServers": {
    "ai-changelog-generator": {
      "command": "ai-changelog-mcp",
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

📊 Functionality Matrix

Feature	CLI	MCP	AI-Powered	Status
Basic Changelog	✅	✅	✅	Excellent
Repository Health	✅	✅	❌	NEW v2.5.1 - Excellent
Commit Quality Scoring	✅	✅	❌	NEW v2.5.1 - Excellent
Enhanced Error Handling	✅	✅	✅	NEW v2.5.1 - Excellent
Staged Changes	✅	✅	✅	Excellent
Commit Analysis	✅	✅	✅	Excellent
Branch Analysis	✅	✅	❌	NEW v2.4.0 - Good
Dangling Commits	✅	✅	❌	NEW v2.4.0 - Good
Untracked Files	✅	✅	❌	NEW v2.4.0 - Good
Interactive Mode	✅	❌	✅	Excellent
Model Override	✅	✅	✅	NEW v2.4.0 - Excellent
Diff Analysis	✅	✅	✅	Excellent
Smart Model Selection	✅	✅	✅	Excellent

🎯 Core Commands

Standard Changelog Generation

# Generate AI-powered changelog (global install)
ai-changelog
# Or using npm scripts (local install)
npm run changelog

# Generate with specific analysis mode (global install)
ai-changelog --detailed         # Comprehensive business + technical analysis
ai-changelog --enterprise       # Stakeholder-ready format with compliance notes
# Or using npm scripts (local install)
npm run changelog:detailed
npm run changelog:enterprise

# Generate for specific version range (global install)
ai-changelog --version v2.0.0   # Generate with specific version
ai-changelog --since v1.5.0     # Generate since specific version/commit
# For npm scripts, use: npm run changelog -- --version v2.0.0

Repository Analysis

# Analyze current working directory changes (global install)
ai-changelog --analyze
# Or using npm scripts (local install)
npm run changelog:analyze

# Comprehensive repository analysis (global install)
ai-changelog --branches         # Analyze all branches and unmerged commits
ai-changelog --comprehensive    # Full repository health check
ai-changelog --untracked       # Categorize untracked files with recommendations
# For npm scripts, use: npm run changelog -- --branches

Interactive Mode

# Launch interactive commit selection interface (global install)
ai-changelog --interactive
# Or using npm scripts (local install)
npm run changelog:interactive

Interactive Options:

📋 Analyze staged changes - Review what's ready for commit
🔍 Analyze unstaged changes - Check working directory modifications
✅ Select specific commits - Cherry-pick commits with checkbox interface
📊 Analyze recent commits - Process last N commits
🔄 Analyze all commits - Full repository analysis

Model Override

# Force specific model instead of smart selection (global install)
ai-changelog --model gpt-4.1-nano    # Ultra-efficient for small changes
ai-changelog --model gpt-4.1          # Balanced performance
ai-changelog --model o3               # Advanced reasoning (Azure-only)

# Combine with other options (global install)
ai-changelog --model gpt-4.1-mini --detailed
ai-changelog --model o3 --enterprise

# For npm scripts (local install), use:
npm run changelog -- --model gpt-4.1-nano
npm run changelog:detailed -- --model gpt-4.1-mini

Attribution Control

# Generate changelog with attribution footer (default)
ai-changelog

# Disable attribution footer for clean output (global install)
ai-changelog --no-attribution
# For npm scripts (local install)
npm run changelog -- --no-attribution

# Combined with other options (global install)
ai-changelog --detailed --no-attribution
ai-changelog --enterprise --since v1.0.0 --no-attribution

About Attribution:

By default, changelogs include a small footer: "Generated using ai-github-changelog-generator-cli-mcp"
Use --no-attribution flag for clean output without promotional footer
For MCP server, set "includeAttribution": false in tool parameters

🧠 Smart Model Selection

The tool automatically selects the optimal model based on change complexity:

Change Type	Auto-Selected Model	Manual Override Available
Minimal changes (<3 files, <50 lines)	`gpt-4.1-nano`	`--model gpt-4.1-nano`
Simple changes (3-10 files, <200 lines)	`gpt-4.1-mini`	`--model gpt-4.1-mini`
Standard changes (10-20 files, <1000 lines)	`gpt-4.1`	`--model gpt-4.1`
Complex changes (20+ files, 1000+ lines)	`gpt-4.1`	`--model gpt-4.1`
Architectural changes (100+ files, breaking)	`o4` (Azure)	`--model o4`

💡 Tip: Use --model to override smart selection for testing, cost optimization, or specific requirements.

🏥 Repository Health Assessment (NEW v2.5.1)

Comprehensive repository health analysis with actionable recommendations:

# Run health assessment (global install)
ai-changelog --health

# Or using npm scripts (local install)  
npm run changelog -- --health

What it analyzes:

Commit Quality: 8-point scoring system for commit message quality
Working Directory: Clean status vs. uncommitted changes
Recent Activity: Commit frequency and patterns over last 30 days
Code Diversity: Number of different file types and categories
Repository Hygiene: Overall maintainability score

Sample Output:

🏥 Repository Health Assessment
==================================================
Overall Health: EXCELLENT (84/100)

📊 Health Metrics:
  Commit Quality: good (7.6/8.0)
  Working Directory: Has Changes  
  Recent Activity: 14 commits (last 30 days)
  Code Diversity: 2 categories

⚠️  Issues Found:
  • Working directory has uncommitted changes

💡 Recommendations:
  • Commit or stash pending changes
  • Consider adding tests, documentation, or configuration

MCP Server Usage:

{
  "name": "assess_repository_health",
  "arguments": {
    "includeRecommendations": true,
    "analyzeRecentCommits": 50
  }
}

Commit Quality Scoring (8-point system):

✅ Descriptive (2 points): Clear, meaningful description
✅ Length (2 points): 10+ characters, not too verbose
✅ Informative (2 points): Explains what changed and why
✅ Conventional Format (2 points): Follows type(scope): description pattern

Health Score Ranges:

80-100: Excellent - Well-maintained repository
65-79: Good - Minor improvements recommended
50-64: Fair - Several areas need attention
<50: Poor - Significant improvements required

🛠️ Configuration

Option 1: Environment Variables

# OpenAI
export OPENAI_API_KEY="your-key"

# Azure OpenAI (Recommended - supports reasoning models)
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
export AZURE_OPENAI_KEY="your-key"
export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4.1"
export AZURE_OPENAI_API_VERSION="2025-04-01-preview"

Option 2: .env.local File

Create a .env.local file in your project root:

AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_KEY=your-key
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4.1
AZURE_OPENAI_API_VERSION=2025-04-01-preview

Advanced Configuration

Add these to your environment variables or .env.local file:

# Model Configuration
AI_MODEL=gpt-4.1                    # Default model
AI_MODEL_SIMPLE=gpt-4.1-mini        # Simple changes
AI_MODEL_NANO=gpt-4.1-nano          # Minimal changes
AI_MODEL_COMPLEX=gpt-4.1            # Complex analysis
AI_MODEL_REASONING=o4-mini          # Latest reasoning model (Azure-only)
AI_MODEL_ADVANCED_REASONING=o4      # Latest advanced reasoning (Azure-only)
AI_MODEL_REASONING_LEGACY=o3-mini   # Previous gen reasoning (Azure-only)
AI_MODEL_ADVANCED_REASONING_LEGACY=o3 # Previous gen advanced reasoning (Azure-only)

# Provider Settings
AI_PROVIDER=auto                    # auto, openai, azure
AI_TEMPERATURE=0.3                  # AI creativity (0.0-1.0)
AI_MAX_TOKENS=1000                  # Response length limit

📖 Complete CLI Reference

Global Installation Commands

# Basic usage
ai-changelog                    # Generate standard AI changelog
ai-changelog --help            # Show all available options

# Analysis modes
ai-changelog --detailed        # Comprehensive business + technical analysis
ai-changelog --enterprise      # Enterprise-ready documentation
ai-changelog --analyze         # Analyze current changes

# Repository analysis
ai-changelog --branches        # Analyze all branches and unmerged commits
ai-changelog --comprehensive   # Full repository health check  
ai-changelog --untracked      # Categorize untracked files

# Advanced options
ai-changelog --interactive     # Interactive commit selection
ai-changelog --model gpt-4.1   # Force specific model
ai-changelog --validate        # Validate configuration
ai-changelog --metrics         # Show performance metrics

# Version and range options
ai-changelog --version v2.0.0  # Generate with specific version
ai-changelog --since v1.5.0    # Generate since specific version
ai-changelog --since HEAD~5    # Generate since specific commit

# Repository health assessment  
ai-changelog --health          # Comprehensive repository health report

# Combinations
ai-changelog --model o4 --detailed --since v1.0.0
ai-changelog --interactive --enterprise

Local Installation (npm scripts)

# Basic usage
npm run changelog               # Generate standard AI changelog
npm run changelog:detailed     # Comprehensive analysis
npm run changelog:enterprise   # Enterprise documentation
npm run changelog:interactive  # Interactive mode
npm run changelog:analyze      # Analyze current changes

# MCP server
npm run mcp                     # Start MCP server

# Testing and validation
npm test                        # Run tests
npm run config:validate         # Validate configuration
npm run providers:test          # Test AI providers

# Using flags with npm scripts
npm run changelog -- --model gpt-4.1
npm run changelog -- --since v1.0.0
npm run changelog -- --detailed --interactive

🔧 MCP Server Tools

When used as an MCP server, provides these tools for AI assistants:

Tool	Purpose	Parameters
`generate_changelog`	Generate AI changelog from commits + write file	`model`, `analysisMode`, `since`, `version`, `includeAttribution`
`generate_changelog_from_changes`	Generate AI changelog from working directory + write file	`model`, `analysisMode`, `version`, `includeAttribution`
`assess_repository_health`	NEW: Comprehensive repository health assessment	`includeRecommendations`, `analyzeRecentCommits`
`analyze_commits`	Analyze commit patterns	`limit`, `since`
`analyze_current_changes`	Analyze staged/unstaged files	`includeAIAnalysis`, `includeAttribution`
`analyze_branches`	Branch and unmerged analysis	`includeAllBranches`
`analyze_comprehensive`	Full repository health	-
`get_git_info`	Repository information	`includeStats`
`configure_ai_provider`	Test AI provider settings	`provider`, `testConnection`
`validate_models`	Check model availability	`provider`, `checkCapabilities`

MCP Usage Example

// Generate changelog with model override
{
  "name": "generate_changelog",
  "arguments": {
    "model": "gpt-4.1",
    "analysisMode": "detailed",
    "since": "v1.0.0",
    "includeAttribution": true
  }
}

// Generate changelog from working directory changes
{
  "name": "generate_changelog_from_changes",
  "arguments": {
    "model": "gpt-4.1",
    "analysisMode": "detailed",
    "includeAttribution": true
  }
}

// Generate clean changelog without attribution
{
  "name": "generate_changelog",
  "arguments": {
    "model": "gpt-4.1",
    "includeAttribution": false
  }
}

// Comprehensive repository analysis
{
  "name": "analyze_comprehensive", 
  "arguments": {}
  }

📝 Note: generate_changelog and generate_changelog_from_changes both write an AI_CHANGELOG.md file to the project root directory for feature parity with the CLI. This ensures consistent behavior and proper attribution regardless of how the changelog is consumed.

🎮 Interactive Mode Features

The interactive mode provides an interface for precise changelog control:

# Global install
ai-changelog --interactive

# Local install
npm run changelog:interactive

Features:

📊 Repository Status: Shows current branch, staged/unstaged counts
✅ Commit Selection: Checkbox interface for cherry-picking
🔍 Smart Analysis: AI-powered commit message validation
💡 Suggestions: Commit message improvement recommendations
🎯 Targeted Analysis: Focus on specific changes or timeframes
🛡️ Validation: Conventional commit format checking

Perfect for:

Code reviews and PR preparation
Release planning and scoping
Understanding change impact before deployment
Creating focused changelogs for specific features

🚀 What's New Today

Enhanced Repository Analysis

Branch Analysis: Detect unmerged commits across branches
Dangling Commits: Identify unreachable commits for cleanup
Untracked Files: Smart categorization with actionable recommendations
Comprehensive Health Check: Full repository status analysis

Model Override Support

CLI Flag: --model gpt-4.1, --model o3, --model gpt-4.1-nano
MCP Parameter: Include "model": "gpt-4.1" in tool calls
Smart Validation: Shows model capabilities and graceful fallbacks
Cost Optimization: Force efficient models for simple changes

Enhanced Git Parsing

Multiline Commit Support: Properly handles complex commit messages
Improved Diff Analysis: Better context extraction and parsing
Robust Error Handling: Graceful fallbacks for all git operations

💡 Example Outputs

Standard Changelog

# Changelog

## [v2.1.0] - 2025-06-08

### 🚀 Features
- **AI Model Override**: Force specific models with --model flag
  *Enables cost optimization and testing specific model capabilities*

### 🐛 Bug Fixes  
- **Git Parsing**: Fixed multiline commit message handling
  *Improves analysis accuracy for complex commit descriptions*

### 📊 Analysis
- **3** commits processed
- **Processing Time**: 2s
- **Model Used**: gpt-4.1 (auto-selected)

Repository Health Check

# Global install
ai-changelog --comprehensive

# Local install  
npm run changelog -- --comprehensive

📊 Repository Health Check:
   • Total commits: 127
   • Contributors: 5  
   • Active branches: 3
   • Dangling commits: 2 (cleanup recommended)
   • Untracked files: 15 (categorized)
   • Repository age: 3 months

🔍 Troubleshooting

Common Issues

"No API key found" Create a .env.local file with your credentials:

AZURE_OPENAI_KEY=your-key

"No commits found"

git log --oneline  # Check if you have commits
ai-changelog --since HEAD~5  # Try specific range (global)
npm run changelog -- --since HEAD~5  # Try specific range (local)

"Model not available"

ai-changelog --validate  # Check available models (global)
ai-changelog --model gpt-4.1  # Try different model (global)
npm run config:validate  # Check configuration (local)
npm run changelog -- --model gpt-4.1  # Try different model (local)

Test your configuration:

# Global install
ai-changelog --validate     # Check configuration
ai-changelog --analyze      # Test with current changes
ai-changelog --help         # See all options

# Local install
npm run config:validate     # Check configuration  
npm run changelog:analyze   # Test with current changes
npm run changelog -- --help # See all options

🛡️ Requirements

Node.js 18+
Git repository
API Key for OpenAI or Azure OpenAI (optional - works offline with fallback)

🌟 API Providers

Azure OpenAI

Models: GPT-4.1 series + o3/o4 reasoning models (both generations)
Features: Advanced reasoning, 1M token context, prompt caching
Enterprise: Security, compliance, data residency
Cost: 75% reduction with prompt caching

OpenAI

Models: GPT-4.1 series (best changelog quality)
Features: Large context, prompt caching
Setup: Simple API key configuration
Pricing: Pay-per-use

Both providers work identically. Tool auto-detects your configuration.

🏆 Performance

~1-2 seconds for standard changes (gpt-4.1-mini)
~3-5 seconds for complex analysis (gpt-4.1)
~5-10 seconds for reasoning analysis (o4)
Instant fallback mode when offline

Cost Optimization:

Automatic model selection saves ~40% on API costs
Prompt caching reduces costs by 75% on repeated analyses
Ultra-efficient nano model for minimal changes

🎯 Use Cases

Development Teams

Daily Development: Understand current changes before commits
Code Reviews: Generate comprehensive change summaries
Branch Management: Track unmerged work across branches
Repository Maintenance: Identify cleanup opportunities

Release Management

Release Notes: Professional changelog generation
Stakeholder Communication: Business-focused change summaries
Risk Assessment: Impact analysis before deployment
Compliance: Enterprise-ready documentation

CI/CD Integration

# GitHub Actions example
- name: Generate Changelog
  run: |
    npx ai-github-changelog-generator-cli-mcp --since ${{ github.event.before }}
    git add CHANGELOG.md
    git commit -m "docs: update changelog"

🤝 Contributing

This tool succeeds because it solves real problems simply:

No feature bloat - Every feature solves a common use case
No configuration complexity - Intelligent defaults, minimal setup

git clone https://github.com/idominikosgr/AI-github-changelog-generator-cli-mcp
cd AI-github-changelog-generator-cli-mcp
npm install
npm test

🗺️ Roadmap

Current: Comprehensive git analysis with model override support Next: Custom output formats Future: Change risk scoring, automated release note generation

No timeline promises. Features ship when they're production-ready.

📄 License

MIT - Use it however you want.

Made for developers who want better changelogs without the hassle.

Your git repository tells a story. Let AI help you tell it better.

📝 Copyright Notice

All trademarks belong to their respective owners. This project is not affiliated with or endorsed by OpenAI, Microsoft Azure, GitHub, or any other mentioned companies or services.