Toggl MCP Server

# Toggl MCP Server - Logging and Debugging Guide ## Overview The Toggl MCP Server now includes comprehensive logging to help diagnose connection issues and debug problems. ## Logging Improvements Added ### 1. **Startup Logging** (`server.py`) - Server startup is now logged with clear markers - Configuration details are logged on initialization: - Masked API token (first 8 chars + ...) - Workspace ID - Cache directory - Cache TTL - All services log their initialization status individually - Initialization errors are captured and logged with full tracebacks ### 2. **Health Check Tool** (New) A new diagnostic tool `health_check` is available to check MCP server status: ``` Tool Name: health_check Returns: - status: "healthy" or "unhealthy" - services: Status of all services (initialized or not) - configuration: Masked config details - initialization_error: Any errors encountered during init - toggl_api: Connection test results ``` Use this tool first when diagnosing issues: ``` claude_code> /mcp health_check ``` ### 3. **Detailed Tool Logging** (`server.py`) Each tool now logs: - When it's called - Whether services need initialization - Progress of operations - Success/failure with relevant details - Full tracebacks on errors Example output: ``` ================================================================================ get_workspace_users() called Services not initialized, initializing now... Starting service initialization... ✓ Configuration validated - API Token: 43412b01... - Workspace ID: 1637944 - Cache Dir: ./cache - Cache TTL: 1 hours ✓ CacheService initialized ✓ TogglService initialized ✓ ParserService initialized ✓ AggregatorService initialized ================================================================================ ✓✓ All services initialized successfully! ================================================================================ Fetching workspace users... ✓ Successfully fetched 95 users ``` ### 4. **Service Logging** (`toggl_service.py`) - TogglService logs initialization - API requests log details (method, URL, response status) - Rate limiting and retries are logged - Timeout handling is logged - Time entry fetching logs pagination progress ### 5. **Log Levels** - **DEBUG**: Detailed initialization info, service instantiation - **INFO**: Normal operation, API calls, successes (marked with ✓) - **ERROR**: Failures, exceptions, connection issues (marked with ✗) ## Viewing Logs ### When running MCP server directly: ```bash python -m src.toggl_mcp.server ``` All logs appear in stdout with timestamps and log levels. ### In Claude Code: When the MCP fails to reconnect, check: 1. The terminal where the MCP server is running - all logs appear there 2. Look for patterns like: - `✓` = successful operation - `✗` = error occurred - `ERROR` = exception or failure - Stack traces show the full error context ## Common Issues and How to Debug ### Issue: "Failed to reconnect to toggl" **Steps to debug:** 1. Run `health_check` tool to see if services initialized 2. Check for initialization errors in the response 3. If unhealthy, check MCP server logs for: - Configuration validation errors (missing TOGGL_API_TOKEN or TOGGL_WORKSPACE_ID) - API connection failures - Network timeouts **Example Error Log:** ``` ERROR:src.toggl_mcp.server:================================================================================ ERROR:src.toggl_mcp.server:✗ Configuration validation error: TOGGL_API_TOKEN not set ERROR:src.toggl_mcp.server:================================================================================ ``` ### Issue: "Toggl API error: 403" **Steps to debug:** 1. Check the MCP server logs for the full error response 2. Look for authentication-related errors 3. Common causes: - Invalid/expired API token - Wrong workspace ID - API rate limiting (would show 429 instead) **Example Error Log:** ``` ERROR:httpx:HTTP Request: GET https://api.track.toggl.com/api/v9/workspaces/1637944/workspace_users "HTTP/1.1 403 Forbidden" ERROR:src.toggl_mcp.utils:API error: 403 - Invalid credentials ``` ### Issue: "Max retries exceeded" **Steps to debug:** 1. Check for network connectivity 2. Look for rate limiting (429 status codes) 3. Check for timeout errors (30 second timeout) 4. Verify workspace_id is correct **Example Error Log:** ``` INFO:src.toggl_mcp.utils:Rate limited. Waiting 60s before retry 1 INFO:src.toggl_mcp.utils:Rate limited. Waiting 120s before retry 2 ERROR:src.toggl_mcp.services.toggl_service:Max retries exceeded for https://api.track.toggl.com/api/v9/... ``` ## Log Output Format Logs follow this format: ``` %(asctime)s - %(name)s - %(levelname)s - %(message)s ``` Example: ``` 2025-10-16 10:47:05,123 - src.toggl_mcp.server - INFO - ✓ Configuration validated ``` ## Best Practices for Debugging 1. **Always check the full log output** - errors are logged with context 2. **Look for patterns**: - Messages with ✓ show what's working - Messages with ✗ show what failed - Stack traces show the exact error location 3. **Reproduce issues** with specific dates/user IDs 4. **Check configuration**: - Verify `.env` file has both TOGGL_API_TOKEN and TOGGL_WORKSPACE_ID - Use `health_check` to verify they're loaded ## Monitoring in Production For production deployments: 1. Redirect logs to a file: `python -m src.toggl_mcp.server > toggl_mcp.log 2>&1` 2. Monitor for ERROR level messages 3. Set up alerts for repeated failures 4. Archive logs periodically ## Related Files - `src/toggl_mcp/server.py` - Main MCP server with tool definitions - `src/toggl_mcp/services/toggl_service.py` - API integration with logging - `src/toggl_mcp/utils.py` - Logging utility functions - `.env` - Configuration (not logged, but used for initialization)