@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.

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

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)

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:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
npm run dev

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

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:

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:

npm run build

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

{
  "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.