# @mcpforge/demo-github

Public demo of the **MCP Connector Starter Kit**: connects the GitHub API (issues and pull requests) as a real MCP server, callable from Claude Desktop, Claude.ai, or any host compatible with [Model Context Protocol](https://modelcontextprotocol.io).

This demo isn't a mock — it talks directly to `https://api.github.com` using your own token. It's proof that the starter kit works against a real external API, not just sample data.

> **Note:** this repo shows real, tested source for the *demo connector*. The underlying `@mcpforge/starter-kit` engine it's built on (auth, auditing, transport, redaction, validation) is the paid product — this repo won't build standalone without it. Want the full kit or a connector built for your own SaaS? Get in touch.

## Exposed tools

| Tool | Scope | What it does |
|---|---|---|
| `github_list_issues` | read | Lists issues (open/closed/all) for a repo |
| `github_create_issue` | write | Creates a new issue |
| `github_comment_on_issue` | write | Comments on an existing issue |
| `github_list_pull_requests` | read | Lists pull requests (open/closed/all) for a repo |
| `github_get_pull_request_diff_summary` | read | Summarizes a PR: files changed, +/- lines (no full diff) |

## 1. Generate a GitHub token

Go to **GitHub → Settings → Developer settings → Personal access tokens**.

Recommended: **Fine-grained tokens** → "Generate new token":
- **Repository access:** select only the repo(s) you want to test the connector against (don't grant access to all your repos unless you need to).
- **Permissions → Repository permissions:**
  - `Issues`: **Read and write** (needed for `github_create_issue` and `github_comment_on_issue`)
  - `Pull requests`: **Read-only** (this demo only reads PRs, never modifies them)

Simpler but broader alternative: a **classic token** with the `repo` scope (or `public_repo` if you'll only use it against public repositories).

Copy the generated token — GitHub only shows it once.

## 2. Install

```bash
cd demo
cp .env.example .env
# edit .env and paste your token into GITHUB_TOKEN
npm install
```

`npm install` resolves `@mcpforge/starter-kit` as a local dependency (`file:../product`). Make sure `product/` is built (`cd ../product && npm run build`) before installing here.

## 3. Run locally (stdio)

```bash
npm run dev
```

This starts the MCP server over stdio (the same transport Claude Desktop uses for local servers). It needs `GITHUB_TOKEN` in the environment — `npm run dev` picks it up from `.env` if your shell loads it, or export it manually:

```bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
npm run dev
```

To run it in HTTP mode (Streamable HTTP, for remote deployment):

```bash
npm run dev -- --transport=http --port=8080
```

## 4. Test it with the MCP Inspector

Before wiring up a real LLM, verify the server responds correctly with the official [Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

(or, to test straight from TypeScript without building: `npx @modelcontextprotocol/inspector npx tsx src/index.ts`)

The Inspector opens a browser UI where you can list tools, inspect their schemas, and invoke them manually with test parameters (e.g. `github_list_issues` with `owner: "anthropics"`, `repo: "claude-code"`, `state: "open"`).

## 5. Connect to Claude Desktop

Build first:

```bash
npm run build
```

Then edit your Claude Desktop config (**Settings → Developer → Edit Config**) and add:

```json
{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/absolute/path/to/mcpforge/demo/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}
```

Restart Claude Desktop. You should see all 5 `github_*` tools available in the tool picker.

## Design notes

- Every tool normalizes GitHub's response before returning it — the API's raw JSON or an uninterpreted error never reaches the model (see `src/lib/github-client.ts`).
- `github_get_pull_request_diff_summary` deliberately does **not** return the line-by-line diff — only the file summary + line totals, so a large PR doesn't flood the model's context.
- `github_list_issues` filters out the pull requests GitHub's API mixes into the `/issues` endpoint (native GitHub behavior, not a bug in this tool).
- Auth headers come from `ctx.authHeaders` (built by the starter kit's engine from the connector's `AuthConfig`) — this demo doesn't re-derive `Authorization: Bearer` by hand, it uses the kit's own abstraction, same as any connector built with it would.

## Verified working

Built and tested end-to-end against the real `@mcpforge/starter-kit` engine and the real GitHub API: `npm install && npm run build` passes clean from a fresh install, and a real MCP client (`list_tools` / `call_tool`) confirms all 5 tools register with correct schemas and normalized error handling.