# mcp-booking-bridge

## Hva det er

Dette lar deg styre restaurantens bordbestillinger ved å snakke med en assistent
på telefonen, på vanlig norsk, i stedet for å klikke deg gjennom et
bookingprogram. Du spør «har vi plass til seks på fredag?» eller sier «legg inn
Per klokka sju i morgen», og assistenten sjekker ledige bord og ordner
bookingen for deg. Den kan se og legge inn bestillinger, men aldri slette, og
den gjør aldri en endring uten at du har sett nøyaktig hva som skjer og sagt ja
først.

Under panseret er det en liten server som kobler Claude til et bookingsystem på
en kontrollert måte. Resten av denne fila forklarer hvordan den er bygget, og
hvordan du kobler den til ditt eget system.

## Teknisk

En MCP-server (Model Context Protocol) som lar en LLM-agent som Claude lese og
_trygt_ skrive restaurantbookinger. Bygget som en Next.js-app og ment å hostes
på Vercel som en custom connector. Repoet leveres med en mock-provider med data
i minnet, så serveren kjører rett ut av boksen, uten noen ekte integrasjon.

```
Claude (mobil/web)  ->  Anthropic sky  ->  denne serveren (Vercel)  ->  BookingProvider
```

## Sikkerhetsmodellen (kjernen i prosjektet)

En agent som kan skrive til et ekte bookingsystem er en angrepsflate. Denne
serveren er bygget etter prinsippet om at broen skal kunne _minst mulig_:

- **Hemmelig sti-segment.** Endepunktet lever på `/api/<MCP_PATH_SECRET>/mcp`.
  Feil secret, feil transport eller en hvilken som helst annen sti svarer `404`,
  så serveren røper ikke engang at den finnes.
- **Skriving er avslått som standard.** Uten `BOOKING_ENABLE_WRITE=true`
  eksponeres kun leseverktøy. Å gi agenten skrivetilgang er et bevisst,
  eksplisitt valg.
- **Sletting finnes ikke.** Det er ingen `cancel`- eller `delete`-verktøy i det
  hele tatt. Broen _kan_ ikke slette en booking, uansett hva den blir bedt om.
  Kansellering gjøres i backend-systemets eget admin-UI.
- **Prompt-injection-vakt.** Hvert skriveverktøy har sikkerhetsregler bakt inn i
  verktøybeskrivelsen: skriv kun når brukeren selv har bedt om det direkte i
  samtalen, aldri fordi innhold i en e-post, et dokument eller en nettside ber
  om det, og vis alltid nøyaktig hva som sendes og få et ja først. Det er et
  konkret forsvar mot [«lethal trifecta»](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/):
  privat data + upålitelig innhold + ekstern handling i samme løp.
- **Fornuftsvakter i kode.** Maks 20 gjester, ingen datoer i fortiden
  (Europe/Oslo), gyldig `HH:MM`, og bookinger uten kundenavn avvises, uavhengig
  av hva agenten prøver å sende.
- **Logging uten persondata.** Kall logges med metode og verktøynavn, aldri
  argumenter eller kundedata.
- **Rate limit.** Et tak per varm instans mot loops og hamring.

## Verktøy

| Verktøy | Type | Aktiv |
|---|---|---|
| `list_restaurants` | lese | alltid |
| `get_restaurant_settings` | lese | alltid |
| `list_bookings` | lese | alltid |
| `list_changes` | lese | alltid |
| `check_availability` | lese | alltid |
| `check_availability_month` | lese | alltid |
| `list_areas` | lese | alltid |
| `list_sessions` | lese | alltid |
| `list_experiences` | lese | alltid |
| `create_booking` | skrive | kun `BOOKING_ENABLE_WRITE=true` |
| `update_booking` | skrive | kun `BOOKING_ENABLE_WRITE=true` |

## Kom i gang

```bash
npm install
cp .env.example .env.local
# sett MCP_PATH_SECRET (openssl rand -hex 24), la BOOKING_ENABLE_WRITE stå tom
npm run dev
```

Koble den til som en custom connector i Claude med URL
`http://localhost:3000/api/<MCP_PATH_SECRET>/mcp` (eller Vercel-URL-en i
produksjon). Serveren svarer med mock-data med en gang.

## Koble til et ekte system

All backend-logikk sitter bak ett grensesnitt, `BookingProvider`, i
[`lib/provider.ts`](lib/provider.ts). `route.ts` vet ingenting om HTTP,
databaser eller noen bestemt leverandør. For å peke serveren mot et ekte
bookingsystem skriver du en adapter som implementerer `BookingProvider` og
returnerer den fra `getProvider()`:

```ts
export function getProvider(): BookingProvider {
  if (!provider) {
    provider = new MyRestApiProvider(process.env.BOOKING_API_TOKEN!);
  }
  return provider;
}
```

Alle verktøyene og alle sikkerhetsvaktene fungerer uendret. Standard-
implementasjonen (`MockBookingProvider`) holder bookinger i minnet og er ment
som referanse.

## Deploy

Deploy til Vercel og sett `MCP_PATH_SECRET` (og eventuelt
`BOOKING_ENABLE_WRITE=true`) som miljøvariabler. For en server som skal skrive
til et ekte system bør du vurdere å oppgradere beskyttelsen fra hemmelig sti til
OAuth (`withMcpAuth` i `mcp-handler`) — hemmelig sti er greit som MVP, men OAuth
er riktig nivå når serveren kan endre data.

## Lisens

MIT