**English** | [中文](./README.zh.md)

# mcp-hub

[![CI](https://github.com/Gholls/mcp-hub/actions/workflows/ci.yml/badge.svg)](https://github.com/Gholls/mcp-hub/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

![mcp-hub — interactive micro-tools for humans and AI agents](https://mcp.gholl.com/og/site.png)

Interactive micro-tools for humans **and** AI agents, served from
[`mcp.gholl.com`](https://mcp.gholl.com).

- **For humans** — a login-free playground of fast, single-purpose widgets.
- **For AI agents** — the same widgets exposed as [MCP](https://modelcontextprotocol.io)
  tools that render as sandboxed iframe apps
  ([MCP Apps](https://github.com/modelcontextprotocol/ext-apps)).

> **Reference implementation.** mcp-hub is a working reference for the
> [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) interactive-UI
> pattern ([SEP-1865](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp)):
> every tool ships a self-contained UI card over `resources/read`, side by side
> with the pure-data MCP path.

One tool definition (`shared/tools.ts`) powers four surfaces: the gallery, the
SEO landing page, the sandboxed embed, and the MCP server + discovery document.

| Live | |
| --- | --- |
| Site | https://mcp.gholl.com |
| MCP endpoint | `https://mcp.gholl.com/mcp` (Streamable HTTP, no auth) |
| Discovery | https://mcp.gholl.com/.well-known/mcp.json |
| Agent index | https://mcp.gholl.com/llms.txt |

## Tools

> The live catalogue has **42 cards across 13 categories** (Culture, Data, Design, Developer, Education, Everyday, Finance, Games, Infrastructure, Math, Monitoring, Security, Text). See the gallery at https://mcp.gholl.com or the
> machine-readable list at https://mcp.gholl.com/.well-known/mcp.json. Full list:

| id | Tool | Category | What it does |
| --- | --- | --- | --- |
| `chrono-energy` | BaZi Chrono-Energy Wheel | Culture | Compute the Four Pillars (BaZi) from a birth date/time and explore the five-element energy wheel and luck cycles. |
| `csv-chart` | CSV to Chart | Data | Chart a CSV instantly (bar or line). |
| `echarts` | ECharts Data Visualization | Data | Render interactive Apache ECharts charts from an ECharts option — line, bar, pie, radar, scatter, sankey and more. |
| `schema-viewer` | JSON-LD / Schema Viewer | Data | Inspect, validate and explore structured JSON / JSON-LD with a collapsible tree, syntax checks and JSON-LD detection. |
| `statistics` | Statistics | Data | Mean, median, standard deviation and a histogram for a data set. |
| `color-blindness` | Color Blindness Simulator | Design | Preview a color under different color-vision deficiencies. |
| `color-palette` | Color Palette | Design | Generate a harmonious palette from a base color. |
| `color-studio` | Color Studio & Contrast | Design | Convert between hex/RGB/HSL, generate tints and shades, and check WCAG contrast against black and white. |
| `css-effects` | CSS Effects Studio | Design | Design gradients, box-shadows and border-radius with live previews and copy-ready CSS. |
| `icon-generator` | Icon Logo Generator | Design | Upload a logo once and export ready-to-use icons for web, PWA, iOS, macOS, Android, Windows and Linux — all generated locally. |
| `favicon-generator` | Favicon Generator | Design | Turn text or an emoji into a favicon. |
| `image-compressor` | Image Compressor | Design | Compress an image in the browser. |
| `image-to-base64` | Image to Base64 | Design | Convert an image to a data URI / Base64. |
| `qr-generator` | QR Code Generator | Design | Generate a QR code from text or a URL. |
| `bit-visualizer` | Bit Visualizer | Developer | See an integer as a grid of bits, with binary/octal/hex. |
| `cron-debugger` | Cron & Regex Debugger | Developer | Translate a cron schedule into plain language, preview the next runs, and test regular expressions with live highlighting. |
| `hash-generator` | Hash Generator | Developer | Compute SHA-1 / SHA-256 / SHA-512 digests of text as hex and base64, entirely in your browser. |
| `jwt-decoder` | JWT Decoder | Developer | Decode a JWT into its header, payload and claims, and check whether it is expired. |
| `quiz` | Quiz | Education | A universal quiz card. The AI defines the questions, the options, each option’s score and how many to show per page; the card renders them and reports the answers back. |
| `resistor-color` | Resistor Color Code | Everyday | Decode a 4-band resistor into ohms. |
| `unit-converter` | Unit Converter | Everyday | Convert length, mass, area, volume, temperature, speed, data and time units. |
| `world-clock` | World Clock | Everyday | Live times across major cities with a day/night indicator. |
| `chinese-money` | Amount in Chinese | Finance | Render an amount in Chinese capital numerals, like a receipt. |
| `compound-interest` | Compound Interest | Finance | Project compound growth over time. |
| `loan-calculator` | Loan Calculator | Finance | Monthly payment, total interest and a balance chart. |
| `dice-roller` | Dice Roller | Games | Roll cryptographically-random dice and read the total. |
| `gomoku` | Gomoku · Play vs AI | Games | Play Gomoku (five-in-a-row) against your host AI. The card provides the board, move rules and win detection. |
| `random-picker` | Random Picker | Games | Spin a wheel to fairly pick from a list. |
| `reaction-test` | Reaction Test | Games | Interactive reaction-time measurement. |
| `typing-test` | Typing Test | Games | Measure typing speed and accuracy. |
| `vram-calc` | GPU VRAM & Deployment Estimator | Infrastructure | Estimate the VRAM required to serve an LLM and get GPU recommendations with ready-to-copy vLLM / Ollama commands. |
| `conic-sections` | Conic Sections | Math | Plot circles, ellipses, parabolas and hyperbolas with live sliders, showing foci, eccentricity and asymptotes. |
| `function-grapher` | Function Grapher | Math | Plot common functions with live parameter sliders (linear, inverse, quadratic, power, exponential, logarithmic) and read off key features. |
| `geometry-lab` | Geometry Lab | Math | Drag triangles, quadrilaterals and circles to explore sides, angles, area and the Pythagorean / sine / cosine theorems. |
| `matrix-calculator` | Matrix Calculator | Math | Multiply, transpose and take determinants of matrices. |
| `trig-lab` | Trigonometry Lab | Math | Explore the unit circle and trigonometric functions y = A·sin(ωx+φ)+k with live sliders for amplitude, period and phase. |
| `api-uptime` | API Health & Latency | Monitoring | Probe an API endpoint, measure live latency, and view a 24h uptime and latency dashboard. |
| `dns-lookup` | DNS Lookup | Monitoring | Resolve DNS records over DNS-over-HTTPS. |
| `http-inspector` | HTTP Inspector | Monitoring | Fetch a URL and inspect status, redirects and headers. |
| `password-strength` | Password Strength | Security | Estimate password strength and entropy. |
| `totp-generator` | TOTP Generator | Security | Generate time-based one-time codes (2FA). |
| `text-diff` | Text Diff | Text | Line-by-line diff between two texts. |

## Routes

| Path | Purpose |
| --- | --- |
| `/` | Tool gallery + playground (prerendered) |
| `/tools/:id` | SEO landing page for one tool (prerendered + SPA) |
| `/:category` | Category landing page, e.g. `/math`, `/developer` (prerendered) |
| `/embed/:id` | Sandboxed, per-widget single-file app (iframe / MCP Apps) |
| `/app/:id/index.html` | Raw per-widget bundle (used internally) |
| `/mcp`, `/mcp/sse` | MCP endpoint (Streamable HTTP / JSON-RPC) |
| `/.well-known/mcp.json` | Agent discovery document |
| `/llms.txt`, `/sitemap.xml`, `/robots.txt` | SEO / GEO surfaces |
| `/og/:name.png` | Generated Open Graph images |

`GET /mcp` (no `text/event-stream`) returns the discovery document; a browser
gets a help page. `POST /mcp` is the JSON-RPC transport. See
[`docs/host-integration.md`](docs/host-integration.md) for the full matrix.

## Stack

Vite · React 19 · TypeScript · Tailwind CSS v4 · `@mcp-ui/*` ·
`@modelcontextprotocol/ext-apps` · Apache ECharts · KaTeX · Cloudflare Workers +
static assets · Vitest · GitHub Actions.

> ECharts and KaTeX are imported lazily inside the widgets that need them, so they
> never affect the first paint of the site or other cards.

## Architecture

```
shared/
  tools.ts            Single source of truth (ToolMeta: schema, i18n, examples)
  calc/               Pure logic reused by widgets AND the MCP server
  mcp/                MCP server, HTTP handler, discovery builders
worker/index.ts       Cloudflare Worker: /mcp, /.well-known, /embed, /tools, SPA
src/
  pages/              Home, ToolPage, EmbedPage
  components/         Layout, ToolCard, ParamTable, WidgetHost, ui, ...
  widgets/<id>/       Interactive widget components (lazy-loaded)
scripts/
  build-embeds.mjs    One self-contained HTML per widget -> dist/app/<id>
  build-og.mjs        Open Graph PNGs -> dist/og
  prerender.mjs       Crawler-visible HTML for / and /tools/<id> -> dist/tools
docs/                 integrations.md (clients), host-integration.md (hosts)
```

### How the UI cards are delivered

Each tool returns a small result (`text` + `structuredContent`) plus
`_meta.ui.resourceUri = ui://gholl/<id>`. Hosts fetch the card HTML via
`resources/read` and get a **self-contained single-file app**
(`text/html;profile=mcp-app`, no external requests). The same widgets are also
served as regular pages (`/tools/:id`) and iframes (`/embed/:id`).

### Performance & SEO/GEO

- The main site is **code-split** (lazy routes + lazy widgets); first paint is
  ~2 KB HTML + ~100 KB gzip total. Widgets load only when opened.
- **Prerendered** content is emitted for `/` and every `/tools/:id`, so AI
  crawlers that don't run JS still see full content, parameter tables and links.
- Rich structured data: `WebSite`, `ItemList`, `SoftwareApplication`,
  `BreadcrumbList`, `FAQPage`, `Organization`. Per-tool OG images.

## Scripts

| Command | Description |
| --- | --- |
| `pnpm dev` | Vite dev server (UI only; no Worker/MCP) |
| `pnpm dev:worker` | Serve `dist` + Worker locally via `wrangler dev` (needs `pnpm build` first) |
| `pnpm build` | Type-check, build web, per-widget embeds, OG images, prerender |
| `pnpm build:web` | Fast path: type-check + web build only |
| `pnpm preview` | Preview the built site with `vite preview` |
| `pnpm test` / `test:watch` | Vitest unit + MCP integration tests |
| `pnpm lint` | ESLint |
| `pnpm typecheck` | App TypeScript |
| `pnpm typecheck:functions` | Worker TypeScript |
| `pnpm deploy` | `pnpm build && wrangler deploy` |

## Development

```bash
pnpm install
pnpm dev            # http://localhost:5173 (UI only)
pnpm build && pnpm dev:worker   # full stack incl. /mcp on http://localhost:8787
pnpm test
```

## Deployment (Cloudflare)

Deploys as a **Worker with static assets** (`wrangler.jsonc`):

- `main` → `worker/index.ts` handles `/mcp`, `/mcp/sse`, `/.well-known/mcp.json`,
  `/embed/:id`, `/tools/:id` and the SPA fallback.
- `assets.directory` → `./dist`, `html_handling: none`,
  `not_found_handling: single-page-application`.

Build command `pnpm build`, deploy command `pnpm exec wrangler deploy` (or
connect the repo in the Cloudflare dashboard). Bind the custom domain
`mcp.gholl.com`. Generated files (`llms.txt`, `sitemap.xml`, `robots.txt`,
`dist/app/*`, `dist/og/*`, `dist/tools/*`) come from `shared/tools.ts`.

> **GEO note:** Cloudflare's *managed* `robots.txt` / Content Signals policy can
> block AI crawlers (GPTBot, ClaudeBot, Perplexity, …). If you want AI engines to
> cite the site, allow those crawlers in the Cloudflare dashboard for this zone.

## Connect a client

See [`docs/integrations.md`](docs/integrations.md) for Claude Desktop / Code,
Cursor, VS Code, LibreChat, Dify and FastGPT. Building a host? Use
[`docs/host-integration.md`](docs/host-integration.md). Registry metadata lives
in [`server.json`](server.json).

## Adding a tool

1. Add a `ToolMeta` entry in `shared/tools.ts` (id, i18n, `inputSchema`, examples).
2. Add the widget in `src/widgets/<id>/` and register it in
   `src/widgets/registry.ts`.
3. Optionally add a server-side result in `shared/mcp/server.ts` (`runTool`).

Everything else — gallery card, landing page, per-widget embed, prerendered HTML,
MCP tool listing, discovery document, OG image and sitemap entry — is generated
automatically.

## License

[MIT](./LICENSE)