Tempo Filler MCP Server

# TempoFiller MCP Server - Project Understanding ## Overview TempoFiller is a Model Context Protocol (MCP) server that bridges AI assistants with Tempo (JIRA's time tracking plugin), enabling automated worklog management. Built in TypeScript, it provides tools for retrieving, creating, and managing time entries through AI interfaces like Claude and GitHub Copilot. ## Architecture & Components ### Core Architecture - **Language**: TypeScript with ES modules - **MCP Framework**: `@modelcontextprotocol/sdk` v1.17.0+ - **Transport**: stdio (primary communication method) - **Authentication**: Personal Access Token (PAT) with Bearer token authentication - **API Integration**: Tempo Timesheets API v4 and JIRA REST API ### Project Structure ``` src/ ├── index.ts # MCP server entry point & request handlers ├── tempo-client.ts # Tempo/JIRA API client with authentication ├── tools/ # MCP tool implementations │ ├── get-worklogs.ts # Retrieve worklogs with filtering │ ├── post-worklog.ts # Create single worklog entry │ ├── bulk-post.ts # Create multiple worklogs concurrently │ ├── delete-worklog.ts # Remove worklog entries │ └── index.ts # Tool exports └── types/ # TypeScript definitions ├── tempo.ts # Tempo API response structures ├── mcp.ts # MCP validation schemas with Zod └── index.ts # Type exports ``` ## Key Features & Capabilities ### 1. **Worklog Retrieval** (`get_worklogs`) - Fetch worklogs for authenticated user by date range - Optional filtering by specific JIRA issue - Automatic user authentication and server-side filtering - Supports both Tempo search API and JIRA worklog API fallback ### 2. **Single Worklog Creation** (`post_worklog`) - Create individual worklog entries with automatic issue resolution - Convert JIRA issue keys (PROJ-1234) to numerical IDs for Tempo API - Automatic worker assignment using authenticated user - Support for billable/non-billable time tracking ### 3. **Bulk Worklog Operations** (`bulk_post_worklogs`) - Concurrent creation of multiple worklog entries using Promise.all() - Intelligent issue caching to minimize API calls - Daily summary reporting with pivot table formatting - Error handling with partial success support (up to 100 entries) ### 4. **Worklog Management** (`delete_worklog`) - Remove existing worklog entries by Tempo worklog ID - Confirmation messages with deletion timestamps - Appropriate error handling for missing or unauthorized entries ### 5. **Resource Providers** - Recent issues access for quick reference - User worklog data for specific time periods - JSON-formatted data suitable for AI analysis ### 6. **Prompt Templates** - Worklog analysis prompts for time tracking insights - Bulk entry assistance for complex time filling scenarios ## Technical Implementation Details ### Authentication System - **PAT-based Authentication**: Uses JIRA Personal Access Tokens for secure API access - **Current User Detection**: Automatic resolution of authenticated user identity - **Token Validation**: Built-in connectivity testing and error handling - **Environment Variables**: `TEMPO_BASE_URL` and `TEMPO_PAT` for configuration ### API Integration Patterns 1. **Issue Resolution**: JIRA issue keys → numerical IDs for Tempo API compatibility 2. **Issue Caching**: 5-minute TTL cache for frequently accessed issues 3. **Concurrent Processing**: Promise.all() for bulk operations (matches C# Task.WhenAll pattern) 4. **Fallback Strategies**: Multiple API endpoints for worklog retrieval 5. **Rate Limiting**: Proper error handling for API rate limits (429 responses) ### Data Flow Architecture ``` AI Assistant → MCP Server → TempoClient → [JIRA API + Tempo API] → Response Formatting → AI Assistant ``` ### Error Handling Strategy - **Authentication Errors**: Clear PAT validation messages - **Permission Errors**: Specific guidance for Tempo/JIRA permissions - **API Errors**: Structured error responses with troubleshooting tips - **Rate Limiting**: Graceful handling with retry suggestions - **Data Validation**: Zod schema validation for all inputs ## Development Timeline & Success Factors **Built in 3 hours using AI-powered development:** 1. **Specification Phase**: Complete technical specification using GitHub Copilot + Claude Sonnet 4 2. **Implementation Phase**: One-shot implementation with VS Code + Claude Code 3. **Refinement Phase**: API debugging and polishing with GitHub Copilot + Claude Sonnet 4 ### Key Success Factors - Clear specification-first approach enabled effective AI implementation - Multiple AI tools used for their respective strengths (specification vs implementation vs debugging) - Iterative refinement with quick AI-assisted feedback loops ## Configuration Requirements ### Environment Variables - `TEMPO_BASE_URL`: JIRA instance URL (e.g., "<https://jira.company.com>") - `TEMPO_PAT`: Personal Access Token for authentication - `TEMPO_DEFAULT_HOURS`: Default hours per workday (optional, defaults to 8) ### Prerequisites - Node.js 16+ - JIRA instance with Tempo Timesheets plugin - Valid Personal Access Token with worklog read/write permissions ## AI Assistant Integration ### GitHub Copilot Configuration ```json { "github.copilot.chat.mcp.servers": { "tempo-filler": { "command": "node", "args": ["dist/index.js"], "env": { "TEMPO_BASE_URL": "https://jira.company.com", "TEMPO_PAT": "your-personal-access-token" } } } } ``` ### Claude Desktop Configuration ```json { "mcpServers": { "tempo-filler": { "command": "node", "args": ["dist/index.js"], "env": { "TEMPO_BASE_URL": "https://jira.company.com", "TEMPO_PAT": "your-personal-access-token" } } } } ``` ## API Compatibility ### Supported Systems - **JIRA Core/Software**: 8.14+ (required for PAT authentication) - **Tempo Timesheets**: 4.x (uses `/rest/tempo-timesheets/4/` endpoints) - **MCP Protocol**: Full compliance with Model Context Protocol specification ### Key API Endpoints - `GET /rest/api/latest/myself` - User authentication and identity - `GET /rest/api/latest/issue/{key}` - Issue resolution and caching - `POST /rest/tempo-timesheets/4/worklogs/` - Worklog creation - `POST /rest/tempo-timesheets/4/worklogs/search` - Worklog retrieval - `DELETE /rest/tempo-timesheets/4/worklogs/{id}` - Worklog deletion ## Security Considerations - **No Credential Logging**: PAT tokens never appear in logs or responses - **Input Validation**: Comprehensive Zod schema validation for all inputs - **Authentication Checks**: Bearer token validation on every request - **Permission Boundaries**: Users can only access/modify their own worklogs - **Token Revocation**: PAT tokens can be easily revoked if compromised ## Usage Patterns & Examples ### Common Workflows 1. **Daily Time Logging**: "Log 8 hours on PROJ-1234 for today" 2. **Weekly Time Filling**: "Fill my timesheet for this week - 4 hours PROJ-1111 and 4 hours PROJ-2222 each day" 3. **Monthly Bulk Operations**: "Fill all weekdays in July with 8 hours on PROJ-1234" 4. **Time Analysis**: "Get my July hours" → Detailed breakdown by issue and date 5. **Worklog Management**: "Delete worklog with ID 1211547" ### Response Formatting - **Structured Display**: Markdown-formatted responses with clear sections - **Summary Tables**: Daily totals with pivot table formatting (matches C# patterns) - **Concise Information**: User-friendly summaries with actionable details - **Error Guidance**: Specific troubleshooting steps for common issues ## Development & Maintenance ### Build Commands - `npm run build`: TypeScript compilation to ES modules - `npm run dev`: Development build and execution - `npm run typecheck`: Type validation without compilation ### Testing Strategy - **Unit Testing**: Individual tool implementations with mocked API responses - **Integration Testing**: Real Tempo API testing with staging environments - **MCP Compliance**: Validation using MCP Inspector tools - **Multi-client Testing**: Verification across GitHub Copilot and Claude Desktop ### Code Quality Standards - **Type Safety**: No `any` types, comprehensive TypeScript coverage - **Error Handling**: Structured error responses with helpful messages - **Documentation**: Inline comments and comprehensive README - **Security**: No credential exposure, proper input validation ## Future Enhancement Opportunities ### Planned Features (Phase 2) - HTTP transport support for broader client compatibility - Advanced caching strategies for improved performance - Additional prompt templates for specialized workflows - Enhanced worklog analysis and reporting capabilities ### Scalability Considerations - **Caching Strategy**: Issue resolution caching reduces API overhead - **Bulk Operation Limits**: 100-entry limit prevents API abuse - **Concurrent Processing**: Promise.all() enables efficient bulk operations - **Rate Limit Handling**: Built-in retry and backoff strategies This project demonstrates the power of AI-assisted development for creating production-ready integrations, combining clear specifications with rapid implementation and iterative refinement.