Bruno MCP

Instructions

Implementation Reference

• src/runner.ts:14-90 (handler)

  Core handler implementation that constructs and executes the Bruno CLI command to run the collection, handles output via temporary JSON report, parses results, and formats the response with success status, summary, failures, and timings.

  async runCollection(params: RunCollectionParams): Promise<BrunoRunResult> {
    const startTime = new Date();
    
    return withReportFile('bruno-run-', '.json', async (outputFile) => {
      try {
        // Get collection directory and name
        const collectionDir = dirname(params.collection);
        const collectionName = basename(params.collection);
  
        // Build the command with arguments
        const args: string[] = ['cd', collectionDir, '&&', 'bru', 'run', `${collectionName}`];
  
        // Add environment if specified
        if (params.environment) {
          args.push('--env', params.environment);
        }
  
        // Add environment variables if specified
        if (params.variables && params.variables.length > 0) {
          for (const variable of params.variables) {
            args.push('--env-var', variable);
          }
        }
  
        // Add output file
        args.push('--reporter-json', outputFile);
  
        // Skip all headers
        args.push('--reporter-skip-all-headers');
  
        // Execute the command
        const command = args.join(' ');
        console.error('Running command:', command);
        
        try {
          await execAsync(command);
        } catch (error) {
          const cliError = error as { message: string; stderr: string; stdout: string };
          
          if (!cliError.stdout.match(REQUEST_SUMMARY_REGEX)) {
            throw new Error(`CLI stderr: ${cliError.stderr || 'Unknown error'}`);
          }
        }
  
        // Read the results from the output file
        const resultJson = await readFile(outputFile, 'utf-8');
        const endTime = new Date();
        const duration = endTime.getTime() - startTime.getTime();
        const jsonResult = JSON.parse(resultJson);
  
        const { summary, results = [] } = jsonResult[0];
        const isSuccess = summary.failedRequests === 0;
  
        // Transform CLI results into our standard format
        return {
          success: isSuccess,
          summary: {
            total: summary.totalRequests || 0,
            failed: summary.failedRequests || 0,
            passed: summary.passedRequests || 0
          },
          failures: isSuccess ? [] : results.filter((result: any) => result.error).map((failure: any) => ({
            name: failure.suitename || 'Unknown Test',
            message: failure.error || 'Unknown error'
          })),
          timings: {
            started: startTime.toISOString(),
            completed: endTime.toISOString(),
            duration
          }
        };
      } catch (error) {
        console.error('Error running collection:', error);
        throw error;
      }
    });
  }

• src/server.ts:39-63 (handler)

  MCP server request handler for tool calls that dispatches to BrunoRunner.runCollection for the 'run-collection' tool, including argument validation and response formatting.

  this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
    if (name !== "run-collection") {
      throw new Error(`Unknown tool: ${request.params.name}`);
    }
    
    try {
      const result = await this.runner.runCollection(RunCollectionSchema.parse(args));
      return {
        content: [{
            type: "text",
            text: JSON.stringify(result, null, 2)
        }]
      };
    } catch (error) {
      if (error instanceof z.ZodError) {
        throw new Error(
          `Invalid arguments: ${error.errors
            .map((e) => `${e.path.join(".")}: ${e.message}`)
            .join(", ")}`
        ); 
      }
      throw error;
    }
  });

• src/types.ts:22-26 (schema)

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

  export const RunCollectionSchema = z.object({
    collection: z.string().describe("Path to the Bruno collection"),
    environment: z.string().optional().describe("Optional path to environment file"),
    variables: z.array(z.string()).optional().describe("Optional environment variables"),
  });

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

  Registration of the 'run-collection' tool in the MCP server's listTools response.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: "run-collection",
        description: "Run a Bruno Collection using Bruno CLI",
        inputSchema: zodToJsonSchema(RunCollectionSchema)
      }
    ]
  }));

• src/utils.ts:5-29 (helper)

  Helper utility used by the handler to manage temporary JSON report files for Bruno CLI output.

  export async function withReportFile<T>(
    prefix: string,
    extension: string,
    callback: (filePath: string) => Promise<T>
  ): Promise<T> {
    const buildDir = path.join(process.cwd(), 'build', 'reports');
    
    // Create reports directory if it doesn't exist
    if (!fs.existsSync(buildDir)) {
      await fsPromises.mkdir(buildDir, { recursive: true });
    }
  
    const tempFile = path.join(buildDir, `${prefix}${Date.now()}${extension}`);
    
    try {
      return await callback(tempFile);
    } finally {
      // Clean up temp file
      try {
        await fsPromises.unlink(tempFile);
      } catch (error) {
        // Ignore errors during cleanup
      }
    }
  }