stagmadness-configurator

# Stagmadness Configurator + MCP Server Two artifacts that ship together, backed by the same scraped catalog of [stagmadness.com](https://stagmadness.com): 1. **Web app** (`apps/web`) — Next.js 15 deep-link-driven activity configurator. Lives at **app.stagmadness.com**. 2. **MCP server** (`apps/mcp`) — standalone Node service exposing the catalog as AI-callable tools. Every tool response includes a `checkout_url` deep link that pre-loads the configurator with the caller's selections. ## One-click install (Claude Desktop) ``` claude://mcp/install?name=stagmadness&url=https://mcp.stagmadness.com ``` After publishing to npm: ``` claude://mcp/install?name=stagmadness&command=npx&args=-y,stagmadness-mcp ``` ## MCP tools | Tool | What it does | |---|---| | `search_activities` | Find activities by query, category, price ceiling, or required group size. Returns a `checkout_url` pre-filled with the matches. | | `get_activity` | Get full detail on one activity by slug. | | `list_packages` | List all bundled stag packages. | | `check_availability` | Check whether a given date works for a set of activities at a given group size. Returns alternative dates when unavailable. | | `build_quote` | Compose a quote from selected activities + add-ons (transport, guide). Returns a quote UUID + a `checkout_url` that drops the user straight into the contact form. | Every tool response is grounded in the same DB the web configurator reads from — no separate content trees, no drift. ## Example prompts - *"Plan a 12-person stag do in Budapest with karting and shooting on 2026-07-18."* - *"What activities does Stagmadness offer in Prague for groups under €100 per person?"* - *"Build me a 3-day Krakow stag for 8 lads — heavy on adrenaline, light on partying."* ## Repo layout ``` apps/ web/ Next.js 15 configurator (Vercel) mcp/ MCP server (Railway, stdio + SSE) packages/ db/ Drizzle schema + Neon client shared/ Zod schemas, deep-link codec scripts/ ingest.ts Playwright scraper — re-runnable via `pnpm ingest` sync-tokens.ts Updates Tailwind from design-tokens.json tests/ visual-diff.spec.ts Playwright visual-regression vs design-refs/ ``` ## Development ```bash nvm use pnpm install # 1. Neon Postgres → connection string → .env.local cp .env.example .env.local # Fill in DATABASE_URL + DATABASE_URL_UNPOOLED # 2. Playwright browsers (~150 MB) — only needed for ingest + visual tests pnpm exec playwright install chromium # 3. Apply schema pnpm db:migrate # 4. Scrape stagmadness.com → DB + apps/web/public/scraped/ pnpm ingest # 5. Sync scraped design tokens into Tailwind pnpm sync-tokens # 6. Run the apps pnpm dev:web # http://localhost:3000 pnpm dev:mcp # stdio MCP server MCP_TRANSPORT=sse pnpm dev:mcp # SSE on :8787 (for Railway) # Visual regression (after capturing design-refs/home.png) pnpm test:visual ``` ## Deploy ### apps/web → Vercel ```bash vercel link # link the repo vercel env add DATABASE_URL production vercel env add NEXT_PUBLIC_APP_URL production # set to https://app.stagmadness.com vercel --prod ``` DNS: point `app.stagmadness.com` CNAME → `cname.vercel-dns.com`. ### apps/mcp → Railway ```bash railway login railway init railway link --project <project_id> railway variables set DATABASE_URL=$DATABASE_URL railway variables set WEB_PUBLIC_ORIGIN=https://app.stagmadness.com railway variables set MCP_TRANSPORT=sse railway variables set PORT=8787 railway up ``` DNS: point `mcp.stagmadness.com` CNAME → the Railway-provided hostname. Healthcheck: `https://mcp.stagmadness.com/healthz`. ## AI visibility layer (`/llms.txt`, JSON-LD, sitemap) Auto-generated from the DB once the ingest runs: - `/llms.txt` — short-form entity definition (llmstxt.org spec) - `/llms-full.txt` — every activity with full details + prices + deep links - `/sitemap.xml` — every activity page + alternates for `en`/`hu` - `/robots.txt` — AI crawler allowlist (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot-Extended, CCBot, MistralAI-User, …) - JSON-LD `TouristTrip` + `Offer` schema on every `/[city]/[slug]` page ## Hard rules (from the spec) - All copy, activity data, imagery, design tokens come from **scraping the live site**. No invented content, no placeholders that ship. - Visual fidelity vs stagmadness.com within ~5%, measured by Playwright visual diff (`pnpm test:visual`). - MCP server is **not** a Next.js API route — it runs as a separate Railway process. - No LangChain, no n8n, no orchestration framework. - Hungarian translations come from stagmadness.com only — no algorithmic MT. ## Submitting to MCP directories See [`MCP_SUBMISSIONS.md`](MCP_SUBMISSIONS.md) for the full checklist: Smithery → Claude Desktop community list → mcp.so → glama.ai → npm. ## License MIT — see [LICENSE](LICENSE).