updateSpecFile

Instructions

Implementation Reference

• src/tools/updateSpecFile.ts:28-60 (handler)

  The handler function that executes the 'updateSpecFile' tool logic. It makes a PATCH request to `/specs/{specId}/files/{filePath}` with optional name, type, and content fields in the body.

  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 input parameters: specId (string), filePath (string), name (string, optional), type (enum 'DEFAULT'|'ROOT', optional, preprocessed to uppercase), content (string, optional).

  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:1-25 (registration)

  The tool module defines `export const method = 'updateSpecFile'` which serves as the registration identifier. It is imported/registered in enabledResources.ts as part of the full and minimal tool lists.

  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,

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

  The tool name 'updateSpecFile' is listed in the `full` tools array in enabledResources.ts, registering it as an available tool.

  'updateSpecFile',

• src/enabledResources.ts:208-209 (registration)

  The tool name 'updateSpecFile' is also listed in the `minimal` tools array in enabledResources.ts, making it available in the minimal toolset as well.

  'updateSpecFile',
  'updateSpecProperties',