run-collection

Instructions

Implementation Reference

• src/newman/runner.ts:40-79 (handler)

  Core handler function that executes the Newman CLI to run the Postman collection, processes the run summary and failures into a structured TestResult.

  async runCollection(options: CollectionRunOptions): Promise<TestResult> {
      return new Promise((resolve, reject) => {
          const startTime = new Date().toISOString();
          
          newman.run({
              collection: options.collection,
              environment: options.environment,
              globals: options.globals,
              iterationCount: options.iterationCount,
              reporters: 'cli'
          }, (err, summary) => {
              if (err) {
                  reject(err);
                  return;
              }
  
              const endTime = new Date().toISOString();
              
              // Format the results
              const result: TestResult = {
                  success: summary.run.failures.length === 0,
                  summary: {
                      total: summary.run.stats.tests.total || 0,
                      failed: summary.run.stats.tests.failed || 0,
                      passed: (summary.run.stats.tests.total || 0) - (summary.run.stats.tests.failed || 0)
                  },
                  failures: (summary.run.failures || [])
                      .map(extractFailureInfo)
                      .filter((failure): failure is TestFailure => failure !== null),
                  timings: {
                      started: startTime,
                      completed: endTime,
                      duration: new Date(endTime).getTime() - new Date(startTime).getTime()
                  }
              };
  
              resolve(result);
          });
      });
  }

• src/server/server.ts:69-101 (handler)

  MCP CallToolRequest handler specifically for 'run-collection' tool: validates input, executes NewmanRunner.runCollection, and formats success/error responses.

  this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      if (request.params.name !== "run-collection") {
          throw new Error(`Unknown tool: ${request.params.name}`);
      }
  
      // Validate input
      const args = RunCollectionSchema.parse(request.params.arguments);
  
      try {
          // Run the collection
          const result = await this.runner.runCollection(args);
  
          // Format the response
          return {
              content: [{
                  type: "text",
                  text: JSON.stringify(result, null, 2)
              }]
          };
      } catch (error) {
          const errorMessage = error instanceof Error ? error.message : String(error);
          return {
              content: [{
                  type: "text",
                  text: JSON.stringify({
                      error: errorMessage,
                      success: false
                  }, null, 2)
              }],
              isError: true
          };
      }
  });

• src/server/server.ts:7-12 (schema)

  Zod schema for validating the input arguments to the 'run-collection' tool.

  const RunCollectionSchema = z.object({
      collection: z.string(),
      environment: z.string().optional(),
      globals: z.string().optional(),
      iterationCount: z.number().min(1).optional()
  });

• src/server/server.ts:37-66 (registration)

  Tool registration in ListToolsRequest handler: defines name, description, and JSON inputSchema for 'run-collection'.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
      tools: [
          {
              name: "run-collection",
              description: "Run a Postman Collection using Newman",
              inputSchema: {
                  type: "object",
                  properties: {
                      collection: {
                          type: "string",
                          description: "Path or URL to the Postman collection"
                      },
                      environment: {
                          type: "string",
                          description: "Optional path or URL to environment file"
                      },
                      globals: {
                          type: "string",
                          description: "Optional path or URL to globals file"
                      },
                      iterationCount: {
                          type: "number",
                          description: "Optional number of iterations to run"
                      }
                  },
                  required: ["collection"]
              }
          }
      ]
  }));

• src/newman/runner.ts:7-32 (helper)

  Helper function to safely parse and extract structured failure information from Newman's failure objects.

  function extractFailureInfo(failure: NewmanRunFailure): TestFailure | null {
      try {
          if (!failure.error || !failure.source?.request) {
              return null;
          }
  
          const { error, source } = failure;
          const { request } = source;
  
          // Ensure we have all required properties
          if (!error.test || !error.message || !request.method || !request.url) {
              return null;
          }
  
          return {
              name: error.test,
              error: error.message,
              request: {
                  method: request.method,
                  url: request.url.toString()
              }
          };
      } catch {
          return null;
      }
  }