Git Polite

Git staging on autopilot — let AI organize your changes into clean, focused commits.

Overview

git-polite is a Model Context Protocol (MCP) server that brings intelligent git staging to AI agents. It can automatically organize messy work-in-progress into well-structured commits, or give you surgical precision with line-by-line staging when you need it.

Features

• Autopilot Mode: Let AI analyze your changes and create multiple focused commits automatically

• Line-Level Staging: Stage individual additions and deletions by line number with surgical precision

• Untracked File Support: Stage parts of newly created files (not just modified files)

• Range Selection: Apply multiple changes at once using ranges (e.g., 0001-0005,0020-0025)

• LLM-Friendly Output: Byte-based pagination and smart truncation protect context windows

• Binary File Detection: Automatically detects and skips binary files

• MCP Integration: Works seamlessly with Claude Code, Claude Desktop, and other MCP clients

MCP Server Mode

Run as an MCP server for integration with MCP clients:

uv run git_polite.py mcp

MCP Tools

The server exposes four tools:

1. list_changes: List unstaged git changes (including untracked files) as numbered lines

   • Smart truncation: Large diffs (>10KB) are automatically truncated to protect LLM context

   • Parameters:

     • paths (optional): List of file paths to filter

     • page_token (optional): Pagination token

     • page_size_files (optional, default: 50): Max files per page

     • page_size_bytes (optional, default: 30KB): Max cumulative bytes per page

     • unified (optional, default: 20): Context lines around changes

   • Output includes truncated: true flag for large files with a reason explaining the truncation

   • For truncated files, use the diff tool to view complete content

2. diff: View complete diff for a single file without truncation

   • Use this for files that are truncated in list_changes output

   • Returns the same numbered line format as list_changes, enabling partial staging

   • Unlike git diff, this tool provides line numbers required by apply_changes

   • Never truncates output, suitable for large files with extensive changes

   • Parameters:

     • path (required): File path to view diff for

     • unified (optional, default: 20): Context lines around changes

   • Returns: Complete diff with size_bytes indicating actual output size

3. apply_changes: Apply selected changes to git index by number (supports partial staging of untracked files)

   • Parameters:

     • path: File path to apply changes to

     • numbers: Change numbers (format: NNNN,MMMM,PPPP-QQQQ)

4. auto_commit: Start autopilot mode to organize all changes into focused commits

   • Shows recent commit messages for style reference

   • Analyzes all unstaged changes and suggests logical groupings

   • Guides AI through creating multiple atomic commits from messy WIP

MCP Client Configuration

Using uvx (Recommended)

Use uvx to run directly from GitHub:

Claude Desktop Configuration:

{
  "mcpServers": {
    "git-polite": {
      "command": "uvx",
      "args": [
        "git-polite@git+https://github.com/uneco/mcp-git-polite.git",
        "mcp"
      ]
    }
  }
}

Claude CLI:

claude mcp add -s user git-polite uvx git-polite@git+https://github.com/uneco/mcp-git-polite.git mcp

Using Docker

Alternatively, use the Docker image from GitHub Container Registry:

{
  "mcpServers": {
    "git-polite": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "${workspaceFolder}:/workspace",
        "-w",
        "/workspace",
        "ghcr.io/uneco/mcp-git-polite:latest",
        "mcp"
      ]
    }
  }
}

How It Works

1. List Phase: The tool parses git diff output (including untracked files via git diff --no-index) and numbers each addition (+) and deletion (-) sequentially

2. Truncation Check: Each file's diff size is measured. Files exceeding 10KB are marked as truncated to protect LLM context

3. Display: Changes are shown with their numbers, along with surrounding context lines. Files are marked as "added" (untracked), "modified", or "deleted"

4. Pagination: Results are paginated based on cumulative byte size (default 30KB per page) to prevent overwhelming the LLM

5. Apply Phase: When you specify line numbers, the tool:

   • Reads the staged version from git index (or creates new file for untracked files)

   • Applies only the selected changes

   • Updates the git index with the partial changes

Output Format

List Output

{
  "page_token_next": "optional-token",
  "files": [
    {
      "path": "src/main.py",
      "binary": false,
      "status": "modified",
      "lines": [
        "0001: + new line 1",
        "        context line",
        "0002: - deleted line",
        "0003: + new line 2",
        "        ..."
      ]
    },
    {
      "path": "src/new_file.py",
      "binary": false,
      "status": "added",
      "lines": [
        "0001: + def hello():",
        "0002: +     print('Hello')"
      ]
    },
    {
      "path": "src/refactored_module.py",
      "binary": false,
      "status": "modified",
      "truncated": true,
      "reason": "diff too large (45.2 KB, max 10 KB)",
      "lines": []
    }
  ],
  "stats": {
    "files": 3,
    "lines": 5,
    "truncated_files": 1,
    "page_bytes": 4532
  }
}

When a file shows truncated: true, use the diff tool to view its complete content. The diff tool provides the same numbered line format needed for partial staging, which git diff cannot provide.

Apply Output

{
  "applied": [
    {
      "file": "src/main.py",
      "applied_count": 3,
      "after_applying": {
        "diff": ["0001: + remaining", "0002: - unstaged", "0003: + changes"],
        "unstaged_lines": 5
      }
    }
  ],
  "skipped": [],
  "stats": {
    "files": 1,
    "changes_applied": 3,
    "changes_skipped": 0
  }
}

Requirements

• Python 3.10 or higher

• Git (command-line tool)

• MCP server package (mcp>=1.10.0)

Development

# Install dependencies
uv sync

# Run tests (if available)
uv run pytest

# Format code
uv run black git_polite.py

# Type check
uv run mypy git_polite.py

Use Cases

• AI-Powered Commit Organization: Let AI analyze your WIP and create clean commit history automatically

• Incremental Commits: Break down large changes into logical, atomic commits

• Partial File Staging: Stage only specific lines of a new file while keeping the rest unstaged

• Code Review Preparation: Stage related changes together, even if scattered across files

• Refactoring: Separate formatting changes from logic changes with surgical precision

Example Workflows

Working with Truncated Files

When you encounter a truncated file (e.g., a large refactored file with many changes):

# Step 1: List all changes
result = list_changes()

# Step 2: Notice a truncated file
# {
#   "path": "src/api_client.py",
#   "truncated": true,
#   "reason": "diff too large (45.2 KB, max 10 KB)",
#   "lines": []
# }

# Step 3: View the complete numbered diff
# Use the diff tool (not git diff) because it provides line numbers needed for partial staging
full_diff = diff(path="src/api_client.py")

# Step 4: Selectively stage related changes (e.g., bug fixes separate from refactoring)
apply_changes(path="src/api_client.py", numbers="0001-0050,0120-0135")

Pagination Example

# Get first page (max 30KB)
page1 = list_changes(page_size_bytes=30720)

# Continue with next page if needed
if page1["page_token_next"]:
    page2 = list_changes(page_token=page1["page_token_next"])

Limitations

• Works only with text files (binary files are detected and skipped)

• Line numbers are ephemeral - they change after each apply operation

• Context mismatches (file drift) will cause operations to fail safely

• For untracked files, the entire file content must be present in the working directory

• Large files (>10KB diff) are truncated in list_changes - use diff tool to view them

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

Built with FastMCP and the Model Context Protocol.