@commitsage/mcp-server

v1.1.0

Published

a month ago

MCP server for CommitSage - AI-powered commit message generation with Gemini, OpenAI, Codestral, and Ollama support

0High
0Medium
0Low

vizzle

mcp model-context-protocol git commit ai gemini openai

CommitSage MCP Server

AI-powered commit message generation via Model Context Protocol (MCP).

Overview

CommitSage MCP Server provides AI-powered Git commit message generation through the standardized Model Context Protocol. It supports multiple AI providers (Gemini, OpenAI, Codestral, Ollama) and various commit formats, making it easy to integrate into your workflow with Claude Code, Cursor, Zed, and other MCP-compatible tools.

Features

🤖 Multiple AI Providers: Gemini, OpenAI, Codestral, Ollama
📝 Multiple Commit Formats: Conventional, Angular, Karma, Semantic, Emoji, and more
🌍 Multi-language Support: English, Russian, Chinese, Japanese, Spanish
🔧 Customizable: Custom instructions, formats, and languages
🚀 Fast & Efficient: Local git operations with smart caching
🔌 MCP Compatible: Works with Claude Code, Cursor, Zed, and more

Quick Start

Prerequisites

Node.js 18.0.0 or higher
Git installed and in PATH
API key for your chosen provider (Gemini, OpenAI, or Codestral) - not needed for Ollama

Installation

CommitSage MCP Server is available on npm: @commitsage/mcp-server

No installation required when using npx (recommended), or install globally:

npm install -g @commitsage/mcp-server

Then configure in your MCP client (see Configuration section below).

Configuration for IDE Clients

Claude Code

Add to your Claude Code configuration file:

Windows: %USERPROFILE%\.claude\config.json macOS/Linux: ~/.claude/config.json

{
  "mcpServers": {
    "commitsage": {
      "command": "npx",
      "args": ["-y", "@commitsage/mcp-server"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here",
        "DEFAULT_PROVIDER": "gemini",
        "DEFAULT_COMMIT_FORMAT": "conventional",
        "DEFAULT_COMMIT_LANGUAGE": "english",
        "API_REQUEST_TIMEOUT": "30"
      }
    }
  }
}

Minimal configuration (Gemini only):

{
  "mcpServers": {
    "commitsage": {
      "command": "npx",
      "args": ["-y", "@commitsage/mcp-server"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Add to Cursor settings (Settings > MCP):

{
  "mcp": {
    "servers": {
      "commitsage": {
        "command": "npx",
        "args": ["-y", "@commitsage/mcp-server"],
        "env": {
          "GEMINI_API_KEY": "your-api-key-here",
          "DEFAULT_PROVIDER": "gemini",
          "DEFAULT_COMMIT_FORMAT": "conventional"
        }
      }
    }
  }
}

Zed (Manual Configuration)

Note: For Zed, we recommend using the Zed Extension instead.

If you prefer manual configuration, add to .zed/settings.json:

{
  "context_servers": {
    "commitsage": {
      "command": "npx",
      "args": ["-y", "@commitsage/mcp-server"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here",
        "DEFAULT_PROVIDER": "gemini"
      }
    }
  }
}

Available MCP Tools

1. `generate_commit_message`

Generate an AI-powered commit message for a Git repository. Analyzes all changes (staged and unstaged) using configuration from MCP server environment variables.

Parameters:

repoPath (required): Path to the git repository

Example:

{
  "repoPath": "/path/to/your/repo"
}

Response:

{
  "success": true,
  "message": "feat(auth): add OAuth2 authentication\n\nImplement GitHub OAuth flow with JWT tokens",
  "model": "gemini-2.0-flash",
  "provider": "gemini"
}

Note: All configuration (provider, format, language, etc.) is set through environment variables in the MCP server configuration.

2. `validate_api_key`

Validate that an API key is configured for a provider.

Parameters:

provider (required): Provider to validate (gemini, openai, codestral, ollama)

Example:

{
  "provider": "gemini"
}

Usage Examples

In Claude Code

Generate a commit message for my changes in C:/projects/myapp

Claude Code will call the generate_commit_message tool and provide you with a properly formatted commit message.

In Cursor

Generate commit message for the current repository

Cursor will analyze all changes and generate an appropriate commit message.

In Zed

Create a commit message for my project

Zed will call the generate_commit_message tool and show you the result.

Environment Variables Reference

| Variable | Description | Default | Required | |----------|-------------|---------|----------| | GEMINI_API_KEY | Google Gemini API key | - | For Gemini provider | | OPENAI_API_KEY | OpenAI API key | - | For OpenAI provider | | CODESTRAL_API_KEY | Mistral Codestral API key | - | For Codestral provider | | OLLAMA_BASE_URL | Ollama API base URL | http://localhost:11434 | For Ollama provider | | OLLAMA_MODEL | Ollama model name | llama3.2 | For Ollama provider | | DEFAULT_PROVIDER | Default AI provider | gemini | No | | DEFAULT_COMMIT_FORMAT | Default commit format | conventional | No | | DEFAULT_COMMIT_LANGUAGE | Default language | english | No | | API_REQUEST_TIMEOUT | API timeout in seconds | 30 | No | | ONLY_STAGED | Analyze only staged changes | false | No | | LOG_LEVEL | Logging level | info | No | | USE_CUSTOM_INSTRUCTIONS | Enable custom instructions | false | No | | CUSTOM_INSTRUCTIONS | Custom prompt instructions | - | If USE_CUSTOM_INSTRUCTIONS is true |

Supported Commit Formats

Conventional - type(scope): description
Angular - Angular commit message format
Karma - type(scope): message
Semantic - type: message
Emoji - :emoji: message
EmojiKarma - :emoji: type(scope): message
Google - Google's commit format
Atom - Atom editor commit format

Supported Languages

English
Russian (Русский)
Chinese (中文)
Japanese (日本語)
Spanish (Español)

Development

For local development, clone the repository:

git clone https://github.com/VizzleTF/CommitSage.git
cd CommitSage/mcp-server
npm install

Run in development mode

npm run dev

Run locally via index.ts

You can run the MCP server directly from source using tsx:

GEMINI_API_KEY=your-key npx tsx src/index.ts

On Windows (PowerShell):

$env:GEMINI_API_KEY="your-key"; npx tsx src/index.ts

You can also point your MCP client to the local source instead of the npm package:

{
  "mcpServers": {
    "commitsage": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/CommitSage-MCP/src/index.ts"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Or use the compiled version after npm run build:

{
  "mcpServers": {
    "commitsage": {
      "command": "node",
      "args": ["/absolute/path/to/CommitSage-MCP/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Build

npm run build

Clean build artifacts

npm run clean

Troubleshooting

"Git is not installed or not found in PATH"

Make sure Git is installed and available in your system PATH.

git --version

"Invalid repository path"

Ensure the repoPath parameter points to a valid Git repository (contains .git directory).

"No changes detected"

Make sure you have uncommitted changes in your repository. Use git status to check.

"Authentication failed"

Verify your API key is correct and has the necessary permissions.

Connection timeout

If requests are timing out, increase the timeout:

API_REQUEST_TIMEOUT=60

Or set to -1 for no timeout:

API_REQUEST_TIMEOUT=-1

API Keys

Getting API Keys

Gemini: Google AI Studio (Free tier available)
OpenAI: OpenAI API Keys (Paid)
Codestral: Mistral AI Console (Free tier available)
Ollama: No API key needed, runs locally

Architecture

mcp-server/
├── src/
│   ├── index.ts                 # Entry point
│   ├── server/
│   │   ├── mcpServer.ts         # MCP server implementation
│   │   └── tools.ts             # MCP tools definitions
│   ├── services/                # Business logic
│   │   ├── aiService.ts         # Main AI service coordinator
│   │   ├── geminiService.ts     # Gemini provider
│   │   ├── openaiService.ts     # OpenAI provider
│   │   ├── codestralService.ts  # Codestral provider
│   │   ├── ollamaService.ts     # Ollama provider
│   │   ├── gitService.ts        # Git operations
│   │   ├── gitBlameAnalyzer.ts  # Git blame analysis
│   │   └── promptService.ts     # Prompt generation
│   ├── models/
│   │   ├── types.ts             # TypeScript types
│   │   └── errors.ts            # Custom errors
│   └── utils/
│       ├── config.ts            # Configuration
│       ├── logger.ts            # Logging
│       ├── httpUtils.ts         # HTTP utilities
│       ├── retryUtils.ts        # Retry logic
│       └── textProcessing.ts    # Text processing
├── package.json
├── tsconfig.json
└── README.md

Security

API keys are never logged or exposed
All git operations are read-only
No data is sent to external services except the AI providers
Local git operations only access the specified repository

License

MIT

Support

For issues, questions, or contributions, please visit:

npm package: @commitsage/mcp-server
Main project: CommitSage GitHub
Issues: GitHub Issues

Credits

Built on top of the CommitSage VSCode Extension by VizzleTF.

Changelog

v1.1.0 (2026-02-07)

Security: Gemini API key moved from URL query parameter to x-goog-api-key header
Security: Removed unused apiKey parameter from validate_api_key tool
Feature: Added ONLY_STAGED environment variable to analyze only staged changes
UX: Tool descriptions now specify that repoPath must be an absolute path
Refactor: Unified AI service logic via shared BaseAIService.generateWithRetry method, reducing code duplication across OpenAI, Codestral, Ollama, and Gemini services
Cleanup: Removed unused interfaces (IAIService, GitDiffOptions, CommitMessageOptions, AnalyzeChangesOptions), error classes (NoRepositoriesFoundError, NoRepositorySelectedError, UserCancelledError, AIServiceError), and dead code

v1.0.0 (2026-02-06)

Initial release
Support for Gemini, OpenAI, Codestral, and Ollama providers
8 commit message formats
5 language support
Full MCP protocol implementation
Compatible with Claude Code, Cursor, and Zed