Shadowgit MCP

🚀 ShadowGit MCP Server

ShadowGit MCP Server 是一个模型上下文协议（MCP）服务器，它为 AI 助手提供对 ShadowGit 仓库的安全 Git 访问权限，支持通过会话 API 创建有条理的提交。借助该服务器，AI 可以访问项目的 Git 历史记录，从而实现强大的调试、代码分析和清晰的提交管理。

🚀 快速开始

ShadowGit MCP Server 为 AI 助手提供安全的 Git 访问，帮助实现有效的代码管理和调试。以下是使用该服务器的基本步骤：

1. 安装服务器。
2. 配置与 AI 工具（如 Claude Code 或 Claude Desktop）的集成。
3. 开始使用服务器提供的命令进行代码管理。

✨ 主要特性

• 安全的 Git 访问：为 AI 助手提供对 ShadowGit 仓库的安全访问，仅允许执行安全的 Git 命令。
• 会话 API：支持通过会话 API 暂停自动提交，并创建清晰、有条理的提交。
• 多工具集成：可与 Claude Code、Claude Desktop 等 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 应用程序，且有跟踪的仓库。会话 API 需要 ShadowGit 版本 >= 0.3.0。
• Git 可在系统的 PATH 中找到。

💻 使用示例

基础用法

列出所有跟踪的仓库

await shadowgit.list_repos()

执行只读 Git 命令

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

高级用法

开始 AI 工作会话

const result = await shadowgit.start_session({
  repo: "my-app",
  description: "Fixing authentication bug"
})
// 返回: 会话 ID (例如, "mcp-client-1234567890")

创建检查点提交

// 修复 bug 后
const result = await shadowgit.checkpoint({
  repo: "my-app",
  title: "Fix null pointer exception in auth",
  message: "Added null check before accessing user object",
  author: "Claude"
})
// 返回格式化的提交详情，包括提交哈希

结束 AI 工作会话

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

完整示例工作流程

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

// 2. 在进行更改之前开始会话
const sessionId = await shadowgit.start_session({
  repo: "my-app",
  description: "Refactoring authentication module"
})

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

// 4. 对代码进行更改...
// ... (编辑文件、修复 bug 等) ...

// 5. 重要: 完成任务后创建检查点
const commitHash = await shadowgit.checkpoint({
  repo: "my-app",
  title: "Refactor authentication module",
  message: "Simplified login flow and added better error handling",
  author: "Claude"
})

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

📚 详细文档

工作原理

MCP 服务器是无状态的，使用标准输入输出（stdio）进行通信：

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

环境变量

可以使用以下可选环境变量来配置服务器的行为：

• SHADOWGIT_TIMEOUT - 命令执行超时时间（毫秒），默认值为 10000。
• SHADOWGIT_SESSION_API - 会话 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  # 禁用工作流提示以获得更简洁的输出

可用命令

会话管理

会话 API（需要 ShadowGit >= 0.3.0）允许 AI 助手暂时暂停 ShadowGit 的自动提交功能，并创建清晰、有条理的提交。AI 助手在进行更改时必须遵循以下四步工作流：

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

其他命令

• list_repos()：列出所有 ShadowGit 跟踪的仓库。
• git_command({repo, command})：在特定仓库上执行只读 Git 命令。

安全特性

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

AI 助手最佳实践

使用 ShadowGit MCP Server 时，AI 助手应遵循以下最佳实践：

1. 遵循工作流：始终按照 start_session() → 进行更改 → checkpoint() → end_session() 的顺序操作。
2. 使用描述性标题：标题保持在 50 个字符以内，但要有意义。
3. 始终创建检查点：完成每个任务后调用 checkpoint()。
4. 标识自己：使用 author 参数标识创建检查点的 AI。
5. 记录更改：使用 message 参数解释更改的内容和原因。
6. 正确结束会话：始终调用 end_session() 以恢复自动提交。

示例用例

调试最近的更改

// 查找最近一小时内出现问题的提交
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 环境变量以禁用工作流提示。
• 这将为程序化使用提供更简洁的输出。

会话 API 离线

如果看到 "Session API is offline. Proceeding without session tracking" 提示：

• 可能是 ShadowGit 应用程序未运行。
• 会话将不会被跟踪，但 Git 命令仍可正常工作。
• 自动提交不会暂停（可能导致碎片化提交）。
• 确保 ShadowGit 应用程序正在运行。
• 进入 ShadowGit 设置并检查会话 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 - 模型上下文协议 TypeScript SDK

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