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)

Quick Start

Installation

npm install
npm run build

Development Mode (No Authentication)

# stdio server (for MCP clients)
npm run dev

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

Production Mode (With Authentication)

# 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

# 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

Quick integration:

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

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

{
  "name": "get_vacation_periods",
  "arguments": {
    "region": "flanders",
    "year": 2024
  }
}

3. get_supported_regions

Get a list of all supported regions.

Parameters: None

Example:

{
  "name": "get_supported_regions",
  "arguments": {}
}

Server Modes

1. stdio Server (Standard MCP)

For integration with MCP clients like Claude Desktop:

npm run start

Configuration for Claude Desktop (claude_desktop_config.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:

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:

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:

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:

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:

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.

npm run dev:mcp
# Server runs without authentication

Production Mode

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

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

Request with authentication:

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

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:

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:

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

npm run build

Run in development mode

# stdio server
npm run dev

# HTTP server
npm run dev:http

# Combined HTTP+MCP server
npm run dev:mcp

Testing

# 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 for detailed security recommendations.

Troubleshooting

Port already in use

# Kill existing node processes
pkill node

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

Authentication errors

# 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

# 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 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
• MCP TypeScript SDK
• MCP Documentation

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