Shadowgit MCP

ShadowGit MCP服务器

](https://www.npmjs.com/package/shadowgit-mcp-server)

模型上下文协议（MCP）服务器，为AI助手提供对ShadowGit存储库的安全git访问，包括通过会话API创建有组织的提交的能力。通过让AI控制对项目git历史的访问，这可以实现强大的调试、代码分析和干净的提交管理。

ShadowGit是什么？

ShadowGit 自动将每次保存捕获为git提交，同时还提供会话API，允许AI助手暂停自动提交并创建干净、有组织的提交。MCP服务器提供对详细开发历史的读取权限，以及正确管理人工智能辅助更改的能力。

安装

npm install -g shadowgit-mcp-server

使用Claude代码进行设置

# Add to Claude Code
claude mcp add shadowgit -- shadowgit-mcp-server

# Restart Claude Code to load the server

使用Claude Desktop进行设置

添加到您的Claude Desktop MCP配置中：

macOS/Linux： ~/.config/Claude/claude_desktop_config.json\ 窗户： %APPDATA%\\Claude\\claude_desktop_config.json

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

需求

• Node.js 18+
• ShadowGit应用程序 安装并运行跟踪存储库

- 会话API需要ShadowGit版本>=0.3.0

• Git 在PATH中可用

运作原理

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

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

环境变量

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

• SHADOWGIT_TIMEOUT -命令执行超时（毫秒）（默认值：10000）
• SHADOWGIT_SESSION_API -会话API URL（默认值：http://localhost:45289/api)
• SHADOWGIT_LOG_LEVEL -日志级别：调试、信息、警告、错误（默认值：信息）
• SHADOWGIT_HINTS -设置为 0 禁用git命令输出中的工作流提示（默认值：启用）

例子：

export SHADOWGIT_TIMEOUT=30000  # 30 second timeout
export SHADOWGIT_LOG_LEVEL=debug  # Enable debug logging
export SHADOWGIT_HINTS=0  # Disable workflow banners for cleaner output

可用命令

会话管理

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

重要：人工智能助手在进行更改时必须遵循以下四步工作流程：

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

此工作流程确保人工智能辅助的更改导致干净、可审查的提交，而不是零碎的自动保存。

list_repos()

列出所有ShadowGit跟踪的存储库。

await shadowgit.list_repos()

git_command({repo, command})

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

// View recent commits
await shadowgit.git_command({
  repo: "my-project",
  command: "log --oneline -10"
})

// Check what changed recently
await shadowgit.git_command({
  repo: "my-project", 
  command: "diff HEAD~5 HEAD --stat"
})

// Find who changed a specific line
await shadowgit.git_command({
  repo: "my-project",
  command: "blame src/auth.ts"
})

start_session({repo, description})

使用会话API启动AI工作会话。这将暂停ShadowGit的自动提交功能，允许您进行多个更改，这些更改将被分组到一个干净的提交中。

const result = await shadowgit.start_session({
  repo: "my-app",
  description: "Fixing authentication bug"
})
// Returns: Session ID (e.g., "mcp-client-1234567890")

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

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

// After fixing a 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"
})
// Returns formatted commit details including the commit hash

// After adding a feature
await shadowgit.checkpoint({
  repo: "my-app",
  title: "Add dark mode toggle",
  message: "Implemented theme switching using CSS variables and localStorage persistence",
  author: "GPT-4"
})

// Minimal usage (author defaults to "AI Assistant")
await shadowgit.checkpoint({
  repo: "my-app",
  title: "Update dependencies"
})

end_session({sessionId, commitHash?})

通过会话API结束人工智能工作会话。这将恢复ShadowGit的自动提交功能，以便进行常规开发。

await shadowgit.end_session({
  sessionId: "mcp-client-1234567890",
  commitHash: "abc1234"  // Optional: from checkpoint result
})

参数：

• repo （必填）：存储库名称或完整路径
• title （必填）：短提交标题（最多50个字符）
• message （可选）：更改的详细说明
• author （可选）：您的标识符（例如“Claude”、“GPT-4”、“Gemini”）-默认为“AI Assistant”

笔记：

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

安全

• 只读访问：只允许使用安全的git命令
• 无写入操作：命令如下 commit, push, merge 被封锁
• 无破坏性操作：命令如下 branch, tag, reflog 被阻止以防止删除
• 存储库验证：只能访问ShadowGit存储库
• 路径遍历保护：阻止访问存储库外部文件的尝试
• 命令注入预防：用途 execFileSync 使用数组参数进行安全执行
• 危险旗封锁：块 --git-dir, --work-tree, --exec, -c, --config, -C 以及其他危险标志
• 超时保护：限制命令以防止挂起
• 增强的错误报告：Git错误现在包括stderr/ststdout，以便更好地调试

人工智能助理的最佳实践

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

1. 遵循工作流程：始终： start_session() → 做出改变→ checkpoint() → end_session()
2. 使用描述性标题：保持标题不超过50个字符，但要使其有意义
3. 始终创建检查点：呼叫 checkpoint() 完成每项任务后
4. 表明自己的身份：使用 author 参数，用于标识哪个AI创建了检查点
5. 文档更改：使用 message 用于解释更改内容及其原因的参数
6. 正确结束会话：总是打电话 end_session() 恢复自动提交

完整示例工作流

// 1. First, check available repositories
const repos = await shadowgit.list_repos()

// 2. Start session BEFORE making changes
const sessionId = await shadowgit.start_session({
  repo: "my-app",
  description: "Refactoring authentication module"
})

// 3. Examine recent history
await shadowgit.git_command({
  repo: "my-app",
  command: "log --oneline -5"
})

// 4. Make your changes to the code...
// ... (edit files, fix bugs, etc.) ...

// 5. IMPORTANT: Create a checkpoint after completing the task
const commitHash = await shadowgit.checkpoint({
  repo: "my-app",
  title: "Refactor authentication module",
  message: "Simplified login flow and added better error handling",
  author: "Claude"
})

// 6. End the session when done
await shadowgit.end_session({
  sessionId: sessionId,
  commitHash: commitHash  // Optional but recommended
})

示例用例

调试最近的更改

// Find what broke in the last hour
await shadowgit.git_command({
  repo: "my-app",
  command: "log --since='1 hour ago' --oneline"
})

跟踪代码演变

// See how a function evolved
await shadowgit.git_command({
  repo: "my-app", 
  command: "log -L :functionName:src/file.ts"
})

跨存储库分析

// Compare activity across projects
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脱机

如果您看到“会话API脱机。在不跟踪会话的情况下继续”：

• ShadowGit应用程序可能未运行
• 会话不会被跟踪，但git命令仍然有效
• 自动提交不会暂停（可能会导致提交碎片化）
• 确保ShadowGit应用正在运行
• 进入ShadowGit设置并检查会话API是否正常

发展

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

# Clone the repository (private GitHub repo)
git clone https://github.com/shadowgit/shadowgit-mcp-server.git
cd shadowgit-mcp-server
npm install

# Build
npm run build

# Test
npm test

# Run locally for development
npm run dev

# Test the built version locally
node dist/shadowgit-mcp-server.js

发布更新

# Update version
npm version patch  # or minor/major

# Build and test
npm run build
npm test

# Publish to npm (public registry)
npm publish

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

相关项目

• ShadowGit -自动代码快照工具
• MCP-SDK -模型上下文协议TypeScript SDK

______________________________________________________________________

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

](https://lobehub.com/mcp/shadowgit-shadowgit-mcp-server)