feat(server): add Taskade API v2 tool layer — agent chat + webhooks

[johnxie]

Ports Taskade API v2 into the MCP server as an additive layer next to v1. This is the capability gap that matters: v1 can't do agent chat or webhooks; v2 can.

What you can now do from Claude/Cursor

• Chat with an AI agent — promptAgent, listConversations, getConversation
• Real-time events — subscribeWebhook, unsubscribeWebhook

How (least-effort, zero-regression)

• v2 is registered via a second setupToolsV2(this, { url: '…/api/v2', … }) after the existing v1 setupTools — v1's 57 tools are byte-identical (verified zero drift).
• codegen gains an exportName option (default setupTools) so the two generated tool sets coexist without an export collision.
• gen-taskade-mcp-tools-v2.ts reads the committed taskade-public.v2.json, prunes to the enabled ops + their reachable schemas before dereferencing — sidestepping a broken self-$ref in the v2 Field schema that otherwise crashes dereference(). (Upstream spec bug; remove the prune-workaround once fixed.)
• Relies on the operationId→path fallback from feat(codegen): derive tool name from path when operationId is absent #53 (v2 ops have no operationId).

Verification (local)

build + lint + vitest: green
smoke: 62 tools register = 57 v1 + 5 v2
v2 present: promptAgent, listConversations, getConversation, subscribeWebhook, unsubscribeWebhook
v1 intact:  taskCreate, taskDelete, workspacesGet  ·  v1 tools.generated.ts drift: NONE

Scope / follow-ups

• Out of scope (need runtime work): binary GET endpoints (export/zip, media content) and raw-body uploads (uploadMedia, importBundleZip).
• Enabled set is intentionally small (highest-value first); grows as v2 leaves beta.

Stacked on

• Base is feat(codegen): derive tool name from path when operationId is absent #53 (codegen operationId fallback). Will retarget to main when feat(codegen): derive tool name from path when operationId is absent #53 merges.

[changeset-bot]

🦋 Changeset detected

Latest commit: bbd3230

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@taskade/mcp-server	Minor
@taskade/mcp-openapi-codegen	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[johnxie]

Review follow-up — multi-agent review (1 critical found + fixed)

Ran /pr-review-toolkit:review-pr (code-reviewer, silent-failure-hunter, type-design-analyzer) and the /code-review 5-agent scored pass. cc @deanzaka @lxcid.

One critical issue was found and fixed in-branch; the PR is now clean.

Critical — fixed in 6141019

promptAgent (the flagship "chat with an AI agent" tool) was registering with an empty input schema (z.object({}).shape) — the model couldn't pass prompt / agentId / spaceId, so every call would fail at the API. Root cause: the v2 spec marks the promptAgent request body "nullable": true, which convertOpenApiSchemaToJsonSchema rewrites to type: ['object','null']; the strict bodySchema.type === 'object' guard in the shared parser then skipped the property-copy loop. Fix: accept an object type whether scalar or in a nullable union (found independently by two reviewers).

parser.ts fix → promptAgent now exposes { spaceId, agentId, prompt }.

Because the fix is in the shared codegen path, I re-verified v1: tools.generated.ts is byte-identical (no v1 request body is a nullable object), and CI's full-tree verify gate is green.

Hardening applied from the same review

• Loud-fail on allow-list drift — the v2 generator now throws if an ENABLED_TASKADE_V2_ACTIONS entry has no matching spec path (previously a silent under-generation). gen-taskade-mcp-tools-v2.ts
• Type-enforced sync — HUMANIZED_TASKADE_V2_ACTIONS is keyed to the allow-list union, so a missing/typo'd title is now a compile error. constants.v2.ts
• Clearer dereference error for the known upstream Field self-$ref, plus a doc-comment fix and 3 new parser tests (nullable body, kebab/snake, empty description).

Deferred — out of scope (pre-existing, affects v1 too)

The shared runtime returns non-2xx API responses as successful tool results (no response.ok check, no isError). This predates v2 and applies to all 57 v1 tools; v2's promptAgent normalizer just makes it more visible. Recommend a separate PR to gate on response.ok and set isError once in the runtime so both tool sets benefit — flagging it here rather than folding it in, to keep this PR strictly zero-regression.

Verified

57 v1 + 5 v2 = 62 tools register · v1 tools.generated.ts byte-identical · 13 unit tests pass · lint + CI Verify green.