# Friend of the Show — Full Documentation

> Comprehensive guide for AI agents and developers

## Overview
Friend of the Show tracks comedian appearances on podcasts and TV shows, then finds their upcoming live dates. The site currently indexes 8832 comedians across 41 shows, with 17327 episodes and 3433 live date entries.

## All Public Routes

### Pages (HTML + Markdown)
Every route below is available as HTML (default) or Markdown (append .md or use Accept: text/markdown header).

| Route | Description |
|-------|-------------|
| / | Homepage with featured comedians, upcoming shows, and show directory |
| /comedians | Paginated comedian directory (supports ?q=search&show=filter&page=N) |
| /comedians/{slug} | Full comedian profile: bio, social links, appearances, live dates |
| /shows | Show directory ordered by most recent episode |
| /shows/{slug} | Show detail: description, hosts, episodes, guest live dates |
| /shows/{slug}/episodes/{id} | Episode detail: guests, hosts, description, show notes |
| /live-dates | Upcoming gigs (supports ?city=slug&from=YYYY-MM-DD&to=YYYY-MM-DD&page=N) |
| /locations | City directory grouped by country with live date counts |
| /locations/{slug} | City detail: upcoming gigs in that city (supports ?page=N) |
| /for-comedians | Information for comedians about the platform |
| /contact | Contact form |
| /mcp | MCP server documentation and connection instructions |

### API Endpoints
| Route | Description |
|-------|-------------|
| /api/mcp | MCP server endpoint (Streamable HTTP, stateless) |
| /api/live-dates | Live dates JSON API (supports city, from, to, page params) |
| /api/md/{path} | Markdown API (used internally by .md routes) |

## MCP Server Tools

Connect to `https://friendoftheshow.live/api/mcp` using Streamable HTTP transport.

### search_comedians
Search comedian profiles by name.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| query | string | Yes | Name to search for |
| classification | "comedian" \| "non_comedian" \| "uncertain" | No | Filter by classification |
| limit | integer (1-50) | No | Max results (default 20) |

### search_shows
Search podcast and TV shows by name.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| query | string | Yes | Show name to search for |
| showType | "podcast" \| "tv_show" | No | Filter by show type |
| limit | integer (1-50) | No | Max results (default 20) |

### search_episodes
Search episodes by keyword in title or description.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| query | string | Yes | Keyword to search |
| showSlug | string | No | Filter to a specific show |
| limit | integer (1-50) | No | Max results (default 20) |

### search_live_dates
Search upcoming comedy live dates.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| comedianName | string | No | Filter by comedian name (partial match) |
| city | string | No | Filter by venue city |
| country | string | No | Filter by venue country |
| from | string | No | Start date (YYYY-MM-DD, defaults to today) |
| to | string | No | End date (YYYY-MM-DD) |
| limit | integer (1-50) | No | Max results (default 20) |

### lookup_comedian
Get full comedian profile by slug, including appearances and live dates.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| slug | string | Yes | Comedian slug (e.g. 'james-acaster') |

### lookup_show
Get full show details by slug, including hosts and recent episodes.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| slug | string | Yes | Show slug (e.g. 'off-menu') |

## Data Model

### Comedians
Fields: name, slug, classification (comedian/non_comedian/uncertain), bio, personalWebsite, instagramHandle, twitterHandle, imageUrl, otherLinks

### Shows
Fields: name, slug, showType (podcast/tv_show), description, websiteUrl, feedUrl, artworkUrl

### Episodes (sourceEntries)
Fields: title, description, publishedAt, seasonNumber, episodeNumber, audioUrl, showNotes, entryType

### Live Dates
Fields: date, title, ticketUrl, confidence (high/medium/low), comedian (relation), venue (relation)

### Venues
Fields: name, city, region, country, latitude, longitude

## Usage Tips for AI Agents

1. **Quick lookup**: Use the MCP server tools for structured search and lookup
2. **Full page content**: Append .md to any page URL for markdown content
3. **Browsing**: Start at /comedians.md or /shows.md for directory listings
4. **Live dates**: Use /live-dates.md?city=london-gb for city-specific results
5. **Pagination**: Add ?page=2 to paginated endpoints

## Contact & Feedback
Visit https://friendoftheshow.live/contact or use the /contact.md endpoint.