Tableau MCP Server

# Phase 4 Implementation Log - Core MCP Tools **Date Started**: November 18, 2025 **Phase**: Phase 4 - Core MCP Tools Implementation **Status**: 🚧 In Progress --- ## Overview Phase 4 focuses on implementing the 6 core MCP tools that provide essential Tableau operations. Each tool includes Zod schema validation, error handling, and LLM-friendly response formatting. --- ## Implementation Plan ### Core Tools to Implement 1. **`tableau_list_workbooks`** - List all accessible workbooks with filtering 2. **`tableau_list_views`** - List views/dashboards in a workbook 3. **`tableau_query_view`** - Export view data as CSV or JSON 4. **`tableau_refresh_extract`** - Trigger data source extract refresh 5. **`tableau_search_content`** - Search across Tableau content 6. **`tableau_get_metadata`** - Get detailed workbook/view metadata ### Implementation Approach For each tool, we will: 1. ✅ Define Zod schema for input parameter validation 2. ✅ Implement tool handler function with TableauClient integration 3. ✅ Format responses for optimal LLM consumption 4. ✅ Add comprehensive error handling 5. ✅ Register tool with MCP server in server.ts --- ## Tool Implementations ### Tool 1: `tableau_list_workbooks` **File**: `src/tools/list-workbooks.ts` **Status**: ⏳ Pending **Purpose**: List all workbooks accessible to the authenticated user with optional filtering **Parameters**: - `projectName` (optional, string): Filter workbooks by project name - `tags` (optional, string[]): Filter workbooks by tags **Returns**: Array of workbooks with: - `id` - Workbook identifier - `name` - Workbook name - `contentUrl` - URL-friendly name - `projectName` - Parent project - `createdAt` - Creation timestamp - `updatedAt` - Last modified timestamp - `webpageUrl` - Full URL to workbook **Implementation Notes**: - Uses `TableauClient.listWorkbooks()` - Supports both filter parameters - Returns comprehensive workbook metadata - Handles empty results gracefully --- ### Tool 2: `tableau_list_views` **File**: `src/tools/list-views.ts` **Status**: ⏳ Pending **Purpose**: List all views (worksheets/dashboards) within a specific workbook **Parameters**: - `workbookId` (required, string): Workbook identifier to query **Returns**: Array of views with: - `id` - View identifier - `name` - View display name - `contentUrl` - URL-friendly name - `viewUrlName` - Full view URL path - `workbookId` - Parent workbook ID **Implementation Notes**: - Uses `TableauClient.listViews()` - Validates workbook ID is provided - Returns all views regardless of type (worksheet/dashboard) - Provides clear error if workbook not found --- ### Tool 3: `tableau_query_view` **File**: `src/tools/query-view.ts` **Status**: ⏳ Pending **Purpose**: Export view data in CSV or JSON format with optional row limiting **Parameters**: - `viewId` (required, string): View identifier to query - `format` (optional, 'csv' | 'json'): Output format (default: 'csv') - `maxRows` (optional, number): Maximum rows to return **Returns**: - For CSV: String with CSV-formatted data - For JSON: Parsed JSON data structure **Implementation Notes**: - Uses `TableauClient.queryViewData()` - Supports both CSV and JSON formats - Implements row limiting via API parameter - Returns raw data for LLM analysis - Handles large datasets appropriately --- ### Tool 4: `tableau_refresh_extract` **File**: `src/tools/refresh-extract.ts` **Status**: ⏳ Pending **Purpose**: Trigger a data source extract refresh (full or incremental) **Parameters**: - `datasourceId` (required, string): Data source identifier - `refreshType` (optional, 'full' | 'incremental'): Type of refresh (default: 'full') **Returns**: Job tracking information with: - `jobId` - Background job identifier - `status` - Current job status - `createdAt` - Job creation time **Implementation Notes**: - Uses `TableauClient.refreshExtract()` - Supports both full and incremental refreshes - Returns job ID for tracking - Note: Does not wait for completion (async operation) - Provides job status if available --- ### Tool 5: `tableau_search_content` **File**: `src/tools/search-content.ts` **Status**: ⏳ Pending **Purpose**: Search across all Tableau content (workbooks, views, data sources, projects) **Parameters**: - `searchTerm` (required, string): Search query text - `contentType` (optional, 'workbook' | 'view' | 'datasource' | 'project'): Filter by content type **Returns**: Array of search results with: - `id` - Content identifier - `name` - Content name - `type` - Content type - `description` - Content description (if available) - `projectName` - Parent project (if applicable) **Implementation Notes**: - Uses `TableauClient.searchContent()` - Searches across multiple content types - Supports filtering by specific content type - Returns unified result format - Handles empty search results --- ### Tool 6: `tableau_get_metadata` **File**: `src/tools/get-metadata.ts` **Status**: ⏳ Pending **Purpose**: Get comprehensive metadata for a workbook or view **Parameters**: - `contentId` (required, string): Workbook or view identifier - `contentType` (required, 'workbook' | 'view'): Type of content **Returns**: Detailed metadata including: - Basic info (id, name, description) - Timestamps (created, updated) - Project information - Owner details - Tags - For workbooks: List of views, data sources - For views: Workbook reference, fields **Implementation Notes**: - Uses `TableauClient.getWorkbookMetadata()` or `TableauClient.getViewMetadata()` - Routes to appropriate method based on contentType - Returns comprehensive metadata object - Includes nested resources (views, data sources) - Handles missing optional fields gracefully --- ## Server Integration ### Tool Registration **File**: `src/server.ts` **Status**: ⏳ Pending **Tasks**: 1. Import all 6 tool handlers 2. Register each tool with the MCP server 3. Provide tool name, description, and schema 4. Connect handler functions 5. Verify tools are discoverable via MCP protocol **Implementation Pattern**: ```typescript server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ { name: "tableau_list_workbooks", description: "List all accessible workbooks...", inputSchema: ListWorkbooksArgsSchema }, // ... other tools ] })); server.setRequestHandler(CallToolRequestSchema, async (request) => { switch (request.params.name) { case "tableau_list_workbooks": return await listWorkbooksHandler(request.params.arguments); // ... other tools } }); ``` --- ## Dependencies ### Required from Previous Phases - ✅ Phase 2: `TableauClient` with all API methods implemented - ✅ Phase 3: MCP server with SSE transport and authentication - ✅ TypeScript build configuration - ✅ Zod schema validation library ### External Dependencies - `@modelcontextprotocol/sdk` - MCP protocol types and schemas - `zod` - Schema validation - `TableauClient` - All 13 API methods available --- ## Testing Plan For each tool, verify: 1. ✅ TypeScript compilation succeeds 2. ✅ Zod schema validates correctly 3. ✅ Tool handler calls TableauClient method 4. ✅ Response format is LLM-friendly 5. ✅ Error handling works for common failures 6. 🔄 Manual testing with real Tableau data (deferred to integration phase) --- ## Success Criteria Phase 4 is complete when: 1. ✅ All 6 core tools are fully implemented 2. ✅ Each tool has Zod schema validation 3. ✅ All tools are registered with MCP server 4. ✅ TypeScript compiles without errors 5. ✅ Code follows established patterns from Phase 2 & 3 6. ✅ Error handling is comprehensive 7. ✅ Responses are formatted for LLM consumption --- ## Timeline **Estimated Time**: 6-8 hours **Started**: November 18, 2025 **Target Completion**: November 18, 2025 --- ## Implementation Log ### Session 1: November 18, 2025 **Time**: Completed **Focus**: Implementing all 6 core MCP tools #### Tasks Completed: - [x] ✅ Created PHASE_4_LOG.md (this file) - [x] ✅ Updated PASS_OFF.md with Phase 4 status - [x] ✅ Implemented `tableau_list_workbooks` tool (98 lines) - [x] ✅ Implemented `tableau_list_views` tool (105 lines) - [x] ✅ Implemented `tableau_query_view` tool (127 lines) - [x] ✅ Implemented `tableau_refresh_extract` tool (130 lines) - [x] ✅ Implemented `tableau_search_content` tool (129 lines) - [x] ✅ Implemented `tableau_get_metadata` tool (152 lines) - [x] ✅ Registered all tools in server.ts - [x] ✅ Verified TypeScript compilation (0 errors) - [x] ✅ Updated PASS_OFF.md with completion status #### Files Modified: - [x] ✅ `src/tools/list-workbooks.ts` (98 lines) - [x] ✅ `src/tools/list-views.ts` (105 lines) - [x] ✅ `src/tools/query-view.ts` (127 lines) - [x] ✅ `src/tools/refresh-extract.ts` (130 lines) - [x] ✅ `src/tools/search-content.ts` (129 lines) - [x] ✅ `src/tools/get-metadata.ts` (152 lines) - [x] ✅ `src/server.ts` (added 150+ lines of tool registration code) - [x] ✅ `PASS_OFF.md` #### Implementation Summary: **Total Lines of Code**: ~1,000 lines across 6 tool files + server integration **Tool 1: tableau_list_workbooks** (98 lines) - Zod schema with optional projectName and tags filters - Returns workbook list with comprehensive metadata - Formatted summary + raw JSON for LLM consumption - Handles empty results gracefully **Tool 2: tableau_list_views** (105 lines) - Zod schema requiring workbookId - Lists all views within a specific workbook - Helpful error messages for missing workbooks - Formatted summary + raw JSON output **Tool 3: tableau_query_view** (127 lines) - Zod schema with viewId, format (csv/json), maxRows - Exports view data in CSV or JSON format - Row counting and limit reporting - Timeout and large dataset handling **Tool 4: tableau_refresh_extract** (130 lines) - Zod schema with datasourceId and refreshType (full/incremental) - Triggers background extract refresh job - Returns job tracking information - Permission and extract validation errors **Tool 5: tableau_search_content** (129 lines) - Zod schema with searchTerm and optional contentType filter - Searches across all Tableau content types - Results grouped by type for readability - Handles empty search results **Tool 6: tableau_get_metadata** (152 lines) - Zod schema with contentId and contentType (workbook/view) - Routes to appropriate metadata method - Comprehensive metadata formatting (basic info, timestamps, project, owner, tags) - Workbook-specific: views and data sources list - View-specific: parent workbook reference **Server Integration** (150+ lines added to server.ts) - Imported all 6 tool handlers and metadata - Created toolRegistry array with all tools - Implemented createTableauClient() factory function - Registered ListToolsRequestSchema handler - Registered CallToolRequestSchema handler with switch routing - Added authentication per request - Comprehensive error handling with McpError - Updated startup banner to show 6 tools #### Technical Highlights: - ✅ All tool implementations follow established patterns from Phase 2 & 3 - ✅ Each tool includes comprehensive JSDoc documentation - ✅ Zod schemas provide runtime validation for all parameters - ✅ Error handling includes user-friendly messages for common failures - ✅ Responses formatted for optimal LLM consumption (summary + raw JSON) - ✅ Type safety with TypeScript throughout - ✅ Consistent error handling patterns - ✅ Logging integration for all operations #### Compilation Results: ```bash npm run build ✅ SUCCESS: TypeScript compilation completed with 0 errors ✅ All 6 tools compile successfully ✅ Server integration compiles successfully ✅ No type errors, no linting issues ``` --- ## Next Phase **Phase 5**: Advanced MCP Tools Implementation (Ready to Start) - Tool 7: `tableau_get_dashboard_filters` - Tool 8: `tableau_export_dashboard_pdf` - Tool 9: `tableau_export_dashboard_pptx` Phase 5 can begin immediately - all dependencies from Phase 4 are complete. --- ## Phase 4 Success Criteria - ALL MET ✅ 1. ✅ All 6 core tools are fully implemented 2. ✅ Each tool has Zod schema validation 3. ✅ All tools are registered with MCP server 4. ✅ TypeScript compiles without errors 5. ✅ Code follows established patterns from Phase 2 & 3 6. ✅ Error handling is comprehensive 7. ✅ Responses are formatted for LLM consumption --- **Status**: ✅ Phase 4 COMPLETE - Core Tools Successfully Implemented **Completed**: November 18, 2025 **Total Implementation Time**: ~2-3 hours **Total Lines of Code**: ~1,000 lines **Tools Implemented**: 6 core MCP tools **TypeScript Errors**: 0 **Ready for**: Phase 5 (Advanced Tools)