# GitHub App MCP gateway

This is a local stdio MCP gateway for the official `github-mcp-server`. It adds a
required, nullable `scope` argument to every proxied GitHub tool, resolves the GitHub
App installation through GitHub's API, and starts one downstream server per active
installation. Downstream servers are stopped when the client session closes.

## Configure

Copy `config.example.yaml` to `config.yaml`. The YAML file deliberately contains
only gateway-owned settings: the GitHub MCP executable, the GitHub App
private-key path and the default installation used for explicit `scope: null`.

Set `appId` in the YAML configuration. Every environment variable supplied by the
MCP client is forwarded to each `github-mcp-server` child, except values owned by
the gateway.
The gateway deliberately overrides only:

- `GITHUB_APP_ID`, selected from YAML;
- `GITHUB_APP_INSTALLATION_ID`, selected from `scope`;
- `GITHUB_APP_PRIVATE_KEY_PATH`, selected from YAML;
- `GITHUB_APP_PRIVATE_KEY`, removed so the configured key path is authoritative.

All gateway command-line arguments after `--` are forwarded unchanged to the
GitHub MCP server. The gateway adds `stdio` when it is not already present.

## Build and register

```powershell
npm install
npm run build
```

Example client configuration:

```json
{
  "command": "node",
  "args": [
    "/path/to/github-app-mcp-gateway/dist/index.js",
    "--config", "/path/to/github-app-mcp-gateway/config.yaml",
    "--",
    "--toolsets", "repos,issues,pull_requests"
  ],
  "env": {
    "GITHUB_HOST": "https://github.com",
    "GITHUB_API_URL": "https://api.github.com",
    "GITHUB_LOCKDOWN_MODE": "1"
  }
}
```

The `scope` argument is required, but candidate scopes are deliberately not
enumerated in the tool definition. Pass a repository (`owner/repo`), organization,
or user name and the gateway will query GitHub for this App's installation ID;
use `null` only for an operation intentionally allowed through the configured
default installation. For repository and organization tools, the gateway rejects
a scope that does not match the original `owner`/`repo`/`org` arguments.