# GitWhy MCP Server

The shared AI context engine for git — save, search, and share the reasoning behind code changes.

GitWhy captures the *why* behind every commit: reasoning, decisions, and trade-offs. This MCP server makes GitWhy's tools available to AI coding agents like Claude, Cursor, Windsurf, and VS Code Copilot.

## Install

### npm (recommended for MCP clients)

```bash
npm install -g gitwhy-mcp
```

### Homebrew (macOS/Linux)

```bash
brew install gitwhy-cli/tap/git-why
```

### Scoop (Windows)

```bash
scoop bucket add gitwhy https://github.com/quanng28/gitwhy-scoop-bucket
scoop install git-why
```

## MCP Configuration

### Claude Desktop / Claude Code

Add to your MCP config (`~/.claude/settings.json` or Claude Desktop settings):

```json
{
  "mcpServers": {
    "gitwhy": {
      "command": "gitwhy-mcp",
      "args": []
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "gitwhy": {
      "command": "npx",
      "args": ["-y", "gitwhy-mcp"]
    }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "gitwhy": {
      "command": "npx",
      "args": ["-y", "gitwhy-mcp"]
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `gitwhy_save` | Save development context (reasoning, decisions, trade-offs) for the current session |
| `gitwhy_get` | Retrieve a saved context by its ID |
| `gitwhy_search` | Search saved contexts by keyword or natural language query |
| `gitwhy_list` | Browse saved contexts by domain/topic hierarchy |
| `gitwhy_status` | Check setup state, pending commits, and sync status |
| `gitwhy_sync` | Upload local contexts to the cloud (private) |
| `gitwhy_publish` | Share synced contexts with your team |
| `gitwhy_post_pr` | Post context summary as a GitHub PR comment |

## Authentication

For cloud features (sync, publish, PR comments), you need a GitWhy API key:

1. Sign up at [app.gitwhy.dev](https://app.gitwhy.dev)
2. Get your API key at [app.gitwhy.dev/dashboard/api-keys](https://app.gitwhy.dev/dashboard/api-keys)
3. For local CLI: run `git why setup` to authenticate
4. For remote (Smithery/Glama): paste your API key when prompted

## Links

- [Website](https://gitwhy.dev)
- [MCP Registry](https://registry.modelcontextprotocol.io)
- [npm Package](https://www.npmjs.com/package/gitwhy-mcp)

## License

MIT