generateSpecFromCollection

Instructions

Implementation Reference

• src/tools/generateSpecFromCollection.ts:31-63 (handler)

  Handler function that generates an API specification from a collection. Makes a POST request to /collections/{collectionUid}/generations/spec with name, type, and format parameters.

  export async function handler(
    args: z.infer<typeof parameters>,
    extra: { client: PostmanAPIClient; headers?: IsomorphicHeaders; serverContext?: ServerContext }
  ): Promise<CallToolResult> {
    try {
      const endpoint = `/collections/${args.collectionUid}/generations/${args.elementType}`;
      const query = new URLSearchParams();
      const url = query.toString() ? `${endpoint}?${query.toString()}` : endpoint;
      const bodyPayload: any = {};
      if (args.name !== undefined) bodyPayload.name = args.name;
      if (args.type !== undefined) bodyPayload.type = args.type;
      if (args.format !== undefined) bodyPayload.format = args.format;
      const options: any = {
        body: JSON.stringify(bodyPayload),
        contentType: ContentType.Json,
        headers: extra.headers,
      };
      const result = await extra.client.post(url, options);
      return {
        content: [
          {
            type: 'text',
            text: `${typeof result === 'string' ? result : JSON.stringify(result, null, 2)}`,
          },
        ],
      };
    } catch (e: unknown) {
      if (e instanceof McpError) {
        throw e;
      }
      throw asMcpError(e);
    }
  }

• src/tools/generateSpecFromCollection.ts:9-22 (schema)

  Zod schema defining input parameters: collectionUid (string), elementType (literal 'spec'), name (string), type (enum OPENAPI:2.0/3.0/3.1 with case-insensitive preprocessing), format (enum JSON/YAML with case-insensitive preprocessing).

  export const parameters = z.object({
    collectionUid: z.string().describe("The collection's unique ID."),
    elementType: z.literal('spec').describe('The `spec` value.'),
    name: z.string().describe("The API specification's name."),
    type: z
      .preprocess(
        (v) => (typeof v === 'string' ? v.toUpperCase() : v),
        z.enum(['OPENAPI:2.0', 'OPENAPI:3.0', 'OPENAPI:3.1'])
      )
      .describe("The specification's type."),
    format: z
      .preprocess((v) => (typeof v === 'string' ? v.toUpperCase() : v), z.enum(['JSON', 'YAML']))
      .describe('The format of the API specification.'),
  });

• src/enabledResources.ts:15-15 (registration)

  Registered in the 'full' tool set list of enabled resources.

  'generateSpecFromCollection',

• src/enabledResources.ts:184-184 (registration)

  Also registered in the 'minimal' tool set list of enabled resources.

  'generateSpecFromCollection',

• src/tools/utils/toolHelpers.ts:10-13 (helper)

  Supporting helper: asMcpError function used by the handler to wrap errors into MCP errors.

  export function asMcpError(error: unknown): McpError {
    const cause = (error as any)?.cause ?? String(error);
    return new McpError(ErrorCode.InternalError, cause);
  }