booking-mcp-app: Add view-only MCP App for court availability

booking-mcp-app/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

booking-mcp-app/README.md

@@ -0,0 +1,99 @@
+# booking-mcp-app
+
+A **view-only MCP App**: an MCP server that exposes court-availability data and renders it as a
+read-only panel inside an MCP host (Claude Desktop, VS Code, or the free local test host), using
+the [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) protocol (spec
+`2026-01-26`).
+
+This is the first phase of porting the `generative-ui` POC to MCP Apps. Read-only, no booking yet:
+the important shift from `generative-ui` is that the data lives on the **server** (the tool), not
+in the conversation. The UI only displays what the server returns.
+
+## What it does
+
+The server registers one tool, `get_court_availability`, that returns which courts and time slots
+are free for a given **date + sport** from in-memory mock data. The tool is linked to a UI resource
+(`ui://court-availability/panel.html`) that the host renders in a sandboxed iframe as a read-only
+grid of courts x time slots (free vs taken).
+
+Two data paths, both handled the same way in the UI:
+
+- The **host pushes** a tool result to the app (`app.ontoolresult`) whenever the agent calls
+  `get_court_availability`, e.g. with a different date or sport. The panel updates.
+- The **app pulls** its own initial data on load (`app.callServerTool`). This is the
+  app -> server -> app round trip, and it also populates the panel when it is opened directly.
+
+There are no inputs, no submit, no booking. Changing the date or sport happens by calling the tool
+with different arguments (from the agent or the test host), not from a form.
+
+## Layout
+
+```
+booking-mcp-app/
+  server.ts         MCP server: registers the tool + the ui:// resource, served over HTTP
+  availability.ts   the booking domain (sports, courts, slots) + deterministic mock data
+  mcp-app.html      UI entry point
+  src/
+    mcp-app.ts      the view: App client, ontoolresult + callServerTool, renders the grid
+    mcp-app.css     panel styling (single light theme)
+  vite.config.ts    bundles the UI into one self-contained HTML (vite-plugin-singlefile)
+  dist/mcp-app.html the built UI, read by the server and served as the resource
+```
+
+Reuses the booking domain from `generative-ui` (Tennis / Football / Basketball / Padel, courts and
+time slots). Availability is deterministic per query, so the same date + sport always renders the
+same grid.
+
+## Run
+
+Requires Node 18+ (developed on Node 24).
+
+```console
+npm install
+npm run build      # typecheck + bundle the UI to dist/mcp-app.html
+npm run serve      # start the MCP server on http://localhost:3001/mcp
+```
+
+`npm start` does the build and serve in one step. Rerun `npm run build` after any UI change; the
+server reads `dist/mcp-app.html` fresh on each resource request.
+
+- `npm run check` typechecks only (`tsc --noEmit`).
+- `PORT=4000 npm run serve` changes the port.
+
+## See the panel in a host
+
+### Free: the local test host
+
+The [ext-apps](https://github.com/modelcontextprotocol/ext-apps) repo ships a local host that
+renders MCP Apps with no account needed.
+
+```console
+# 1) in this project, with the server already running (npm run serve)
+# 2) in a separate clone of the ext-apps repo:
+git clone https://github.com/modelcontextprotocol/ext-apps.git
+cd ext-apps/examples/basic-host
+npm install
+SERVERS='["http://localhost:3001/mcp"]' npm start
+```
+
+Open <http://localhost:8080>, call `get_court_availability` (try `{ "sport": "Padel", "date":
+"2026-08-21" }`), and the availability grid renders in the iframe. Call it again with a different
+sport to see the panel update.
+
+### Claude Desktop (paid plan)
+
+Expose the local server with a tunnel and add it as a custom connector:
+
+```console
+npx cloudflared tunnel --url http://localhost:3001
+```
+
+In Claude, go to Settings -> Connectors -> Add custom connector, paste the
+`https://<something>.trycloudflare.com/mcp` URL, then ask Claude to show court availability.
+
+## References
+
+- MCP Apps overview — <https://modelcontextprotocol.io/extensions/apps/overview>
+- Build guide — <https://modelcontextprotocol.io/extensions/apps/build>
+- Spec (2026-01-26) — <https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx>
+- Examples — <https://github.com/modelcontextprotocol/ext-apps/tree/main/examples>

booking-mcp-app/availability.ts

@@ -0,0 +1,66 @@
+// The booking domain, reused from the generative-ui POC (sports courts).
+// This is the in-memory data the MCP server reads from. In a real system this
+// module would be a call to the booking backend; here it is deterministic mock
+// data so the same query always renders the same grid.
+
+export const SPORTS = ["Tennis", "Football", "Basketball", "Padel"] as const
+export type Sport = (typeof SPORTS)[number]
+
+// One shared daily slot grid: these are the columns of the availability panel.
+export const SLOTS = ["08:00", "10:00", "12:00", "14:00", "16:00", "18:00", "20:00"]
+
+// How many courts each sport has (the rows of the panel).
+const COURTS: Record<Sport, string[]> = {
+  Tennis: ["Court 1", "Court 2", "Court 3"],
+  Football: ["Pitch A", "Pitch B"],
+  Basketball: ["Court 1", "Court 2"],
+  Padel: ["Court 1", "Court 2", "Court 3"],
+}
+
+export interface Cell {
+  time: string
+  taken: boolean
+}
+export interface Court {
+  name: string
+  cells: Cell[]
+}
+export interface Availability {
+  date: string
+  sport: Sport
+  slots: string[]
+  courts: Court[]
+  summary: { free: number; total: number }
+}
+
+export function isoToday(): string {
+  const d = new Date()
+  const p = (n: number) => String(n).padStart(2, "0")
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`
+}
+
+// FNV-1a: a tiny stable string hash. Used to decide free vs taken from the
+// (date, sport, court, slot) tuple, so availability is deterministic per query
+// but still varies believably across dates and sports.
+function hash(s: string): number {
+  let h = 2166136261
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i)
+    h = Math.imul(h, 16777619)
+  }
+  return h >>> 0
+}
+
+export function getAvailability(date: string, sport: Sport): Availability {
+  const courts: Court[] = COURTS[sport].map((name) => {
+    const cells: Cell[] = SLOTS.map((time) => ({
+      time,
+      // roughly one slot in three is taken, chosen deterministically
+      taken: hash(`${date}|${sport}|${name}|${time}`) % 3 === 0,
+    }))
+    return { name, cells }
+  })
+  const total = courts.length * SLOTS.length
+  const free = courts.reduce((n, c) => n + c.cells.filter((x) => !x.taken).length, 0)
+  return { date, sport, slots: SLOTS, courts, summary: { free, total } }
+}

booking-mcp-app/mcp-app.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Court availability</title>
+  </head>
+  <body>
+    <main id="root" class="panel">
+      <div class="state">Loading availability…</div>
+    </main>
+    <script type="module" src="/src/mcp-app.ts"></script>
+  </body>
+</html>