feat(server): signed webhook management tools — create/list/get/delete (62 → 66)

Refresh taskade-public.v2.json from the live spec (45 → 47 paths; adds the
signed-webhook CRUD from upstream v6.213.0) and expose it as four new v2
tools: createWebhook, listWebhooks, getWebhook, deleteWebhook.

These REST-shaped ops omit operationId and their path-derived names would
all collide as 'webhooks' (deriveToolName drops {param} segments and
ignores the method), so the codegen/parser gains an explicit nameOverrides
map keyed by '<lowercase-method> <path>'; the v2 gen script supplies the
four overrides and its prune matcher now mirrors the codegen's
override -> operationId -> derived resolution order.

createWebhook's description surfaces the HMAC reality: the signing secret
is returned exactly once and must be stored securely.

Author: johnxie

.changeset/lazy-webhooks-sign.md

@@ -0,0 +1,5 @@
+---
+'@taskade/mcp-openapi-codegen': minor
+---
+
+New `nameOverrides` codegen/parser option: explicit tool-name overrides keyed by `"<lowercase-method> <path>"` (e.g. `'post /webhooks': 'createWebhook'`). An override beats both `operationId` and the path-derived fallback, disambiguating REST-shaped operations without `operationId` whose derived names would collide (`POST/GET /webhooks`, `GET/DELETE /webhooks/{id}` all derive to `webhooks`). The parser (`parseOpenApi`, `deriveToolName`) is now exported from the package root.

.changeset/many-webhooks-crud.md

@@ -0,0 +1,5 @@
+---
+'@taskade/mcp-server': minor
+---
+
+Four new signed-webhook management tools from Taskade API v2 (upstream v6.213.0 "Signed Webhooks"): `createWebhook`, `listWebhooks`, `getWebhook`, `deleteWebhook` — 62 → 66 tools. `createWebhook`'s description warns that the HMAC signing secret is returned exactly once and must be stored securely. The legacy unsigned `subscribeWebhook`/`unsubscribeWebhook` remain available but are deprecated upstream.

README.md

@@ -13,7 +13,7 @@
 [![Add to Cursor](https://img.shields.io/badge/Add_to-Cursor-0098FF?style=flat-square)](cursor://anysphere.cursor-deeplink/mcp/install?name=taskade&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB0YXNrYWRlL21jcC1zZXJ2ZXIiXSwiZW52Ijp7IlRBU0tBREVfQVBJX0tFWSI6InlvdXItYXBpLWtleS1oZXJlIn19)
 [![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-007ACC?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22taskade%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40taskade%2Fmcp-server%22%5D%2C%22env%22%3A%7B%22TASKADE_API_KEY%22%3A%22%24%7Binput%3Ataskade_api_key%7D%22%7D%7D)
 
-**62 tools** for workspaces, projects, tasks, AI agents, agent chat, webhooks, knowledge bases, templates, media, and sharing — all from your AI client.
+**66 tools** for workspaces, projects, tasks, AI agents, agent chat, webhooks, knowledge bases, templates, media, and sharing — all from your AI client.
 
 </div>
 
@@ -26,7 +26,7 @@
 
 - [Demo](#demo)
 - [Quick Start](#quick-start)
-- [Tools (62)](#tools-62)
+- [Tools (66)](#tools-66)
 - [Why Taskade MCP?](#why-taskade-mcp)
 - [Agent Recipes](#agent-recipes)
 - [Use Cases](#use-cases)
@@ -169,7 +169,7 @@ The server starts at `http://localhost:3000` (configure with `PORT` env var). Co
 
 ---
 
-## Tools (62)
+## Tools (66)
 
 ### Workspaces
 
@@ -274,8 +274,14 @@ Capabilities the v1 API doesn't have: hold a live conversation with an AI agent,
 | `promptAgent` | Send a message to an AI agent and get its reply |
 | `listConversations` | List an agent's conversations |
 | `getConversation` | Get a conversation's messages |
-| `subscribeWebhook` | Subscribe to real-time Taskade event webhooks |
-| `unsubscribeWebhook` | Remove a webhook subscription |
+| `createWebhook` | Register a signed (HMAC) webhook for one or more events |
+| `listWebhooks` | List your registered signed webhooks |
+| `getWebhook` | Get a signed webhook by id |
+| `deleteWebhook` | Delete a signed webhook |
+| `subscribeWebhook` | Subscribe to event webhooks (legacy, unsigned — prefer `createWebhook`) |
+| `unsubscribeWebhook` | Remove a legacy webhook subscription |
+
+> **Warning:** `createWebhook` returns the HMAC signing secret exactly **once** — it cannot be retrieved again (not even via `getWebhook`). Store it securely before doing anything else; you need it to verify the signatures on incoming deliveries.
 
 ---
 
@@ -293,7 +299,7 @@ Taskade MCP gives your AI assistant **access to your workspace** — projects, t
                          ↓
   ┌──────────────────────────────────┐
   │     Taskade MCP Server           │
-  │     (62 tools, 8 categories)     │
+  │     (66 tools, 8 categories)     │
   └──────────────────────────────────┘
        ↓              ↓            ↓
   folderCreateAgent  agentKnowledge  agentPublicAccess
@@ -320,7 +326,7 @@ Taskade MCP gives your AI assistant **access to your workspace** — projects, t
 
 ### Why Taskade MCP Over Other MCP Servers?
 
-Taskade is the only MCP server that includes **AI agent management** (create, train, deploy agents), **knowledge base training** (attach docs, projects, media), and **OpenAPI codegen** (generate MCP tools from any API spec). 62 tools across 8 categories.
+Taskade is the only MCP server that includes **AI agent management** (create, train, deploy agents), **knowledge base training** (attach docs, projects, media), and **OpenAPI codegen** (generate MCP tools from any API spec). 66 tools across 8 categories.
 
 ---
 

packages/openapi-codegen/src/codegen.ts

@@ -4,7 +4,7 @@ import { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 import path from 'path';
 import prettier from 'prettier';
 
-import { ParsedTool, parseOpenApi } from './parser';
+import { ParsedTool, parseOpenApi, ParseOpenApiOpts } from './parser';
 
 type IsActionsEnabledOpt = Array<string> | ((actionName: string) => boolean);
 
@@ -64,13 +64,20 @@ type CodegenOpts = {
    * the first without an export-name collision.
    */
   exportName?: string;
+  /**
+   * Explicit tool-name overrides keyed by `"<lowercase-method> <path>"` — see
+   * `ParseOpenApiOpts.nameOverrides`. Use for operations without `operationId`
+   * whose path-derived names would collide (REST siblings like `GET /webhooks`
+   * and `GET /webhooks/{id}`).
+   */
+  nameOverrides?: ParseOpenApiOpts['nameOverrides'];
 };
 
 export const codegen = async (opts: CodegenOpts) => {
   const { document, path: outputPath } = opts;
   const exportName = opts.exportName ?? 'setupTools';
 
-  const tools = parseOpenApi(document.paths ?? {});
+  const tools = parseOpenApi(document.paths ?? {}, { nameOverrides: opts.nameOverrides });
 
   const runtime = fs.readFileSync(path.join(import.meta.dirname, 'runtime.ts'), 'utf8');
 

packages/openapi-codegen/src/index.ts

@@ -1 +1,2 @@
 export * from './codegen';
+export * from './parser';

packages/openapi-codegen/src/parser.test.ts

@@ -23,6 +23,15 @@ describe('deriveToolName', () => {
     expect(deriveToolName('get', '/')).toBe('get');
     expect(deriveToolName('POST', '/{id}')).toBe('post');
   });
+
+  it('collides for REST siblings: {param} segments dropped, method ignored (the nameOverrides hazard)', () => {
+    // Pins the hazard that motivates nameOverrides: without an override, all four
+    // signed-webhook CRUD ops would emit the same tool name.
+    expect(deriveToolName('post', '/webhooks')).toBe('webhooks');
+    expect(deriveToolName('get', '/webhooks')).toBe('webhooks');
+    expect(deriveToolName('get', '/webhooks/{id}')).toBe('webhooks');
+    expect(deriveToolName('delete', '/webhooks/{id}')).toBe('webhooks');
+  });
 });
 
 describe('parseOpenApi name resolution', () => {
@@ -87,4 +96,60 @@ describe('parseOpenApi name resolution', () => {
     ]);
     expect(tools[0].inputSchema.required).toEqual(['spaceId', 'agentId', 'prompt']);
   });
+
+  it('applies nameOverrides keyed by "<lowercase-method> <path>" to disambiguate REST siblings', () => {
+    const tools = parseOpenApi(
+      {
+        '/webhooks': {
+          post: { summary: 'Register a signed webhook', responses: {} },
+          get: { summary: 'List signed webhooks', responses: {} },
+        },
+        '/webhooks/{id}': {
+          get: { summary: 'Get a signed webhook', responses: {} },
+          delete: { summary: 'Delete a signed webhook', responses: {} },
+        },
+      } as never,
+      {
+        nameOverrides: {
+          'post /webhooks': 'createWebhook',
+          'get /webhooks': 'listWebhooks',
+          'get /webhooks/{id}': 'getWebhook',
+          'delete /webhooks/{id}': 'deleteWebhook',
+        },
+      },
+    );
+    expect(tools.map((t) => t.name).sort()).toEqual([
+      'createWebhook',
+      'deleteWebhook',
+      'getWebhook',
+      'listWebhooks',
+    ]);
+  });
+
+  it('without nameOverrides, REST siblings all fall back to the same derived name (collision pinned)', () => {
+    const tools = parseOpenApi({
+      '/webhooks': {
+        post: { responses: {} },
+        get: { responses: {} },
+      },
+      '/webhooks/{id}': {
+        get: { responses: {} },
+        delete: { responses: {} },
+      },
+    } as never);
+    expect(tools.map((t) => t.name)).toEqual(['webhooks', 'webhooks', 'webhooks', 'webhooks']);
+  });
+
+  it('an explicit override beats operationId; unkeyed operations are unaffected', () => {
+    const tools = parseOpenApi(
+      {
+        '/projects': {
+          post: { operationId: 'projectCreate', responses: {} },
+          get: { operationId: 'projectsList', responses: {} },
+        },
+      } as never,
+      { nameOverrides: { 'post /projects': 'createProject' } },
+    );
+    expect(tools.map((t) => t.name).sort()).toEqual(['createProject', 'projectsList']);
+  });
 });

packages/openapi-codegen/src/parser.ts

@@ -21,13 +21,28 @@ export type ParsedTool = {
   outputSchema: IJsonSchema;
 };
 
+export type ParseOpenApiOpts = {
+  /**
+   * Explicit tool-name overrides keyed by `"<lowercase-method> <path>"`, e.g.
+   * `{ 'post /webhooks': 'createWebhook' }`. An override wins over both
+   * `operationId` and the path-derived fallback. Needed for REST-shaped specs
+   * without `operationId`, where `deriveToolName` drops `{param}` segments and
+   * ignores the HTTP method — all four of `POST /webhooks`, `GET /webhooks`,
+   * `GET /webhooks/{id}` and `DELETE /webhooks/{id}` would otherwise collide
+   * as `webhooks`.
+   */
+  nameOverrides?: Record<string, string>;
+};
+
 /**
  * Derive a stable camelCase tool name from an operation's path when the spec omits
  * `operationId` — e.g. Taskade API v2's flat RPC routes (`POST /promptAgent`). Path
  * params (`{id}`) are dropped and remaining segments are camelCased
  * (`/media/{mediaId}/content` → `mediaContent`). Falls back to the HTTP method for a
  * root or param-only path (`/`, `/{id}`). Specs that DO provide `operationId` (e.g.
- * Taskade v1) are unaffected.
+ * Taskade v1) are unaffected. NOTE: because `{param}` segments are dropped and the
+ * method is ignored, sibling REST routes (`GET /webhooks` vs `GET /webhooks/{id}`)
+ * collide — disambiguate those via `ParseOpenApiOpts.nameOverrides`.
  */
 export const deriveToolName = (method: string, path: string): string => {
   const words = path
@@ -52,6 +67,7 @@ export const deriveToolName = (method: string, path: string): string => {
 
 export const parseOpenApi = (
   paths: OpenAPIV3_1.PathsObject | OpenAPIV3.PathsObject | OpenAPIV2.PathsObject,
+  opts: ParseOpenApiOpts = {},
 ): ParsedTool[] => {
   const tools: ParsedTool[] = [];
 
@@ -166,7 +182,10 @@ export const parseOpenApi = (
       }
 
       tools.push({
-        name: operation.operationId ?? deriveToolName(method, path),
+        name:
+          opts.nameOverrides?.[`${method.toLowerCase()} ${path}`] ??
+          operation.operationId ??
+          deriveToolName(method, path),
         method: method,
         path: path,
         description: operation.description ?? operation.summary ?? '',

packages/server/scripts/gen-taskade-mcp-tools-v2.ts

@@ -1,12 +1,41 @@
 import { dereference } from '@readme/openapi-parser';
-import { codegen } from '@taskade/mcp-openapi-codegen';
+import { codegen, deriveToolName } from '@taskade/mcp-openapi-codegen';
 import fs from 'fs';
 
-import { ENABLED_TASKADE_V2_ACTIONS, HUMANIZED_TASKADE_V2_ACTIONS } from '../src/constants.v2';
+import {
+  ENABLED_TASKADE_V2_ACTIONS,
+  HUMANIZED_TASKADE_V2_ACTIONS,
+  TASKADE_V2_ACTION_DESCRIPTIONS,
+  TaskadeV2Action,
+} from '../src/constants.v2';
 
-// Taskade API v2 is a flat RPC API whose operations omit `operationId`; the codegen
-// derives tool names from the path (e.g. POST /promptAgent -> "promptAgent").
-const deriveName = (p: string) => p.replace(/^\//, '').split('/')[0];
+// Taskade API v2 is mostly a flat RPC API whose operations omit `operationId`; the
+// codegen derives tool names from the path (e.g. POST /promptAgent -> "promptAgent").
+// The signed-webhook CRUD (upstream v6.213.0) is the exception: REST-shaped routes
+// where path-derived naming would collide (POST/GET /webhooks and GET/DELETE
+// /webhooks/{id} all derive to "webhooks"), so those get explicit name overrides,
+// keyed by "<lowercase-method> <path>".
+const NAME_OVERRIDES: Record<string, string> = {
+  'post /webhooks': 'createWebhook',
+  'get /webhooks': 'listWebhooks',
+  'get /webhooks/{id}': 'getWebhook',
+  'delete /webhooks/{id}': 'deleteWebhook',
+};
+
+const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace']);
+
+// Tool names a path item will produce, mirroring the codegen's resolution order
+// (override -> operationId -> derived) so the prune allow-list matcher below cannot
+// drift from the names the codegen actually emits.
+const toolNamesForPath = (p: string, item: object): string[] =>
+  Object.entries(item)
+    .filter(([m]) => HTTP_METHODS.has(m.toLowerCase()))
+    .map(
+      ([m, op]) =>
+        NAME_OVERRIDES[`${m.toLowerCase()} ${p}`] ??
+        (op as { operationId?: string }).operationId ??
+        deriveToolName(m, p),
+    );
 
 // Why prune before dereferencing: the live v2 spec currently has a broken self-$ref
 // inside components.schemas.Field (data.fillerConfig...sourceRef) that makes a full
@@ -19,9 +48,10 @@ const pruneToEnabled = (doc: any) => {
   const paths: Record<string, unknown> = {};
   const matched = new Set<string>();
   for (const [p, ms] of Object.entries(doc.paths ?? {})) {
-    if (enabled.has(deriveName(p))) {
+    const enabledNames = toolNamesForPath(p, ms as object).filter((name) => enabled.has(name));
+    if (enabledNames.length > 0) {
       paths[p] = ms;
-      matched.add(deriveName(p));
+      enabledNames.forEach((name) => matched.add(name));
     }
   }
 
@@ -79,13 +109,17 @@ try {
 }
 
 const actions = Object.fromEntries(
-  Object.entries(HUMANIZED_TASKADE_V2_ACTIONS).map(([name, title]) => [name, { title }]),
+  Object.entries(HUMANIZED_TASKADE_V2_ACTIONS).map(([name, title]) => [
+    name,
+    { title, description: TASKADE_V2_ACTION_DESCRIPTIONS[name as TaskadeV2Action] },
+  ]),
 );
 
 await codegen({
   path: 'src/tools.v2.generated.ts',
   document: document as never,
   isActionsEnabled: [...ENABLED_TASKADE_V2_ACTIONS],
   actions,
+  nameOverrides: NAME_OVERRIDES,
   exportName: 'setupToolsV2',
 });

packages/server/server.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.taskade/mcp-server",
-  "description": "Connect Taskade to any AI assistant — 62 tools: projects, tasks, agents, agent chat, webhooks.",
+  "description": "Connect Taskade to any AI assistant — 66 tools: projects, tasks, agents, agent chat, signed webhooks.",
   "repository": {
     "url": "https://github.com/taskade/mcp.git",
     "source": "github"

packages/server/src/constants.v2.ts

@@ -14,6 +14,13 @@ export const ENABLED_TASKADE_V2_ACTIONS = [
   // Real-time events
   'subscribeWebhook',
   'unsubscribeWebhook',
+  // Signed webhooks (HMAC) — upstream v6.213.0; these ops omit operationId AND
+  // share paths (/webhooks, /webhooks/{id}), so their names come from the
+  // nameOverrides map in scripts/gen-taskade-mcp-tools-v2.ts, not the path.
+  'createWebhook',
+  'listWebhooks',
+  'getWebhook',
+  'deleteWebhook',
 ] as const;
 
 export type TaskadeV2Action = (typeof ENABLED_TASKADE_V2_ACTIONS)[number];
@@ -26,4 +33,18 @@ export const HUMANIZED_TASKADE_V2_ACTIONS: Record<TaskadeV2Action, string> = {
   getConversation: 'Get Agent Conversation',
   subscribeWebhook: 'Subscribe to a Webhook',
   unsubscribeWebhook: 'Unsubscribe from a Webhook',
+  createWebhook: 'Create a Signed Webhook',
+  listWebhooks: 'List Signed Webhooks',
+  getWebhook: 'Get a Signed Webhook',
+  deleteWebhook: 'Delete a Signed Webhook',
+};
+
+// Per-action description overrides (fed to the codegen's ActionConfig.description).
+// Only needed where the spec's summary omits something the model must know.
+export const TASKADE_V2_ACTION_DESCRIPTIONS: Partial<Record<TaskadeV2Action, string>> = {
+  createWebhook:
+    'Register a signed outbound webhook for one or more Taskade events. ' +
+    'The response includes the HMAC signing secret exactly ONCE — it cannot be ' +
+    'retrieved again later, so store it securely (e.g. a secret manager) before ' +
+    'doing anything else.',
 };