# mcp-github

GitHub MCP server for [Lume](https://pa.bryar.tech) — the first non-built-in plugin in the Lume marketplace, used to validate the third-party plugin flow end to end.

Read-only in v1. Lets the assistant search and read GitHub repos, issues, pull requests, commits, and file contents on the user's behalf, scoped to whatever the user's personal access token can see.

## Tools (read-only v1)

| Tool | Purpose |
|---|---|
| `search_repositories` | Search repos using GitHub query syntax |
| `search_issues` | Search issues across visible repos |
| `search_code` | Search code across visible repos |
| `list_issues` | List issues in a specific repo |
| `get_issue` | Read full body and metadata of one issue |
| `list_pull_requests` | List PRs in a specific repo |
| `get_pull_request` | Read PR body, branches, diff stats |
| `list_commits` | List recent commits in a repo |
| `get_file_contents` | Read a file at a path/ref |

## Authentication

Per-user model: the api process injects a JSON `X-PA-Credentials` header on each call; this server reads `github_token` from it. Falls back to the `GITHUB_TOKEN` env var only when no header is present (bootstrap admin).

To configure as a Lume user:
1. Create a personal access token at <https://github.com/settings/tokens>. Fine-grained or classic; read-only scopes are sufficient (`repo:read`, `read:org`, etc.).
2. In Lume → Settings → Plugins → GitHub, paste the token. The server retrieves it on every tool call via the encrypted credential vault.

## Running

The plugin is intended to run as a sidecar to the PA-iOS docker-compose stack. To install:

1. Clone this repo next to your PA-iOS clone:
   ```
   git clone https://github.com/bryarpatch36/mcp-github.git
   ```
2. Merge the [`compose.fragment.yml`](./compose.fragment.yml) snippet into your `PA-iOS/docker-compose.yml`.
3. `docker compose up -d --build mcp-github`.
4. Install the plugin in Lume from Settings → Plugins → Discover.

## Manifest

The Lume plugin manifest lives at [`manifest.json`](./manifest.json) and is fetched by Lume's marketplace catalog from `https://raw.githubusercontent.com/bryarpatch36/mcp-github/main/manifest.json`.

## Roadmap

- v1.0 — read-only (this release)
- v1.1 — issue and PR comments behind Lume's two-phase confirmation protocol
- v1.2 — issue and PR creation behind confirmation
- Forks, branches, merges remain explicitly out of scope; those should run from a real shell, not an LLM tool call.

## License

MIT