@agentforge-io/connectors-clickup

ClickUp connector for AgentForge. Adds a task toolbelt (list / get / create / update / set status / comment) that any agent can use after the end user has authorized via OAuth2.

Companion design doc: CLICKUP_CONNECTOR_SDD.md at the repo root.

Quickstart

1. Create the ClickUp OAuth app at https://app.clickup.com → Settings → Apps → Create an App.

   • Redirect URL = https://<your-agentforge-host>/connectors/oauth/callback
   • Copy Client ID and Client Secret.

2. Register the connector in your host's bootstrap (or rely on the platform's vault-driven wiring — connectors.module.ts already does this if you set CLICKUP_OAUTH_CLIENT_ID / CLICKUP_OAUTH_CLIENT_SECRET in Settings → Secrets):

   import { clickupConnector } from '@agentforge-io/connectors-clickup';
   
   connectorRegistry.register(clickupConnector({
     clientId: env.CLICKUP_OAUTH_CLIENT_ID,
     clientSecret: env.CLICKUP_OAUTH_CLIENT_SECRET,
   }));

3. End-users authorize via the /connectors directory page in the dashboard. Each user gets their own grant in af_connector_auths — same storage model HubSpot/Google use.

4. Tools light up in the agent editor under a "ClickUp" group. Or just @clickup_create_task from the prompt and the auto-sync wires it for you.

Tools

| Tool | Backend | |---|---| | clickup_list_tasks | GET /api/v2/list/{listId}/task | | clickup_get_task | GET /api/v2/task/{taskId} | | clickup_create_task | POST /api/v2/list/{listId}/task | | clickup_update_task | PUT /api/v2/task/{taskId} | | clickup_set_task_status | PUT /api/v2/task/{taskId} (status only) | | clickup_add_task_comment | POST /api/v2/task/{taskId}/comment |

See the SDD for input/output shapes and rate-limit / error semantics.

Notable deviations from HubSpot/Google

• No refresh tokens. ClickUp issues long-lived access tokens; the af_connector_auths.refresh_token_encrypted column is null for ClickUp rows. On 401 the agent surfaces auth_required and the user reconnects from /connectors.
• No scope parameter. ClickUp tokens carry the authorizing user's workspace access, not OAuth scopes. scopes: [] is correct.
• Bare-token Authorization. ClickUp expects Authorization: <token>, not Authorization: Bearer <token>. The http wrapper hard-codes this.
• Rate-limit header is X-RateLimit-Reset (epoch seconds), not Retry-After. The http wrapper computes the sleep from that with a 30-second cap so tool latency stays bounded.