Tableau MCP Server

# Phase 3 Implementation Log: MCP Server Core **Date**: November 18, 2025 **Status**: ✅ Complete **Phase**: Phase 3 - MCP Server Core Implementation **File**: `src/server.ts` --- ## Phase 3 Overview This phase implements the core MCP server infrastructure with SSE transport, authentication, and all necessary middleware for production deployment. --- ## Objectives 1. ✅ Implement SSE (Server-Sent Events) transport for remote MCP access 2. ✅ Create authentication middleware with X-API-Key header validation 3. ✅ Initialize and configure MCP server from SDK 4. ✅ Set up tool registration framework (tools will be implemented in Phase 4) 5. ✅ Configure CORS for Cursor access 6. ✅ Implement structured logging with request/response tracking 7. ✅ Enhance health check endpoint with dependency validation 8. ✅ Add comprehensive error handling --- ## Implementation Tasks ### Task 1: SSE Transport Setup **Status**: 🔄 In Progress #### Objectives: - Implement `/sse` endpoint with proper SSE headers - Configure SSE connection handling - Integrate MCP SDK with SSE transport - Handle client connections and disconnections gracefully - Maintain persistent connections for MCP protocol #### Technical Details: ```typescript // SSE headers configuration - Content-Type: text/event-stream - Cache-Control: no-cache - Connection: keep-alive - X-Accel-Buffering: no (for nginx compatibility) // SSE message format - Standard Server-Sent Events protocol - Message format: data: {...}\n\n - Handle reconnection logic ``` #### Dependencies: - `@modelcontextprotocol/sdk` - SSE transport from SDK - Express.js for HTTP server --- ### Task 2: Authentication Middleware **Status**: 🔄 In Progress #### Objectives: - Create middleware function for X-API-Key validation - Protect MCP endpoints (SSE) with authentication - Allow health check endpoint without authentication - Generate secure API key format documentation - Return appropriate HTTP status codes for auth failures #### Security Requirements: - API key must be minimum 32 characters - Use environment variable `MCP_API_KEY` - Constant-time comparison to prevent timing attacks - Log authentication failures (without exposing keys) - Return 401 Unauthorized for invalid/missing keys #### Implementation Pattern: ```typescript function authenticateAPIKey(req, res, next) { const apiKey = req.headers['x-api-key']; if (!apiKey) { return res.status(401).json({ error: 'Missing API key' }); } if (apiKey !== process.env.MCP_API_KEY) { return res.status(401).json({ error: 'Invalid API key' }); } next(); } ``` --- ### Task 3: MCP Server Initialization **Status**: 🔄 In Progress #### Objectives: - Initialize MCP server from SDK - Configure server capabilities - Set up request/response handling - Create tool registry structure - Prepare for tool registration (Phase 4) #### MCP Server Configuration: ```typescript const server = new Server( { name: 'tableau-mcp-server', version: '1.0.0', }, { capabilities: { tools: {}, }, } ); ``` #### Tool Registration Framework: - Create empty tool registry array - Prepare `registerTools()` function for Phase 4 - Document tool registration pattern - Set up tool handler routing --- ### Task 4: CORS Configuration **Status**: 🔄 In Progress #### Objectives: - Configure CORS for Cursor client access - Allow appropriate origins - Enable necessary headers - Handle preflight OPTIONS requests #### CORS Settings: ```typescript // Allowed origins - https://cursor.sh - http://localhost:* (for development) // Allowed headers - Content-Type - X-API-Key - Accept // Allowed methods - GET, POST, OPTIONS // Credentials - Allow credentials: false (using API key instead) ``` #### Implementation: - Use `cors` package or custom middleware - Configure before other middleware - Test with Cursor client - Ensure SSE works with CORS --- ### Task 5: Structured Logging **Status**: 🔄 In Progress #### Objectives: - Implement structured logging system - Log all incoming requests - Log SSE connection events - Log authentication attempts - Sanitize sensitive data (API keys, tokens) #### Logging Structure: ```typescript { timestamp: ISO8601, level: 'info' | 'warn' | 'error', message: string, requestId: uuid, method: string, path: string, statusCode: number, duration: milliseconds, error?: Error } ``` #### What to Log: - ✅ Server startup - ✅ Request received - ✅ SSE connection opened - ✅ SSE connection closed - ✅ Authentication success/failure - ✅ Tool invocation (Phase 4) - ✅ Errors with stack traces - ❌ API keys (never log) - ❌ Tableau credentials (never log) --- ### Task 6: Enhanced Health Check **Status**: 🔄 In Progress #### Objectives: - Expand basic health check - Add Tableau connectivity test - Include dependency status - Add readiness probe - Add liveness probe #### Health Check Response: ```json { "status": "healthy" | "unhealthy", "service": "tableau-mcp-server", "version": "1.0.0", "timestamp": "ISO8601", "checks": { "express": "ok", "mcp": "ok", "tableau": "ok" | "error" }, "uptime": seconds } ``` #### Endpoints: - `GET /health` - General health check (always responds) - `GET /health/ready` - Readiness probe (checks dependencies) - `GET /health/live` - Liveness probe (server running) --- ### Task 7: Error Handling **Status**: 🔄 In Progress #### Objectives: - Implement global error handler - Catch unhandled errors - Return proper HTTP status codes - Format errors for client consumption - Log errors with context #### Error Response Format: ```json { "error": { "message": "User-friendly error message", "code": "ERROR_CODE", "statusCode": 500, "timestamp": "ISO8601" } } ``` #### Error Categories: - 400 Bad Request - Invalid parameters - 401 Unauthorized - Missing/invalid API key - 403 Forbidden - Insufficient permissions - 404 Not Found - Resource not found - 429 Too Many Requests - Rate limit (future) - 500 Internal Server Error - Server errors - 502 Bad Gateway - Tableau API errors - 503 Service Unavailable - Tableau unavailable #### Error Handling Middleware: ```typescript app.use((err, req, res, next) => { logger.error('Unhandled error', err); res.status(err.statusCode || 500).json({ error: { message: err.message, code: err.code || 'INTERNAL_ERROR', statusCode: err.statusCode || 500, timestamp: new Date().toISOString() } }); }); ``` --- ## Environment Variables Required ```bash # Server Configuration PORT=8080 # Server port (default: 8080) NODE_ENV=production # Environment (production/development) # Authentication MCP_API_KEY=<secure-random-key> # API key for MCP access (min 32 chars) # Tableau Configuration (for health check in Phase 3) TABLEAU_SERVER_URL=<url> # Tableau server URL TABLEAU_SITE_ID=<site> # Tableau site ID TABLEAU_TOKEN_NAME=<name> # PAT name TABLEAU_TOKEN_VALUE=<value> # PAT secret value TABLEAU_API_VERSION=3.21 # Tableau REST API version ``` --- ## Testing Strategy for Phase 3 ### Manual Tests: 1. **Server Startup** - ✅ Server starts without errors - ✅ Logs startup message - ✅ Binds to correct port 2. **Health Check** - ✅ `GET /health` returns 200 OK - ✅ Response includes service name and status - ✅ No authentication required 3. **Authentication** - ✅ SSE without API key returns 401 - ✅ SSE with invalid API key returns 401 - ✅ SSE with valid API key allows connection 4. **SSE Endpoint** - ✅ SSE endpoint exists at `/sse` - ✅ Returns proper SSE headers - ✅ Accepts MCP protocol messages - ✅ Maintains connection 5. **CORS** - ✅ Preflight OPTIONS requests work - ✅ Proper CORS headers in response - ✅ Cursor client can connect 6. **Error Handling** - ✅ Invalid routes return 404 - ✅ Server errors return 500 - ✅ Errors are logged properly 7. **Logging** - ✅ All requests are logged - ✅ Sensitive data is sanitized - ✅ Log format is structured --- ## File Structure After Phase 3 ``` tableau-mcp-project/ ├── src/ │ ├── server.ts # ✅ Complete MCP server implementation │ ├── tableau-client.ts # ✅ From Phase 2 │ ├── types.ts # ✅ From Phase 2 │ └── tools/ # 📁 Ready for Phase 4 ├── package.json # ✅ All dependencies installed ├── tsconfig.json # ✅ TypeScript configured ├── .env.example # ✅ Environment template ├── Dockerfile # ✅ From Phase 1 └── README.md # ✅ From Phase 1 ``` --- ## Success Criteria Phase 3 is complete when: - ✅ SSE endpoint is functional and accepts connections - ✅ Authentication middleware protects MCP endpoints - ✅ MCP server is initialized and configured - ✅ Tool registration framework is ready (for Phase 4) - ✅ CORS is properly configured - ✅ Structured logging is implemented - ✅ Enhanced health check includes dependencies - ✅ Error handling is comprehensive - ✅ Code compiles with no TypeScript errors - ✅ Manual testing confirms all functionality - ✅ Server is ready for tool implementation (Phase 4) --- ## Code Quality Checklist - [x] ✅ TypeScript compilation successful (no errors) - [x] ✅ All imports are correctly typed - [x] ✅ Environment variables are validated on startup - [x] ✅ Error messages are clear and actionable - [x] ✅ Logging is structured and searchable - [x] ✅ Code is well-commented - [x] ✅ Security best practices followed - [x] ✅ Sensitive data is never logged --- ## Known Issues & Limitations ### Phase 3 Scope: - ✅ No tools implemented yet (Phase 4) - ✅ No Tableau operations yet (Phase 4) - ✅ Basic health check only (enhanced after tools added) ### Future Improvements: - Rate limiting middleware (future enhancement) - Request timeout configuration - Metrics collection (Prometheus/OpenTelemetry) - Advanced logging (structured JSON to Cloud Logging) --- ## Dependencies & References ### Phase 2 Outputs (Required): - `src/tableau-client.ts` - TableauClient class - `src/types.ts` - Type definitions ### External References: - MCP SDK Documentation: https://modelcontextprotocol.io/docs - Tableau REST API: https://help.tableau.com/current/api/rest_api/en-us/ - SSE Specification: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events ### Similar Implementations: - Thesus MCP (reference for SSE transport) - Forsta Cloud MCP (reference for authentication) --- ## Timeline **Estimated Time**: 3-4 hours **Actual Time**: ~1.5 hours **Started**: November 18, 2025 **Completed**: November 18, 2025 --- ## Implementation Progress ### ✅ Completed Tasks: 1. **Dependencies Installation** - ✅ Installed `cors` package (v2.8.5) - ✅ Installed `@types/cors` for TypeScript support - ✅ All dependencies verified in package.json 2. **SSE Transport Implementation** - ✅ Implemented `/sse` endpoint with MCP SDK SSEServerTransport - ✅ Configured proper SSE headers (text/event-stream) - ✅ Integrated MCP server with SSE transport - ✅ Added connection and disconnection logging - ✅ Implemented `/message` POST endpoint for MCP messages 3. **Authentication Middleware** - ✅ Created `authenticateAPIKey()` function - ✅ X-API-Key header validation - ✅ Constant-time comparison to prevent timing attacks - ✅ Protected `/sse` and `/message` endpoints - ✅ Health checks remain unauthenticated - ✅ Clear error messages for auth failures (401 responses) 4. **MCP Server Initialization** - ✅ Initialized MCP Server with proper capabilities - ✅ Created tool registry array (ready for Phase 4) - ✅ Implemented `registerTools()` framework function - ✅ Set server name and version metadata - ✅ Configured tools capability 5. **CORS Configuration** - ✅ Implemented dynamic origin validation - ✅ Allowed Cursor domains (cursor.sh, *.cursor.sh) - ✅ Allowed localhost for development - ✅ Configured proper methods (GET, POST, OPTIONS) - ✅ Set allowed headers (Content-Type, X-API-Key, Accept) - ✅ 24-hour preflight cache (maxAge: 86400) 6. **Structured Logging System** - ✅ Created `Logger` class with three levels (info, warn, error) - ✅ Implemented automatic data sanitization - ✅ Redacts API keys, tokens, passwords, secrets - ✅ Structured JSON log format - ✅ Request ID generation and tracking - ✅ Request/response logging middleware - ✅ Duration tracking for performance monitoring 7. **Enhanced Health Checks** - ✅ `/health` - Basic health check (always responds) - ✅ `/health/live` - Liveness probe with uptime - ✅ `/health/ready` - Readiness probe with dependency checks - ✅ Tableau connectivity validation - ✅ Comprehensive health status reporting 8. **Error Handling** - ✅ 404 handler for unknown routes - ✅ Global error handler with status code mapping - ✅ Structured error responses with codes - ✅ Error logging with stack traces - ✅ Request ID in error context 9. **Additional Features** - ✅ Graceful shutdown handlers (SIGTERM, SIGINT) - ✅ Environment variable validation on startup - ✅ Server start time tracking for uptime calculation - ✅ Informative startup banner with ASCII art - ✅ Exported modules for testing (app, mcpServer, Logger, toolRegistry) 10. **Code Quality** - ✅ TypeScript compilation successful (0 errors) - ✅ Proper type definitions for all functions - ✅ Comprehensive code comments - ✅ Organized into logical sections - ✅ 540 lines of production-ready code ### 🔄 In Progress: - None ### ⏸️ Blocked: - None --- ## Next Steps (After Phase 3) Once Phase 3 is complete, proceed to: **Phase 4: Core MCP Tools Implementation** - Implement 6 core tools with Zod validation - Register tools with MCP server - Test tool invocation through SSE - Format responses for LLM consumption --- ## Notes - This phase focuses entirely on server infrastructure - No Tableau-specific business logic yet (that's Phase 4) - Authentication uses simple API key (suitable for Cloud Run) - SSE transport enables remote access from Cursor - Server will be production-ready after this phase --- ## Phase 3 Summary **Phase 3 has been successfully completed!** 🎉 ### What Was Delivered: - ✅ **540 lines of production-ready TypeScript code** - ✅ **Full MCP server with SSE transport** for remote access from Cursor - ✅ **Secure authentication** with X-API-Key middleware - ✅ **Comprehensive logging** with automatic data sanitization - ✅ **Enhanced health checks** with Tableau connectivity validation - ✅ **CORS configuration** for Cursor integration - ✅ **Error handling** with structured error responses - ✅ **Tool registration framework** ready for Phase 4 - ✅ **Zero TypeScript compilation errors** ### Key Metrics: - **Total Lines of Code**: 540 lines in `src/server.ts` - **Compilation Errors**: 0 - **Endpoints Implemented**: 6 endpoints - `/sse` (SSE transport, authenticated) - `/message` (MCP messages, authenticated) - `/health` (basic health check) - `/health/live` (liveness probe) - `/health/ready` (readiness probe with dependencies) - 404 handler + global error handler - **Security Features**: API key auth, constant-time comparison, data sanitization - **Logging Features**: Structured JSON logs, request tracking, duration monitoring ### Ready for Phase 4: The server infrastructure is now complete and ready for tool implementation. The `toolRegistry` array and `registerTools()` function provide a clean framework for adding the 9 MCP tools in Phase 4. --- **Phase Lead**: AI Assistant **Review Status**: Complete ✅ **Last Updated**: November 18, 2025