merge: inherit #70 review fixes (raw-target-URL webhook descriptions, registry-safe server.json)

Author: johnxie

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

@@ -67,6 +67,27 @@ describe('codegen derived annotations', () => {
     });
   });
 
+  it('lets a per-action config override the LLM-visible description (spec text loses)', async () => {
+    // Pins the mechanism used to fix misleading upstream descriptions (e.g. v2's
+    // getWebhook/deleteWebhook telling callers to pre-URL-encode the id while the
+    // runtime already encodes path params).
+    const output = await codegen({
+      document,
+      actions: {
+        thingDelete: { description: 'Delete a thing by raw id — do NOT URL-encode it.' },
+      },
+    });
+
+    const chunkFor = (toolName: string) =>
+      output.split('server.tool(').find((part) => part.trimStart().startsWith(`"${toolName}"`));
+
+    // Overridden tool carries the override, not the spec description.
+    expect(chunkFor('thingDelete')).toContain('Delete a thing by raw id — do NOT URL-encode it.');
+    expect(chunkFor('thingDelete')).not.toContain('"Delete a thing"');
+    // Tools without an override keep the spec description.
+    expect(chunkFor('thingList')).toContain('"List things"');
+  });
+
   it('lets a per-action config override any derived hint, including to false', async () => {
     const output = await codegen({
       document,

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 — 68 tools: projects, tasks, agents, agent chat, signed webhooks, space bundles.",
+  "description": "Connect Taskade to any AI assistant — 68 tools: projects, tasks, agents, agent chat, webhooks.",
   "repository": {
     "url": "https://github.com/taskade/mcp.git",
     "source": "github"

packages/server/src/constants.v2.ts

@@ -40,11 +40,21 @@ export const HUMANIZED_TASKADE_V2_ACTIONS: Record<TaskadeV2Action, string> = {
 };
 
 // Per-action description overrides (fed to the codegen's ActionConfig.description).
-// Only needed where the spec's summary omits something the model must know.
+// Only needed where the spec's summary omits something the model must know — or,
+// for getWebhook/deleteWebhook, actively misleads: the upstream spec says the id is
+// the webhook's "URL-encoded target URL", but the generated runtime already applies
+// encodeURIComponent to every path param, so a caller that pre-encodes double-encodes
+// the id and the lookup fails. The override tells the model to pass the RAW URL.
 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.',
+  getWebhook:
+    'Get a webhook subscription by id. Pass the webhook’s raw target URL as `id` ' +
+    '— do NOT URL-encode it; encoding is applied automatically.',
+  deleteWebhook:
+    'Delete a webhook subscription by id. Pass the webhook’s raw target URL as `id` ' +
+    '— do NOT URL-encode it; encoding is applied automatically.',
 };

packages/server/src/tools.v2.generated.ts

@@ -405,7 +405,7 @@ export const setupToolsV2 = (server: McpServer, opts: OpenAPIToolRuntimeConfigOp
   );
   server.tool(
     'getWebhook',
-    'Get one registered outbound webhook by id (its URL-encoded target URL)',
+    'Get a webhook subscription by id. Pass the webhook’s raw target URL as `id` — do NOT URL-encode it; encoding is applied automatically.',
     z.object({ id: z.string().min(1) }).shape,
     {
       readOnlyHint: true,
@@ -427,7 +427,7 @@ export const setupToolsV2 = (server: McpServer, opts: OpenAPIToolRuntimeConfigOp
   );
   server.tool(
     'deleteWebhook',
-    'Delete a registered outbound webhook by id (its URL-encoded target URL)',
+    'Delete a webhook subscription by id. Pass the webhook’s raw target URL as `id` — do NOT URL-encode it; encoding is applied automatically.',
     z.object({ id: z.string().min(1) }).shape,
     {
       readOnlyHint: false,