School Vacation MCP Server

# MCP 2025-06-18 Upgrade Summary ## Completed Changes ### ✅ Core Protocol Upgrade 1. **SDK Updated**: `v0.4.0` → `v1.21.0` - File: [package.json](package.json#L17) 2. **Protocol Version**: `2024-11-05` → `2025-06-18` - File: [src/mcp-http-server.ts](src/mcp-http-server.ts#L222) - Now using SDK constant `LATEST_PROTOCOL_VERSION` 3. **API Breaking Changes Fixed** - Updated `Server` constructor to new signature - Files changed: - [src/index.ts](src/index.ts#L12-L22) - [src/mcp-http-server.ts](src/mcp-http-server.ts#L23-L33) ### ✅ Security Enhancements 4. **Authentication Middleware Added** - New file: [src/auth.ts](src/auth.ts) - Token-based authentication via `MCP_AUTH_TOKEN` environment variable - Automatic dev mode when token not set - Audit logging for all MCP requests 5. **HTTP Server Protection** - Applied auth middleware to `/mcp` endpoint - Returns proper JSON-RPC error codes for auth failures - File: [src/mcp-http-server.ts](src/mcp-http-server.ts#L192) ### ✅ Testing & Validation All three server modes tested and working: - ✓ stdio transport (standard MCP) - ✓ HTTP REST API - ✓ Combined HTTP+MCP with JSON-RPC ## Files Changed ``` Modified: - package.json (SDK version) - src/index.ts (Server constructor) - src/mcp-http-server.ts (Protocol version, auth middleware) Added: - src/auth.ts (Authentication & audit logging) - MCP_COMPLIANCE.md (Detailed compliance report) - UPGRADE_SUMMARY.md (This file) ``` ## How to Use ### Development Mode (No Authentication) ```bash npm run build npm run start:mcp ``` ### Production Mode (With Authentication) ```bash export MCP_AUTH_TOKEN="your-secret-token-here" npm run build npm run start:mcp ``` ### Docker Deployment ```bash # Set token in docker-compose.yml or .env file MCP_AUTH_TOKEN=your-secret-token docker-compose up ``` ### Testing with Authentication ```bash # Without auth (will fail if token is set) curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' # With auth curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your-secret-token" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' ``` ## Compliance Status ### ✅ Fully Compliant - JSON-RPC 2.0 protocol - Protocol version 2025-06-18 - Proper capability negotiation - Tool definitions with JSON Schema - Error handling per spec ### ⚠️ Partially Compliant - Basic token authentication (not full OAuth 2.0) - Audit logging (basic implementation) - Tool outputs as text (not structured schemas) ### ❌ Not Implemented - Full OAuth 2.0 / RFC 8707 Resource Indicators - Elicitation (server-initiated user prompts) - Structured output schemas (Zod validation) - Rate limiting - Comprehensive input validation ## Next Steps (Optional) For full production compliance, consider: 1. **Implement OAuth 2.0** if exposing publicly 2. **Add rate limiting** (express-rate-limit) 3. **Migrate to `McpServer`** high-level API for structured outputs 4. **Add input validation** for dates and parameters 5. **Set up monitoring** and alerting ## Documentation - **[MCP_COMPLIANCE.md](MCP_COMPLIANCE.md)** - Detailed compliance analysis with code examples - **[src/auth.ts](src/auth.ts)** - Authentication implementation details - **[MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18)** - Official spec ## Testing Commands ```bash # Build npm run build # 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 start:mcp curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' # Test tool execution curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"check_school_vacation","arguments":{"date":"25/12/2024","region":"flanders"}}}' ``` ## Breaking Changes Alert ⚠️ **Server Constructor API Changed** If you have custom code creating Server instances, update from: ```typescript // OLD (v0.4.0) new Server({ name: 'server', version: '1.0.0', capabilities: { tools: {} } }) ``` To: ```typescript // NEW (v1.21.0) new Server( { name: 'server', version: '1.0.0' }, { capabilities: { tools: {} } } ) ``` ## Security Notice 🔒 **Important**: The authentication implementation is basic token-based auth suitable for internal use or development. For production deployment: 1. Always set `MCP_AUTH_TOKEN` environment variable 2. Use HTTPS/TLS in production 3. Consider implementing full OAuth 2.0 for public-facing deployments 4. Review [MCP_COMPLIANCE.md](MCP_COMPLIANCE.md) security section ## Support - MCP Specification: https://modelcontextprotocol.io - TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk - Issues: Open an issue in your repository --- **Upgrade completed**: 2025-11-07 **SDK Version**: 1.21.0 **Protocol Version**: 2025-06-18 **Status**: ✅ Production Ready (with basic auth)