runCollection

Instructions

Implementation Reference

• src/tools/runCollection.ts:48-69 (handler)

  The main handler function for the runCollection MCP tool. Calls runCollection() from the runner module, which uses Newman to execute a Postman collection and returns output text.

  export async function handler(
    params: z.infer<typeof parameters>,
    extra: { client: PostmanAPIClient; headers?: IsomorphicHeaders; serverContext?: ServerContext }
  ): Promise<CallToolResult> {
    try {
      const output = await runCollection(params, extra.client);
  
      return {
        content: [
          {
            type: 'text',
            text: output,
          },
        ],
      };
    } catch (e: unknown) {
      if (e instanceof McpError) {
        throw e;
      }
      throw asMcpError(e);
    }
  }

• src/tools/runCollection.ts:11-39 (schema)

  Zod schema defining input parameters for runCollection: collectionId (required), environmentId, stopOnError, stopOnFailure, abortOnError, abortOnFailure, iterationCount, requestTimeout, scriptTimeout (all optional).

  export const parameters = z.object({
    collectionId: z
      .string()
      .describe(
        'The collection ID in the format <OWNER_ID>-<UUID> (e.g. 12345-33823532ab9e41c9b6fd12d0fd459b8b).'
      ),
    environmentId: z
      .string()
      .optional()
      .describe('Optional environment ID to use for variable substitution during the run.'),
    stopOnError: z.boolean().optional().describe('Gracefully halt on errors (default: false)'),
    stopOnFailure: z
      .boolean()
      .optional()
      .describe('Gracefully halt on test failures (default: false)'),
    abortOnError: z.boolean().optional().describe('Abruptly halt on errors (default: false)'),
    abortOnFailure: z
      .boolean()
      .optional()
      .describe('Abruptly halt on test failures (default: false)'),
    iterationCount: z.number().optional().describe('Number of iterations to run (default: 1)'),
    requestTimeout: z
      .number()
      .optional()
      .describe('Request timeout in milliseconds (default: 60000)'),
    scriptTimeout: z.number().optional().describe('Script timeout in milliseconds (default: 5000)'),
  });
  
  export type RunCollectionParameters = z.infer<typeof parameters>;

• src/enabledResources.ts:49-50 (registration)

  Registration of 'runCollection' in the full resources list (line 49), minimal resources list (line 215), and excludedFromGeneration list (line 249), marking it as enabled but not auto-generated.

  'runCollection',

• src/tools/runner/index.ts:8-32 (helper)

  The core runCollection orchestrator function that fetches the collection and optional environment from the Postman API, executes via Newman, formats output, and reports telemetry.

  export async function runCollection(
    params: CollectionRunParams,
    client: PostmanAPIClient
  ): Promise<string> {
    const collection = await fetchCollection(params.collectionId, client);
  
    let environment;
    if (params.environmentId) {
      environment = await fetchEnvironment(params.environmentId, client);
    }
  
    const result = await executeCollection({
      collection,
      environment,
      params,
    });
  
    const telemetryPayload = parseToTelemetry(result, params.collectionId, collection.name);
  
    const userOutput = formatUserOutput(result);
  
    reportTelemetryAsync(telemetryPayload, client);
  
    return userOutput;
  }

• src/tools/runner/executor.ts:112-142 (helper)

  The executeCollection function that runs the collection using Newman library, builds options from params, tracks assertions/test results, and produces an ExecutionResult with output, stats, summary, and timing.

  export async function executeCollection(context: ExecutionContext): Promise<ExecutionResult> {
    const tracker = new TestTracker();
    const output = new OutputBuilder();
  
    output.add(`🚀 Starting collection: ${context.collection.name}`);
    if (context.environment) {
      output.add(`🌍 Using environment: ${context.environment.name}\n`);
    }
  
    const newmanOptions = buildNewmanOptions(
      context.params,
      context.collection.json,
      context.environment?.json
    );
  
    const startTime = Date.now();
  
    const summary = await runNewman(newmanOptions, tracker, output);
  
    const endTime = Date.now();
    const durationMs = endTime - startTime;
  
    return {
      output: output.build(),
      testStats: tracker.getTotalStats(),
      summary,
      startTime,
      endTime,
      durationMs,
    };
  }