@timesheet/mcp/CHANGELOG.md

Model Context Protocol server for Timesheet API

# Changelog

## [1.1.0] - 2026-02-07

### Added
- **`statistics_get` MCP Tool**: New tool for aggregated time tracking statistics
  - Required params: `startDate`, `endDate` for defining the analysis period
  - Optional filters: `projectId`, `projectIds`, `teamId`, `teamIds`, `tagIds`, `userIds`, `filter`
  - Server-side aggregation: total hours, billable/non-billable breakdown, break hours, task count
  - Project breakdown with hours, percentage, task count per project
  - Daily hours with billable/non-billable/break split and zero-day fill
  - Weekly hours auto-computed when date range exceeds 14 days (grouped by ISO week)
  - Paginates up to 500 tasks (5 pages) for detailed breakdowns
- **Recharts Statistics Widget**: Interactive charts replacing CSS-based visualizations
  - `DailyChart`: Stacked `BarChart` with billable (green) and non-billable (amber) bars
  - `ProjectBreakdown`: Donut `PieChart` with project colors from SDK and side legend
  - `chartTheme.ts`: Theme-aware color palettes for light/dark mode
  - Auto-switches between daily and weekly chart views based on data range
  - Date range subtitle in widget header
  - 4-column summary grid (Total Hours, Billable Hours, Billable %, Tasks)
- **MCP Apps SDK Migration** (SEP-1865): Standardized widget communication protocol
  - `McpAppProvider.tsx` wraps all widget roots with `useApp()` hook
  - URI scheme: `ui://timesheet/<component>.html`
  - MIME type: `text/html;profile=mcp-app`
  - Metadata namespace: `_meta.ui.*` with OpenAI backward compatibility keys retained
  - `useDocumentTheme` from ext-apps/react replaces old theme hook

### Changed
- `Statistics` type interface extended with `nonBillableHours`, `totalTasks`, `totalBreakHours`, `startDate`/`endDate`, and richer project/daily/weekly breakdown fields
- `formatStatisticsResponse` now provides detailed text fallback with date range, project breakdown list, and daily summary for non-widget MCP clients
- Widget hooks (`useToolOutput`, `useCallTool`, `useTheme`, `useDisplayMode`) backed by MCP Apps SDK while preserving identical signatures
- `tsconfig.json` upgraded to `"module": "node16"` + `"moduleResolution": "node16"` for package.json `exports` support

### Removed
- `src/openai-helpers.ts` replaced by `src/mcp-app-helpers.ts`

### Dependencies
- Added `recharts` ^2.15.0
- Added `@modelcontextprotocol/ext-apps` ^1.0.1

## [1.0.4] - 2026-01-06

### Added
- OAuth 2.1 Authorization Server Metadata endpoint with PKCE support
  - `code_challenge_methods_supported: ['S256']` for ChatGPT compatibility
  - `authorization_endpoint`, `token_endpoint`, `registration_endpoint`
  - Serves metadata directly instead of redirecting

### Fixed
- Set `MCP_SERVER_URL` in Cloud Build for correct OAuth resource identifier
- Debug logging for environment variable troubleshooting

## [1.0.3] - 2026-01-06

### Added
- **Landing Page**: Modern dark-themed landing page at mcp.timesheet.io root
  - Installation instructions for Claude Code, Claude Desktop, and ChatGPT
  - Feature cards with gradient icons
  - Copy-to-clipboard code blocks
  - Responsive design with timesheet.io branding
- **Root URL Routing**: Serve landing page on GET, MCP protocol on POST at root
  - Content negotiation based on Accept header and User-Agent
  - Clean URL structure (mcp.timesheet.io instead of mcp.timesheet.io/mcp)
- **Reports API - Document Reports**: New tools for document/invoice data and PDF generation
  - `report_document_get` - Retrieve formatted document data with tasks, expenses, and financials
  - `report_document_pdf` - Generate PDF version of documents/invoices
  - `report_document_xml` - Generate e-invoicing XML (Zugferd, XRechnung, ebInterface)
- **Reports API - Task Reports**: New tools for task report data and PDFs
  - `report_task_get` - Retrieve formatted task data with time tracking and rates
  - `report_task_pdf` - Generate PDF report for a task
- **Reports API - Expense Reports**: New tools for expense report data and PDFs
  - `report_expense_get` - Retrieve formatted expense data with amounts
  - `report_expense_pdf` - Generate PDF report with receipt images
- **Reports API - Note Reports**: New tools for note report data and PDFs
  - `report_note_get` - Retrieve formatted note data with content
  - `report_note_pdf` - Generate PDF report with attachments
- **Reports API - Export Generation**: New tools for timesheet exports
  - `export_generate` - Generate Excel/CSV/PDF exports with filters and options
  - `export_send` - Send exports directly via email
  - `export_from_template` - Generate exports using saved templates
- **Reports API - Export Configuration**: New tools for export customization
  - `export_fields` - Get available export fields/columns
  - `export_report_types` - Get available report types
- **Reports API - Export Templates**: New tools for template management
  - `export_template_list` - List saved export templates
  - `export_template_get` - View template details
  - `export_template_create` - Save export configuration as template
  - `export_template_update` - Modify existing templates
  - `export_template_delete` - Delete templates
- **ExportWidget**: Interactive React widget for ChatGPT integration
  - Template selector dropdown with format indicators
  - Date range inputs with quick presets (This Month, Last Month, This Week, Last Week)
  - Template details display with format, summarize, and filter badges
  - Generate button with loading state and result feedback
  - Calls `export_from_template` via `useCallTool` hook
- Tag display in TaskList widget with colored chips
- TagList and TagItem components for displaying task tags
- Automatic tag population in task_list tool (populateTags default: true)
- Contrasting text color calculation for tag backgrounds
- Table-row layout for TaskListItem with 3 columns (time, details, duration)
- i18n translations for TaskList component strings (English and German)
- **Cloud Run Deployment**: Production-ready container deployment
  - Multi-stage Dockerfile for optimized builds
  - Cloud Build configuration (`cloudbuild.yaml`) for GitHub CI/CD
  - `.dockerignore` for efficient Docker builds
  - CORS configuration for Cloud Run domains

### Changed
- Enhanced all tool definitions with detailed titles and user-friendly descriptions
- Added comprehensive output schemas to document return values for all tools
- Added tool annotations (readOnlyHint, destructiveHint) for better UX
- Improved parameter descriptions with format specifications (date-time, date formats)
- Added validation constraints (minLength, minimum, maximum) to parameters
- Refactored Tailwind configuration to use CSS custom properties for theme colors
- TaskListItem now displays description and tags below project title
- Extracted hardcoded strings to i18n translation files in TaskListView and TaskListItem

## [1.0.1] - 2025-01-14

### Added
- Support for TIMESHEET_API_URL environment variable (undocumented, for testing)

### Fixed
- CI/CD pipeline issues
- Test suite compatibility
- npm publish workflow

## [1.0.0] - 2025-01-14

### Added
- Initial release of Timesheet MCP Server
- Timer management tools (start, stop, pause, resume, status, update)
- Task enhancement tools (add notes, expenses, pauses)
- Project management tools (list, create, update, delete)
- Task management tools (list, create, update, delete)
- Natural language support for timer operations
- Authentication configuration tool
- Comprehensive error handling
- Full integration with @timesheet/sdk
- Example usage documentation
- Support for retroactive time entries