feat(codegen): derive idempotentHint + openWorldHint, allow per-action annotation overrides (#69)

Author: johnxie

.changeset/wild-hints-complete.md

@@ -0,0 +1,6 @@
+---
+'@taskade/mcp-openapi-codegen': patch
+'@taskade/mcp-server': patch
+---
+
+Generated tools now carry the full MCP annotation set: derived idempotentHint and openWorldHint:false alongside readOnly/destructive hints; per-action overrides supported.

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

@@ -0,0 +1,94 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { describe, expect, it } from 'vitest';
+
+import { codegen } from './codegen';
+
+const document = {
+  openapi: '3.0.0',
+  info: { title: 'Tiny API', version: '1.0.0' },
+  paths: {
+    '/things': {
+      get: { operationId: 'thingList', description: 'List things', responses: {} },
+      post: { operationId: 'thingCreate', description: 'Create a thing', responses: {} },
+    },
+    '/things/{thingId}': {
+      put: { operationId: 'thingUpdate', description: 'Update a thing', responses: {} },
+      delete: { operationId: 'thingDelete', description: 'Delete a thing', responses: {} },
+    },
+  },
+} as OpenAPIV3.Document;
+
+/**
+ * Extracts the annotation hints for a named tool out of the generated
+ * (prettier-formatted) source.
+ */
+const hintsFor = (output: string, toolName: string) => {
+  const chunk = output
+    .split('server.tool(')
+    .find((part) => part.trimStart().startsWith(`"${toolName}"`));
+  expect(chunk, `generated output contains tool ${toolName}`).toBeDefined();
+
+  const hints: Record<string, boolean> = {};
+  for (const key of ['readOnlyHint', 'destructiveHint', 'idempotentHint', 'openWorldHint']) {
+    const match = chunk?.match(new RegExp(`${key}:\\s*(true|false)`));
+    expect(match, `${toolName} carries ${key}`).toBeTruthy();
+    hints[key] = match?.[1] === 'true';
+  }
+  return hints;
+};
+
+describe('codegen derived annotations', () => {
+  it('derives the full MCP hint set from the HTTP method', async () => {
+    const output = await codegen({ document });
+
+    expect(hintsFor(output, 'thingList')).toEqual({
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    });
+    expect(hintsFor(output, 'thingCreate')).toEqual({
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+    });
+    expect(hintsFor(output, 'thingUpdate')).toEqual({
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    });
+    expect(hintsFor(output, 'thingDelete')).toEqual({
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false,
+    });
+  });
+
+  it('lets a per-action config override any derived hint, including to false', async () => {
+    const output = await codegen({
+      document,
+      actions: {
+        // A POST that is actually idempotent (e.g. taskComplete-style actions).
+        thingCreate: { idempotentHint: true },
+        // An explicit `false` override must beat a derived `true`.
+        thingDelete: { destructiveHint: false },
+      },
+    });
+
+    expect(hintsFor(output, 'thingCreate')).toEqual({
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    });
+    expect(hintsFor(output, 'thingDelete')).toEqual({
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    });
+  });
+});

packages/openapi-codegen/src/codegen.ts

@@ -12,8 +12,24 @@ type ActionConfig = Partial<{
   title: string;
   description: string;
   normalizer: (args: any) => any;
+  /**
+   * Explicit MCP annotation overrides. When set, they beat the values derived
+   * from the HTTP method (e.g. a POST action that is actually idempotent can
+   * set `idempotentHint: true`).
+   */
+  readOnlyHint: boolean;
+  destructiveHint: boolean;
+  idempotentHint: boolean;
+  openWorldHint: boolean;
 }>;
 
+const ANNOTATION_HINT_KEYS = [
+  'readOnlyHint',
+  'destructiveHint',
+  'idempotentHint',
+  'openWorldHint',
+] as const;
+
 const isActionsEnabled = (isActionsEnabledOpt: IsActionsEnabledOpt, actionName: string) => {
   if (typeof isActionsEnabledOpt === 'function') {
     return isActionsEnabledOpt(actionName);
@@ -81,23 +97,39 @@ export const codegen = async (opts: CodegenOpts) => {
     }
 
     // Derive MCP tool annotations from the HTTP method: GET/HEAD are read-only,
-    // DELETE is destructive. A human-friendly title can be supplied via opts.actions.
+    // DELETE is destructive, GET/HEAD/PUT/DELETE are idempotent per HTTP
+    // semantics (POST is not). openWorldHint is always false: this server only
+    // talks to the Taskade API — a closed world. A human-friendly title and
+    // explicit hint overrides can be supplied via opts.actions.
     const method = tool.method.toUpperCase();
     const annotations: Record<string, any> = {
       readOnlyHint: method === 'GET' || method === 'HEAD',
       destructiveHint: method === 'DELETE',
+      idempotentHint: ['GET', 'HEAD', 'PUT', 'DELETE'].includes(method),
+      openWorldHint: false,
     };
 
-    const actionTitle = opts.actions?.[tool.name]?.title;
+    const actionConfig = opts.actions?.[tool.name];
+
+    // Explicit per-action overrides beat derived values. Undefined-checked so
+    // an explicit `false` override wins too.
+    for (const hint of ANNOTATION_HINT_KEYS) {
+      const override = actionConfig?.[hint];
+      if (override !== undefined) {
+        annotations[hint] = override;
+      }
+    }
+
+    const actionTitle = actionConfig?.title;
     if (actionTitle) {
       annotations.title = actionTitle;
     }
 
-    const description = opts.actions?.[tool.name]?.description ?? tool.description;
+    const description = actionConfig?.description ?? tool.description;
 
     const toolArgs = [`"${tool.name}"`, `"${description}"`, generateToolInputFromParsedTool(tool)];
 
-    // annotations always carry read-only/destructive hints, so always include them
+    // annotations always carry the derived hint set, so always include them
     toolArgs.push(JSON.stringify(annotations));
 
     toolArgs.push(`async (args) => {