Skip to main content
Glama
uneco

Git Polite

by uneco
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

GitHub Workflow Status GitHub GitHub commit activity GitHub last commit

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.

Related MCP server: Git Code Review MCP

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

      • lines: 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", lines="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.

Available Tools

5 tools
apply_changesA
Destructive

Stage selected lines to git index for partial commits (alternative to git add -p).

After using list_changes to view numbered changes, use this tool to selectively stage specific lines or ranges to the git index. This enables creating multiple logical commits from a single file with intermixed changes.

Unlike git add, this tool can stage parts of untracked files (newly created files). You can commit only the first 10 lines of a new file while keeping the rest unstaged.

Number format examples:

  • Single lines: "0001,0002,0005"

  • Ranges: "0001-0010"

  • Combined: "0001-0005,0020-0025"

The tool updates the git index directly and reports remaining unstaged changes, allowing iterative staging for multiple commits from the same file.

Args: path: File path to apply changes to numbers: Change numbers in format: NNNN,MMMM,PPPP-QQQQ

Returns: JSON string with format: {applied: [{file, applied_count, after_applying: {diff, unstaged_lines}}], skipped, stats}

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
numbersYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate destructiveHint=true and readOnlyHint=false, which the description aligns with by stating 'updates the git index directly' and 'reports remaining unstaged changes'. It adds valuable context about iterative staging and handling of untracked files, though it doesn't detail rate limits or auth needs beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by usage guidelines, examples, and behavioral details in a logical flow. Every sentence adds value, such as clarifying capabilities with untracked files and providing format examples, with no wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (destructive operation with partial staging), the description is complete: it explains the purpose, usage, parameters, and behavior, and with an output schema present, it doesn't need to detail return values, covering all necessary context for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining both parameters: 'path' as 'File path to apply changes to' and 'numbers' with detailed format examples (e.g., '0001,0002,0005', '0001-0010'), adding meaning beyond the basic schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Stage selected lines to git index for partial commits') and resource ('git index'), distinguishing it from siblings like 'auto_commit' and 'unstack' by emphasizing selective staging for partial commits, unlike full-file operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use this tool ('After using list_changes to view numbered changes') and provides alternatives ('alternative to `git add -p`'), with clear differentiation from siblings by noting it can stage parts of untracked files, unlike typical 'git add'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

auto_commitA
Read-only

Start a guided session to organize and commit all unstaged changes with appropriate granularity.

This tool helps you organize your changes and create multiple focused commits by:

  1. Showing recent commit messages as style reference

  2. Displaying summary statistics of all unstaged changes (file counts, line counts)

  3. Providing step-by-step instructions for the commit workflow

This tool uses progressive disclosure: it shows only statistics (additions/deletions per file) to avoid token limits. Use list_changes or diff tools to view detailed changes for specific files.

Use this when you have multiple logical changes mixed together and want to organize them into separate, well-structured commits.

Returns: JSON with recent commits, file statistics, and next steps for the agent

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true and openWorldHint=true, indicating a safe, exploratory operation. The description adds valuable behavioral context beyond annotations: it explains the tool uses 'progressive disclosure' to avoid token limits, shows recent commits and file statistics, and provides step-by-step instructions. However, it doesn't mention rate limits, authentication needs, or potential side effects, keeping it from a perfect score.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and concise. It starts with a clear purpose statement, then lists key features in bullet points, provides usage guidance, and ends with return information. Every sentence adds value without repetition, and it's front-loaded with the most important information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (guided session for organizing commits), the description is complete. It explains the purpose, workflow, when to use it, alternatives, and behavioral traits. With annotations covering safety and an output schema declared, the description doesn't need to detail return values or permissions, making it fully adequate for the agent's needs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on the tool's behavior and output. A baseline of 4 is applied for zero parameters, as the description compensates by explaining what the tool does without redundant parameter info.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Start a guided session to organize and commit all unstaged changes with appropriate granularity.' It specifies the verb ('organize and commit'), resource ('unstaged changes'), and scope ('with appropriate granularity'). It distinguishes from siblings by focusing on guided organization rather than direct diff viewing (list_changes, diff) or other operations (apply_changes, unstack).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool: 'Use this when you have multiple logical changes mixed together and want to organize them into separate, well-structured commits.' It also provides alternatives: 'Use list_changes or diff tools to view detailed changes for specific files.' This gives clear context for when to choose this tool over its siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

diffA
Read-only

View complete diff for a single file without truncation.

This tool is designed for viewing the full diff of a single file, regardless of size. Unlike list_changes, this tool will NEVER truncate the output, making it suitable for reviewing large files like lock files or generated code.

Use this when you need to:

  • View the complete diff of a large file (e.g., uv.lock, package-lock.json)

  • Review all changes in a specific file before staging

  • Analyze files that would be truncated by list_changes

Args: path: File path to view diff for (required) unified: Context lines around changes (default: UNIFIED_LIST_DEFAULT)

Returns: JSON string with format: {path, binary, status, lines, size_bytes}

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
unifiedNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds valuable behavioral context beyond annotations: it specifies that output is never truncated (a key trait not covered by readOnlyHint or openWorldHint), mentions suitability for large files, and implies performance considerations. No contradiction with annotations exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded, with a clear purpose statement followed by usage guidelines and parameter details. Every sentence adds value, and there's no redundant information, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, rich annotations, and the presence of an output schema (which handles return values), the description is complete. It covers purpose, usage, behavioral traits, and parameter semantics adequately without needing to explain outputs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining 'path' as 'File path to view diff for' and 'unified' as 'Context lines around changes', adding meaning beyond the bare schema. However, it doesn't detail default values or constraints beyond what's implied.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('view complete diff') and resource ('single file'), explicitly distinguishing it from sibling 'list_changes' by emphasizing no truncation. It directly answers what the tool does in the first sentence.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool vs. alternatives, listing three specific use cases (e.g., 'View the complete diff of a large file') and naming 'list_changes' as an alternative that truncates output. It clearly defines the context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_changesA
Read-only

View unstaged git changes with line-level selection numbers for partial staging.

PREFER THIS OVER git diff when you need to selectively stage changes. Unlike git diff, this tool includes untracked files (newly created files) in the output. This tool numbers each changed line (0001, 0002, etc.) so you can stage specific lines or ranges instead of entire files. Essential for creating multiple logical commits from intermixed changes.

Key features:

  • Includes untracked files (status: "added") as well as modified files (status: "modified")

  • Numbers every changed line for precise selection

  • Supports byte-based pagination to protect LLM context

  • Auto-truncates large diffs (>10KB) with clear indication

Handling truncated files: When a file shows truncated: true with empty lines: [], use the diff tool to view its complete content. The diff tool returns the same numbered line format needed for partial staging with apply_changes, whereas git diff output lacks line numbers and cannot be used for selective staging. For example, if a large refactored file is truncated, call diff(path="src/large_module.py") to see the full numbered diff and selectively stage related changes.

Use cases:

  • Breaking up large changes into multiple focused commits

  • Staging only specific changes while keeping others unstaged

  • Creating atomic commits from work-in-progress code

  • Separating refactoring from feature changes

  • Selectively staging parts of newly created files

After viewing changes, use apply_changes with the line numbers to stage selected changes.

Args: paths: Optional list of file paths to filter (default: all files) page_token: Opaque pagination token from previous response page_size_files: Max files per page - safety limit (default: PAGE_SIZE_FILES_DEFAULT) page_size_bytes: Max bytes per page - primary limit (default: PAGE_SIZE_BYTES_DEFAULT) unified: Context lines around changes (default: UNIFIED_LIST_DEFAULT)

Returns: JSON string with format: {page_token_next, files: [{path, binary, lines}], stats}

ParametersJSON Schema
NameRequiredDescriptionDefault
pathsNo
page_tokenNo
page_size_filesNo
page_size_bytesNo
unifiedNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint=true and openWorldHint=true, but the description adds valuable behavioral context beyond this. It explains key features like including untracked files, numbering changed lines, pagination support, and auto-truncation of large diffs. It details how to handle truncated files and clarifies that this tool's output format is required for selective staging with `apply_changes`. No contradiction with annotations exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the core purpose. Each section (Key features, Handling truncated files, Use cases, Args, Returns) earns its place by providing essential information without redundancy. The text is dense with actionable guidance while remaining focused on helping the agent use the tool correctly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (pagination, truncation, line numbering) and the presence of annotations and output schema, the description is complete. It covers purpose, usage guidelines, behavioral details, parameter semantics, and integration with sibling tools. The output schema handles return format documentation, so the description appropriately focuses on operational context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates well by explaining all 5 parameters in the Args section. It provides meaning for each parameter: 'paths' filters files, 'page_token' is for pagination, 'page_size_files' is a safety limit, 'page_size_bytes' is the primary limit, and 'unified' controls context lines. Default values are noted, adding clarity beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'View unstaged git changes with line-level selection numbers for partial staging.' It specifies the verb ('view'), resource ('unstaged git changes'), and key functionality ('line-level selection numbers'). It explicitly distinguishes from sibling `git diff` by noting inclusion of untracked files and line numbering for staging.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool: 'PREFER THIS OVER `git diff` when you need to selectively stage changes.' It also specifies when to use alternatives: use `diff` tool for truncated files, and notes that `git diff` output lacks line numbers. It lists specific use cases and mentions the next step: 'After viewing changes, use apply_changes with the line numbers.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

unstackA
Destructive

Unstack linear commits into parallel branches for separate PRs.

This tool transforms a linear commit history (A -> B -> C -> D) into parallel branches (A -> B, A -> C, A -> D) where each branch contains specific commits cherry-picked from the original history.

Use this when you've made multiple changes in sequence but want to create separate PRs for different logical changes. Each branch can be independently reviewed and merged.

Example scenario: You have commits: fix-bug -> add-feature -> update-docs You want separate PRs, so you create:

  • feat/999: [fix-bug, update-docs]

  • feat/1000: [add-feature]

This creates two branches from origin/main:

  • feat/999 with fix-bug and update-docs cherry-picked in order

  • feat/1000 with add-feature cherry-picked

Args: branches: Dictionary mapping branch names to lists of commit references. Commits can be specified as SHA, branch names, or symbolic refs (e.g., HEAD~2). Commits are cherry-picked in the order specified. parent: Base commit to branch from (default: "origin/main"). All branches will start from this commit.

Returns: JSON string with format: { created_branches: [{name, commits_applied, head_sha}], errors: [{branch, commit, error}], stats: {total_branches, successful_branches, failed_branches} }

Note: - Existing branches with the same name will cause an error - The current branch is not changed by this operation - Uses low-level git commands (commit-tree, update-ref) to avoid changing working directory

ParametersJSON Schema
NameRequiredDescriptionDefault
branchesYes
parentNoorigin/main

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds significant behavioral context beyond annotations. While annotations indicate destructive and non-read-only operations, the description details that it 'creates branches from origin/main', 'cherry-picks commits in order', warns about 'existing branches with the same name will cause an error', clarifies 'the current branch is not changed', and explains it 'uses low-level git commands to avoid changing working directory'. This provides crucial operational insights.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured and appropriately sized. It front-loads the core purpose, provides usage guidelines with an example, details parameters, return format, and important notes. Every sentence adds value without redundancy, efficiently covering complex functionality in a clear hierarchy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (destructive operation with nested parameters) and 0% schema coverage, the description is exceptionally complete. It explains purpose, usage, parameters, return values (though output schema exists, it clarifies format), and behavioral notes. With annotations covering safety aspects, the description adds all necessary operational context for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining both parameters. It details that 'branches' is a dictionary mapping names to commit lists with examples of commit references (SHA, branch names, symbolic refs) and ordering. It explains 'parent' as the base commit with default 'origin/main' and that all branches start from it. This adds essential meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('unstack', 'transforms', 'creates') and resources ('linear commits', 'parallel branches', 'separate PRs'). It distinguishes from siblings by focusing on restructuring commit history rather than applying changes, auto-committing, diffing, or listing changes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'Use this when you've made multiple changes in sequence but want to create separate PRs for different logical changes.' It also provides a concrete example scenario and distinguishes from alternatives by explaining the transformation from linear to parallel branches.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.6/5.0
Disambiguation5/5

Each tool has a distinct, non-overlapping purpose: list_changes shows numbered unstaged changes, apply_changes stages selected lines, diff provides full file diffs, auto_commit guides commit organization, and unstack restructures commit history. The descriptions clearly differentiate their roles, with no ambiguity about when to use each tool.

Naming Consistency4/5

Four tools follow a consistent verb_noun pattern (list_changes, apply_changes, auto_commit, unstack), but 'diff' deviates as a single noun without a verb. While this minor inconsistency is noticeable, the naming remains readable and intuitive for the domain.

Tool Count5/5

With 5 tools, this server is well-scoped for its purpose of advanced git operations like partial staging and commit management. Each tool earns its place by addressing specific workflows, such as selective staging, full diff viewing, commit organization, and history restructuring, without being overly sparse or bloated.

Completeness4/5

The tool set covers core workflows for selective staging, diff viewing, commit organization, and branch restructuring, with no obvious dead ends. A minor gap exists in lacking a tool for direct commit creation or push operations, but agents can work around this using auto_commit guidance or external commands.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Git Workflow MCP Server

    archis17
    F
    license
    Not graded
    quality
    Not graded
    maintenance
    Enables AI assistants to interact with local Git repositories for operations like status, commits, branching, and diffs, plus GitHub API integration for managing pull requests when authenticated.

  • Git Code Review MCP

    AyoubTRD
    A
    license
    B
    quality
    D
    maintenance
    Enables AI assistants to perform code reviews by providing access to staged files, git diffs, and repository file content. It allows users to evaluate changes and context within any local git repository before committing or pushing.
    3
    17
    ISC

  • git-mcp

    selfagency
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI agents to perform full Git operations including branching, committing, pushing, stashing, rebasing, and more, with safety features and support for advanced workflows like Git Flow and LFS.
    128
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/uneco/mcp-git-polite'

If you have feedback or need assistance with the MCP directory API, please join our Discord server