# @dragons-claw/mcp-github

A Model Context Protocol (MCP) server for GitHub operations. Provides high-level, verified GitHub workflows via git/gh CLI.

## Features

- **Clone & Branch**: Clone repositories and create feature branches
- **Full Contribution**: Complete PR workflow in one command (clone → branch → edit → commit → push → PR)
- **Issue Management**: Create issues with duplicate checking
- **PR Management**: Create PRs with branch verification
- **Commit & Push**: Stage, commit, and push changes
- **Workspace Cleanup**: Remove cloned repositories

All operations include:
- Step-by-step verification
- Windows/PowerShell compatibility
- Intelligent stderr handling (git/gh write progress to stderr)
- Existing resource detection (reuse clones, skip existing PRs)

## Installation

```bash
npm install @dragons-claw/mcp-github
```

Or run directly:
```bash
npx @dragons-claw/mcp-github
```

## Requirements

- Node.js 18+
- Git CLI installed and configured
- GitHub CLI (`gh`) installed and authenticated (`gh auth login`)

## Usage

### As MCP Server (stdio mode)

For integration with MCP clients like Claude Desktop:

```bash
mcp-github --stdio --workspace /path/to/workspace
```

Add to Claude Desktop config (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@dragons-claw/mcp-github", "--stdio", "--workspace", "/path/to/workspace"]
    }
  }
}
```

### As CLI Tool

```bash
# List all available tools
mcp-github

# Clone and create branch
mcp-github --tool github_clone_and_branch \
  --repo owner/repo \
  --branch feature-name

# Full contribution workflow
mcp-github --tool github_full_contribution \
  --repo owner/repo \
  --branch feature-name \
  --filePath src/new-file.ts \
  --fileContent "console.log('hello');" \
  --commitMessage "Add new file" \
  --prTitle "Add new feature"

# Create issue
mcp-github --tool github_create_issue \
  --repo owner/repo \
  --title "Bug report" \
  --body "Description of the issue"
```

### As Library

```typescript
import { MCPGitHubServer, initMCPGitHubServer } from '@dragons-claw/mcp-github';

const server = initMCPGitHubServer({
  workspacePath: '/path/to/workspace',
});

await server.start();

// Execute a tool
const result = await server.executeTool('github_clone_and_branch', {
  repo: 'owner/repo',
  branch: 'feature-name',
});

console.log(result.success ? result.content : result.error);
```

## Available Tools

| Tool | Description |
|------|-------------|
| `github_clone_and_branch` | Clone a repo and create/checkout a branch |
| `github_full_contribution` | Complete PR workflow: clone, branch, edit, commit, push, create PR |
| `github_create_issue` | Create a GitHub issue |
| `github_create_pr` | Create a pull request (requires branch pushed first) |
| `github_commit_and_push` | Stage, commit, and push changes |
| `github_get_checklist` | Get status of a task checklist |
| `github_list_active_tasks` | List all in-progress tasks |
| `github_cleanup_workspace` | Remove a cloned repository |

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_WORKSPACE` | Default workspace directory | Current directory |
| `DEBUG` | Enable debug logging | `false` |

## License

MIT

## Contributing

See [SKILLS.md](./SKILLS.md) for workflow documentation and best practices.