# github-mcp-demo

A small, working MCP (Model Context Protocol) server that wraps the GitHub
REST API as four tools an AI agent can call directly: search repositories,
get repository details, list issues, and read a README.

This exists for two reasons:

1. **Portfolio proof** — a real, tested MCP server you can point to (GitHub pin,
   Fiverr/Contra gig samples, Upwork portfolio) that shows exactly what the
   $99 "custom MCP server" gig delivers.
2. **Reusable boilerplate** — the fastest way to deliver a paid job is to copy
   this folder and swap the API-specific pieces (see "Adapting this for a
   client" below), not start from a blank file each time.

## What it does

| Tool | What it calls | What it returns |
|---|---|---|
| `search_repositories` | `GET /search/repositories` | Top matching repos: name, stars, description, URL |
| `get_repository` | `GET /repos/{owner}/{repo}` | Stars, forks, open issues, license, topics |
| `list_issues` | `GET /repos/{owner}/{repo}/issues` | Open/closed issues, most recently updated first |
| `get_readme` | `GET /repos/{owner}/{repo}/readme` | Decoded README text (truncated to 6000 chars) |

## Setup

```bash
npm install
npm run build
```

This produces `dist/index.js`, a standard stdio-based MCP server.

### Optional: raise the rate limit

Without a token, GitHub allows 60 unauthenticated API requests/hour **per IP**,
shared across anything else on that network — you'll hit this fast in testing.
Set a token for real use:

```bash
export GITHUB_TOKEN=ghp_yourPersonalAccessToken
```

A read-only, no-scopes personal access token is enough for public repos.

## Connect to Claude Desktop

Add this to your Claude Desktop config (`claude_desktop_config.json`):

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

Restart Claude Desktop, then try asking it things like:
- "Search GitHub for popular MCP servers written in TypeScript"
- "What are the open issues on modelcontextprotocol/typescript-sdk?"
- "Show me the README for anthropics/anthropic-sdk-python"

## Adapting this for a client (the actual delivery workflow)

This is the part that makes a $99, 48-hour turnaround realistic:

1. Copy this whole folder, rename it.
2. In `src/index.ts`, replace `GITHUB_API_BASE` and the auth header logic in
   `githubRequest()` with the client's API base URL and auth scheme
   (API key header, Bearer token, Basic auth — same shape, different values).
3. Replace the four `registerTool(...)` blocks with tools matching *their*
   API's endpoints. Keep the same pattern: a Zod `inputSchema` for arguments,
   a fetch call, a small object shaping the response, `textResult(...)`.
4. `npm run build`, run it through the same test pattern (spin up an MCP
   client over stdio, call each tool once, check the output).
5. Deliver `dist/index.js` + a short README with their own Claude Desktop
   config snippet filled in.

Steps 2–3 are the only genuinely custom work per client — everything else
(project scaffold, error handling, stdio wiring, response shaping pattern)
is already done.

## Notes

- Errors from the upstream API (rate limits, 404s, bad auth) are caught and
  returned as a readable message rather than crashing the server — this
  matters more than it sounds like once a client is testing it themselves.
- `get_readme` truncates long files to ~6000 characters so a huge README
  doesn't eat the calling model's whole context window on one tool call.