claudetools/session-logs/2026-03-31-session.md

Session Log: 2026-03-31 - TickTick Integration & Dev Project Tracking

Session Summary

Built a complete TickTick integration for ClaudeTools, including OAuth authentication, MCP server with 9 tools, FastAPI service+router, and a dev project tracking system that syncs between the ClaudeTools database and TickTick.

Key Decisions

• Hybrid approach (Option 3): TickTick for mobile/cross-device visibility of active dev projects, ClaudeTools DB for granular tracking (sessions, notes, timestamps)
• MCP server + API service: Both access paths -- MCP tools for Claude Code direct use, REST API for external access
• SOPS vault for credentials: Consistent with project standards, no env vars
• JWT auth on all router endpoints: Matches existing security pattern

Problems Encountered & Resolutions

1. "Guru" not appearing in API results: It's a TickTick folder, not a list. The API only returns lists. "Tasks" and "Call Back List" are the actual lists inside the Guru folder.
2. Bash not found from PowerShell: The auth script uses subprocess.run(["bash", ...]) for vault access. Must run from bash/Claude Code terminal, not PowerShell directly.
3. DB server unreachable: 172.16.3.30 not reachable from ACG-5070 without Tailscale. Installed Tailscale via winget, connected, then ran migration.
4. mcp package not installed: Installed mcp and httpx via pip for Python 3.14.
5. Code review found 4 issues: All fixed before proceeding -- gitignore, token permissions, JWT auth, SOPS vault credentials.

---

Credentials

TickTick API (OAuth 2.0)

• Developer Portal: https://developer.ticktick.com/
• App Name: ClaudeTools
• Client ID: 1J86gMsTJ0JH63gtf0
• Client Secret: pI4U78vtLQrZwcW5MmdNFdxA0eeoy7GJ
• OAuth Redirect URL: http://localhost:9876/callback
• Scopes: tasks:read tasks:write
• SOPS Vault: services/ticktick.sops.yaml (client_id, client_secret, oauth_redirect_url)
• Token File: mcp-servers/ticktick/.tokens.json (gitignored, auto-refreshes)

TickTick API Endpoints

• Base URL: https://api.ticktick.com/open/v1
• Auth URL: https://ticktick.com/oauth/authorize
• Token URL: https://ticktick.com/oauth/token
• Token endpoint requires: Content-Type: application/x-www-form-urlencoded (NOT JSON)

Database

• Host: 172.16.3.30:3306
• DB: claudetools
• User: claudetools
• Password: CT_e8fcd5a3952030a79ed6debae6c954ed

---

Infrastructure & Servers

Tailscale

• Installed on ACG-5070 via winget install Tailscale.Tailscale (v1.96.3)
• Required to reach 172.16.3.30 from home network
• Tailscale must be connected before DB/API access works

TickTick IDs

• Dev Projects list ID: 69cbd7138f0826bd72746074
• TickTick Integration task ID: 69cbe8ca8f0898cc050064e5
• DB dev_projects row UUID: 65783890-2d12-11f1-ae01-52540020ee14

User's TickTick Projects (16 total)

• Call Back List, COSTCO, Private, Capacitance, Website Department, Household Tasks & Projects, PacketDial, Tasks, Grocery, Kitchen Decon, Camper Packing, MOVE 2024, Photography Challenge, Business Planning, Libations shopping, Da Move
• "Guru" is a folder containing "Tasks" (21 items) and "Call Back List"
• "HomeStuff" is another folder (15 items)

---

Files Created

MCP Server

• mcp-servers/ticktick/ticktick_auth.py - One-time OAuth browser auth flow (localhost:9876 callback, CSRF protection, vault credential retrieval)
• mcp-servers/ticktick/ticktick_mcp.py - MCP server with 9 tools: ticktick_list_projects, ticktick_get_project, ticktick_create_project, ticktick_update_project, ticktick_delete_project, ticktick_create_task, ticktick_update_task, ticktick_complete_task, ticktick_delete_task

API Integration

• api/services/ticktick_service.py - Async service class with SOPS vault credentials, auto token refresh on 401, httpx client
• api/routers/ticktick.py - REST endpoints at /api/ticktick/, JWT-protected, 9 endpoints matching MCP tools

Database

• migrations/add_dev_projects_table.sql - Migration SQL for dev_projects table (14 columns, status index)

Configuration

• .mcp.json - MCP server registration (ticktick server using python)
• vault/services/ticktick.sops.yaml - SOPS-encrypted TickTick credentials

Files Modified

• api/main.py - Added ticktick router import and registration at /api/ticktick/
• .gitignore - Added **/.tokens.json to prevent token leakage
• .claude/memory/MEMORY.md - Added TickTick integration reference
• .claude/memory/reference_ticktick_integration.md - New memory file with full integration details

Database Changes

• New table: dev_projects (14 columns) with index on status
• First row inserted: "TickTick Integration" project, status=active, linked to TickTick task

Packages Installed

• mcp (v1.26.0) - MCP protocol library for Python
• httpx (v0.28.1) - Async HTTP client
• pydantic (v2.12.5) - Data validation (mcp dependency)
• Tailscale (v1.96.3) - VPN/mesh networking via winget
• Plus ~25 transitive dependencies

---

Pending/Incomplete Tasks

1. Dev projects API service + router - Need api/services/dev_project_service.py and api/routers/dev_projects.py for CRUD on dev_projects table
2. Bidirectional sync logic - Auto-update TickTick when DB status changes and vice versa
3. MCP server testing - Need to restart Claude Code session to load the TickTick MCP server and test tools
4. TickTick folder placement - API can't place "Dev Projects" list inside the "Guru" folder (no folder API). It appears at top level.
5. Existing project backfill - Could add existing dev projects (like the TickTick integration itself) to track history

---

Reference

TickTick API Gotchas

• No webhooks (must poll for changes)
• No search endpoint (filter client-side)
• No folder management API
• Priority values non-sequential: 0=none, 1=low, 3=medium, 5=high
• Task update may need POST or PUT (code tries POST first, falls back to PUT)
• Deletions are permanent via API
• Date format: ISO 8601 with timezone offset

Re-authentication

If tokens expire completely: python mcp-servers/ticktick/ticktick_auth.py (run from bash, not PowerShell)

MCP Tools Available (after session restart)

All prefixed with ticktick_: list_projects, get_project, create_project, update_project, delete_project, create_task, update_task, complete_task, delete_task