updateSpecFile

Instructions

Implementation Reference

• src/tools/updateSpecFile.ts:1-61 (handler)

  Main handler implementation for updateSpecFile tool. Makes a PATCH request to /specs/{specId}/files/{filePath} with optional name, type, and content parameters. Validates type as 'DEFAULT' or 'ROOT' using zod schema.

  import { z } from 'zod';
  import { PostmanAPIClient, ContentType } from '../clients/postman.js';
  import { IsomorphicHeaders, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
  import { ServerContext, asMcpError, McpError } from './utils/toolHelpers.js';
  
  export const method = 'updateSpecFile';
  export const description =
    "Updates an API specification's file.\n\n**Note:**\n\n- This endpoint does not accept an empty request body. You must pass one of the accepted values.\n- This endpoint does not accept multiple request body properties in a single call. For example, you cannot pass both the \\`content\\` and \\`type\\` property at the same time.\n- Multi-file specifications can only have one root file.\n- When updating a file type to \\`ROOT\\`, the previous root file is updated to the \\`DEFAULT\\` file type.\n- Files cannot exceed a maximum of 10 MB in size.\n";
  export const parameters = z.object({
    specId: z.string().describe("The spec's ID."),
    filePath: z.string().describe('The path to the file.'),
    name: z.string().describe("The file's name.").optional(),
    type: z
      .preprocess((v) => (typeof v === 'string' ? v.toUpperCase() : v), z.enum(['DEFAULT', 'ROOT']))
      .describe(
        'The type of file:\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'
      )
      .optional(),
    content: z.string().describe("The specification's stringified contents.").optional(),
  });
  export const annotations = {
    title: "Updates an API specification's file.",
    readOnlyHint: false,
    destructiveHint: false,
    idempotentHint: true,
  };
  
  export async function handler(
    args: z.infer<typeof parameters>,
    extra: { client: PostmanAPIClient; headers?: IsomorphicHeaders; serverContext?: ServerContext }
  ): Promise<CallToolResult> {
    try {
      const endpoint = `/specs/${args.specId}/files/${args.filePath}`;
      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.content !== undefined) bodyPayload.content = args.content;
      const options: any = {
        body: JSON.stringify(bodyPayload),
        contentType: ContentType.Json,
        headers: extra.headers,
      };
      const result = await extra.client.patch(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/updateSpecFile.ts:9-20 (schema)

  Zod schema defining the input parameters: specId (string), filePath (string), name (optional string), type (optional enum DEFAULT|ROOT with case preprocessing), content (optional string).

  export const parameters = z.object({
    specId: z.string().describe("The spec's ID."),
    filePath: z.string().describe('The path to the file.'),
    name: z.string().describe("The file's name.").optional(),
    type: z
      .preprocess((v) => (typeof v === 'string' ? v.toUpperCase() : v), z.enum(['DEFAULT', 'ROOT']))
      .describe(
        'The type of file:\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'
      )
      .optional(),
    content: z.string().describe("The specification's stringified contents.").optional(),
  });

• src/tools/updateSpecFile.ts:21-26 (helper)

  Annotations for the tool: title, readOnlyHint, destructiveHint, idempotentHint.

  export const annotations = {
    title: "Updates an API specification's file.",
    readOnlyHint: false,
    destructiveHint: false,
    idempotentHint: true,
  };

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

  Registered in the 'full' enabled resources list (line 106).

  'updateSpecFile',

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

  Also registered in the 'minimal' enabled resources list (line 195).

  'updateSpecFile',