codegen.ts

import fs from 'fs';
import { jsonSchemaToZod } from 'json-schema-to-zod';
import { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
import path from 'path';
import prettier from 'prettier';

import { ParsedTool, parseOpenApi, ParseOpenApiOpts } from './parser';

type IsActionsEnabledOpt = Array<string> | ((actionName: string) => boolean);

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);
  }
  return isActionsEnabledOpt.includes(actionName);
};

const generateToolInputFromParsedTool = (tool: ParsedTool) => {
  const mergedSchema = JSON.parse(JSON.stringify(tool.inputSchema));
  mergedSchema.properties = {
    ...mergedSchema.properties,
    ...tool.pathParamsSchema?.properties,
    ...tool.queryParamsSchema?.properties,
  };
  mergedSchema.required = [
    ...mergedSchema.required,
    ...(tool.pathParamsSchema?.required ?? []),
    ...(tool.queryParamsSchema?.required ?? []),
  ];

  return `${jsonSchemaToZod(mergedSchema)}.shape`;
};

type CodegenOpts = {
  path?: string;
  document: OpenAPIV3_1.Document | OpenAPIV3.Document | OpenAPIV2.Document;
  isActionsEnabled?: IsActionsEnabledOpt;
  actions?: Record<string, ActionConfig>;
  /**
   * Name of the generated setup function. Defaults to `setupTools`. Override it
   * (e.g. `setupToolsV2`) so a second generated tool set can be imported alongside
   * 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 ?? {}, { nameOverrides: opts.nameOverrides });

  const runtime = fs.readFileSync(path.join(import.meta.dirname, 'runtime.ts'), 'utf8');

  let output: string = `
    /**
     * This file is auto-generated by yarn generate:mcp-tools
     * DO NOT EDIT THIS FILE MANUALLY
     */
  
      import { z } from "zod";
      import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

      ${runtime}\n

      export const ${exportName} = (server: McpServer, opts: OpenAPIToolRuntimeConfigOpts) => {

      const config = new OpenAPIToolRuntimeConfig(opts);

    `;

  tools.forEach((tool) => {
    if (opts.isActionsEnabled && !isActionsEnabled(opts.isActionsEnabled, tool.name)) {
      return;
    }

    // Derive MCP tool annotations from the HTTP method: GET/HEAD are read-only,
    // 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 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 = actionConfig?.description ?? tool.description;

    const toolArgs = [`"${tool.name}"`, `"${description}"`, generateToolInputFromParsedTool(tool)];

    // annotations always carry the derived hint set, so always include them
    toolArgs.push(JSON.stringify(annotations));

    toolArgs.push(`async (args) => {
            return await config.executeToolCall({
                name: "${tool.name}",
                path: "${tool.path}",
                method: "${tool.method.toUpperCase()}",
                input: args,
                pathParamKeys: ${
                  tool.pathParamsSchema
                    ? `[${Object.keys(tool.pathParamsSchema.properties ?? {})
                        .map((r) => `"${r}"`)
                        .join(',')}]`
                    : '[]'
                },
                queryParamKeys: ${
                  tool.queryParamsSchema
                    ? `[${Object.keys(tool.queryParamsSchema.properties ?? {})
                        .map((r) => `"${r}"`)
                        .join(',')}]`
                    : '[]'
                },
              });
        }`);

    output += `server.tool(${toolArgs.join(',')});\n`;
  });

  output += `
    }
    `;

  const formattedOutput = await prettier.format(output, { parser: 'typescript' });

  if (outputPath) {
    fs.writeFileSync(outputPath, formattedOutput);
  }

  return formattedOutput;
};