Shadowgit MCP

🚀 ShadowGit MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with secure git access to your ShadowGit repositories, enabling powerful debugging, code analysis, and clean commit management.

🚀 Quick Start

This Model Context Protocol (MCP) server offers AI assistants secure git access to your ShadowGit repositories. It allows for organized commit creation via the Session API, giving AI controlled access to your project's git history for effective debugging, code analysis, and commit management.

✨ Features

• Secure Git Access: Grants AI assistants secure access to ShadowGit repositories.
• Session API: Enables the creation of organized commits and pauses auto - commits during AI work.
• Comprehensive History: Provides read access to detailed development history.
• Security Measures: Implements multiple security features to protect repositories.

📦 Installation

npm install -g shadowgit-mcp-server

📚 Documentation

Setup with Claude Code

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

# Restart Claude Code to load the server

Setup with Claude Desktop

Add to your Claude Desktop MCP configuration:

macOS/Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json

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

Requirements

• Node.js 18+
• ShadowGit app installed and running with tracked repositories (Session API requires ShadowGit version >= 0.3.0)
• Git available in PATH

How It Works

MCP servers are stateless and use stdio transport:

• The server runs on - demand when AI tools (Claude, Cursor) invoke it.
• Communication happens via stdin/stdout, not HTTP.
• The server starts when needed and exits when done.
• No persistent daemon or background process.

Environment Variables

You can configure the server behavior using these optional environment variables:

• SHADOWGIT_TIMEOUT - Command execution timeout in milliseconds (default: 10000).
• SHADOWGIT_SESSION_API - Session API URL (default: http://localhost:45289/api).
• SHADOWGIT_LOG_LEVEL - Log level: debug, info, warn, error (default: info).
• SHADOWGIT_HINTS - Set to 0 to disable workflow hints in git command outputs (default: enabled).

Example:

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

💻 Usage Examples

Basic Usage

List Repositories

await shadowgit.list_repos()

Execute Read - only Git Commands

// 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"
})

Advanced Usage

Start an AI Work Session

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

Create a Checkpoint Commit

// 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 an AI Work Session

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

Complete Example Workflow

// 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
})

🔧 Technical Details

Security

• Read - only access: Only safe git commands are allowed.
• No write operations: Commands like commit, push, merge are blocked.
• No destructive operations: Commands like branch, tag, reflog are blocked to prevent deletions.
• Repository validation: Only ShadowGit repositories can be accessed.
• Path traversal protection: Attempts to access files outside repositories are blocked.
• Command injection prevention: Uses execFileSync with array arguments for secure execution.
• Dangerous flag blocking: Blocks --git-dir, --work-tree, --exec, -c, --config, -C and other risky flags.
• Timeout protection: Commands are limited to prevent hanging.
• Enhanced error reporting: Git errors now include stderr/stdout for better debugging.

Best Practices for AI Assistants

When using ShadowGit MCP Server, AI assistants should:

1. Follow the workflow: Always: start_session() → make changes → checkpoint() → end_session().
2. Use descriptive titles: Keep titles under 50 characters but make them meaningful.
3. Always create checkpoints: Call checkpoint() after completing each task.
4. Identify yourself: Use the author parameter to identify which AI created the checkpoint.
5. Document changes: Use the message parameter to explain what was changed and why.
6. End sessions properly: Always call end_session() to resume auto - commits.

📄 License

This project is under the MIT License. See the LICENSE file for details.

Related Projects

• ShadowGit - Automatic code snapshot tool
• MCP SDK - Model Context Protocol TypeScript SDK

Transform your development history into a powerful AI debugging assistant! 🚀