STARWARCLOUD STARWAR.AI
返回市场
影子git-mcp

影子git-mcp

作者：blade4745 星标更新：2025-09-11
安装使用来源：spider==github.com

项目介绍

ShadowGit MCP Server

npm 版本

这是一个提供给AI助手安全访问您的ShadowGit仓库的Model Context Protocol (MCP)服务器，包括通过Session API创建组织良好的提交的能力。这使得强大的调试、代码分析和干净的提交管理成为可能，通过给予AI对项目git历史的受控访问。

什么是ShadowGit？

ShadowGit 自动捕获每次保存作为git提交，同时提供一个Session API，允许AI助手暂停自动提交并创建干净、有组织的提交。MCP服务器提供了对您详细开发历史的读取访问，并且能够正确地管理AI辅助的变化。

安装

npm install -g shadowgit-mcp-server

配置与Claude Code

# 添加到Claude Code
claude mcp add shadowgit -- shadowgit-mcp-server

# 重启Claude Code以加载服务器

配置与Claude Desktop

添加到您的Claude Desktop MCP配置：

macOS/Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "shadowgit": {
      "command": "shadowgit-mcp-server"
    }
  }
}

要求

  • Node.js 18+
  • 已安装并运行的ShadowGit应用，带有跟踪的仓库
    • Session API需要ShadowGit版本>=0.3.0
  • PATH中可用的Git

工作原理

MCP服务器是无状态的，并使用stdio传输：

  • 当AI工具（如Claude、Cursor）调用时，服务器按需运行
  • 通信通过stdin/stdout进行，而不是HTTP
  • 需要时启动，完成后退出
  • 没有持久守护进程或后台进程

环境变量

您可以使用这些可选环境变量来配置服务器行为：

  • SHADOWGIT_TIMEOUT - 命令执行超时时间（毫秒，默认值：10000）
  • SHADOWGIT_SESSION_API - Session API URL（默认值：http://localhost:45289/api）
  • SHADOWGIT_LOG_LEVEL - 日志级别：debug, info, warn, error（默认值：info）
  • SHADOWGIT_HINTS - 设置为0以禁用git命令输出中的工作流提示（默认值：启用）

示例：

export SHADOWGIT_TIMEOUT=30000  # 30秒超时
export SHADOWGIT_LOG_LEVEL=debug  # 启用调试日志
export SHADOWGIT_HINTS=0  # 禁用工作流横幅以获得更干净的输出

可用命令

会话管理

Session API（需要ShadowGit >= 0.3.0）允许AI助手暂时暂停ShadowGit的自动提交功能，并创建干净、有组织的提交，而不是在AI工作期间产生碎片化的自动提交。

重要：AI助手必须遵循以下四步工作流程进行更改：

  1. start_session({repo, description}) - 在进行更改之前开始工作会话（暂停自动提交）
  2. 进行更改 - 编辑代码，修复错误，添加功能
  3. checkpoint({repo, title, message?, author?}) - 在完成工作后创建一个干净的提交
  4. end_session({sessionId, commitHash?}) - 完成后结束会话（恢复自动提交）

此工作流程确保AI辅助更改的结果是干净、可审查的提交，而不是碎片化的自动保存。

list_repos()

列出所有被ShadowGit跟踪的仓库。

await shadowgit.list_repos()

git_command({repo, command})

在特定仓库上执行只读git命令。

// 查看最近的提交
await shadowgit.git_command({
  repo: "my-project",
  command: "log --oneline -10"
})

// 检查最近发生了什么变化
await shadowgit.git_command({
  repo: "my-project", 
  command: "diff HEAD~5 HEAD --stat"
})

// 找出谁修改了特定行
await shadowgit.git_command({
  repo: "my-project",
  command: "blame src/auth.ts"
})

start_session({repo, description})

使用Session API开始AI工作会话。这会暂停ShadowGit的自动提交功能，允许您进行多次更改，这些更改将被组合成一个干净的提交。

const result = await shadowgit.start_session({
  repo: "my-app",
  description: "修复认证错误"
})
// 返回：会话ID（例如："mcp-client-1234567890"）

checkpoint({repo, title, message?, author?})

创建一个检查点提交以保存您的工作。

// 修复错误后
const result = await shadowgit.checkpoint({
  repo: "my-app",
  title: "修复auth中的空指针异常",
  message: "在访问用户对象前添加了空检查",
  author: "Claude"
})
// 返回格式化的提交详情，包括提交哈希

// 添加功能后
await shadowgit.checkpoint({
  repo: "my-app",
  title: "添加暗模式切换",
  message: "使用CSS变量和localStorage持久性实现了主题切换",
  author: "GPT-4"
})

// 最小使用（作者默认为"AI助手"）
await shadowgit.checkpoint({
  repo: "my-app",
  title: "更新依赖项"
})

end_session({sessionId, commitHash?})

通过Session API结束AI工作会话。这恢复了ShadowGit的自动提交功能，用于常规开发。

await shadowgit.end_session({
  sessionId: "mcp-client-1234567890",
  commitHash: "abc1234"  // 可选：来自checkpoint结果
})

参数：

  • repo（必需）：仓库名称或完整路径
  • title（必需）：短提交标题（最多50个字符）
  • message（可选）：更改的详细描述
  • author（可选）：您的标识符（例如："Claude"，"GPT-4"，"Gemini"）- 默认为"AI助手"

注意事项：

  • 会话防止自动提交干扰AI工作
  • 自动尊重.gitignore模式
  • 创建带时间戳和作者标识的提交
  • 如果没有更改可提交，则会报告

安全性

  • 只读访问：仅允许安全的git命令
  • 禁止写操作：禁止commit，push，merge等命令
  • 禁止破坏性操作：禁止branch，tag，reflog等命令以防止删除
  • 仓库验证：只能访问ShadowGit仓库
  • 路径遍历保护：阻止访问仓库外的文件
  • 命令注入预防：使用execFileSync和数组参数进行安全执行
  • 危险标志阻塞：阻止--git-dir，--work-tree，--exec，-c，--config，-C和其他危险标志
  • 超时保护：限制命令以防止挂起
  • 增强错误报告：现在包含stderr/stdout的git错误，便于调试

AI助手的最佳实践

当使用ShadowGit MCP服务器时，AI助手应：

  1. 遵循工作流程：始终：start_session() → 进行更改 → checkpoint() → end_session()
  2. 使用描述性标题：保持标题在50个字符以内但有意义
  3. 始终创建检查点：在完成每个任务后调用checkpoint()
  4. 识别自己：使用author参数标识哪个AI创建了检查点
  5. 记录更改：使用message参数解释更改了什么以及为什么
  6. 正确结束会话：始终调用end_session()以恢复自动提交

完整的工作流程示例

// 1. 首先，检查可用的仓库
const repos = await shadowgit.list_repos()

// 2. 在进行更改之前开始会话
const sessionId = await shadowgit.start_session({
  repo: "my-app",
  description: "重构认证模块"
})

// 3. 检查最近的历史
await shadowgit.git_command({
  repo: "my-app",
  command: "log --oneline -5"
})

// 4. 对代码进行更改...
// ...（编辑文件，修复错误等）...

// 5. 重要：在完成任务后创建一个检查点
const commitHash = await shadowgit.checkpoint({
  repo: "my-app",
  title: "重构认证模块",
  message: "简化登录流程并添加更好的错误处理",
  author: "Claude"
})

// 6. 完成后结束会话
await shadowgit.end_session({
  sessionId: sessionId,
  commitHash: commitHash  // 可选但推荐
})

示例用例

调试最近的更改

// 查找过去一小时内出了什么问题
await shadowgit.git_command({
  repo: "my-app",
  command: "log --since='1 hour ago' --oneline"
})

追踪代码演变

// 查看函数是如何演进的
await shadowgit.git_command({
  repo: "my-app", 
  command: "log -L :functionName:src/file.ts"
})

跨仓库分析

// 比较项目的活动
const repos = await shadowgit.list_repos()
for (const repo of repos) {
  await shadowgit.git_command({
    repo: repo.name,
    command: "log --since='1 day ago' --oneline"
  })
}

故障排除

没有找到仓库

  • 确保已安装ShadowGit应用并且有跟踪的仓库
  • 检查~/.shadowgit/repos.json是否存在

未找到仓库

  • 使用list_repos()查看确切的仓库名称
  • 确保仓库有一个.shadowgit.git目录

Git命令失败

  • 验证git是否已安装：git --version
  • 只允许只读命令
  • 使用绝对路径或从list_repos()获取的仓库名称
  • 检查错误输出，其中现在包含stderr细节，以便调试

工作流提示过于冗长

  • 设置SHADOWGIT_HINTS=0环境变量以禁用工作流横幅
  • 这为程序化使用提供了更干净的输出

Session API离线

如果您看到“Session API离线。继续不跟踪会话”：

  • ShadowGit应用可能没有运行
  • 会话不会被跟踪，但git命令仍然可以工作
  • 自动提交不会暂停（可能会导致碎片化的提交）
  • 确保ShadowGit应用正在运行
  • 进入ShadowGit设置并检查Session API是否健康

开发

对于希望修改或扩展MCP服务器的贡献者：

# 克隆仓库（私有GitHub仓库）
git clone https://github.com/shadowgit/shadowgit-mcp-server.git
cd shadowgit-mcp-server
npm install

# 构建
npm run build

# 测试
npm test

# 本地开发运行
npm run dev

# 测试构建版本
node dist/shadowgit-mcp-server.js

发布更新

# 更新版本
npm version patch  # 或minor/major

# 构建和测试
npm run build
npm test

# 发布到npm（公共注册表）
npm publish

许可证

MIT许可证 - 详情见LICENSE文件。

相关项目

  • ShadowGit - 自动代码快照工具
  • MCP SDK - Model Context Protocol TypeScript SDK

将您的开发历史转变为强大的AI调试助手！🚀

MCP 徽章