GitHub MCP App Demo (json-render + LLM)

An MCP App that fetches public GitHub repositories and uses an LLM to generate a json-render 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

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

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`

mcp-app