Connect Oracle OPERA to Claude

mkdir opera-mcp
cd opera-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod

{
  "name": "opera-mcp",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.22.0"
  }
}

#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const GATEWAY = process.env.OHIP_GATEWAY_URL;   // e.g. https://your-env.hospitality-api.us-....oraclecloud.com
const CLIENT_ID = process.env.OHIP_CLIENT_ID;
const CLIENT_SECRET = process.env.OHIP_CLIENT_SECRET;
const APP_KEY = process.env.OHIP_APP_KEY;
const HOTEL_ID = process.env.OHIP_HOTEL_ID;
const SCOPE = process.env.OHIP_SCOPE;           // assigned scope for the client_credentials grant

for (const [name, v] of Object.entries({ GATEWAY, CLIENT_ID, CLIENT_SECRET, APP_KEY, HOTEL_ID })) {
  if (!v) { console.error(`Missing OHIP_${name} environment variable`); process.exit(1); }
}

// --- OAuth: POST {gateway}/oauth/v1/tokens, Basic auth + x-app-key ---
let cachedToken = null;
let tokenExpiresAt = 0;

async function getToken() {
  if (cachedToken && Date.now() < tokenExpiresAt - 60_000) return cachedToken;

  const body = new URLSearchParams({ grant_type: "client_credentials" });
  if (SCOPE) body.set("scope", SCOPE);

  const basic = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64");
  const res = await fetch(`${GATEWAY}/oauth/v1/tokens`, {
    method: "POST",
    headers: {
      Authorization: `Basic ${basic}`,
      "x-app-key": APP_KEY,
      "Content-Type": "application/x-www-form-urlencoded",
      Accept: "application/json",
    },
    body,
  });

  if (!res.ok) {
    throw new Error(`OHIP token request failed ${res.status}: ${await res.text()}`);
  }
  const data = await res.json();
  cachedToken = data.access_token;
  tokenExpiresAt = Date.now() + (data.expires_in ? data.expires_in * 1000 : 50 * 60_000);
  return cachedToken;
}

async function ohipGet(path, params = {}) {
  const token = await getToken();
  const url = new URL(`${GATEWAY}${path}`);
  for (const [k, v] of Object.entries(params)) {
    if (v !== undefined && v !== null && v !== "") url.searchParams.append(k, String(v));
  }
  const res = await fetch(url.toString(), {
    headers: {
      Authorization: `Bearer ${token}`,
      "x-app-key": APP_KEY,
      "x-hotelid": HOTEL_ID,
      Accept: "application/json",
    },
  });
  if (!res.ok) {
    throw new Error(`OHIP API ${res.status} on ${path}: ${await res.text()}`);
  }
  return res.json();
}

const server = new McpServer({ name: "opera-cloud", version: "1.0.0" });

// Tool 1: Housekeeping room status overview
server.tool(
  "get-housekeeping-overview",
  "Get the housekeeping status of rooms at the property: clean, dirty, inspected, pickup, plus front office status and room assignment. Supports filtering by housekeeping or front office room status. Use this for any 'what state are the rooms in' question.",
  {
    housekeepingRoomStatus: z.string().optional()
      .describe("Optional filter, e.g. Clean, Dirty, Inspected, Pickup"),
    limit: z.number().optional().describe("Max rooms to return (default 50)"),
  },
  async ({ housekeepingRoomStatus, limit }) => {
    const data = await ohipGet(`/hsk/v1/hotels/${HOTEL_ID}/housekeepingOverview`, {
      housekeepingRoomStatus,
      limit: limit ?? 50,
    });
    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
  }
);

// Tool 2: Housekeeping vs front office discrepancies
server.tool(
  "get-room-discrepancies",
  "List rooms where the housekeeping status does not match the front office status (skips and sleeps). These are the rooms most likely to cause a bad check-in. Returns the discrepancy type per room.",
  {},
  async () => {
    const data = await ohipGet(`/hsk/v1/hotels/${HOTEL_ID}/housekeepingDiscrepancies`);
    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
  }
);

// Tool 3: Out of order rooms
server.tool(
  "get-out-of-order-rooms",
  "List rooms currently Out of Order at the property, with reason codes and date ranges. Out of Order rooms are removed from inventory entirely.",
  {},
  async () => {
    const data = await ohipGet(`/hsk/v1/hotels/${HOTEL_ID}/rooms/outOfOrderRooms`);
    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
  }
);

// Tool 4: Search reservations
server.tool(
  "search-reservations",
  "Search reservations at the property by arrival date range. Returns guest, room type, status, and stay dates. Use with get-housekeeping-overview to compare arrivals against room readiness.",
  {
    arrivalStartDate: z.string().optional().describe("YYYY-MM-DD, start of arrival window"),
    arrivalEndDate: z.string().optional().describe("YYYY-MM-DD, end of arrival window"),
    limit: z.number().optional().describe("Max reservations to return (default 50)"),
  },
  async ({ arrivalStartDate, arrivalEndDate, limit }) => {
    const data = await ohipGet(`/rsv/v1/hotels/${HOTEL_ID}/reservations`, {
      arrivalStartDate,
      arrivalEndDate,
      limit: limit ?? 50,
    });
    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

~/Library/Application Support/Claude/claude_desktop_config.json

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "opera-cloud": {
      "command": "node",
      "args": ["/absolute/path/to/opera-mcp/index.js"],
      "env": {
        "OHIP_GATEWAY_URL": "https://your-environment-gateway-url",
        "OHIP_CLIENT_ID": "your_client_id",
        "OHIP_CLIENT_SECRET": "your_client_secret",
        "OHIP_APP_KEY": "your_application_key",
        "OHIP_HOTEL_ID": "YOURHOTELCODE",
        "OHIP_SCOPE": "your_assigned_scope"
      }
    }
  }
}