Skip to main content
Glama

Toggl MCP Server

by ikido
MCP_TOGGL_SERVER_PRD.md11.1 kB
# MCP Toggl Server - Product Requirements Document **Status**: Draft **Date**: 2025-10-16 **Objective**: Create an MCP server that replaces the current Toggl data fetching, parsing, and aggregation pipeline --- ## 1. Executive Summary Currently, the volt-agent pipeline has a multi-step process to fetch time tracking data from Toggl, parse descriptions to extract Fibery entity references, and aggregate data per user. This PRD describes an MCP server that: - **Takes as input**: `start_date`, `end_date` - **Returns as output**: Complete structured `toggl_aggregated.json` format - **Replaces**: Activities 1-2 in the current pipeline (fetch_toggl_data + aggregate_toggl_data) - **Benefits**: - Decouples Toggl data fetching from volt-agent - Enables reusability across multiple projects - Simplifies volt-agent pipeline (fewer activities) - Allows independent testing and versioning --- ## 2. Problem Statement ### Current Architecture Issues 1. **Tight Coupling**: Toggl integration is hardcoded into volt-agent workflow 2. **Single-Purpose**: The aggregation logic can't be reused in other projects 3. **No Abstraction**: Pipeline details are mixed with application logic 4. **Testing Complexity**: Can't test Toggl pipeline without full Temporal setup ### Ideal Solution An MCP server provides: - Clean interface between Toggl and volt-agent - Reusability across projects - Independent versioning and testing - Decoupled deployment --- ## 3. Scope & Requirements ### 3.1 MCP Server Capabilities #### Input Parameters ``` Tool: get_toggl_aggregated_data Parameters: - start_date (string, ISO 8601): "2025-10-06" - end_date (string, ISO 8601): "2025-10-13" - user_emails_filter (array[string], optional): Filter to specific users - workspace_id (string, optional): Override workspace ID from env ``` #### Output Format Returns complete `toggl_aggregated.json` structure with: - Per-user matched entities (with Fibery references) - Per-user unmatched activities - Comprehensive statistics - Metadata (run timestamp, date range) ### 3.2 Data Processing Steps The MCP server will internally execute these steps: 1. **Fetch from Toggl API** - Day-by-day pagination - Exponential backoff for rate limiting - Enrich with user email and project info 2. **Parse Descriptions** - Extract Fibery entity IDs using pattern: `#(\d+) \[Database\] \[Type\]` - Clean descriptions (remove metadata) - Classify as matched or unmatched 3. **Aggregate** - Group by user - For matched: group by (database, type, entity_id, description) - For unmatched: group by description - Calculate cumulative duration and counts 4. **Return Aggregated Data** - Complete JSON structure ready for enrichment stage - No further processing needed by consumer ### 3.3 Non-Goals - **LLM Integration**: No AI/summarization (that's a separate stage) - **Fibery Querying**: Only Toggl + Fibery reference extraction - **Report Generation**: Just the data, no markdown outputs - **Workflow Orchestration**: Just the data tool, not a full MCP server with multiple resources --- ## 4. Technical Architecture ### 4.1 MCP Server Structure ``` mcp-toggl-server/ ├── pyproject.toml ├── src/ │ └── toggl_mcp/ │ ├── __init__.py │ ├── server.py # MCP server implementation │ ├── tools/ │ │ └── toggl_tool.py # Tool definition │ ├── service/ │ │ ├── toggl_service.py # Core service logic │ │ ├── parser_service.py # Description parsing │ │ └── aggregator_service.py # Aggregation logic │ └── models/ │ ├── schemas.py # Pydantic models │ └── types.py # Type definitions ├── tests/ │ ├── test_toggl_service.py │ ├── test_parser_service.py │ └── test_integration.py └── README.md ``` ### 4.2 MCP Tool Definition ```python # Tool: get_toggl_aggregated_data Input: { "start_date": "2025-10-06", # ISO 8601 "end_date": "2025-10-13", # ISO 8601 "user_emails_filter": ["a@b.com"], # Optional "workspace_id": "123456" # Optional, from env if not provided } Output: { "status": "success" | "error", "data": { "run_id": "mcp-toggl-20251016-120000", "start_date": "2025-10-06", "end_date": "2025-10-13", "users": { "user@email.com": { "user_email": "user@email.com", "matched_entities": [...], "unmatched_activities": [...], "statistics": {...} } }, "statistics": {...} }, "error": null | "error message" } ``` ### 4.3 Service Layer #### TogglService - Fetches data from Toggl API v3 - Handles pagination (day-by-day, X-Next-ID) - Implements rate limiting retry logic (exponential backoff) - Returns raw time entries grouped by user #### ParserService - Parses Toggl descriptions - Extracts entity patterns: `#<ID> [DB] [TYPE]` - Returns: `(description_clean, entity_id, database, type, project, is_matched)` #### AggregatorService - Groups entries by user - For matched: groups by (db, type, entity_id, description) - For unmatched: groups by description - Calculates totals and statistics ### 4.4 Integration with volt-agent Current pipeline stage 1-2 (fetch + aggregate): ```python # OLD: 2 activities activity_1_result = fetch_toggl_data(run_id, date_range, users) # returns raw_toggl_data.json activity_2_result = aggregate_toggl_data(run_id) # returns toggl_aggregated.json ``` New pipeline with MCP server: ```python # NEW: 1 MCP tool call toggl_data = call_mcp_tool("get_toggl_aggregated_data", { "start_date": "2025-10-06", "end_date": "2025-10-13" }) # Result: toggl_aggregated.json format directly ``` --- ## 5. Data Flow Diagram ``` ┌──────────────────┐ │ volt-agent │ │ Pipeline │ └────────┬─────────┘ │ │ Calls MCP Tool │ get_toggl_aggregated_data(start, end) ▼ ┌──────────────────────────────────┐ │ MCP Toggl Server │ │ │ │ ┌────────────────────────────┐ │ │ │ 1. TogglService │ │ │ │ - Fetch from API │ │ │ │ - Pagination (day-by-day) │ │ - Backoff/retry │ │ │ │ → raw time entries │ │ │ └────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────┐ │ │ │ 2. ParserService │ │ │ │ - Extract #ID [DB] [TY] │ │ │ │ - Clean descriptions │ │ │ │ - Classify matched/etc │ │ │ │ → parsed entries │ │ │ └────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────┐ │ │ │ 3. AggregatorService │ │ │ │ - Group by user │ │ │ │ - Group matched entries │ │ │ │ - Calculate statistics │ │ │ │ → aggregated structure │ │ │ └────────────────────────────┘ │ │ │ │ └──────────────────┼────────────────┘ │ ▼ ┌─────────────────┐ │ toggl_aggregated│ │ _data.json │ └─────────────────┘ (ready for Stage 2: Fibery Enrichment) ``` --- ## 6. Implementation Details ### 6.1 Configuration Environment variables: ```bash # From volt-agent (shared) TOGGL_API_TOKEN=your_toggl_token TOGGL_WORKSPACE_ID=1637944 # MCP-specific (optional) MCP_TOGGL_PORT=8001 # For stdio transport MCP_TOGGL_LOG_LEVEL=info ``` ### 6.2 Error Handling - **Rate Limiting (429)**: Exponential backoff, max 3 retries, start at 60s - **Invalid Date Format**: Return error with expected format - **API Errors (5xx)**: Retry with backoff, fail after max attempts - **No Data**: Return empty users object with success status - **Parser Errors**: Log and skip malformed entries (non-blocking) ### 6.3 Performance Characteristics - **Input**: 1 week date range, ~13 users - **Expected Duration**: ~30-45 seconds (limited by Toggl API pagination) - **Pagination**: ~90 API calls (13 users × 7 days) - **Rate Limit**: 3 requests per second (Toggl limit) - **Memory**: ~50-100MB (in-memory buffering of parsed entries) ### 6.4 Testing Strategy Unit Tests: - ParserService: Test regex patterns, edge cases - AggregatorService: Test grouping logic, statistics - Schema validation: Ensure output matches expected structure Integration Tests: - Mock Toggl API responses - Test full pipeline with sample data - Validate output structure matches volt-agent expectations --- ## 7. Migration Plan ### Phase 1: Development 1. Create MCP server repository 2. Implement services (Toggl, Parser, Aggregator) 3. Add comprehensive tests 4. Document API ### Phase 2: Integration 1. Create volt-agent activity to call MCP server 2. Update pipeline workflow 3. Test end-to-end with real Toggl data 4. Compare outputs with current pipeline ### Phase 3: Deployment 1. Deploy MCP server (stdio transport initially) 2. Update volt-agent to use MCP tool 3. Deprecate old fetch_toggl_data activity 4. Monitor for issues --- ## 8. Success Criteria ✅ MCP server takes start_date + end_date as input ✅ Returns toggl_aggregated.json format ✅ Processes multiple users correctly ✅ Parses Fibery entity references from descriptions ✅ Aggregates by user and entity ✅ Handles rate limiting and retries ✅ Comprehensive test coverage (>80%) ✅ Output matches current pipeline output exactly ✅ Performance: <60 seconds for 1-week range ✅ Documentation complete --- ## 9. Future Enhancements 1. **Caching**: Cache Toggl API responses for repeated requests 2. **Multiple Workspaces**: Support multiple Toggl workspaces 3. **Custom Parsers**: Pluggable description parsers for different formats 4. **Webhooks**: Real-time updates via Toggl webhooks 5. **Metrics**: Expose metrics for monitoring (request counts, durations) 6. **CLI Tool**: Standalone CLI for testing MCP server

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ikido/toggl-mcp-custom'

If you have feedback or need assistance with the MCP directory API, please join our Discord server