gitrama-mcp 1.0.0__tar.gz

gitrama_mcp-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*$py.class
+dist/
+build/
+*.egg-info/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.pytest_cache/

gitrama_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alfonso Harding / One Great Dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gitrama_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,343 @@
+Metadata-Version: 2.4
+Name: gitrama-mcp
+Version: 1.0.0
+Summary: MCP Server for Gitrama — AI-powered Git intelligence for your IDE
+Project-URL: Homepage, https://gitrama.ai
+Project-URL: Repository, https://github.com/onegreatdev/gitrama-mcp
+Project-URL: Documentation, https://gitrama.ai/docs
+Project-URL: Issues, https://github.com/onegreatdev/gitrama-mcp/issues
+Author-email: Alfonso Harding <alfonso@onegreatdev.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,commit,cursor,git,gitrama,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Requires-Dist: gitrama>=1.0.3
+Requires-Dist: mcp>=1.2.0
+Description-Content-Type: text/markdown
+
+# 🌿 Gitrama MCP Server
+
+> AI-powered Git intelligence for your IDE — smart commits, branch names, PR descriptions, changelogs, and workflow management.
+
+[![PyPI](https://img.shields.io/pypi/v/gitrama-mcp)](https://pypi.org/project/gitrama-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/gitrama-mcp)](https://pypi.org/project/gitrama-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## What is this?
+
+Gitrama MCP Server exposes [Gitrama](https://gitrama.ai)'s CLI as **10 MCP tools** that any AI assistant can use. Instead of typing `gtr commit` in your terminal, your AI assistant calls the tool directly — analyzing your code changes, generating commit messages, suggesting branch names, and more.
+
+**Works with:** Cursor · Claude Desktop · Claude Code · Windsurf · VS Code (Copilot) · Zed · any MCP-compatible client
+
+## Install (< 60 seconds)
+
+### Step 1: Install the package
+
+```bash
+pip install gitrama-mcp
+```
+
+Or with uv:
+```bash
+uv pip install gitrama-mcp
+```
+
+This installs both the MCP server and the `gitrama` CLI.
+
+### Step 2: Connect to your IDE
+
+<details>
+<summary><b>Cursor</b></summary>
+
+Add to `.cursor/mcp.json` in your project (or global settings):
+
+```json
+{
+  "mcpServers": {
+    "gitrama": {
+      "command": "gitrama-mcp"
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Claude Desktop</b></summary>
+
+Add to `claude_desktop_config.json`:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "gitrama": {
+      "command": "gitrama-mcp"
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+```bash
+claude mcp add gitrama gitrama-mcp
+```
+</details>
+
+<details>
+<summary><b>VS Code (Copilot)</b></summary>
+
+Add to `.vscode/settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "gitrama": {
+        "command": "gitrama-mcp"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Windsurf</b></summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gitrama": {
+      "command": "gitrama-mcp"
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Zed</b></summary>
+
+Add to Zed settings (`⌘,`):
+
+```json
+{
+  "context_servers": {
+    "gitrama": {
+      "command": {
+        "path": "gitrama-mcp"
+      }
+    }
+  }
+}
+```
+</details>
+
+### Step 3: Done.
+
+Ask your AI: *"Commit my staged changes"* — and watch it call `gitrama_commit`.
+
+---
+
+## Tools (10)
+
+### Commit Intelligence
+
+| Tool | Description |
+|------|-------------|
+| `gitrama_commit` | Generate an AI commit message for staged changes |
+| `gitrama_stage_and_commit` | Stage files + commit in one step |
+| `gitrama_commit_quality` | Analyze quality of recent commit messages |
+
+### Branch Management
+
+| Tool | Description |
+|------|-------------|
+| `gitrama_branch` | Create a new branch |
+| `gitrama_branch_suggest` | Get AI-suggested branch names from a description |
+
+### PR & Changelog
+
+| Tool | Description |
+|------|-------------|
+| `gitrama_pr` | Generate a PR description from branch diff |
+| `gitrama_changelog` | Generate a changelog between refs |
+
+### Stream (Workflow) Management
+
+| Tool | Description |
+|------|-------------|
+| `gitrama_stream_status` | Show current workflow stream |
+| `gitrama_stream_switch` | Switch to a different stream |
+| `gitrama_stream_list` | List all streams in the repo |
+
+---
+
+## Tool Details
+
+### `gitrama_commit`
+
+Generate an AI-powered commit message for staged changes.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `message_type` | string | `"conventional"` | Style: `"conventional"`, `"detailed"`, or `"simple"` |
+| `context` | string | `""` | Optional context (e.g., `"fixing auth bug"`) |
+| `model` | string | `""` | AI model override (e.g., `"gpt-4o"`, `"claude-sonnet-4-20250514"`) |
+
+**Example prompt:** *"Commit my changes with a conventional message, context: refactoring the payment module"*
+
+---
+
+### `gitrama_stage_and_commit`
+
+Stage files and commit in one step.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `files` | string | `"."` | Files to stage (`.` for all, or space-separated paths) |
+| `message_type` | string | `"conventional"` | Commit style |
+| `context` | string | `""` | Optional context |
+| `model` | string | `""` | AI model override |
+
+**Example prompt:** *"Stage and commit all my changes"*
+
+---
+
+### `gitrama_commit_quality`
+
+Analyze recent commit message quality.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `count` | int | `10` | Number of commits to analyze (1-50) |
+
+**Example prompt:** *"How good are our last 20 commit messages?"*
+
+---
+
+### `gitrama_branch_suggest`
+
+Get AI-suggested branch names.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `description` | string | *required* | Task description |
+| `model` | string | `""` | AI model override |
+
+**Example prompt:** *"Suggest a branch name for adding OAuth2 support"*
+
+---
+
+### `gitrama_pr`
+
+Generate a PR description.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `base` | string | `""` | Target branch (default: main/master) |
+| `model` | string | `""` | AI model override |
+
+**Example prompt:** *"Write a PR description for this branch"*
+
+---
+
+### `gitrama_changelog`
+
+Generate a changelog.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `since` | string | `""` | Start ref (tag, branch, hash) |
+| `until` | string | `""` | End ref (default: HEAD) |
+| `format` | string | `"markdown"` | `"markdown"` or `"json"` |
+| `model` | string | `""` | AI model override |
+
+**Example prompt:** *"Generate a changelog since v1.0.0"*
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GTR_CWD` | `os.getcwd()` | Working directory for git operations |
+| `GTR_MCP_TRANSPORT` | `"stdio"` | Transport: `"stdio"` or `"streamable-http"` |
+| `GTR_MCP_HOST` | `"0.0.0.0"` | HTTP host (when using streamable-http) |
+| `GTR_MCP_PORT` | `"8765"` | HTTP port (when using streamable-http) |
+
+### HTTP Transport (for CI/CD)
+
+```bash
+GTR_MCP_TRANSPORT=streamable-http GTR_MCP_PORT=8765 gitrama-mcp
+```
+
+Then connect your client to `http://localhost:8765/mcp`.
+
+---
+
+## Requirements
+
+- Python 3.10+
+- Git installed and in PATH
+- A Gitrama API key or local Ollama instance
+
+Set your API key:
+```bash
+gtr config --key YOUR_API_KEY
+```
+
+Or use a local model:
+```bash
+gtr config --provider ollama --model llama3
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/onegreatdev/gitrama-mcp.git
+cd gitrama-mcp
+pip install -e ".[dev]"
+
+# Test with MCP Inspector
+mcp dev src/gitrama_mcp/server.py
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+Built by [Alfonso Harding](https://linkedin.com/in/alfonsoharding) · [gitrama.ai](https://gitrama.ai)
+
+🌿

gitrama_mcp-1.0.0/README.md

@@ -0,0 +1,317 @@
+# 🌿 Gitrama MCP Server
+
+> AI-powered Git intelligence for your IDE — smart commits, branch names, PR descriptions, changelogs, and workflow management.
+
+[![PyPI](https://img.shields.io/pypi/v/gitrama-mcp)](https://pypi.org/project/gitrama-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/gitrama-mcp)](https://pypi.org/project/gitrama-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## What is this?
+
+Gitrama MCP Server exposes [Gitrama](https://gitrama.ai)'s CLI as **10 MCP tools** that any AI assistant can use. Instead of typing `gtr commit` in your terminal, your AI assistant calls the tool directly — analyzing your code changes, generating commit messages, suggesting branch names, and more.
+
+**Works with:** Cursor · Claude Desktop · Claude Code · Windsurf · VS Code (Copilot) · Zed · any MCP-compatible client
+
+## Install (< 60 seconds)
+
+### Step 1: Install the package
+
+```bash
+pip install gitrama-mcp
+```
+
+Or with uv:
+```bash
+uv pip install gitrama-mcp
+```
+
+This installs both the MCP server and the `gitrama` CLI.
+
+### Step 2: Connect to your IDE
+
+<details>
+<summary><b>Cursor</b></summary>
+
+Add to `.cursor/mcp.json` in your project (or global settings):
+
+```json
+{
+  "mcpServers": {
+    "gitrama": {
+      "command": "gitrama-mcp"
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Claude Desktop</b></summary>
+
+Add to `claude_desktop_config.json`:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "gitrama": {
+      "command": "gitrama-mcp"
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+```bash
+claude mcp add gitrama gitrama-mcp
+```
+</details>
+
+<details>
+<summary><b>VS Code (Copilot)</b></summary>
+
+Add to `.vscode/settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "gitrama": {
+        "command": "gitrama-mcp"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Windsurf</b></summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gitrama": {
+      "command": "gitrama-mcp"
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Zed</b></summary>
+
+Add to Zed settings (`⌘,`):
+
+```json
+{
+  "context_servers": {
+    "gitrama": {
+      "command": {
+        "path": "gitrama-mcp"
+      }
+    }
+  }
+}
+```
+</details>
+
+### Step 3: Done.
+
+Ask your AI: *"Commit my staged changes"* — and watch it call `gitrama_commit`.
+
+---
+
+## Tools (10)
+
+### Commit Intelligence
+
+| Tool | Description |
+|------|-------------|
+| `gitrama_commit` | Generate an AI commit message for staged changes |
+| `gitrama_stage_and_commit` | Stage files + commit in one step |
+| `gitrama_commit_quality` | Analyze quality of recent commit messages |
+
+### Branch Management
+
+| Tool | Description |
+|------|-------------|
+| `gitrama_branch` | Create a new branch |
+| `gitrama_branch_suggest` | Get AI-suggested branch names from a description |
+
+### PR & Changelog
+
+| Tool | Description |
+|------|-------------|
+| `gitrama_pr` | Generate a PR description from branch diff |
+| `gitrama_changelog` | Generate a changelog between refs |
+
+### Stream (Workflow) Management
+
+| Tool | Description |
+|------|-------------|
+| `gitrama_stream_status` | Show current workflow stream |
+| `gitrama_stream_switch` | Switch to a different stream |
+| `gitrama_stream_list` | List all streams in the repo |
+
+---
+
+## Tool Details
+
+### `gitrama_commit`
+
+Generate an AI-powered commit message for staged changes.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `message_type` | string | `"conventional"` | Style: `"conventional"`, `"detailed"`, or `"simple"` |
+| `context` | string | `""` | Optional context (e.g., `"fixing auth bug"`) |
+| `model` | string | `""` | AI model override (e.g., `"gpt-4o"`, `"claude-sonnet-4-20250514"`) |
+
+**Example prompt:** *"Commit my changes with a conventional message, context: refactoring the payment module"*
+
+---
+
+### `gitrama_stage_and_commit`
+
+Stage files and commit in one step.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `files` | string | `"."` | Files to stage (`.` for all, or space-separated paths) |
+| `message_type` | string | `"conventional"` | Commit style |
+| `context` | string | `""` | Optional context |
+| `model` | string | `""` | AI model override |
+
+**Example prompt:** *"Stage and commit all my changes"*
+
+---
+
+### `gitrama_commit_quality`
+
+Analyze recent commit message quality.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `count` | int | `10` | Number of commits to analyze (1-50) |
+
+**Example prompt:** *"How good are our last 20 commit messages?"*
+
+---
+
+### `gitrama_branch_suggest`
+
+Get AI-suggested branch names.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `description` | string | *required* | Task description |
+| `model` | string | `""` | AI model override |
+
+**Example prompt:** *"Suggest a branch name for adding OAuth2 support"*
+
+---
+
+### `gitrama_pr`
+
+Generate a PR description.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `base` | string | `""` | Target branch (default: main/master) |
+| `model` | string | `""` | AI model override |
+
+**Example prompt:** *"Write a PR description for this branch"*
+
+---
+
+### `gitrama_changelog`
+
+Generate a changelog.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `since` | string | `""` | Start ref (tag, branch, hash) |
+| `until` | string | `""` | End ref (default: HEAD) |
+| `format` | string | `"markdown"` | `"markdown"` or `"json"` |
+| `model` | string | `""` | AI model override |
+
+**Example prompt:** *"Generate a changelog since v1.0.0"*
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GTR_CWD` | `os.getcwd()` | Working directory for git operations |
+| `GTR_MCP_TRANSPORT` | `"stdio"` | Transport: `"stdio"` or `"streamable-http"` |
+| `GTR_MCP_HOST` | `"0.0.0.0"` | HTTP host (when using streamable-http) |
+| `GTR_MCP_PORT` | `"8765"` | HTTP port (when using streamable-http) |
+
+### HTTP Transport (for CI/CD)
+
+```bash
+GTR_MCP_TRANSPORT=streamable-http GTR_MCP_PORT=8765 gitrama-mcp
+```
+
+Then connect your client to `http://localhost:8765/mcp`.
+
+---
+
+## Requirements
+
+- Python 3.10+
+- Git installed and in PATH
+- A Gitrama API key or local Ollama instance
+
+Set your API key:
+```bash
+gtr config --key YOUR_API_KEY
+```
+
+Or use a local model:
+```bash
+gtr config --provider ollama --model llama3
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/onegreatdev/gitrama-mcp.git
+cd gitrama-mcp
+pip install -e ".[dev]"
+
+# Test with MCP Inspector
+mcp dev src/gitrama_mcp/server.py
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+Built by [Alfonso Harding](https://linkedin.com/in/alfonsoharding) · [gitrama.ai](https://gitrama.ai)
+
+🌿

gitrama_mcp-1.0.0/configs/claude_desktop_config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitrama": {
+      "command": "gitrama-mcp",
+      "env": {}
+    }
+  }
+}

gitrama_mcp-1.0.0/configs/cursor_mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "gitrama": {
+      "command": "gitrama-mcp",
+      "env": {
+        "GTR_CWD": "${workspaceFolder}"
+      }
+    }
+  }
+}

gitrama_mcp-1.0.0/configs/vscode_settings.json

@@ -0,0 +1,12 @@
+{
+  "mcp": {
+    "servers": {
+      "gitrama": {
+        "command": "gitrama-mcp",
+        "env": {
+          "GTR_CWD": "${workspaceFolder}"
+        }
+      }
+    }
+  }
+}

gitrama_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gitrama-mcp"
+version = "1.0.0"
+description = "MCP Server for Gitrama — AI-powered Git intelligence for your IDE"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Alfonso Harding", email = "alfonso@onegreatdev.com" },
+]
+keywords = ["mcp", "git", "ai", "commit", "gitrama", "cursor", "claude"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = [
+    "mcp>=1.2.0",
+    "gitrama>=1.0.3",
+]
+
+[project.urls]
+Homepage = "https://gitrama.ai"
+Repository = "https://github.com/onegreatdev/gitrama-mcp"
+Documentation = "https://gitrama.ai/docs"
+Issues = "https://github.com/onegreatdev/gitrama-mcp/issues"
+
+[project.scripts]
+gitrama-mcp = "gitrama_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gitrama_mcp"]

gitrama_mcp-1.0.0/src/gitrama_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Gitrama MCP Server — AI-powered Git intelligence for your IDE."""
+
+__version__ = "1.0.0"

gitrama_mcp-1.0.0/src/gitrama_mcp/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running with: python -m gitrama_mcp"""
+from gitrama_mcp.server import main
+
+main()

gitrama_mcp-1.0.0/src/gitrama_mcp/server.py

@@ -0,0 +1,407 @@
+"""
+Gitrama MCP Server — 10 tools for AI-powered Git intelligence.
+
+Exposes Gitrama's CLI capabilities as MCP tools for use in:
+- Cursor
+- Claude Desktop
+- Claude Code
+- Windsurf
+- VS Code (Copilot)
+- Zed
+- CI/CD pipelines
+
+Transport: stdio (default) or streamable-http
+"""
+
+import asyncio
+import json
+import os
+import subprocess
+import sys
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+# ---------------------------------------------------------------------------
+# Server initialisation
+# ---------------------------------------------------------------------------
+
+mcp = FastMCP(
+    "gitrama",
+    instructions=(
+        "AI-powered Git intelligence — smart commits, branch naming, "
+        "PR descriptions, changelogs, and stream-based workflow management. "
+        "Requires `gitrama` CLI installed (pip install gitrama)."
+    ),
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _get_cwd() -> str:
+    """Return the working directory — prefer GTR_CWD env var, then os.getcwd()."""
+    return os.environ.get("GTR_CWD", os.getcwd())
+
+
+async def _run_gtr(args: list[str], cwd: Optional[str] = None, timeout: int = 120) -> dict:
+    """
+    Run a `gtr` CLI command and return structured output.
+
+    Returns:
+        dict with keys: success (bool), stdout (str), stderr (str), returncode (int)
+    """
+    cmd = ["gtr"] + args
+    work_dir = cwd or _get_cwd()
+
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=work_dir,
+        )
+        stdout_bytes, stderr_bytes = await asyncio.wait_for(
+            proc.communicate(), timeout=timeout
+        )
+        stdout = stdout_bytes.decode("utf-8", errors="replace").strip()
+        stderr = stderr_bytes.decode("utf-8", errors="replace").strip()
+        return {
+            "success": proc.returncode == 0,
+            "stdout": stdout,
+            "stderr": stderr,
+            "returncode": proc.returncode,
+        }
+    except asyncio.TimeoutError:
+        return {
+            "success": False,
+            "stdout": "",
+            "stderr": f"Command timed out after {timeout}s: {' '.join(cmd)}",
+            "returncode": -1,
+        }
+    except FileNotFoundError:
+        return {
+            "success": False,
+            "stdout": "",
+            "stderr": (
+                "gitrama CLI not found. Install with: pip install gitrama\n"
+                "Docs: https://gitrama.ai"
+            ),
+            "returncode": -1,
+        }
+
+
+def _format_result(result: dict, context: str = "") -> str:
+    """Format a CLI result into a clean MCP response."""
+    if result["success"]:
+        return result["stdout"] if result["stdout"] else f"✅ {context or 'Done'}"
+    else:
+        msg = result["stderr"] or result["stdout"] or "Unknown error"
+        return f"❌ Error: {msg}"
+
+
+# ---------------------------------------------------------------------------
+# Tool 1: gitrama_commit
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def gitrama_commit(
+    message_type: str = "conventional",
+    context: str = "",
+    model: str = "",
+) -> str:
+    """
+    Generate an AI-powered commit message for currently staged changes.
+
+    Analyzes the git diff of staged files and produces a high-quality,
+    contextual commit message. Requires files to be staged first (git add).
+
+    Args:
+        message_type: Commit message style — "conventional" (default),
+                      "detailed", or "simple".
+        context: Optional context to guide the AI (e.g., "fixing auth bug",
+                 "refactoring payment module").
+        model: Optional AI model override (e.g., "gpt-4o", "claude-sonnet-4-20250514",
+               "ollama/llama3").
+    """
+    args = ["commit", "--type", message_type]
+    if context:
+        args.extend(["--context", context])
+    if model:
+        args.extend(["--model", model])
+    # Use --yes to auto-confirm in non-interactive mode
+    args.append("--yes")
+
+    result = await _run_gtr(args)
+    return _format_result(result, "Commit created")
+
+
+# ---------------------------------------------------------------------------
+# Tool 2: gitrama_stage_and_commit
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def gitrama_stage_and_commit(
+    files: str = ".",
+    message_type: str = "conventional",
+    context: str = "",
+    model: str = "",
+) -> str:
+    """
+    Stage files and create an AI-powered commit in one step.
+
+    Equivalent to `git add <files> && gtr commit`. Stages the specified
+    files (or all changes), then generates and applies an AI commit message.
+
+    Args:
+        files: Files to stage — "." for all changes (default), or
+               space-separated paths (e.g., "src/auth.py tests/test_auth.py").
+        message_type: Commit style — "conventional", "detailed", or "simple".
+        context: Optional context to guide the AI.
+        model: Optional AI model override.
+    """
+    # Stage files first
+    file_list = files.split() if files != "." else ["."]
+    stage_cmd = ["git", "add"] + file_list
+    try:
+        stage_proc = await asyncio.create_subprocess_exec(
+            *stage_cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=_get_cwd(),
+        )
+        await stage_proc.communicate()
+    except Exception as e:
+        return f"❌ Failed to stage files: {e}"
+
+    # Now commit
+    return await gitrama_commit(
+        message_type=message_type,
+        context=context,
+        model=model,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tool 3: gitrama_commit_quality
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def gitrama_commit_quality(
+    count: int = 10,
+) -> str:
+    """
+    Analyze the quality of recent commit messages in the repository.
+
+    Scores commits on clarity, specificity, and conventional format adherence.
+    Returns a quality report with per-commit scores and suggestions.
+
+    Args:
+        count: Number of recent commits to analyze (default: 10, max: 50).
+    """
+    count = min(max(count, 1), 50)
+    result = await _run_gtr(["commit", "--quality", "--count", str(count)])
+    return _format_result(result, "Commit quality analysis complete")
+
+
+# ---------------------------------------------------------------------------
+# Tool 4: gitrama_branch
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def gitrama_branch(
+    name: str,
+    base: str = "",
+) -> str:
+    """
+    Create a new git branch with the specified name.
+
+    Creates and checks out a new branch. Use gitrama_branch_suggest to
+    get AI-suggested branch names first.
+
+    Args:
+        name: Branch name (e.g., "feat/user-auth", "fix/payment-timeout").
+        base: Base branch to create from (default: current branch).
+    """
+    args = ["branch", name]
+    if base:
+        args.extend(["--base", base])
+    result = await _run_gtr(args)
+    return _format_result(result, f"Branch '{name}' created")
+
+
+# ---------------------------------------------------------------------------
+# Tool 5: gitrama_branch_suggest
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def gitrama_branch_suggest(
+    description: str,
+    model: str = "",
+) -> str:
+    """
+    Get AI-suggested branch names based on a task description.
+
+    Analyzes the description and suggests properly formatted branch names
+    following conventional patterns (feat/, fix/, chore/, etc.).
+
+    Args:
+        description: What you're working on (e.g., "add user authentication
+                     with OAuth2", "fix timeout in payment processing").
+        model: Optional AI model override.
+    """
+    args = ["branch", "--suggest", description]
+    if model:
+        args.extend(["--model", model])
+    result = await _run_gtr(args)
+    return _format_result(result, "Branch suggestions generated")
+
+
+# ---------------------------------------------------------------------------
+# Tool 6: gitrama_pr
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def gitrama_pr(
+    base: str = "",
+    model: str = "",
+) -> str:
+    """
+    Generate an AI-powered pull request description.
+
+    Analyzes the diff between the current branch and the base branch,
+    then generates a comprehensive PR description with title, summary,
+    changes list, and testing notes.
+
+    Args:
+        base: Target branch for the PR (default: main or master).
+        model: Optional AI model override.
+    """
+    args = ["pr"]
+    if base:
+        args.extend(["--base", base])
+    if model:
+        args.extend(["--model", model])
+    result = await _run_gtr(args)
+    return _format_result(result, "PR description generated")
+
+
+# ---------------------------------------------------------------------------
+# Tool 7: gitrama_changelog
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def gitrama_changelog(
+    since: str = "",
+    until: str = "",
+    format: str = "markdown",
+    model: str = "",
+) -> str:
+    """
+    Generate an AI-powered changelog from commit history.
+
+    Groups commits by type (features, fixes, etc.) and produces a
+    human-readable changelog. Great for release notes.
+
+    Args:
+        since: Start ref — tag, branch, or commit hash (e.g., "v1.0.0").
+               Defaults to the last tag.
+        until: End ref (default: HEAD).
+        format: Output format — "markdown" (default) or "json".
+        model: Optional AI model override.
+    """
+    args = ["changelog"]
+    if since:
+        args.extend(["--since", since])
+    if until:
+        args.extend(["--until", until])
+    if format:
+        args.extend(["--format", format])
+    if model:
+        args.extend(["--model", model])
+    result = await _run_gtr(args)
+    return _format_result(result, "Changelog generated")
+
+
+# ---------------------------------------------------------------------------
+# Tool 8: gitrama_stream_status
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def gitrama_stream_status() -> str:
+    """
+    Show the current Gitrama stream (workflow context).
+
+    Streams are Gitrama's concept of workflow focus — they track what
+    you're working on and influence AI suggestions. Returns the active
+    stream name, description, and associated branch.
+    """
+    result = await _run_gtr(["stream", "status"])
+    return _format_result(result, "Stream status retrieved")
+
+
+# ---------------------------------------------------------------------------
+# Tool 9: gitrama_stream_switch
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def gitrama_stream_switch(
+    name: str,
+    description: str = "",
+) -> str:
+    """
+    Switch to a different Gitrama stream (workflow context).
+
+    Creates a new stream or switches to an existing one. Streams help
+    the AI understand what you're working on for better suggestions.
+
+    Args:
+        name: Stream name (e.g., "auth-refactor", "payment-v2").
+        description: Optional description of the stream's purpose.
+    """
+    args = ["stream", "switch", name]
+    if description:
+        args.extend(["--description", description])
+    result = await _run_gtr(args)
+    return _format_result(result, f"Switched to stream '{name}'")
+
+
+# ---------------------------------------------------------------------------
+# Tool 10: gitrama_stream_list
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def gitrama_stream_list() -> str:
+    """
+    List all Gitrama streams in the current repository.
+
+    Shows all defined streams with their names, descriptions,
+    and associated branches. The active stream is highlighted.
+    """
+    result = await _run_gtr(["stream", "list"])
+    return _format_result(result, "Streams listed")
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main():
+    """Run the Gitrama MCP server."""
+    transport = os.environ.get("GTR_MCP_TRANSPORT", "stdio")
+
+    if transport == "stdio":
+        mcp.run(transport="stdio")
+    elif transport == "streamable-http":
+        host = os.environ.get("GTR_MCP_HOST", "0.0.0.0")
+        port = int(os.environ.get("GTR_MCP_PORT", "8765"))
+        mcp.settings.host = host
+        mcp.settings.port = port
+        mcp.run(transport="streamable-http")
+    else:
+        print(f"Unknown transport: {transport}. Use 'stdio' or 'streamable-http'.", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()