MCP BSI

Lille read-only MCP-server til dev-brug, så Codex kan slå BSI- og BookingStudio-data op uden projekt-specifik forklaring hver gang.

Plan

1. Holde v1 read-only og stdio-baseret.
2. Samle HTTP-kald i små client-klasser.
3. Samle normalisering i simple transformers.
4. Validere alt tool-input med Zod.
5. Returnere ensartede JSON-resultater med tekst + structured content.
6. Dokumentere setup, Codex-konfiguration og næste skridt.

Filer

• src/server.ts: starter MCP-serveren via stdio og registrerer tools.
• src/config/env.ts: læser og validerer miljøvariabler.
• src/clients/http-client.ts: fælles HTTP-klient med timeout og fejlbehandling.
• src/clients/bsi-client.ts: read-only BSI-kald.
• src/clients/bookingstudio-client.ts: read-only BookingStudio-kald.
• src/transformers/*.ts: normaliserer svar til stabile kontrakter.
• src/tools/*.ts: tool-schemas, tool-handlers og ensartede resultater.
• src/types/*.ts: delte typer.
• src/smoke.ts: simpel lokal smoke-test uden live API-afhængighed.
• .env.example: nødvendige miljøvariabler.
• codex.config.toml.example: forslag til MCP-registrering i Codex.
• AGENTS.global.example.md: forslag til global kontekst til Codex.

Arkitektur

Serveren er bevidst lille:

• Ingen write-tools i v1.
• Ingen caching eller persistence i v1.
• Ingen framework-lag oven på SDK'et.
• Kun clients, transformers og tool-registrering.

Når data findes via BSI, bruges BSI før BookingStudio.

Antagelser i v1

Der er ikke givet konkrete endpoint-kontrakter, så v1 bruger disse standardstier, som kan overskrives i .env:

• BSI:
  • /health
  • /reservations/:reservationId
  • /customers/search
  • /customers/:customerId/reservations
  • /lodgings/:lodgingId
  • /reservations/search
• BookingStudio:
  • /languages
  • /items

Standard query-parametre i v1:

• kundesøgning: q
• reservationssøgning: q, from, to, email

Hvis dine reelle endpoints afviger, justeres kun klientmetoderne og evt. transformer-felter.

Setup

1. Installer dependencies:

npm install

2. Opret lokal env:

cp .env.example .env

3. Tilpas base URLs, tokens og evt. endpoint-stier i .env.

4. Byg projektet:

npm run build

5. Start MCP-serveren:

npm start

Den kompilerede entrypoint er:

node dist/server.js

Tools i v1

bsi_health

Input:

{}

Output:

{
  "ok": true,
  "service": "bsi",
  "environment": "dev",
  "base_url": "https://bsi-dev.example.com/api"
}

bsi_get_reservation

Input:

{
  "reservation_id": 12345
}

bsi_search_customer

Input:

{
  "query": "mail eller telefon eller navn"
}

bsi_customer_reservations

Input:

{
  "customer_id": 1
}

bsi_get_lodging

Input:

{
  "lodging_id": 99
}

bsi_search_reservations

Input:

{
  "query": "3413"
}

eller:

{
  "from": "2026-01-01",
  "to": "2026-01-31",
  "email": "test@example.com"
}

bookingstudio_get_languages

Input:

{}

bookingstudio_get_items

Input:

{}

Smoke-test

Projektet indeholder en lille smoke-test, som ikke rammer live services. Den validerer:

• env-parsing med eksempelværdier
• input-schemas
• transformer-output på kendte prøvepayloads
• reservations-søgevalidering

Kør:

npm run build
npm run smoke

Hvis du vil lave en manuel live-test bagefter, så:

1. sæt rigtige credentials i .env
2. start serveren med npm start
3. registrer den i Codex
4. kald bsi_health
5. kald derefter et kendt opslag som bsi_get_reservation

Codex MCP config

Se codex.config.toml.example.

Eksempel:

[mcp_servers.bsi]
command = "node"
args = ["/mysql/source/mcp/mcp-bsi/dist/server.js"]
cwd = "/mysql/source/mcp/mcp-bsi"

[mcp_servers.bsi.env]
BSI_ENVIRONMENT = "dev"
BSI_BASE_URL = "https://bsi-dev.example.com/api"
BSI_AUTH_TOKEN = "replace-me"
BOOKINGSTUDIO_BASE_URL = "https://bookingstudio-dev.example.com/api"
BOOKINGSTUDIO_AUTH_TOKEN = "replace-me"

Forslag til global ~/.codex/AGENTS.md

Se AGENTS.global.example.md.

TODO v2

• Tilføj write-tools som eksplicit preview/commit-flow.
• Tilføj idempotency og request-correlation på write-kald.
• Tilføj mere præcise transformers for kendte live payloads.
• Tilføj integration-tests mod et dev-sandbox-miljø.
• Tilføj pagination-støtte hvor endpoints kræver det.