# GitHub MCP App Demo (json-render + LLM)

An [MCP App](https://modelcontextprotocol.io/extensions/apps/overview) that fetches public GitHub repositories and uses an **LLM** to generate a [json-render](https://json-render.dev) UI spec.

## Project layout

```
mcp-app/
├── server/          # MCP server (tools, GitHub API, LLM spec generation)
│   ├── main.ts      # entry — HTTP / stdio transport
│   ├── server.ts    # tool + resource registration
│   ├── github.ts    # GitHub REST API
│   ├── llm-spec.ts  # DeepSeek / OpenAI → json-render spec
│   ├── catalog.ts   # json-render component catalog
│   └── types.ts
├── app/             # MCP App UI (iframe)
│   ├── index.html
│   ├── main.tsx
│   └── registry.tsx
├── dist/            # build output (index.html bundle)
└── .env
```

## Flow

```
GitHub API → repos data → LLM + catalog.prompt() → json-render Spec → Renderer
```

## Setup

```bash
npm install
cp .env.example .env
# Set DEEPSEEK_API_KEY and DEEPSEEK_MODEL in .env
npm run build
npm start
```

Server listens at `http://localhost:3001/mcp`.

## Test with basic-host

```bash
cd /Users/CYKUO/Codes/ext-apps/examples/basic-host && npm start
```

Open http://localhost:8080 → `http://localhost:3001/mcp` → pick a tool → **Call Tool**.

## Tools

All tools require `DEEPSEEK_API_KEY` and use the LLM to generate the UI spec. The `layout` parameter (`table` or `cards`) is passed as a hint to the LLM.

### `list-repos`

| Parameter | Description |
|-----------|-------------|
| `username` | GitHub user (default: `modelcontextprotocol`) |
| `perPage` | Max repos to fetch (default: 10) |
| `layout` | `table` or `cards` (default: `table`) |
| `prompt` | Natural language UI instructions for the LLM |

### `get-user-profile`

| Parameter | Description |
|-----------|-------------|
| `username` | GitHub user (default: `modelcontextprotocol`) |
| `layout` | `table` or `cards` (default: `table`) |
| `prompt` | Natural language UI instructions for the LLM |

Returns profile fields such as bio, followers, following, public repo count, location, and company.

### `list-repo-issues`

| Parameter | Description |
|-----------|-------------|
| `owner` | Repo owner (default: `modelcontextprotocol`) |
| `repo` | Repo name (default: `ext-apps`) |
| `state` | `open`, `closed`, or `all` (default: `open`) |
| `perPage` | Max issues to fetch (default: 10) |
| `layout` | `table` or `cards` (default: `table`) |
| `prompt` | Natural language UI instructions for the LLM |

Pull requests are filtered out; only issues are returned.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `DEEPSEEK_API_KEY` | Yes | DeepSeek API key |
| `DEEPSEEK_MODEL` | No | e.g. `deepseek-v4-flash` |
| `DEEPSEEK_BASE_URL` | No | Default `https://api.deepseek.com/v1` |
| `GITHUB_TOKEN` | No | Higher GitHub rate limits |
| `PORT` | No | Default `3001` |