Claude Code MCP 服务器开发实战：造一个 Git 考古工具，让模型秒懂提交历史

mkdir ~/mcp-git-archaeology && cd ~/mcp-git-archaeology
python -m venv .venv && source .venv/bin/activate
pip install "fastmcp>=3.0"

Successfully installed fastmcp-3.x.x pydantic-2.x.x ...

touch git_archaeology_mcp.py

import subprocess
from pathlib import Path
from fastmcp import FastMCP

mcp = FastMCP("git-archaeology")

# 只放行只读/查询类子命令，写操作（add/commit/push/reset 等）一律拒绝
ALLOWED_SUBCOMMANDS = {
    "log", "show", "diff", "blame", "branch", "name-rev",
    "rev-parse", "ls-files", "describe", "shortlog", "merge-base",
}
# 这些参数一旦出现就拒绝，防止 git 通过 -c / ext.* 执行外部命令
FORBIDDEN_TOKENS = ("--no-pager", "-c", "core.", "ext.", "GIT_")

MAX_OUTPUT = 20_000  # 单次工具返回上限，避免撑爆模型上下文


def _run_git(repo: str, args: list[str], timeout: float = 15.0) -> str:
    """安全地执行一条只读 git 命令并返回文本。"""
    repo_path = Path(repo).expanduser().resolve()

    # 1) 仓库存在性校验
    if not repo_path.exists():
        raise ValueError(f"路径不存在: {repo_path}")

    # 2) 子命令白名单
    if not args or args[0] not in ALLOWED_SUBCOMMANDS:
        cmd = args[0] if args else "(空)"
        raise ValueError(f"不允许的子命令: {cmd}（仅允许只读查询）")

    # 3) 注入防护：扫描每个参数，拦截危险 token
    for a in args:
        if any(tok in a for tok in FORBIDDEN_TOKENS):
            raise ValueError(f"参数含被禁止的 token: {a!r}")

    # 4) 真正执行（用列表传参，不经 shell，杜绝 shell 注入）
    proc = subprocess.run(
        ["git", "-C", str(repo_path), "--no-pager"] + args,
        capture_output=True, text=True, timeout=timeout,
    )
    if proc.returncode != 0:
        # 把 git 的 stderr 透传给模型，便于它自我修正
        raise RuntimeError(proc.stderr.strip() or f"git {args[0]} 执行失败")

    out = proc.stdout
    if len(out) > MAX_OUTPUT:
        out = out[:MAX_OUTPUT] + f"\n\n…（输出已截断，原始长度 {len(proc.stdout)} 字符，请缩小查询范围）"
    return out

@mcp.tool
def git_log(
    repo: str,
    max_count: int = 20,
    path: str | None = None,
    author: str | None = None,
    since: str | None = None,
) -> str:
    """查看仓库提交历史，可按文件路径、作者、时间过滤。

    Args:
        repo: 本地 Git 仓库的绝对路径或相对路径。
        max_count: 返回的提交数量上限，默认 20。
        path: 只看某个文件的提交历史，例如 src/api/bill.py。
        author: 按作者名模糊匹配过滤。
        since: 起始时间，例如 2.weeks 或 2026-06-01。
    返回: 每行一条提交，格式 `短哈希|作者|日期|提交说明`。
    """
    args = ["log", f"-n{max_count}",
            "--pretty=format:%h|%an|%ad|%s", "--date=short"]
    if author:
        args += ["--author", author]
    if since:
        args += ["--since", since]
    if path:
        args += ["--", path]  # -- 之后是路径，避免和选项混淆
    return _run_git(repo, args)


@mcp.tool
def git_show(repo: str, ref: str) -> str:
    """查看某次提交的完整内容：提交说明 + 改动 diff。

    Args:
        repo: 仓库路径。
        ref: 提交哈希、标签或引用，例如 a1b2c3d、v1.5.0、HEAD~3。
    返回: 该提交的元数据与 unified diff。
    """
    return _run_git(repo, ["show", "--stat", "--patch", ref])


@mcp.tool
def git_blame(repo: str, file: str, start: int | None = None,
              end: int | None = None) -> str:
    """逐行追溯某个文件每一行最后由谁、哪次提交修改。

    Args:
        repo: 仓库路径。
        file: 相对仓库根的文件路径，例如 src/api/bill.py。
        start: 起始行号（可选）。
        end: 结束行号（可选）。
    返回: blame 文本，每行前缀是提交短哈希与作者。
    """
    args = ["blame", "-w", "-M"]  # -w 忽略空白, -M 检测行内移动
    if start and end:
        args += ["-L", f"{start},{end}"]
    args += ["--", file]
    return _run_git(repo, args)


@mcp.tool
def git_diff_refs(repo: str, base: str, head: str) -> str:
    """对比两个引用（分支/标签/哈希）之间的差异。

    Args:
        repo: 仓库路径。
        base: 基线引用，例如 main。
        head: 目标引用，例如 feature/checkout。
    返回: base...head 的 unified diff 与文件清单。
    """
    return _run_git(repo, ["diff", "--stat", "--patch", f"{base}...{head}"])


@mcp.tool
def git_branches(repo: str, remote: bool = True) -> str:
    """列出仓库所有分支及其最新提交。

    Args:
        repo: 仓库路径。
        remote: 是否包含远程分支，默认 True。
    返回: 每行一个分支：`分支名 最新短哈希 提交说明`。
    """
    args = ["branch", "--list", "-v",
            "--format=%(refname:short)|%(objectname:short)|%(contents:subject)"]
    if remote:
        args = ["branch", "-a", "--format=%(refname:short)|%(objectname:short)|%(contents:subject)"]
    return _run_git(repo, args)


if __name__ == "__main__":
    mcp.run()  # 默认 stdio 传输

git_log        查看提交历史
git_show       查看某次提交内容
git_blame      逐行追溯修改者
git_diff_refs  对比两个引用差异
git_branches   列出所有分支

claude mcp add git-archaeology -- python /home/你/mcp-git-archaeology/git_archaeology_mcp.py

{
  "mcpServers": {
    "git-archaeology": {
      "command": "python",
      "args": ["/home/你/mcp-git-archaeology/git_archaeology_mcp.py"]
    }
  }
}

claude mcp list

git-archaeology  ✓ connected  (5 tools)

npx -y @modelcontextprotocol/inspector python git_archaeology_mcp.py

a1b2c3d|张三|2026-07-01|fix: 修复订单总额四舍五入错误
e4f5g6h|李四|2026-06-28|feat: 新增优惠券叠加逻辑
...

DOCS = ["README.md", "CHANGELOG.md", "CONTRIBUTING.md"]


@mcp.resource("git://{repo}/docs/{name}")
def read_doc(repo: str, name: str) -> str:
    """读取仓库根目录下的指定文档文件。

    URI 模板中的 {repo} 和 {name} 由客户端填充。
    """
    if name not in DOCS:
        raise ValueError(f"只允许读取: {DOCS}")
    target = (Path(repo).expanduser().resolve()) / name
    if not target.exists():
        return f"（{name} 不存在）"
    return target.read_text(encoding="utf-8")

orderTotal 由 张三 在 c9d8e7f（2026-07-01）最后一次修改，
提交说明："fix: 修复订单总额四舍五入错误"。
那次改动把第 42 行的 round(total, 1) 改成了 round(total, 2)，
原因是金额按角舍入会少收 0.1 元。

flowchart LR
    U[用户提问] --> CC[Claude Code]
    CC -->|JSON-RPC over stdio| Srv[git-archaeology MCP]
    Srv --> WH[子命令白名单/注入护栏]
    WH -->|列表传参, no shell| GIT[git CLI]
    GIT --> R[(本地 .git 仓库)]
    R --> Srv -->|截断后文本| CC --> U

sequenceDiagram
    participant U as 用户
    participant C as Claude Code
    participant M as MCP 服务器
    participant G as git
    U->>C: orderTotal 谁改的?
    C->>M: tools/call git_blame(bill.py)
    M->>G: git -C repo blame bill.py
    G-->>M: 每行 -> 哈希 c9d8e7f
    M-->>C: blame 文本
    C->>M: tools/call git_show(c9d8e7f)
    M->>G: git show c9d8e7f
    G-->>M: 提交说明 + diff
    M-->>C: show 文本
    C-->>U: 综合 blame+show 结论