# School Vacation MCP Server

A Model Context Protocol (MCP) server for querying school vacation calendars across Belgium, Netherlands, and Luxembourg (2019-2028).

**Protocol Version**: MCP 2025-06-18
**SDK Version**: @modelcontextprotocol/sdk v1.21.0

## Features

- 🗓️ School vacation calendar data for 2019-2028
- 🌍 Multi-region support: Belgium (Flanders, Wallonia), Netherlands (North, Middle, South), Luxembourg
- 🔧 Three tools: check dates, get vacation periods, list regions
- 🔒 Token-based authentication for production
- 📝 Audit logging for all requests
- 🚀 Multiple deployment modes: stdio, HTTP, Docker
- 🔗 LibreChat integration ready (see [LIBRECHAT_INTEGRATION.md](LIBRECHAT_INTEGRATION.md))

## Quick Start

### Installation

```bash
npm install
npm run build
```

### Development Mode (No Authentication)

```bash
# stdio server (for MCP clients)
npm run dev

# HTTP+MCP server (for REST and MCP clients)
npm run dev:mcp
```

### Production Mode (With Authentication)

```bash
# Generate a secure token
export MCP_AUTH_TOKEN=$(openssl rand -hex 32)

# Or set a custom token
export MCP_AUTH_TOKEN="your-secret-token"

# Start the server
npm run build
npm run start:mcp
```

### Docker Deployment

```bash
# Set auth token
echo "MCP_AUTH_TOKEN=your-secret-token" > .env

# Start with Docker Compose
docker-compose up -d

# Check health
curl http://localhost:3000/health
```

### LibreChat Integration

This server is configured to work with LibreChat on the `LibreChat` Docker network. See the complete integration guide: **[LIBRECHAT_INTEGRATION.md](LIBRECHAT_INTEGRATION.md)**

Quick integration:
```bash
# From LibreChat container, MCP server is accessible at:
http://school-vacation-mcp:3000/mcp
```

## Available Tools

### 1. check_school_vacation

Check if a specific date is a school vacation day in a given region.

**Parameters**:
- `date` (string, required): Date in DD/MM/YYYY format (e.g., "25/12/2024")
- `region` (string, required): One of: flanders, wallonia, north-netherlands, middle-netherlands, south-netherlands, luxembourg

**Example**:
```json
{
  "name": "check_school_vacation",
  "arguments": {
    "date": "25/12/2024",
    "region": "flanders"
  }
}
```

### 2. get_vacation_periods

Get all school vacation periods for a region, optionally filtered by year.

**Parameters**:
- `region` (string, required): Region code
- `year` (number, optional): Year between 2019-2028

**Example**:
```json
{
  "name": "get_vacation_periods",
  "arguments": {
    "region": "flanders",
    "year": 2024
  }
}
```

### 3. get_supported_regions

Get a list of all supported regions.

**Parameters**: None

**Example**:
```json
{
  "name": "get_supported_regions",
  "arguments": {}
}
```

## Server Modes

### 1. stdio Server (Standard MCP)

For integration with MCP clients like Claude Desktop:

```bash
npm run start
```

**Configuration for Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "school-vacation": {
      "command": "node",
      "args": ["/path/to/School_MCP/dist/index.js"]
    }
  }
}
```

### 2. HTTP Server (REST API)

Basic REST API without MCP protocol:

```bash
npm run start:http
```

Endpoints:
- `GET /health` - Health check
- `GET /ping` - Connectivity test
- `POST /tools/*` - Tool execution endpoints

### 3. Combined HTTP+MCP Server (Recommended)

Supports both REST API and MCP JSON-RPC 2.0 protocol:

```bash
npm run start:mcp
```

Endpoints:
- `GET /health` - Health check
- `GET /ping` - Connectivity test
- `POST /mcp` - MCP JSON-RPC 2.0 endpoint (authentication required in production)

## API Examples

### MCP Protocol (JSON-RPC 2.0)

**Initialize**:
```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {"name": "test", "version": "1.0.0"}
    }
  }'
```

**List Tools**:
```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'
```

**Call Tool**:
```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "check_school_vacation",
      "arguments": {
        "date": "25/12/2024",
        "region": "flanders"
      }
    }
  }'
```

## Authentication

### Development Mode

When `MCP_AUTH_TOKEN` is not set, authentication is **disabled**. This is suitable for local development only.

```bash
npm run dev:mcp
# Server runs without authentication
```

### Production Mode

When `MCP_AUTH_TOKEN` is set, all requests to `/mcp` endpoint require authentication:

```bash
export MCP_AUTH_TOKEN="your-secret-token"
npm run start:mcp
```

**Request with authentication**:
```bash
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

**Without authentication** (will return 401 error):
```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Configuration

### Environment Variables

Create a `.env` file based on `.env.example`:

```bash
cp .env.example .env
```

Available variables:
- `MCP_AUTH_TOKEN` - Authentication token (leave empty for dev mode)
- `PORT` - Server port (default: 3000)
- `NODE_ENV` - Environment (development/production)

### Docker Configuration

Edit `docker-compose.yml` to configure the Docker deployment:

```yaml
environment:
  - NODE_ENV=production
  - PORT=3000
  - MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN:-}
```

## MCP 2025-06-18 Compliance

This server is compliant with the MCP 2025-06-18 specification:

✅ **Implemented**:
- JSON-RPC 2.0 protocol
- Protocol version 2025-06-18
- Capability negotiation
- Tool definitions with JSON Schema
- Proper error handling
- Token-based authentication
- Audit logging

⚠️ **Optional** (not implemented):
- Full OAuth 2.0 / RFC 8707 (using basic token auth)
- Elicitation support
- Structured output schemas (Zod validation)
- Rate limiting

See [MCP_COMPLIANCE.md](MCP_COMPLIANCE.md) for detailed compliance analysis.

## Project Structure

```
School_MCP/
├── src/
│   ├── calendar-data.ts        # Core calendar data logic
│   ├── index.ts                # stdio MCP server
│   ├── http-server.ts          # REST API server
│   ├── mcp-http-server.ts      # Combined HTTP+MCP server
│   └── auth.ts                 # Authentication middleware
├── dist/                       # Compiled JavaScript
├── kalender 2019_2028.csv      # Calendar data
├── package.json                # Dependencies
├── tsconfig.json               # TypeScript config
├── Dockerfile                  # Docker build config
├── docker-compose.yml          # Docker Compose config
├── MCP_COMPLIANCE.md          # Compliance report
├── UPGRADE_SUMMARY.md         # Upgrade guide
└── README.md                  # This file
```

## Data Coverage

- **Regions**: Belgium (Flanders, Wallonia), Netherlands (North, Middle, South), Luxembourg
- **Years**: 2019-2028
- **Data includes**: Weekends, holidays, school vacation flags per region

## Development

### Build

```bash
npm run build
```

### Run in development mode

```bash
# stdio server
npm run dev

# HTTP server
npm run dev:http

# Combined HTTP+MCP server
npm run dev:mcp
```

### Testing

```bash
# Test stdio server
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node dist/index.js

# Test HTTP server
npm run dev:mcp &
curl http://localhost:3000/health
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Security Best Practices

🔒 **For Production Deployment**:

1. **Always set `MCP_AUTH_TOKEN`** - Never run without authentication in production
2. **Use HTTPS/TLS** - Encrypt traffic in production
3. **Strong tokens** - Generate with `openssl rand -hex 32`
4. **Rotate tokens** - Change authentication tokens regularly
5. **Monitor logs** - Review audit logs for suspicious activity
6. **Network isolation** - Use firewall rules to restrict access
7. **CORS configuration** - Set specific origins, not wildcard

See [MCP_COMPLIANCE.md](MCP_COMPLIANCE.md#security-best-practices) for detailed security recommendations.

## Troubleshooting

### Port already in use

```bash
# Kill existing node processes
pkill node

# Or use a different port
PORT=3001 npm run start:mcp
```

### Authentication errors

```bash
# Check if token is set
echo $MCP_AUTH_TOKEN

# Test without authentication in dev mode
unset MCP_AUTH_TOKEN
npm run dev:mcp
```

### Docker issues

```bash
# Rebuild container
docker-compose down
docker-compose build --no-cache
docker-compose up

# Check logs
docker-compose logs -f
```

## Upgrade Notes

This server was recently upgraded to MCP 2025-06-18. See [UPGRADE_SUMMARY.md](UPGRADE_SUMMARY.md) for:
- Changes made during upgrade
- Breaking changes from SDK v0.4.0 to v1.21.0
- Migration guide for custom code

## References

- [MCP Specification 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [MCP Documentation](https://modelcontextprotocol.io/docs)

## License

[Your License Here]

## Contributing

[Your Contributing Guidelines Here]

---

**Status**: ✅ Production Ready
**Protocol**: MCP 2025-06-18
**SDK**: v1.21.0
**Last Updated**: 2025-11-07