# 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