MCP Git Line Stage

](https://github.com/uneco/mcp-git-polite/actions) ](https://github.com/uneco/mcp-git-polite/blob/main/LICENSE) ](https://github.com/uneco/mcp-git-polite/pulse) ](https://github.com/uneco/mcp-git-polite/commits/main)

Git自动运行——让AI将你的更改组织成干净、专注的提交。

概述

git-polite 是一个模型上下文协议（MCP）服务器，为AI代理带来智能git登台。它可以自动将正在进行的混乱工作组织成结构良好的提交，或者在需要时通过逐行分期为您提供手术精度。

特性

• 自动驾驶模式：让AI分析您的更改并自动创建多个重点提交
• 线路级分段：按行号进行分期个体增删，具有手术精度
• 无标记文件支持：新创建文件的阶段部分（不仅仅是修改后的文件）
• 范围选择：使用范围一次应用多个更改（例如。， 0001-0005,0020-0025)
• LLM友好输出：基于字节的分页和智能截断保护上下文窗口
• 二进制文件检测：自动检测并跳过二进制文件
• MCP集成：与Claude Code、Claude Desktop和其他MCP客户端无缝协作

MCP服务器模式

作为MCP服务器运行，以便与MCP客户端集成：

uv run git_polite.py mcp

MCP工具

服务器公开了四个工具：

1. list_更改：将未标记的git更改（包括未跟踪的文件）列为编号行

- 智能截断：大差异（>10KB）会自动截断以保护LLM上下文 - 参数： - paths （可选）：要筛选的文件路径列表 - page_token （可选）：分页标记 - page_size_files （可选，默认值：50）：每页最大文件数 - page_size_bytes （可选，默认值：30KB）：每页最大累积字节数 - unified （可选，默认值：20）：更改周围的上下文行 - 输出包括 truncated: true 带有标记的大文件 reason 解释截断 - 对于截断的文件，请使用 diff 查看完整内容的工具

1. 差异：查看单个文件的完整差异，不进行截断

- 将其用于在中截断的文件 list_changes 输出 - 返回与相同的编号行格式 list_changes，实现部分分期 - 不像 git diff，此工具提供以下所需的行号 apply_changes - 从不截断输出，适用于具有大量更改的大文件 - 参数： - path （必填）：查看差异的文件路径 - unified （可选，默认值：20）：更改周围的上下文行 - 返回值：与完全不同 size_bytes 指示实际输出大小

1. 应用程序_更改：按编号将所选更改应用于git索引（支持未跟踪文件的部分暂存）

- 参数： - path：应用更改的文件路径 - lines：更改数字（格式： NNNN,MMMM,PPPP-QQQQ)

1. 自动提交：启动自动驾驶模式，将所有更改组织成集中的提交

- 显示最近的提交消息以供样式参考 - 分析所有未记录的变化，并提出逻辑分组建议 - 引导AI从混乱的WIP创建多个原子提交

MCP客户端配置

使用uvx（推荐）

使用 uvx 直接从GitHub运行：

Claude桌面配置：

{
  "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

使用Docker

或者，使用GitHub容器注册表中的Docker镜像：

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

运作原理

1. 列表阶段：该工具解析 git diff 输出（包括未跟踪的文件，通过 git diff --no-index)并对每次加法进行编号(+)和删除(-)按顺序
2. 截断检查：测量每个文件的差异大小。超过10KB的文件被标记为截断，以保护LLM上下文
3. 显示：变化以数字和周围的背景线显示。文件被标记为“已添加”（未跟踪）、“已修改”或“已删除”
4. 分页：结果根据累积字节大小进行分页（默认每页30KB），以防止超出LLM
5. 应用阶段：指定行号时，该工具：

- 从git索引读取暂存版本（或为未跟踪的文件创建新文件） - 仅应用选定的更改 - 用部分更改更新git索引

输出格式

列表输出

{
  "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
  }
}

当文件显示时 truncated: true，使用 diff 工具查看其完整内容。这 diff 该工具提供了部分分段所需的相同编号行格式 git diff 无法提供。

应用输出

{
  "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
  }
}

需求

• Python 3.10或更高版本
• Git（命令行工具）
• MCP服务器包(mcp>=1.10.0)

发展

# 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

用例

• AI驱动的提交组织：让AI分析您的WIP并自动创建干净的提交历史记录
• 增量承诺：将大型更改分解为逻辑、原子提交
• 部分文件暂存：仅暂存新文件的特定行，同时保持其余行未暂存
• 代码审查准备：与阶段相关的更改一起进行，即使分散在文件中
• 重构：以手术精度将格式更改与逻辑更改分开

示例工作流

使用截断文件

当你遇到一个截断的文件（例如，一个有很多更改的大型重构文件）：

# 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")

分页示例

# 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"])

局限性

• 仅适用于文本文件（检测并跳过二进制文件）
• 行号是短暂的，每次应用操作后都会发生变化
• 上下文不匹配（文件漂移）将导致操作安全失败
• 对于未跟踪的文件，整个文件内容必须存在于工作目录中
• 大文件（差异大于10KB）在中被截断 list_changes -使用 diff 查看它们的工具

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！请随时提交拉取请求。

致谢

内置于 FastMCP 和那个 模型上下文协议.