@commitsage/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,434 @@
+# 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 Options
+
+#### Option 1: Zed Extension (Recommended)
+
+The easiest way to use CommitSage is through the Zed extension, which handles installation and configuration automatically.
+
+See the [Zed Extension README](./zed-extension/README.md) for details.
+
+#### Option 2: Manual Installation
+
+1. **Clone or download the project**
+
+```bash
+cd C:\Users\IVAN\Documents\home\CommitSage\mcp-server
+```
+
+2. **Install dependencies**
+
+```bash
+npm install
+```
+
+3. **Build the project**
+
+```bash
+npm run build
+```
+
+4. **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`
+
+```json
+{
+  "mcpServers": {
+    "commitsage": {
+      "command": "node",
+      "args": ["C:/Users/IVAN/Documents/home/CommitSage/mcp-server/dist/index.js"],
+      "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):**
+
+```json
+{
+  "mcpServers": {
+    "commitsage": {
+      "command": "node",
+      "args": ["C:/Users/IVAN/Documents/home/CommitSage/mcp-server/dist/index.js"],
+      "env": {
+        "GEMINI_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to Cursor settings (Settings > MCP):
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "commitsage": {
+        "command": "node",
+        "args": ["C:/Users/IVAN/Documents/home/CommitSage/mcp-server/dist/index.js"],
+        "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](./zed-extension/README.md) instead.
+
+If you prefer manual configuration, add to `.zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "commitsage": {
+      "command": "node",
+      "args": ["C:/Users/IVAN/Documents/home/CommitSage/mcp-server/dist/index.js"],
+      "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.
+
+**Parameters:**
+- `repoPath` (required): Path to the git repository
+- `provider` (optional): AI provider (`gemini`, `openai`, `codestral`, `ollama`)
+- `format` (optional): Commit format (`conventional`, `angular`, `karma`, `semantic`, `emoji`, `emojiKarma`, `google`, `atom`)
+- `language` (optional): Language (`english`, `russian`, `chinese`, `japanese`, `spanish`)
+- `onlyStaged` (optional): Only analyze staged changes (default: `false`)
+- `customInstructions` (optional): Custom instructions for generation
+
+**Example:**
+```json
+{
+  "repoPath": "/path/to/your/repo",
+  "provider": "gemini",
+  "format": "conventional",
+  "language": "english",
+  "onlyStaged": true
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "feat(auth): add OAuth2 authentication\n\nImplement GitHub OAuth flow with JWT tokens",
+  "model": "gemini-2.0-flash",
+  "provider": "gemini"
+}
+```
+
+### 2. `analyze_changes`
+
+Analyze git changes in a repository.
+
+**Parameters:**
+- `repoPath` (required): Path to the git repository
+- `onlyStaged` (optional): Only analyze staged changes
+
+**Example:**
+```json
+{
+  "repoPath": "/path/to/your/repo",
+  "onlyStaged": false
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "analysis": {
+    "hasStagedChanges": true,
+    "hasUnstagedChanges": false,
+    "hasUntrackedFiles": false,
+    "changedFilesCount": 3,
+    "changedFiles": ["src/auth.ts", "src/config.ts", "README.md"],
+    "diffLength": 1234,
+    "diffPreview": "diff --git a/src/auth.ts..."
+  }
+}
+```
+
+### 3. `list_commit_formats`
+
+List all available commit message formats.
+
+**Parameters:** None
+
+**Response:**
+```json
+{
+  "success": true,
+  "formats": [
+    {
+      "name": "conventional",
+      "description": "Conventional Commits format: type(scope): description",
+      "example": "feat(auth): add OAuth2 authentication"
+    },
+    ...
+  ],
+  "currentFormat": "conventional"
+}
+```
+
+### 4. `validate_api_key`
+
+Validate that an API key is configured for a provider.
+
+**Parameters:**
+- `provider` (required): Provider to validate (`gemini`, `openai`, `codestral`, `ollama`)
+
+**Example:**
+```json
+{
+  "provider": "gemini"
+}
+```
+
+## Usage Examples
+
+### In Claude Code
+
+```
+Generate a commit message for my staged changes in C:/projects/myapp using conventional format
+```
+
+Claude Code will call the `generate_commit_message` tool and provide you with a properly formatted commit message.
+
+### In Cursor
+
+```
+Analyze the changes in /home/user/projects/webapp
+```
+
+Cursor will call the `analyze_changes` tool to show you what's changed.
+
+### In Zed
+
+```
+List all available commit formats
+```
+
+Zed will call the `list_commit_formats` tool and show you all options.
+
+## 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 |
+| `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
+
+1. **Conventional** - `type(scope): description`
+2. **Angular** - Angular commit message format
+3. **Karma** - `type(scope): message`
+4. **Semantic** - `type: message`
+5. **Emoji** - `:emoji: message`
+6. **EmojiKarma** - `:emoji: type(scope): message`
+7. **Google** - Google's commit format
+8. **Atom** - Atom editor commit format
+
+## Supported Languages
+
+- English
+- Russian (Русский)
+- Chinese (中文)
+- Japanese (日本語)
+- Spanish (Español)
+
+## Development
+
+### Run in development mode
+
+```bash
+npm run dev
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Clean build artifacts
+
+```bash
+npm run clean
+```
+
+## Troubleshooting
+
+### "Git is not installed or not found in PATH"
+
+Make sure Git is installed and available in your system PATH.
+
+```bash
+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:
+
+```env
+API_REQUEST_TIMEOUT=60
+```
+
+Or set to `-1` for no timeout:
+
+```env
+API_REQUEST_TIMEOUT=-1
+```
+
+## API Keys
+
+### Getting API Keys
+
+- **Gemini**: [Google AI Studio](https://makersuite.google.com/app/apikey) (Free tier available)
+- **OpenAI**: [OpenAI API Keys](https://platform.openai.com/api-keys) (Paid)
+- **Codestral**: [Mistral AI Console](https://console.mistral.ai/codestral) (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:
+- Main project: [CommitSage GitHub](https://github.com/VizzleTF/CommitSage)
+- Issues: [GitHub Issues](https://github.com/VizzleTF/CommitSage/issues)
+
+## Credits
+
+Built on top of the [CommitSage VSCode Extension](https://marketplace.visualstudio.com/items?itemName=VizzleTF.commitsage) by VizzleTF.
+
+## Changelog
+
+### 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

package/dist/adapters/sse.d.ts

@@ -0,0 +1,26 @@
+/**
+ * SSE (Server-Sent Events) Transport for remote MCP access
+ * Used for Vercel deployment
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export interface SSETransportOptions {
+    endpoint: string;
+    response: any;
+}
+/**
+ * Creates and configures SSE transport for remote MCP server
+ */
+export declare class SSETransportAdapter {
+    private transport;
+    private server;
+    constructor(server: Server, options: SSETransportOptions);
+    /**
+     * Start the SSE transport connection
+     */
+    connect(): Promise<void>;
+    /**
+     * Close the SSE transport connection
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=sse.d.ts.map

package/dist/adapters/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/adapters/sse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,GAAG,CAAC;CACf;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB;IAMxD;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAS7B"}

package/dist/adapters/sse.js

@@ -0,0 +1,45 @@
+/**
+ * SSE (Server-Sent Events) Transport for remote MCP access
+ * Used for Vercel deployment
+ */
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { Logger } from '../utils/logger.js';
+/**
+ * Creates and configures SSE transport for remote MCP server
+ */
+export class SSETransportAdapter {
+    transport;
+    server;
+    constructor(server, options) {
+        this.server = server;
+        this.transport = new SSEServerTransport(options.endpoint, options.response);
+        Logger.log(`SSE transport created for endpoint: ${options.endpoint}`);
+    }
+    /**
+     * Start the SSE transport connection
+     */
+    async connect() {
+        try {
+            await this.server.connect(this.transport);
+            Logger.log('SSE transport connected successfully');
+        }
+        catch (error) {
+            Logger.error('Failed to connect SSE transport:', error);
+            throw error;
+        }
+    }
+    /**
+     * Close the SSE transport connection
+     */
+    async close() {
+        try {
+            await this.transport.close();
+            Logger.log('SSE transport closed');
+        }
+        catch (error) {
+            Logger.error('Error closing SSE transport:', error);
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=sse.js.map

package/dist/adapters/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/adapters/sse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAE7E,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAO5C;;GAEG;AACH,MAAM,OAAO,mBAAmB;IACtB,SAAS,CAAqB;IAC9B,MAAM,CAAS;IAEvB,YAAY,MAAc,EAAE,OAA4B;QACtD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,IAAI,kBAAkB,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC5E,MAAM,CAAC,GAAG,CAAC,uCAAuC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACxE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC1C,MAAM,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,kCAAkC,EAAE,KAAK,CAAC,CAAC;YACxD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;YAC7B,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,8BAA8B,EAAE,KAAK,CAAC,CAAC;YACpD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/auth/jwt.d.ts

@@ -0,0 +1,70 @@
+/**
+ * JWT Token Management for MCP Authentication
+ */
+export interface JWTPayload {
+    userId: string;
+    email: string;
+    name: string;
+    provider: string;
+    iat: number;
+    exp: number;
+}
+export interface TokenPair {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+}
+/**
+ * JWT Service for token generation and validation
+ * Note: In production, use a proper JWT library like 'jsonwebtoken'
+ * This is a simplified implementation for demonstration
+ */
+export declare class JWTService {
+    private secret;
+    private accessTokenExpiry;
+    private refreshTokenExpiry;
+    constructor(secret: string);
+    /**
+     * Generate access and refresh tokens
+     */
+    generateTokenPair(user: {
+        id: string;
+        email: string;
+        name: string;
+        provider: string;
+    }): TokenPair;
+    /**
+     * Validate and decode token
+     */
+    validateToken(token: string): JWTPayload | null;
+    /**
+     * Refresh access token using refresh token
+     */
+    refreshAccessToken(refreshToken: string): string | null;
+    /**
+     * Encode payload to JWT token (simplified implementation)
+     * In production, use a proper library like 'jsonwebtoken'
+     */
+    private encode;
+    /**
+     * Decode JWT token (simplified implementation)
+     */
+    private decode;
+    /**
+     * Create signature for token
+     */
+    private sign;
+    /**
+     * Base64 URL encode
+     */
+    private base64UrlEncode;
+    /**
+     * Base64 URL decode
+     */
+    private base64UrlDecode;
+}
+/**
+ * Create JWT service from environment variables
+ */
+export declare function createJWTServiceFromEnv(): JWTService;
+//# sourceMappingURL=jwt.d.ts.map

package/dist/auth/jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../src/auth/jwt.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,iBAAiB,CAAgB;IACzC,OAAO,CAAC,kBAAkB,CAAkB;gBAEhC,MAAM,EAAE,MAAM;IAO1B;;OAEG;IACH,iBAAiB,CAAC,IAAI,EAAE;QACtB,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,SAAS;IAiCb;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAsB/C;;OAEG;IACH,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAkBvD;;;OAGG;IACH,OAAO,CAAC,MAAM;IAad;;OAEG;IACH,OAAO,CAAC,MAAM;IA0Bd;;OAEG;IACH,OAAO,CAAC,IAAI;IASZ;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACH,OAAO,CAAC,eAAe;CAUxB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,UAAU,CAQpD"}