createSpec

Instructions

Implementation Reference

• src/tools/createSpec.ts:61-94 (handler)

  The handler function that executes the createSpec tool logic. It POSTs to the /specs endpoint with workspaceId, name, type, and files to create an API specification in Postman's Spec Hub.

  export async function handler(
    args: z.infer<typeof parameters>,
    extra: { client: PostmanAPIClient; headers?: IsomorphicHeaders; serverContext?: ServerContext }
  ): Promise<CallToolResult> {
    try {
      const endpoint = `/specs`;
      const query = new URLSearchParams();
      if (args.workspaceId !== undefined) query.set('workspaceId', String(args.workspaceId));
      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.files !== undefined) bodyPayload.files = args.files;
      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/createSpec.ts:9-52 (schema)

  Input schema for createSpec defined using Zod. Requires workspaceId (string), name (string), type (enum of OpenAPI/AsyncAPI/Protobuf/GraphQL versions), and files (array of file objects with path, content, optional type).

  export const parameters = z.object({
    workspaceId: z.string().describe("The workspace's ID."),
    name: z.string().describe("The specification's name."),
    type: z
      .preprocess(
        (v) => (typeof v === 'string' ? v.toUpperCase() : v),
        z.enum([
          'OPENAPI:2.0',
          'OPENAPI:3.0',
          'OPENAPI:3.1',
          'ASYNCAPI:2.0',
          'PROTOBUF:2',
          'PROTOBUF:3',
          'GRAPHQL',
        ])
      )
      .describe("The specification's type."),
    files: z
      .array(
        z.union([
          z.object({
            path: z
              .string()
              .describe("The file's path. Accepts .json, .yaml, .proto and .graphql file types."),
            content: z.string().describe("The file's stringified contents."),
            type: z
              .preprocess(
                (v) => (typeof v === 'string' ? v.toUpperCase() : v),
                z.enum(['DEFAULT', 'ROOT'])
              )
              .describe(
                'The type of file. This property is required when creating multi-file specifications:\n- `ROOT` — The file containing the full OpenAPI structure. This serves as the entry point for the API spec and references other (`DEFAULT`) spec files. Multi-file specs can only have one root file.\n- `DEFAULT` — A file referenced by the `ROOT` file.\n'
              ),
          }),
          z.object({
            path: z
              .string()
              .describe("The file's path. Accepts .json, .yaml, .proto and .graphql file types."),
            content: z.string().describe("The file's stringified contents."),
          }),
        ])
      )
      .describe("A list of the specification's files and their contents."),
  });

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

  Registration of 'createSpec' in the 'full' tools list in enabledResources.

  'createSpec',

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

  Registration of 'createSpec' in the 'minimal' tools list in enabledResources.

  'createSpec',

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

  Helper utilities used by createSpec handler: asMcpError for error wrapping and ServerContext type definition.

  import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
  
  export { McpError };
  
  export interface ServerContext {
    serverType: 'full' | 'minimal' | 'code';
    availableTools: string[];
  }
  
  export function asMcpError(error: unknown): McpError {
    const cause = (error as any)?.cause ?? String(error);
    return new McpError(ErrorCode.InternalError, cause);
  }