SevenRooms MCP Server

# SevenRooms MCP Server HTTP-based Model Context Protocol (MCP) server exposing tools and resources for SevenRooms reservations and availability. Uses `StreamableHTTPServerTransport` (HTTP + SSE) instead of stdio. Built with TypeScript and the official `@modelcontextprotocol/sdk`. ## Features - `make_reservations` tool: Create restaurant reservations with guest details - `available_time_slot` resource: Query available reservation time slots - TypeScript + Zod validation - Streamable HTTP transport (JSON responses + optional SSE streaming) - Ready for Azure App Service deployment via GitHub Actions ## Project Structure ``` src/ server.ts # Main MCP HTTP server (/mcp endpoint) tools/makeReservation.ts # make_reservations tool registration resources/available_time_slot.ts # available_time_slot resource registration test/ # Integration tests .env.example # Example environment vars tsconfig.json package.json .github/workflows/azure-deploy.yml # CI/CD workflow to Azure App Service ``` ## Environment Variables | Name | Required | Description | |------|----------|-------------| | SEVENROOMS_API_KEY | Yes | Authentication for SevenRooms API | | SEVENROOMS_API_URL | Yes | Base API URL (e.g. https://api.sevenrooms.com) | | PORT | Optional | Listening port (App Service sets automatically) | Copy `.env.example` to `.env` for local use: ``` SEVENROOMS_API_KEY=your_key_here SEVENROOMS_API_URL=https://api.sevenrooms.com ``` ## Local Development ```bash npm install npm run build npm start # starts HTTP server on PORT (default 3000) # or npm run start:dev # tsx live-reload ``` Server endpoints: - `POST /mcp` – JSON-RPC MCP requests (initialize, tools/list, resources/list, tools/call, etc.) - `GET /mcp` – SSE stream (if using streaming scenarios) - `DELETE /mcp` – Close session (stateful mode; stateless here so optional) - `GET /health` – Simple health probe ### Sample Initialize Request ```bash curl -X POST http://localhost:3000/mcp \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "id":1, "method":"initialize", "params":{ "protocolVersion":"1.0", "clientInfo":{"name":"local-client","version":"1.0"}, "capabilities":{} } }' ``` ### List Tools ```bash curl -X POST http://localhost:3000/mcp \ -H "Accept: application/json" -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' ``` ### Call make_reservations Tool (example) ```bash curl -X POST http://localhost:3000/mcp \ -H "Accept: application/json" -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "id":3, "method":"tools/call", "params":{ "name":"make_reservations", "arguments":{ "date":"2025-12-20", "time":"19:00", "party_size":2, "first_name":"Jane", "last_name":"Doe", "email":"jane@example.com", "phone":"+15555550123" } } }' ``` ## Tools & Resources Details ### Tool: make_reservations Input fields: ``` date, time, party_size, first_name, last_name, email, phone ``` Returns success or detailed error text from SevenRooms API. ### Resource: available_time_slot URI format: ``` available://YYYY-MM-DD/HH:MM/party_size ``` Returns JSON: `{ "available_times": ["18:00", "18:30", ...] }` filtered for entries where `type === 'book`. ## SevenRooms API Endpoints Used - Reservations: `POST {SEVENROOMS_API_URL}/reservations` - Availability: `GET {SEVENROOMS_API_URL}/availability` with query params `date`, `time`, `party_size` Adjust endpoint paths if your SevenRooms account differs. ## Azure App Service Deployment ### 1. Create Azure Resources (CLI Example) ```bash az group create -n sevenrooms-rg -l eastus az appservice plan create -g sevenrooms-rg -n sevenrooms-plan --sku B1 --is-linux az webapp create -g sevenrooms-rg -p sevenrooms-plan -n <WEBAPP_NAME> --runtime "NODE:18-lts" ``` ### 2. Configure App Settings ```bash az webapp config appsettings set -g sevenrooms-rg -n <WEBAPP_NAME> --settings \ SEVENROOMS_API_KEY="<secret>" \ SEVENROOMS_API_URL="https://api.sevenrooms.com" ``` Azure injects `PORT` automatically; do not hardcode it unless needed. ### 3. GitHub Secrets Add in repo Settings → Actions → Secrets: - `AZURE_WEBAPP_NAME` = <WEBAPP_NAME> - `AZURE_WEBAPP_PUBLISH_PROFILE` = publish profile XML pasted verbatim ### 4. Workflow (`azure-deploy.yml`) Steps: checkout, setup Node + cache, install (skip if cache hit), test, build, list build output, deploy. ### 5. Verify Deployment ```bash curl https://<WEBAPP_NAME>.azurewebsites.net/health curl -X POST https://<WEBAPP_NAME>.azurewebsites.net/mcp \ -H "Accept: application/json" -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"1.0","clientInfo":{"name":"remote","version":"1.0"},"capabilities":{}}}' ``` ## Logging & Observability - Use `console.error()` for server logs (stderr captured by App Service). - Add Application Insights: set `APPINSIGHTS_INSTRUMENTATIONKEY` or connection string. - Consider structured logging (JSON) for easier analysis. ## Troubleshooting | Issue | Cause | Fix | |-------|-------|-----| | 404 /mcp | Build missing or wrong start path | Ensure `npm run build` and start uses `node build/server.js` | | 500 SevenRooms errors | Invalid API key or payload | Verify env vars & input fields | | Timeout | Low SKU or network latency | Increase plan size / adjust retry | | Not Acceptable | Missing Accept header | Use `Accept: application/json` (JSON-only enabled) | | Capabilities error | Missing `capabilities` in initialize | Include `"capabilities":{}` | ## Production Recommendations - Use at least B1 plan; scale out based on CPU or HTTP queue length. - Restrict ingress with Access Restrictions or Front Door. - Rotate `SEVENROOMS_API_KEY` regularly. - Implement retries for transient SevenRooms failures (429, 5xx). - Add rate limiting if exposed publicly. ## Contributing 1. Branch from `main` 2. Implement changes in `src/` 3. `npm test && npm run build` 4. PR and merge to trigger deployment ## License MIT (update as needed). ## References - MCP Docs: https://modelcontextprotocol.io/ - SDK Repo: https://github.com/modelcontextprotocol/typescript-sdk - SevenRooms API Docs: (refer to account-specific portal) # SevenRooms MCP Server A Model Context Protocol (MCP) server for managing restaurant reservations with SevenRooms. Built according to the [MCP specification](https://modelcontextprotocol.io/docs/develop/build-server) using TypeScript and the official `@modelcontextprotocol/sdk`. ## Features - **make_reservations** Tool: Create restaurant reservations with guest details - **available_time_slot** Resource: Query available reservation time slots - Fully typed with TypeScript and Zod validation - STDIO-based communication for seamless MCP integration - Azure App Service deployment ready ## Project Structure ``` src/ index.ts # Main MCP server with tools and resources test/ makeReservation.test.js # Unit tests for make_reservations tool availableTimeSlot.test.js # Unit tests for available_time_slot resource .env.example # Example environment variables tsconfig.json # TypeScript configuration package.json # Project dependencies and scripts .github/ workflows/ azure-deploy.yml # GitHub Actions CI/CD workflow ``` ## Prerequisites - Node.js >= 16 - npm - SevenRooms API key and base URL ## Local Development ### 1. Install Dependencies ```bash npm install ``` ### 2. Configure Environment Variables Copy `.env.example` to `.env` and fill in your SevenRooms credentials: ```bash cp .env.example .env ``` Then edit `.env`: ``` SEVENROOMS_API_KEY=your_sevenrooms_api_key_here SEVENROOMS_API_URL=https://api.sevenrooms.com ``` ### 3. Build the Server ```bash npm run build ``` This compiles TypeScript to JavaScript in the `build/` directory. ### 4. Run Tests ```bash npm test ``` Expected output: ``` available_time_slot resource ✓ throws when required fields missing ✓ returns only times with type == "book" make_reservations tool ✓ throws when required fields missing ✓ calls SevenRooms reservations endpoint and returns data 4 passing ``` ### 5. Start the Server For production: ```bash npm start ``` For development with auto-reload: ```bash npm run start:dev ``` The server will start on stdio, ready for MCP clients to connect. ## MCP Tools & Resources ### Tool: make_reservations Makes a reservation at a restaurant through SevenRooms. **Input Schema:** ```json { "date": "YYYY-MM-DD (e.g., 2025-12-25)", "time": "HH:MM (e.g., 19:00)", "party_size": 4, "first_name": "John", "last_name": "Doe", "email": "john@example.com", "phone": "555-1234" } ``` **Response:** Returns the SevenRooms API response with reservation confirmation details (ID, status, etc.). ### Resource: available_time_slot Queries available reservation time slots for a given date, time, and party size. **URI Format:** ``` available://YYYY-MM-DD/HH:MM/party_size ``` **Example:** ``` available://2025-12-25/19:00/4 ``` **Response:** ```json { "available_times": ["18:00", "18:30", "19:00", "19:30"] } ``` The resource automatically filters to only include times where `type === 'book'` from the SevenRooms availability API. ## SevenRooms API Integration The server calls the following SevenRooms endpoints: ### Reservations Endpoint - **URL:** `{SEVENROOMS_API_URL}/reservations` - **Method:** POST - **Auth:** Bearer token in `Authorization` header - **Payload:** ```json { "datetime": "2025-12-25T19:00", "party_size": 4, "guest": { "first_name": "John", "last_name": "Doe", "email": "john@example.com", "phone": "555-1234" } } ``` ### Availability Endpoint - **URL:** `{SEVENROOMS_API_URL}/availability` - **Method:** GET - **Auth:** Bearer token in `Authorization` header - **Query Params:** `date`, `time`, `party_size` **Note:** Adjust endpoints and request payloads if your SevenRooms API account requires different paths or authentication methods. ## Testing The project includes unit tests using Mocha, Chai, and Nock (for HTTP mocking). Run tests: ```bash npm test ``` Tests cover: - Input validation for both tool and resource - Mocked SevenRooms API responses - Filtering logic for available time slots (type === 'book') ## Azure Deployment ### Prerequisites 1. Azure App Service instance 2. GitHub repository with this code 3. Azure publish profile exported ### Setup Steps 1. **Create Azure App Service** - Create a new Web App (Node.js 18 LTS or later) - Copy the publish profile XML 2. **Configure GitHub Secrets** - In your GitHub repository, go to Settings → Secrets and variables → Actions - Add these secrets: - `AZURE_WEBAPP_NAME` — The name of your Azure Web App - `AZURE_WEBAPP_PUBLISH_PROFILE` — The publish profile XML content 3. **Set App Service Configuration** - In Azure portal, go to your App Service → Configuration - Add these application settings: - `SEVENROOMS_API_KEY` — Your SevenRooms API key - `SEVENROOMS_API_URL` — Your SevenRooms API base URL (e.g., `https://api.sevenrooms.com`) - `PORT` — Leave blank to auto-bind (Azure sets this automatically) 4. **Deploy** - Push to `main` branch - GitHub Actions workflow runs automatically - Deployment proceeds to Azure App Service The workflow is defined in `.github/workflows/azure-deploy.yml` and: - Checks out the code - Installs dependencies - Builds the TypeScript - Deploys using the publish profile ### Verify Deployment After deployment, you can: - Check the App Service activity log in Azure portal - Review GitHub Actions workflow run logs on GitHub - Test the server by connecting via MCP client pointing to the deployed instance ## Logging **Important:** The MCP server uses stdio for communication, so logging is restricted: - ✅ Use `console.error()` for logging (writes to stderr, safe for STDIO-based MCP) - ❌ Never use `console.log()` (writes to stdout, corrupts MCP JSON-RPC messages) For production, consider: - Redirecting logs to Application Insights via Azure SDK - Using structured logging libraries that write to stderr - Checking Azure App Service logs in the Azure portal ## Troubleshooting ### "Cannot find module '@modelcontextprotocol/sdk'" - Run `npm install` to ensure all dependencies are installed - Check that `@modelcontextprotocol/sdk` is in `package.json` dependencies ### Build errors (TypeScript) - Ensure Node.js >= 16 is installed - Delete `build/` and `node_modules/` and reinstall: `npm install && npm run build` ### Tests failing - Ensure `.env` file exists (even if empty) or set env vars in your shell before running tests - Check that nock mocks match your actual SevenRooms API requests ### Server not connecting as MCP client - Ensure the server runs without throwing errors: `npm start` (should print to stderr) - Verify the MCP client is correctly configured to call the server ## Contributing 1. Make changes to `src/index.ts` 2. Run tests: `npm test` 3. Build: `npm run build` 4. Commit and push to trigger CI/CD ## License MIT ## References - [Model Context Protocol Documentation](https://modelcontextprotocol.io/) - [MCP SDK for Node.js](https://github.com/modelcontextprotocol/typescript-sdk) - [SevenRooms API Documentation](https://sevenrooms.com/developers)