# ghe-mcp-gateway

An **MCP (Model Context Protocol) server** that exposes GitHub Enterprise administration
operations as agent tools. Point Claude (Code or Desktop) at it and ask things like
*"list private repos in the org with no recent pushes"* or *"who has admin on payments-api?"* -
the model calls the GitHub API through typed, permissioned tools instead of raw curl.

Built as a working reference for GitHub Enterprise Cloud administration: repository management,
access governance, audit-log review, webhook management, and secret-scanning triage.

## Why
Admin work is repetitive API calls (access reviews, alert triage, config audits). Wrapping the
GitHub REST/GraphQL API as MCP tools lets an agent do the legwork while keeping a human in the
loop - and keeps writes behind an explicit safety switch.

## Tools (21)
| Category | Tools |
|---|---|
| Repository admin | `list_repositories`, `get_repository` |
| Access & teams | `list_organization_members`, `list_teams`, `list_team_members`, `list_repo_collaborators`, `get_repo_permission`, `list_team_repos`, `set_repo_collaborator_permission`*, `set_team_repo_permission`* |
| Branch protection | `get_branch_protection`, `set_branch_protection`*, `list_org_rulesets`, `get_org_ruleset` |
| Security (GHAS) | `list_secret_scanning_alerts`, `list_code_scanning_alerts`, `list_dependabot_alerts`, `resolve_secret_scanning_alert`* |
| Audit log | `get_org_audit_log` |
| Webhooks | `list_org_webhooks` |
| Escape hatch | `graphql_query` |

`*` write operation - blocked unless `GITHUB_MCP_READ_ONLY=false`.

## Companion skill
[`.claude/skills/github-admin/SKILL.md`](.claude/skills/github-admin/SKILL.md) packages these
tools into admin **playbooks** - access review/certification, leaked-secret response, repo
onboarding & governance, security-posture audit, and access changes. Open Claude Code in this
repo and the `/github-admin` skill is available; it drives the MCP tools with a read-first,
least-privilege, confirm-before-write discipline.

## Setup
```bash
uv sync                       # create venv + install deps
cp .env.example .env          # then add your GITHUB_TOKEN
```

Suggested token scopes (classic): `repo`, `read:org`, `admin:org`, `read:audit_log`,
`admin:org_hook`, `security_events`. For GitHub Enterprise Server, set `GITHUB_API_URL` to
`https://<host>/api/v3`.

## Run
```bash
# stdio server (how MCP clients launch it)
uv run github-admin-mcp

# quick manual check with the MCP Inspector
uv run mcp dev src/github_admin_mcp/server.py
```

### Register with Claude Code
```bash
claude mcp add github-admin -- uv run --directory /Users/mikeholzinger/src/github_mcp github-admin-mcp
```
(or add an entry to your client's MCP config pointing at the same command).

### 60-second demo
```bash
# 1. add your token (read-only by default - safe)
cp .env.example .env && $EDITOR .env        # set GITHUB_TOKEN

# 2. register the server + open Claude Code in this repo
claude mcp add github-admin -- uv run --directory "$PWD" github-admin-mcp
claude

# 3. the /github-admin skill is now available. Try, in natural language:
#    "Run an access review on the <org> organization"
#    "Audit the security posture of <org>/<repo>"
#    "Who has admin on <org>/<repo>?"
# The skill calls the MCP tools read-only and reports an auditor-ready summary.
```

## Safety
- Read-only by default (`GITHUB_MCP_READ_ONLY=true`); mutating tools refuse until you opt in.
- No credentials in code - token comes from the environment. `.env` is git-ignored.

## Layout
```
src/github_admin_mcp/
  client.py   # async REST + GraphQL client (auth, pagination, GHES-aware, read-only guard)
  server.py   # FastMCP server; one @mcp.tool() per operation
docs/
  GITHUB_API_REFERENCE.md   # the endpoint research this server is built on
```

## Example GitHub Actions workflows
Healthcare-oriented admin automation lives in `.github/workflows/` with the logic in
`scripts/` (Python + `requests`). All follow least-privilege `permissions:` and pin actions.

| Workflow | Trigger | What it does |
|---|---|---|
| **Access Review** (`access-review.yml`) | Monthly cron + manual | Certifies repo access org-wide; flags outside collaborators, admin grants, write-on-archived; emits a JSON evidence artifact (13-mo retention) and files a tracking issue. |
| **Secret Scanning Alerts** (`secret-scanning-alerts.yml`) | `secret_scanning_alert` event + hourly sweep | Real-time + safety-net notification to a security Slack channel. Sends metadata only - never the secret value. |
| **Repository Governance** (`repo-governance.yml`) | Org `repo-created` → `repository_dispatch` + weekly sweep | Enforces the branch-protection baseline (PR + 2 reviews, Code Owner, signed commits, no force-push/delete, conversation resolution, Dependabot). **Dry-run by default**; auto-applies to brand-new repos. |

Required CI config: secret `ORG_ADMIN_TOKEN` (org PAT/App), secret `SECURITY_SLACK_WEBHOOK`,
and variable `GITHUB_ORG`. The scripts honor `GITHUB_API_URL` for GitHub Enterprise Server.

## Roadmap
- Branch-protection / rulesets tools, team-repo access management
- Secret-scanning alert resolution, code-scanning + Dependabot alerts
- Audit-log streaming config; enterprise-level endpoints
- A companion Claude **skill** that drives these tools for common admin playbooks