csnkarthik/seven-rooms-mcp-v2

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

Copy .env.example to .env for local use:

SEVENROOMS_API_KEY=your_key_here
SEVENROOMS_API_URL=https://api.sevenrooms.com

Local Development

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

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

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)

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)

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

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

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

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 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

npm install

2. Configure Environment Variables

Copy .env.example to .env and fill in your SevenRooms credentials:

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

npm run build

This compiles TypeScript to JavaScript in the build/ directory.

4. Run Tests

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:

npm start

For development with auto-reload:

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:

{
  "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:

{
  "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:

  {
    "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:

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
• MCP SDK for Node.js
• SevenRooms API Documentation