Showtime

A monorepo for browsing movie and TV data from TMDB and OMDB. Three deployables share a single data layer, so upstream API access lives in exactly one place.

Workspaces

Package	Name	What it is
packages/core	@showtime/core	Shared data layer: TMDB + OMDB API clients, response types, and pure formatters. The only code that talks to the upstream APIs.
apps/mcp	@showtime/mcp	Local stdio MCP server that exposes the data as 24 tools. Runs on Node via tsx; not deployed.
apps/web	web	TanStack Start site (React 19, Tailwind v4) deployed to Cloudflare Workers.

apps/mcp and apps/web depend on @showtime/core via workspace:* and never call TMDB or OMDB directly.

showtime/
├── packages/core   @showtime/core : clients, types, formatters
├── apps/mcp        @showtime/mcp  : stdio MCP server
└── apps/web        web            : TanStack Start, Cloudflare Workers

Each workspace has its own CLAUDE.md with the details: core, mcp, web.

Toolchain

This repo uses Vite+, a unified toolchain exposed through the global vp CLI (it wraps Vite, Rolldown, Vitest, tsdown, Oxlint, and Oxfmt). pnpm workspaces manage the packages; shared dependency versions live in the catalog: in pnpm-workspace.yaml.

• Node >=22.18.0
• pnpm 11.9.0 (downloaded automatically via devEngines if missing)
• The vp CLI. Run vp help for commands, or read the docs at node_modules/vite-plus/docs.

Getting started

vp install

Both apps need a TMDB and an OMDB API key at runtime:

• apps/mcp: copy apps/mcp/.env.example to apps/mcp/.env and fill in TMDB_API_KEY and OMDB_API_KEY.
• apps/web: put the same keys in apps/web/.dev.vars locally; in production set them with wrangler secret put.

Common commands

Run from the repo root.

Command	Does
vp run ready	vp check + tests + build across every workspace. Run before considering a change done.
vp run dev	Start the web dev server (port 3000).
vp check	Format, lint, and typecheck.
vp run fix	Apply formatting and lint fixes.
vp run -r test	Run tests in every workspace.
vp run -r build	Build every workspace.

Per-workspace scripts run with vp run <script> from inside the workspace (or vp run <name>#<script> from the root), for example:

• apps/mcp: vp run start (run once), vp run dev (watch), vp run typecheck.
• apps/web: vp dev, vp build, vp preview, vp run generate-routes.

Continuous integration

.github/workflows/ci.yml runs the checks on every push and pull request to master. It installs with pnpm install --frozen-lockfile, generates the Cloudflare Worker types the web typecheck needs (wrangler types, since worker-configuration.d.ts is gitignored), then runs pnpm check (format, lint, typecheck) and pnpm test. Deployment is separate: a push to master also triggers a Cloudflare Workers Build that deploys apps/web (see apps/web/CLAUDE.md).

MCP server

apps/mcp is a stdio server, so it is launched by an MCP client rather than run standalone. To register it with Claude Code:

claude mcp add showtime-mcp -- \
  ./apps/mcp/node_modules/.bin/tsx \
  --env-file-if-exists=$PWD/apps/mcp/.env \
  $PWD/apps/mcp/src/index.ts

Conventions

• TypeScript ESM throughout. Relative imports inside a package use .js extensions even for .ts files.
• All TMDB/OMDB access goes through @showtime/core; nothing else reads API keys or calls the upstream APIs.