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