Metadata-Version: 2.5
Name: pia-mcp-server-git
Version: 0.2.2
Summary: A Model Context Protocol server providing tools to read, search, and manipulate Git repositories programmatically via LLMs
Author: Anthropic, PBC., PIA Shanghai
Maintainer: PIA Shanghai
License: MIT
License-File: LICENSE
Keywords: automation,git,llm,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
Requires-Python: >=3.10
Requires-Dist: click>=8.1.7
Requires-Dist: gitpython>=3.1.50
Requires-Dist: mcp<2,>=1.29.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# pia-mcp-server-git: A git MCP server

## Overview

A Model Context Protocol server for Git repository interaction and automation. This server provides tools to read, search, and manipulate Git repositories via Large Language Models.

Requires MCP Python SDK 1.x (`mcp>=1.29.0,<2`). SDK 2.0 renamed APIs this server uses. The port to v2 is in progress.

Please note that pia-mcp-server-git is currently in early development. The functionality and available tools are subject to change and expansion as we continue to develop and improve the server.

### Tools

1. `git_status`
   - Shows the working tree status
   - Input:
     - `repo_path` (string): Path to Git repository
   - Returns: Current status of working directory as text output

2. `git_diff_unstaged`
   - Shows changes in working directory not yet staged
   - Inputs:
     - `repo_path` (string): Path to Git repository
     - `context_lines` (number, optional): Number of context lines to show (default: 3)
   - Returns: Diff output of unstaged changes

3. `git_diff_staged`
   - Shows changes that are staged for commit
   - Inputs:
     - `repo_path` (string): Path to Git repository
     - `context_lines` (number, optional): Number of context lines to show (default: 3)
   - Returns: Diff output of staged changes

4. `git_diff`
   - Shows differences between branches or commits
   - Inputs:
     - `repo_path` (string): Path to Git repository
     - `target` (string): Target branch or commit to compare with
     - `context_lines` (number, optional): Number of context lines to show (default: 3)
   - Returns: Diff output comparing current state with target

5. `git_commit`
   - Records changes to the repository
   - Inputs:
     - `repo_path` (string): Path to Git repository
     - `message` (string): Commit message
   - Returns: Confirmation with new commit hash

6. `git_add`
   - Adds file contents to the staging area
   - Inputs:
     - `repo_path` (string): Path to Git repository
     - `files` (string[]): Array of file paths to stage
   - Returns: Confirmation of staged files

7. `git_reset`
   - Unstages all staged changes
   - Input:
     - `repo_path` (string): Path to Git repository
   - Returns: Confirmation of reset operation

8. `git_log`
   - Shows the commit logs with optional date filtering
   - Inputs:
     - `repo_path` (string): Path to Git repository
     - `max_count` (number, optional): Maximum number of commits to show (default: 10)
     - `start_timestamp` (string, optional): Start timestamp for filtering commits. Accepts ISO 8601 format (e.g., '2024-01-15T14:30:25'), relative dates (e.g., '2 weeks ago', 'yesterday'), or absolute dates (e.g., '2024-01-15', 'Jan 15 2024')
     - `end_timestamp` (string, optional): End timestamp for filtering commits. Accepts ISO 8601 format (e.g., '2024-01-15T14:30:25'), relative dates (e.g., '2 weeks ago', 'yesterday'), or absolute dates (e.g., '2024-01-15', 'Jan 15 2024')
   - Returns: Array of commit entries with hash, author, date, and message

9. `git_create_branch`
   - Creates a new branch
   - Inputs:
     - `repo_path` (string): Path to Git repository
     - `branch_name` (string): Name of the new branch
     - `base_branch` (string, optional): Base branch to create from (defaults to current branch)
   - Returns: Confirmation of branch creation

10. `git_checkout`
    - Switches branches
    - Inputs:
      - `repo_path` (string): Path to Git repository
      - `branch_name` (string): Name of branch to checkout
    - Returns: Confirmation of branch switch

11. `git_show`
    - Shows the contents of a commit
    - Inputs:
      - `repo_path` (string): Path to Git repository
      - `revision` (string): The revision (commit hash, branch name, tag) to show
    - Returns: Contents of the specified commit

12. `git_branch`
    - List Git branches
    - Inputs:
      - `repo_path` (string): Path to the Git repository.
      - `branch_type` (string): Whether to list local branches ('local'), remote branches ('remote') or all branches('all').
      - `contains` (string, optional): The commit sha that branch should contain. Do not pass anything to this param if no commit sha is specified
      - `not_contains` (string, optional): The commit sha that branch should NOT contain. Do not pass anything to this param if no commit sha is specified
    - Returns: List of branches

## Installation

### Using uv (recommended)

Install `uv`, then prepare the project environment from the lock file:

```bash
uv --directory /path/to/pia-mcp-server-git sync --locked
```

### Using pip

Alternatively, install the package with pip:

```bash
pip install pia-mcp-server-git
```

## Deployment

This server communicates over stdio. A host service must launch the process and connect its standard input and output to the MCP client. The project does not expose an HTTP endpoint by itself.

### Using uv from the source tree

```bash
uv --directory /path/to/pia-mcp-server-git run --no-sync pia-mcp-server-git --repository /path/to/git/repo
```

`--repository` limits the server to the specified repository and its subdirectories. Omit `--no-sync` if the environment has not been prepared with `uv sync`.

### Using an installed package

```bash
pia-mcp-server-git --repository /path/to/git/repo
```

The equivalent module invocation is:

```bash
python -m mcp_server_git --repository /path/to/git/repo
```

### Verification

Use the MCP Inspector to verify the stdio server locally:

```bash
npx @modelcontextprotocol/inspector uv --directory /path/to/pia-mcp-server-git run --no-sync pia-mcp-server-git --repository /path/to/git/repo
```

For automated unit tests:

```bash
uv --directory /path/to/pia-mcp-server-git run pytest
```


## 发布到 PyPI

发布脚本使用 PyPI 项目级 API Token 进行身份认证，并通过 Windows DPAPI 将凭据加密保存在本地。该流程仅适用于 Windows PowerShell 环境。

### 发布前准备

- 安装并确保 `uv` 命令可用。
- 在 PyPI 中创建仅限 `pia-mcp-server-git` 项目的 API Token。
- 确认 [pyproject.toml](pyproject.toml) 中的 `version` 尚未发布。PyPI 不允许覆盖已经发布的同版本文件。

### 1. 配置 PyPI 凭据

在项目根目录运行：

```powershell
.\scripts\setup-pypi-auth.ps1
```

根据提示输入 PyPI 项目级 API Token。脚本会将加密凭据保存到：

```text
.secrets/pypi-token.clixml
```

不要手动把明文 Token 写入该文件，也不要提交或分享 `.secrets` 目录。凭据通常只能由创建它的同一台 Windows 计算机和同一 Windows 用户解密。除非 Token 发生变化或被撤销，否则不需要在每次发布前重复配置。

### 2. 发布包

确认版本号和待发布内容无误后运行：

```powershell
.\scripts\publish-pypi.ps1
```

发布脚本会依次执行以下操作：

1. 从 Windows 凭据文件中临时读取 PyPI Token。
2. 使用 `uv build` 构建 wheel 和源码分发包。
3. 使用 `uv publish --dry-run` 验证发布参数和制品。
4. 将两个制品正式上传到 PyPI。
5. 清理临时 Token 和临时构建目录。

终端显示以下内容表示发布成功：

```text
PyPI publish completed successfully.
```

发布完成后，可以在以下页面检查版本和制品：

```text
https://pypi.org/project/pia-mcp-server-git/
```

### 常见问题

- `No encrypted PyPI credential file was found`：先运行 `setup-pypi-auth.ps1` 配置凭据。
- `File already exists`：当前版本已经发布，需要先在 `pyproject.toml` 中更新版本号，再重新构建和发布。
- Token 无效或已撤销：在 PyPI 创建新的项目级 Token，然后重新运行凭据配置脚本。
