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 調試助手！🚀