TickTick MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview A Python client library for the TickTick API with two implementations: 1. **OAuth Client** (`ticktick_setup.py`) - Uses the `ticktick-py` library with a monkey-patched fix for the deprecated `/user/signin` endpoint 2. **REST API Client** (`ticktick_rest_api.py`) - Direct REST API implementation using OAuth 2.0 Both implementations create a health and marriage tracking system with recurring tasks, milestones, and weekly check-ins. ## Development Commands ```bash # Install dependencies pip install -r requirements.txt # Add individual tasks (RECOMMENDED for daily use) python add_task.py "Task title" --content "Description" --priority 5 --due today python add_task.py "Task title" --project Health --priority 3 # Add task with long description python add_task.py "Task title" --content "$(cat <<'EOF' Multi-line description here With bullet points: - Item 1 - Item 2 EOF )" # Test REST API authentication only python ticktick_rest_api.py --auth # Create a test task to verify REST API works python ticktick_rest_api.py --test # Run full setup (REST API) - Creates entire Health & Marriage system python ticktick_rest_api.py --setup # View status (REST API) python ticktick_rest_api.py --status # DEPRECATED - OAuth client (broken, re-authenticates every time) # python ticktick_setup.py --setup # python test_ticktick_auth.py ``` ## Authentication Architecture ### Environment Variables (.env file) All scripts require credentials in `.env`: - `TICKTICK_CLIENT_ID` - From developer.ticktick.com/manage - `TICKTICK_CLIENT_SECRET` - From developer.ticktick.com/manage - `TICKTICK_REDIRECT_URI` - Must be `http://127.0.0.1:8080` - `TICKTICK_USERNAME` - TickTick account email - `TICKTICK_PASSWORD` - TickTick account password ### OAuth Flow Differences **ticktick_setup.py (ticktick-py library):** - Uses `ticktick-py` library with monkey-patched `_login` method - Monkey patch at lines 29-39 fixes the `/user/signin` → `/user/signon` endpoint change - Caches token in `.token-oauth` file - OAuth handled by the library's OAuth2 class - Browser authorization flow managed by library **ticktick_rest_api.py (REST API):** - Custom OAuth 2.0 implementation using `requests` library - Starts local HTTP server (`OAuthCallbackHandler`) on port 8080 to receive callback - Opens browser for user authorization (lines 92-125) - Exchanges authorization code for access token - Caches token in `.ticktick-token.json` file - Implements token refresh logic (lines 181-204) ## Critical Implementation Details ### Monkey Patch for ticktick-py The `ticktick-py` library uses a deprecated endpoint. Lines 29-39 in `ticktick_setup.py` and `test_ticktick_auth.py` patch the `TickTickClient._login` method to use `/user/signon` instead of `/user/signin`. This MUST be applied before creating a TickTickClient instance. ### Date/Time Handling - OAuth client uses `datetime` objects directly - REST API requires ISO 8601 strings with timezone: `strftime("%Y-%m-%dT%H:%M:%S+0000")` - Both use helper methods `_get_next_sunday()` and `_get_next_weekday()` for scheduling ### Task Priority Levels - `5` = High (red) - `3` = Medium (yellow) - `1` = Low (blue) - `0` = None ### RRULE Format for Recurring Tasks ```python # Daily repeat="RRULE:FREQ=DAILY;INTERVAL=1" # Weekly on specific day repeat="RRULE:FREQ=WEEKLY;BYDAY=SU" # Sunday # Monthly repeat="RRULE:FREQ=MONTHLY;BYMONTHDAY=1" ``` ## API Differences Between Implementations ### Creating Tasks **OAuth Client (ticktick_setup.py):** ```python task = client.task.builder( title="Task Title", content="Description", projectId=project_id, priority=5, repeat="RRULE:FREQ=DAILY;INTERVAL=1", startDate=datetime_object, dueDate=datetime_object ) client.task.create(task) ``` **REST API (ticktick_rest_api.py):** ```python client.create_task( title="Task Title", content="Description", projectId=project_id, priority=5, repeat="RRULE:FREQ=DAILY;INTERVAL=1", startDate="2024-01-01T09:00:00+0000", dueDate="2024-01-01T10:00:00+0000", timeZone="America/Los_Angeles" ) ``` Key differences: - OAuth client uses `.task.builder()` + `.task.create()` pattern - REST API uses direct `create_task()` method - REST API requires ISO 8601 string dates and explicit timezone - OAuth client accepts datetime objects ## Token Files - `.token-oauth` - OAuth client token cache (gitignored) - `.ticktick-token.json` - REST API token cache (gitignored) If authentication fails, delete these files and re-authenticate. ## Common Issues ### Re-authentication on Every Run (CRITICAL ISSUE) **Problem**: `ticktick_setup.py` (OAuth client using ticktick-py library) opens browser for authentication every time it runs. **Root Cause**: - The `ticktick-py` library's OAuth2 implementation doesn't properly cache tokens - The monkey-patched `/user/signon` endpoint is also failing with "Could Not Complete Request" error - The library attempts browser authorization on each initialization **Solution**: **Use `ticktick_rest_api.py` instead**. It properly caches tokens in `.ticktick-token.json` and only re-authenticates when the token expires (~165 days). **Status of Each Implementation**: - ✅ `ticktick_rest_api.py` - **WORKING** - Properly caches tokens, no re-authentication needed - ❌ `ticktick_setup.py` - **BROKEN** - Re-authenticates every time, /user/signon endpoint fails - ❌ `test_ticktick_auth.py` - **BROKEN** - Same issues as ticktick_setup.py ### "signin endpoint deprecated" Error The ticktick-py library needs the monkey patch, but even with the patch, the `/user/signon` endpoint is now failing. This suggests TickTick has changed their authentication flow. Use `ticktick_rest_api.py` instead. ### OAuth Callback Failed - Verify redirect URI is exactly `http://127.0.0.1:8080` in both .env and TickTick developer console - Port 8080 must be available - Copy the ENTIRE redirect URL from browser when prompted ### Token Expired For REST API implementation, delete token cache and re-run: ```bash rm .ticktick-token.json python ticktick_rest_api.py --auth ``` ## Project Structure Pattern Both implementations create three projects: 1. **Marriage** (Pink #E91E63) - Weekly check-ins, intimacy tracking 2. **Health** (Green #4CAF50) - Daily exercise, weekly weigh-ins 3. **Milestones** (Orange #FF9800) - 30/90/180-day goals The `HealthMarriageTracker` class in both files follows the same pattern: - `create_marriage_tasks()` - Marriage-specific recurring tasks - `create_health_tasks()` - Health-specific recurring tasks - `create_milestone_tasks()` - One-time milestone checkpoints - `setup_complete_system()` - Orchestrates full setup - `view_status()` - Display current tasks by project