Tempo Filler MCP Server

# TempoFiller MCP Server - Project Understanding ## Overview TempoFiller is a production-ready Model Context Protocol (MCP) server that bridges AI assistants with Tempo (JIRA's time tracking plugin), enabling automated worklog management. Built in TypeScript using modern ES modules, it provides comprehensive tools for retrieving, creating, and managing time entries through AI interfaces like Claude, GitHub Copilot, and other MCP-compatible assistants. **Current Status**: Published as `@tranzact/tempo-filler-mcp-server` v1.0.2 on NPM registry with full npx support for zero-friction installation and Claude Desktop bundle distribution. ## Specifications & Documentation The project follows a specification-driven development approach with comprehensive documentation: ### Specification Files 1. **`specs/tempo-filler-mcp-v1.md`**: Original comprehensive specification - Defines all core MCP server components (tools, resources, prompts) - Documents Tempo API integration patterns and authentication - Establishes TypeScript architecture and type system - Provides API endpoint reference and error handling strategies - Details implementation phases and success criteria 2. **`specs/npm-publishing.md`**: NPM publication and automation specification - Package configuration for `@tranzact/tempo-filler-mcp-server` - NPX compatibility requirements and executable binary setup - GitHub Actions automation for release-triggered publishing - Quality gates, security standards, and documentation requirements - Success metrics and cross-platform validation criteria 3. **`specs/get-schedule.md`**: GET Schedule tool product specification - Purpose, scope, and intended outcomes for schedule retrieval - Functional and non-functional requirements - Technical constraints and API integration details - Acceptance criteria and usage examples - Integration with existing worklog creation workflows ### Specification Benefits The specification-first approach enabled: - **Clear Implementation Targets**: Detailed requirements before coding - **AI-Assisted Development**: Specs provided clear context for AI tools - **Consistent Architecture**: All features follow established patterns - **Quality Assurance**: Acceptance criteria guide testing and validation - **Documentation**: Specs serve as comprehensive reference documentation ## Architecture & Components ### Core Architecture - **Language**: TypeScript 5.9.2+ with ES modules - **Runtime**: Node.js 16+ (specified in engine requirements) - **MCP Framework**: `@modelcontextprotocol/sdk` v1.17.1 - **Transport**: stdio (primary communication method) - **Authentication**: Personal Access Token (PAT) with Bearer token authentication - **API Integration**: Tempo Timesheets API v4, Tempo Core API v2, and JIRA REST API v3 ### Key Dependencies **Production Dependencies:** - `@modelcontextprotocol/sdk` ^1.17.1 - Model Context Protocol implementation - `axios` ^1.6.0 - HTTP client for API requests with interceptors - `date-fns` ^3.0.0 - Date formatting and manipulation utilities - `zod` ^3.25.76 - Runtime type validation and schema definitions **Development Dependencies:** - `typescript` ^5.9.2 - TypeScript compiler and type system - `@types/node` ^24.1.0 - Node.js type definitions **Bundling & Distribution:** - `@anthropic-ai/mcpb` - MCP bundler for creating `.mcpb`/`.dxt` distribution files ### TypeScript Configuration The project uses modern TypeScript with strict settings: - **Target**: ES2022 (modern JavaScript features) - **Module System**: Node16 (native ES modules support) - **Module Resolution**: Node16 (proper .js imports for ES modules) - **Strict Mode**: Enabled for maximum type safety - **Declaration Files**: Generated for TypeScript consumers - **Source Maps**: Enabled for debugging - **Output**: `dist/` directory with compiled JavaScript ### Project Structure ``` src/ ├── index.ts # MCP server entry point & request handlers (executable via shebang) ├── tempo-client.ts # Tempo/JIRA API client with authentication & caching ├── tools/ # MCP tool implementations │ ├── get-worklogs.ts # Retrieve worklogs with filtering & formatting │ ├── post-worklog.ts # Create single worklog entry │ ├── bulk-post.ts # Create multiple worklogs concurrently │ ├── delete-worklog.ts # Remove worklog entries │ ├── get-schedule.ts # Retrieve work schedule information │ └── 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 - Hybrid date formatting (ISO + human-readable) - Support for both Tempo search API and JIRA worklog API fallback - Concise summary with issue grouping and recent entry details ### 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 - Rich success feedback with creation details ### 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) - Comprehensive results table showing success/failure breakdown ### 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. **Work Schedule Retrieval** (`get_schedule`) - Retrieve work schedule information for authenticated user - Display working days vs non-working days with expected hours per day - Support for date range queries with period summary - Integration with Tempo Core API v2 schedule search endpoint - Hybrid date formatting consistent with other tools (ISO + human-readable) - Schedule-aware planning capabilities for intelligent time entry - Helpful guidance for integrating with worklog creation tools ### 6. **Resource Providers** - Recent issues access for quick reference (basic implementation) - User worklog data for specific time periods - JSON-formatted data suitable for AI analysis ### 7. **Prompt Templates** - `worklog_summary`: Worklog analysis prompts for time tracking insights - `schedule_aware_bulk_entry`: Guide AI assistants through schedule-first bulk worklog creation workflow - Smart integration of schedule verification with bulk time entry operations ## 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 via `/rest/api/latest/myself` - **Token Validation**: Built-in connectivity testing and error handling - **Environment Variables**: `TEMPO_BASE_URL` and `TEMPO_PAT` for configuration - **User Caching**: Current user identity cached to avoid repeated API calls ### 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) 6. **Request Debugging**: Comprehensive request/response logging via axios interceptors ### 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 - **Issue Resolution Failures**: Proper 404 handling with helpful messages ## 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 - Thorough understanding of existing C# implementation patterns ## 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 ### NPX Usage (Recommended) ```json { "mcpServers": { "tempo-filler": { "command": "npx", "args": ["@tranzact/tempo-filler-mcp-server"], "env": { "TEMPO_BASE_URL": "https://jira.company.com", "TEMPO_PAT": "your-personal-access-token" } } } } ``` ### GitHub Copilot Configuration ```json { "github.copilot.chat.mcp.servers": { "tempo-filler": { "command": "npx", "args": ["@tranzact/tempo-filler-mcp-server"], "env": { "TEMPO_BASE_URL": "https://jira.company.com", "TEMPO_PAT": "your-personal-access-token" } } } } ``` ### Claude Desktop Configuration ```json { "mcpServers": { "tempo-filler": { "command": "npx", "args": ["@tranzact/tempo-filler-mcp-server"], "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 - `GET /rest/api/latest/issue/{key}/worklog` - JIRA worklog fallback - `POST /rest/tempo-core/2/user/schedule/search` - Work schedule retrieval ## 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 - **Request Debugging**: Debug logging to stderr only, not stdout (MCP protocol compliance) ## Usage Patterns & Examples ### Common Workflows 1. **Daily Time Logging**: "Log 8 hours on PROJ-1234 for today" 2. **Schedule Verification**: "What's my work schedule for October 2025?" 3. **Schedule-Aware Bulk Entry**: "Check my October schedule, then fill all working days with 8 hours on PROJ-1234" 4. **Weekly Time Filling**: "Fill my timesheet for this week - 4 hours PROJ-1111 and 4 hours PROJ-2222 each day" 5. **Monthly Bulk Operations**: "Fill all weekdays in July with 8 hours on PROJ-1234" 6. **Time Analysis**: "Get my July hours" → Detailed breakdown by issue and date 7. **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) - **Hybrid Date Format**: ISO dates with human-readable format in parentheses - **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 + MCP bundle creation via `npm run build:bundle` - `npm run build:bundle`: Create MCP bundle using `@modelcontextprotocol/bundler` for Claude Desktop distribution - `npm run build:unix`: Unix-specific build with executable permissions (chmod +x) - `npm run dev`: Development build and execution - `npm run typecheck`: Type validation without compilation - `npm run prepublishOnly`: Pre-publish hook for NPM (runs build automatically) ### Package Configuration - **Scoped Package**: `@tranzact/tempo-filler-mcp-server` - **NPX Executable**: Configured with proper shebang (`#!/usr/bin/env node`) and bin entry - **File Optimization**: Only includes dist files in published package - **Engine Requirements**: Node.js 16+ compatibility - **ES Modules**: Full ES module support with proper TypeScript configuration - **MCP Bundle**: Distributable `.dxt` bundle for Claude Desktop drag-and-drop installation ### Distribution Channels 1. **NPM Registry** (Primary): `npx @tranzact/tempo-filler-mcp-server` - Zero-friction installation - Automatic dependency resolution - Cross-platform compatibility - Ideal for VS Code, GitHub Copilot, and other MCP clients 2. **GitHub Releases** (Bundle): Direct download of `.dxt` bundle - Claude Desktop drag-and-drop installation - Self-contained executable with dependencies bundled - Version-specific releases (e.g., v1.0.2) - Link: `https://github.com/TRANZACT/tempo-filler-mcp-server/releases/download/v1.0.2/bundle.dxt` 3. **One-Click Install Badges**: README includes install buttons - VS Code MCP install link with pre-configured settings - Claude Desktop install link with download URL - Environment variable configuration guidance ### 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 ## Current Implementation Status & Achievements ### Production Deployment ✅ - **NPM Publication**: Successfully published as `@tranzact/tempo-filler-mcp-server` v1.0.2 - **NPX Support**: Zero-friction installation with `npx @tranzact/tempo-filler-mcp-server` - **Cross-Platform**: Verified working on Windows with PowerShell and Unix-like systems - **Bundle Distribution**: MCP bundle creation integrated into build process ### Verified Integrations ✅ - **GitHub Copilot Chat (VS Code)**: Full integration with npx configuration - **Claude Desktop**: Complete MCP server support with bundle installation - **Real Tempo API**: Successfully tested against production Tempo Timesheets API v4 ### Core Features Implementation Status ✅ 1. **get_worklogs**: ✅ Complete with user filtering, issue-specific queries, and hybrid date formatting 2. **post_worklog**: ✅ Complete with automatic issue resolution and PAT authentication 3. **bulk_post_worklogs**: ✅ Complete with concurrent processing and pivot table reporting 4. **delete_worklog**: ✅ Complete with proper error handling and confirmation 5. **get_schedule**: ✅ Complete with Tempo Core API v2 integration, hybrid date formatting, and schedule-aware planning guidance 6. **Resources**: ✅ Basic implementation for recent issues access 7. **Prompts**: ✅ Worklog analysis and schedule-aware bulk entry prompt templates ### Technical Accomplishments ✅ - **TypeScript ES Modules**: Modern module system with proper .js imports and Node16 resolution - **Comprehensive Error Handling**: Structured error responses with troubleshooting guidance - **Authentication System**: Robust PAT-based authentication with user resolution - **Issue Caching**: 5-minute TTL cache for performance optimization - **Concurrent Operations**: Promise.all() implementation for bulk worklog creation - **Input Validation**: Zod schemas for all tool inputs with helpful error messages - **Response Formatting**: Rich markdown formatting with hybrid date display ### Development Process Insights **Total Development Time**: 3 hours of AI-assisted development **Success Factors**: 1. **Specification-First Approach**: Detailed spec in `specs/tempo-filler-mcp-v1.md` enabled effective implementation 2. **Multi-AI Tool Strategy**: Different AI assistants used for their strengths: - GitHub Copilot + Claude Sonnet 4: Specification and debugging - VS Code + Claude Code: One-shot implementation 3. **Iterative Refinement**: Quick feedback loops for API integration issues ### Real-World Usage Validation **Tested Workflows**: - Daily time logging: "Log 8 hours on PROJ-1234 for today" ✅ - Schedule verification: "What's my work schedule for October 2025?" ✅ - Schedule-aware bulk entry: "Check my schedule, then fill all working days with 8 hours on PROJ-1234" ✅ - Bulk operations: "Fill all weekdays in July with 8 hours on PROJ-1234" ✅ - Time analysis: "Get my July hours" ✅ - Worklog management: "Delete worklog with ID 1211547" ✅ **Performance Metrics**: - NPX startup time: < 10 seconds - Bulk worklog creation: 23 entries in < 30 seconds - API response times: < 3 seconds for typical operations - Error recovery: Graceful handling of authentication and permission issues This implementation represents a successful example of AI-powered development creating a robust, production-ready integration that bridges modern AI assistants with enterprise time tracking systems, demonstrating the power of specification-driven development and multi-tool AI assistance. ## Recent Enhancements ### GET Schedule Tool (Latest Addition) The `get_schedule` tool was recently added to enhance the MCP server's capabilities with schedule-aware time tracking intelligence. This feature: **Purpose & Benefits:** - Enables AI assistants to check work schedules before creating time entries - Prevents accidental time logging on non-working days (weekends, holidays) - Provides intelligent planning for bulk time entry operations - Shows expected hours per working day based on organizational schedules **Technical Implementation:** - Integrates with Tempo Core API v2 (`/rest/tempo-core/2/user/schedule/search`) - Uses same authentication and user resolution patterns as existing tools - Implements hybrid date formatting (ISO + human-readable) for consistency - Provides comprehensive period summaries (working days, non-working days, total required hours) - Added corresponding types to `tempo.ts` (TempoScheduleResponse, TempoScheduleDay, etc.) - Created Zod validation schema in `mcp.ts` for input validation **Integration Points:** - Tool descriptions for `post_worklog` and `bulk_post_worklogs` now recommend using `get_schedule` first - New `schedule_aware_bulk_entry` prompt template guides AI assistants through schedule-first workflows - Follows established error handling and response formatting patterns **User Experience Improvements:** - Natural language queries: "What's my work schedule for October 2025?" - Smart workflow guidance: "Check my schedule, then fill all working days with 8 hours on PROJ-1234" - Clear visual distinction between working and non-working days - Helpful "Next Steps" guidance in schedule responses **Specification Driven:** - Detailed product specification created in `specs/get-schedule.md` - Defined acceptance criteria, functional requirements, and technical constraints - Aligned with existing tool patterns and architectural standards This enhancement demonstrates the project's continued evolution to provide more intelligent, schedule-aware time tracking capabilities while maintaining consistency with the established codebase architecture and user experience patterns. ## Project Summary & Current State ### Overview TempoFiller MCP Server is a **production-ready, specification-driven TypeScript project** that successfully bridges the gap between AI assistants and enterprise time tracking systems. The project exemplifies modern development practices with AI-assisted implementation. ### Key Achievements 1. **Rapid Development**: Built core functionality in 3 hours using AI-powered development 2. **Production Quality**: Published to NPM with full distribution support 3. **Comprehensive Features**: 5 core tools covering full worklog lifecycle + schedule intelligence 4. **Multiple Distribution Channels**: NPM (npx), GitHub Releases (bundle), one-click install badges 5. **Extensive Documentation**: Detailed specifications, comprehensive README, and project understanding docs 6. **Real-World Validation**: Tested and validated against production Tempo APIs ### Architecture Strengths - **Type Safety**: Full TypeScript with strict mode and comprehensive type definitions - **Modern ES Modules**: Node16 module system with proper import patterns - **MCP Compliance**: Full Model Context Protocol specification adherence - **Authentication**: Secure PAT-based authentication with user identity caching - **Performance**: Issue caching, concurrent operations, efficient API usage - **Error Handling**: Comprehensive error handling with helpful user guidance - **Response Quality**: Rich markdown formatting with hybrid date display ### Distribution Excellence - **Zero-Friction Installation**: `npx @tranzact/tempo-filler-mcp-server` - no installation required - **Cross-Platform**: Works on Windows, macOS, and Linux - **Multiple Clients**: Verified with GitHub Copilot, Claude Desktop, VS Code - **Bundle Support**: `.dxt` files for drag-and-drop installation in Claude Desktop - **Version Management**: Semantic versioning with v1.0.2 currently published ### Feature Completeness **Tools (5):** 1. ✅ `get_worklogs` - Retrieve and analyze time entries 2. ✅ `post_worklog` - Create single worklog entries 3. ✅ `bulk_post_worklogs` - Create multiple entries concurrently 4. ✅ `delete_worklog` - Remove worklog entries 5. ✅ `get_schedule` - Retrieve work schedule intelligence **Resources (1):** - ✅ Recent issues access for quick reference **Prompts (2):** - ✅ `worklog_summary` - Worklog analysis assistance - ✅ `schedule_aware_bulk_entry` - Schedule-first bulk entry workflow ### Technical Stack - **Language**: TypeScript 5.9.2 - **Runtime**: Node.js 16+ - **Framework**: MCP SDK 1.17.1 - **HTTP Client**: Axios 1.6.0 - **Validation**: Zod 3.25.76 - **Date Handling**: date-fns 3.0.0 - **APIs**: Tempo Timesheets v4, Tempo Core v2, JIRA REST v3 ### Development Practices - **Specification-Driven**: All features backed by detailed specs - **AI-Assisted**: Leveraged Claude Sonnet 4 and Claude Code - **Iterative Refinement**: Quick feedback loops for quality - **Consistent Patterns**: All tools follow established architecture - **Quality First**: Comprehensive error handling and user feedback ### Future Considerations Potential areas for enhancement (not currently prioritized): - Advanced resource providers for historical data analysis - Additional prompt templates for complex time tracking scenarios - Enhanced caching strategies for improved performance - Support for custom Tempo attributes and fields - Integration with additional time tracking systems - Comprehensive test suite (unit + integration) - Performance monitoring and analytics ### Maintenance Status The project is **actively maintained** with: - Current version: v1.0.2 - Published on NPM registry - Available via GitHub releases - Fully documented and specified - Production-ready and tested This project successfully demonstrates how specification-driven development combined with AI-assisted implementation can produce enterprise-grade software that integrates modern AI assistants with legacy enterprise systems, creating powerful automation capabilities for knowledge workers.