Shadowgit MCP

🚀 ShadowGit MCP Server

ShadowGit MCP Serverは、AIアシスタントにShadowGitリポジトリへの安全なgitアクセスを提供するModel Context Protocol (MCP)サーバーです。Session APIを通じて整理されたコミットを作成する機能も備えています。これにより、AIがプロジェクトのgit履歴にアクセスすることで、強力なデバッグ、コード分析、きれいなコミット管理が可能になります。

🚀 クイックスタート

ShadowGit MCP Serverを使用することで、AIアシスタントがShadowGitリポジトリに安全にアクセスし、整理されたコミットを作成できます。以下の手順でセットアップしてください。

✨ 主な機能

• AIアシスタントにShadowGitリポジトリへの安全なgitアクセスを提供
• Session APIを通じて整理されたコミットを作成
• 詳細な開発履歴への読み取りアクセスと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が必要
• GitがPATHに含まれていること

動作原理

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に設定（デフォルト: 有効）

例:

export SHADOWGIT_TIMEOUT=30000  # 30秒のタイムアウト
export SHADOWGIT_LOG_LEVEL=debug  # デバッグログを有効にする
export SHADOWGIT_HINTS=0  # ワークフローバナーを無効にしてクリーンな出力を得る

利用可能なコマンド

セッション管理

Session API（ShadowGit >= 0.3.0が必要）により、AIアシスタントはShadowGitの自動コミット機能を一時的に一時停止し、整理されたコミットを作成できます。これにより、AIの作業中に断片的な自動コミットが発生するのを防ぎます。

重要: AIアシスタントは変更を加える際、次の4ステップのワークフローに従う必要があります。

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の自動コミット機能が一時停止され、複数の変更を1つの整理されたコミットにまとめることができます。

const result = await shadowgit.start_session({
  repo: "my-app",
  description: "Fixing authentication bug"
})
// 戻り値: セッションID（例: "mcp-client-1234567890"）

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

作業を保存するためのチェックポイントコミットを作成します。

// バグを修正した後
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"
})
// 戻り値: コミットハッシュを含むフォーマットされたコミット詳細

// 機能を追加した後
await shadowgit.checkpoint({
  repo: "my-app",
  title: "Add dark mode toggle",
  message: "Implemented theme switching using CSS variables and localStorage persistence",
  author: "GPT-4"
})

// 最小限の使用法（作者はデフォルトで "AI Assistant"）
await shadowgit.checkpoint({
  repo: "my-app",
  title: "Update dependencies"
})

end_session({sessionId, commitHash?})

Session APIを介してAI作業セッションを終了します。これにより、通常の開発でShadowGitの自動コミット機能が再開されます。

await shadowgit.end_session({
  sessionId: "mcp-client-1234567890",
  commitHash: "abc1234"  // オプション: チェックポイントの結果から取得
})

パラメータ:

• 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/stdoutが含まれ、デバッグが容易になります。

AIアシスタントのベストプラクティス

ShadowGit MCP Serverを使用する際、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: "Refactoring authentication module"
})

// 3. 最近の履歴を調べる
await shadowgit.git_command({
  repo: "my-app",
  command: "log --oneline -5"
})

// 4. コードに変更を加える...
// ... (ファイルを編集し、バグを修正するなど) ...

// 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  // オプションだが推奨
})

例のユースケース

最近の変更のデバッグ

// 最後の1時間で何が壊れたかを見つける
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 is offline. Proceeding without session tracking」と表示された場合:

• 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デバッグアシスタントに変えましょう！ 🚀