Shadowgit Mcp

开发 TypeScript

🚀 ShadowGit MCP Server

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

🚀 快速开始

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

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

✨ 主要特性

安全的 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 助手在进行更改时必须遵循以下四步工作流：

start_session({repo, description}) - 在进行更改之前开始工作会话（暂停自动提交）。
进行更改 - 编辑代码、修复 bug、添加功能。
checkpoint({repo, title, message?, author?}) - 完成工作后创建检查点提交。
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 助手应遵循以下最佳实践：

遵循工作流：始终按照 start_session() → 进行更改 → checkpoint() → end_session() 的顺序操作。
使用描述性标题：标题保持在 50 个字符以内，但要有意义。
始终创建检查点：完成每个任务后调用 checkpoint()。
标识自己：使用 author 参数标识创建检查点的 AI。
记录更改：使用 message 参数解释更改的内容和原因。
正确结束会话：始终调用 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 文件。