MCP_TOGGL_SERVER_PRD.md•11.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