azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add TickTick integration, MCP server, and dev project tracking

Browse Source 
New integration with TickTick API for project/task management:
- OAuth 2.0 auth flow (mcp-servers/ticktick/ticktick_auth.py)
- MCP server with 9 tools for Claude Code (ticktick_mcp.py)
- FastAPI service with SOPS vault credentials (api/services/ticktick_service.py)
- JWT-protected REST router at /api/ticktick/ (api/routers/ticktick.py)
- Credentials stored in SOPS vault (services/ticktick.sops.yaml)

Dev project tracking (hybrid TickTick + DB):
- New dev_projects table migration (14 columns, status index)
- TickTick "Dev Projects" list for mobile visibility
- First project seeded: TickTick Integration (linked both sides)

Security: .tokens.json gitignored, token file permissions restricted,
HTML-escaped OAuth callback, SOPS vault (not env vars) for secrets.

Also: Installed Tailscale on ACG-5070 for office network access.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Mike Swanson
2026-03-31 10:08:53 -07:00
parent e34f51fe5d
commit b26e185a80
10 changed files with 2030 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

131
session-logs/2026-03-31-session.md Normal file
View File

@@ -0,0 +1,131 @@
# 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