# GitHub MCP Server

Local OpenCode MCP server for safe GitHub developer workflows: pull `main`, create a feature branch, push it, and open a ready-for-review pull request.

## Environment

Set these variables in your shell. Do not commit real secrets.

```bash
export GH_TOKEN="your_github_token_here"
export GITHUB_MCP_ALLOWED_ROOTS="/Users/matiasbinagora/Projects"
export GITHUB_MCP_DEFAULT_BASE_BRANCH="main"
export GITHUB_MCP_DEFAULT_REMOTE="origin"
export GITHUB_MCP_REQUIRE_CLEAN_WORKTREE="true"
```

`GH_TOKEN` is recommended. If it is not set, the server can still work when `gh` is already authenticated locally.

## Build

```bash
npm install
npm run build
```

## Smoke Test

This creates a temporary local bare repo, pulls `main`, creates a test branch, commits a file, pushes the branch, and verifies the remote branch exists.

```bash
npm run smoke
```

## GitHub Integration Test

This creates a real branch and ready-for-review PR in the configured test repo.

```bash
export GITHUB_MCP_SMOKE_REPO_PATH="/Users/matiasbinagora/Projects/binagora"
npm run smoke:github
```

## OpenCode Config

Add this to the global OpenCode config at `~/.config/opencode/opencode.json`.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "local",
      "command": ["node", "/Users/matiasbinagora/Projects/github-mcp/dist/index.js"],
      "enabled": true,
      "environment": {
        "GH_TOKEN": "{env:GH_TOKEN}",
        "GITHUB_MCP_ALLOWED_ROOTS": "/Users/matiasbinagora/Projects",
        "GITHUB_MCP_DEFAULT_BASE_BRANCH": "main",
        "GITHUB_MCP_DEFAULT_REMOTE": "origin",
        "GITHUB_MCP_REQUIRE_CLEAN_WORKTREE": "true"
      }
    }
  }
}
```

If OpenCode is launched before your shell exports `GH_TOKEN`, use this command instead so the MCP server sources `~/.zshrc` before starting:

```json
"command": [
  "zsh",
  "-lc",
  "source \"$HOME/.zshrc\" >/dev/null 2>&1; exec node \"/Users/matiasbinagora/Projects/github-mcp/dist/index.js\""
]
```

## Tools

- `github_repo_status`
- `github_pull_main`
- `github_create_feature_branch`
- `github_push_feature_branch`
- `github_create_pull_request`
- `github_prepare_feature_workflow`

## Safety Notes

- Repositories must be inside `GITHUB_MCP_ALLOWED_ROOTS`.
- No generic shell execution tool is exposed.
- Direct pushes to `main` or `master` are refused.
- Force pushes and branch deletion are not implemented.
- A clean worktree is required before pulling, branch creation, and PR creation by default.
- Branch names are validated with `git check-ref-format --branch`.