Add ClickUp plugin: tasks, webhook app, MCP server

[cosmicBboy]

Adds plugins/clickup (flyteplugins-clickup), a ClickUp integration for Flyte 2.

What's included

Read/write from tasks — ClickUpClient, an async REST v2 client covering workspaces, spaces, folders, lists, list statuses, tasks, and comments. 429 rate limits are retried; errors raised as ClickUpAPIError. Credentials come from a mounted flyte.Secret (CLICKUP_TOKEN). Includes the list_statuses pre-check pattern so workflows validate a status against the list's workflow before attempting a transition (ClickUp otherwise fails those with an opaque 400).

React to ClickUp events — ClickUpAppEnvironment serves a setup/management dashboard (/) with end-to-end setup instructions (token creation, flyte create secret commands, ClickUp webhook config) and status/verify endpoints, plus an HMAC-verified webhook receiver (/webhook, x-clickup-signature) that normalizes payloads into ClickUpEvent objects, applies an optional list allowlist, and dispatches to on_event handlers (taskCreated, taskStatusUpdated, taskCommented, ...). launch_task launches runs idempotently via dedupe labels keyed on event + task + ClickUp's event timestamp, so retries dedupe while later updates to the same task produce new keys.

MCP server for agents on Flyte — the read/write surface doubles as MCP tools via build_mcp_server / clickup_mcp_app_env. Read-only by default; read_only=False adds task creation/updates/commenting; include_destructive=True additionally exposes delete_task. Tool annotations come from the registry. Event ingestion is intentionally not an MCP tool — that stays with the app environment.

Tests

57 tests covering the client (respx-mocked, including raw-token auth header and 429 retry), webhook signature verification and event normalization, the MCP tool registry/server, dispatch idempotency, and the app dashboard/receiver endpoints.

Examples

• examples/manage_ticket.py — open/close tickets with status pre-check
• examples/react_to_clickup_events.py — webhook app launching idempotent runs
• examples/clickup_mcp_server.py — MCP server for agents

Review pass

A follow-up commit fixes issues found while reviewing this branch.

Correctness

• list_id falls back to the nested task's list. Task-scoped events carry the list id only there, so the list_ids allowlist could not attribute them.

Robustness and security

• ⚠️ Behavior change: the list_ids allowlist now fails closed. Events it cannot attribute to a list are skipped rather than dispatched, matching the GitHub and Slack plugins. Previously an event with no list id bypassed the allowlist entirely.
• Signatures compare as bytes. hmac.compare_digest raises TypeError on str operands containing non-ASCII, and the signature header is attacker-controlled: ASGI servers hand Starlette raw header bytes which it decodes as latin-1, so a crafted header turned a clean 401 into a 500.
• Retry-After is parsed defensively and clamped at 60s. The header may carry an HTTP-date, which raised ValueError, and a large value would previously have slept unbounded.

Dashboard and docs

• The recent-events table read the 25 oldest events instead of the newest — [:25] on a deque that appends on the right — so it froze after the first 25 events.
• Allowlist values are HTML-escaped like every other interpolated value.
• The _dispatch module docstring said "Slack retries on non-2xx" (copy-paste from the Slack plugin).

4 new tests cover these.

Follow-up: async launching and label-only idempotency

launch_task no longer blocks the app's event loop. It and blocking_run are now async-first, wrapped with flyte's @syncify, so handlers await launch_task.aio(...). Previously the synchronous call stalled the whole event loop for the duration of two control-plane round-trips plus a launch — with every other in-flight webhook queued behind it, against sender timeouts measured in seconds. The synchronous form still works for scripts. A regression test asserts four concurrent launches overlap; against the old blocking call it measures 0.81s instead of 0.42s and fails.

Idempotency is now purely label-based. The run-name allocation is gone — it probed up to 32 candidate names via Run.get before launching under the winner. That raced with concurrent launches, silently capped how many runs one dedupe key could ever have, and treated a name as an identity it never was. Runs now carry only the dedupe=<key> label and the control plane assigns the name. run_name_for, RUN_NAME_MAX, and the prefix / run_name_base arguments are removed.

The dedupe key is explicitly caller-supplied. dedupe_key() is a sensible default, not a requirement — any string chooses a different idempotency scope.

The module docstring is also honest about the residual race: the label check is a read followed by a launch, so two simultaneous deliveries of one event can both launch. Redeliveries are seconds to minutes apart and dedupe reliably; closing the concurrent case needs a compare-and-set the control plane does not expose.

Follow-up: sync and async call forms on ClickUpClient

The 14 client methods are wrapped with flyte's @syncify, so each has two call forms — matching how the SDK itself exposes Run.listall, flyte.run, and flyte.serve:

# async: in `async def` tasks, webhook handlers, MCP tools
async with ClickUpClient() as client:
    result = await client.some_method.aio(...)

# blocking: in plain `def` tasks and scripts
with ClickUpClient() as client:          # note: `with`, not `async with`
    result = client.some_method(...)

__enter__/__exit__ were added so the blocking form is usable at all. They run __aenter__/__aexit__ on syncify's background loop — the same loop the syncified methods run on — so the httpx.AsyncClient is created and used on a single loop rather than straddling two.

Two call sites had to move to .aio() for correctness, not just style. Internal self. calls would otherwise deadlock, since syncify raises on a blocking call made from its own loop thread. And the MCP tool bridge (await getattr(client, name)(...)) would raise TypeError: object dict can't be used in 'await' expression on the returned value — and, had it not raised, would have stalled the MCP server's event loop for the duration of every tool call. Measured: 0 event-loop ticks during one blocking call.

The dynamic sync_*-method alternative was rejected: it works at runtime but both mypy and ty report "ClickUpClient" has no attribute "sync_..." and fall back to Any, so every typed caller breaks. @syncify in place resolves to SyncFunction[[...], ...] in both checkers. The package's mypy error count is unchanged at 12, all pre-existing, none in _client.py.

Tests, examples, and READMEs use .aio() on async paths and document both forms, including when not to reach for the blocking one.

Follow-up: typed event constants

on_event no longer needs hand-copied strings:

from flyteplugins.clickup import events

@app_env.on_event(events.Task.STATUS_UPDATED)
async def handle(event): ...

flyteplugins.clickup.events adds 6 classes / 28 constants, following the ActionPhase pattern in flyte.models — str enums grouped by event type, so a member drops in wherever a pattern string is accepted and a typo fails at import rather than by silently never matching. ClickUp event names are flat, so each class simply groups the events for one kind of object. Raw strings still work, for events the constants do not cover yet.

The enum base pins __str__/__format__ to str's. Without that, Python 3.11+ renders members as Class.MEMBER rather than the wire value — which would have leaked enum names into the dashboard and /api/status, since handler patterns flow into both.

Tests assert the constants equal what the parser actually produces (through the app's own _matches), that every ANY is the bare type its actions prefix, and that no value appears in two classes.

Follow-up: an end-to-end Testing guide

The README now ends with a numbered walkthrough against a real account, ordered so each step fails in isolation — exercise the client standalone before involving the platform, deploy the launched task before the app that looks it up, run it directly before any webhook is in play. Then wire up the provider, trigger a real event, and check the four places evidence lands: the provider's delivery log, /api/events, flyte get runs, and the resource itself. It ends with a troubleshooting table mapping each symptom to its cause, since 401, 503, and "200 but no run" are three different failures.

It also walks through the idempotency behaviour by hand, which is the part unit tests can only simulate.

Writing the guide surfaced a gap and it is fixed here: the triage_task task react_to_clickup_events.py launches was looked up by name but defined nowhere, so anyone following the README end to end would have hit a task-not-found error at the first real event.

Verified mechanically rather than by eye: every referenced example path resolves, every flyte create secret name matches the actual _config.py default, every flyte deploy <file> <env> names a real TaskEnvironment, every flyte run task is defined, and every example file still executes.