# Bruno MCP Server

An MCP (Model Context Protocol) server that intelligently generates and maintains Bruno API test collections. Automatically create comprehensive test suites for CRUD JSON APIs by simply telling Claude about your endpoints.

## Overview

The Bruno MCP Server bridges the gap between API development and testing by enabling LLMs to generate valid, maintainable Bruno collections. Instead of manually writing API tests, developers describe their API changes and the server generates ready-to-run test collections that validate the behavior.

**Current Focus**: CRUD JSON APIs with environment-based URL configuration.

## Features

### MVP (Minimum Viable Product)

- **Auto-Generate Tests for Endpoint Changes**
  - New endpoints: Create tests that validate successful behavior
  - Updated endpoints: Create tests for modified behavior
  - Removed endpoints: Create tests that validate endpoints return expected error responses

- **Environment-Driven Configuration**
  - Single environment variable (`BRUNO_API_URL`) for base URL
  - Support both localhost development and remote endpoints
  - Generated collections inherit the environment configuration

- **Best Practice Alignment**
  - Server leverages Bruno documentation for test patterns
  - Follows API testing conventions
  - Generates human-readable, maintainable collections

- **Incremental Complexity**
  - MVP handles straightforward CRUD operations
  - Foundation for future enhancements (auth, complex assertions, workflows, etc.)

## Quick Start

### Installation

```bash
git clone <this-repo>
cd bruno-mcp-server
npm install
npm run build
```

### Running the server

The server communicates over stdio (standard MCP transport):

```bash
npm start
# or directly:
node dist/index.js
```

### Configuring in Roo Code

Roo Code (and other MCP clients) launch the server as a subprocess and talk to it
over stdio. Add an entry to Roo Code's MCP settings (`mcp settings.json` /
`.roo/mcp.json`, depending on scope):

```json
{
  "mcpServers": {
    "bruno": {
      "command": "node",
      "args": ["/absolute/path/to/bruno-mcp-server/dist/index.js"]
    }
  }
}
```

No environment variables are required to start the server itself — the
`BRUNO_API_URL` value lives inside the generated Bruno environment file
(`environments/development.bru`) so it can differ per collection and be edited
directly in Bruno.

### Usage Example

From Roo Code, ask the assistant to use the `generate_bruno_test` tool, e.g.:

```
"I just added a POST /users endpoint that creates a new user.
It accepts {name, email} and returns the created user with an id.
Generate a Bruno test for it in ./bruno"
```

This calls the tool with arguments like:

```json
{
  "collectionPath": "./bruno",
  "name": "create-user",
  "changeType": "new",
  "method": "post",
  "path": "/users",
  "description": "Create a new user",
  "requestBody": { "name": "Test User", "email": "test@example.com" }
}
```

The server will:
1. Create the Bruno collection scaffold (`.bruno/bruno.json`,
   `environments/development.bru`) if it doesn't already exist
2. Write a new `.bru` request file with the appropriate method, URL
   (using `{{BRUNO_API_URL}}`), body, and status assertion
3. For `changeType: "removed"`, generate a request that asserts the endpoint
   now fails (defaults to expecting `404`)

## User Stories & Acceptance Criteria

### User Story 1: Generate Tests for New CRUD Endpoints

**As a** developer adding a new API endpoint  
**I want to** automatically generate tests for my endpoint  
**So that** I can quickly validate it works without manually writing test cases

**Acceptance Criteria:**
- [x] Server accepts description of a new endpoint (method, path, request body, expected status)
- [x] Server generates a Bruno collection with the endpoint
- [x] Generated requests use `{{BRUNO_API_URL}}` environment variable for the base URL
- [x] Request includes appropriate HTTP method and path
- [x] Request includes sample data matching the request body
- [x] Test includes assertion for expected status code
- [ ] Test includes assertion validating response JSON structure matches expected schema *(planned — see Roadmap)*
- [x] Collection file is properly formatted and can be opened in Bruno

### User Story 2: Generate Tests for Updated Endpoints

**As a** developer modifying an existing endpoint  
**I want to** regenerate tests to reflect the new behavior  
**So that** I can verify my changes don't break existing functionality

**Acceptance Criteria:**
- [x] Server accepts description of an updated endpoint (new method/path/body/status)
- [x] Server generates a Bruno test reflecting the new behavior (`changeType: "updated"`)
- [x] Generated tests use `{{BRUNO_API_URL}}` environment variable
- [ ] Server automatically replaces/diffs the previous version of the request rather than requiring the same `name` *(planned — see Roadmap; today re-running with the same `name` overwrites the file)*

### User Story 3: Generate Tests for Removed Endpoints

**As a** developer removing or deprecating an endpoint  
**I want to** create tests that validate the endpoint no longer works as expected  
**So that** I can ensure the endpoint has been properly removed or returns appropriate error responses

**Acceptance Criteria:**
- [x] Server accepts description of a removed endpoint (path, previous HTTP method)
- [x] Server generates a Bruno test for the removed endpoint
- [x] Test attempts to call the removed endpoint using `{{BRUNO_API_URL}}`
- [x] Test includes an assertion validating the status code (defaults to 404, overridable via `expectedStatus` for 410/5xx/etc.)
- [ ] Assertion can validate the response *body* indicates the endpoint no longer exists (status-code-only for now) *(planned — see Roadmap)*
- [x] Collection file is properly formatted and can be opened in Bruno

## Architecture

Current (MVP) implementation:

```
bruno-mcp-server/
├── src/
│   ├── index.ts             # MCP server entry point; registers the
│   │                        # generate_bruno_test tool, handles collection
│   │                        # scaffolding and file writes
│   └── brunoGenerator.ts    # Pure functions that build .bru file contents,
│                             # bruno.json, and the development environment file
├── dist/                    # Compiled output (npm run build)
├── README.md
├── package.json
└── tsconfig.json
```

As the server grows (schema-based response assertions, auth, multiple
environments, etc.) this will likely split into `handlers/`, `services/`, and
`models/` as originally sketched — kept flat for now since there's a single
tool.

## Design Decisions

### Environment Variable Over Hardcoded URLs
The server uses `${BRUNO_API_URL}` as an environment variable in generated requests. This allows developers to:
- Test against localhost during development
- Test against staging/production with a single environment variable change
- Share collections across team members with different configurations

### JSON-Based Schema Input
The server accepts endpoint descriptions in structured JSON format, making it:
- Parseable by LLMs
- Compatible with programmatic API documentation
- Extensible for future features

### Bruno Collection Format
Collections are generated as valid Bruno `.bru` files (or collections format) that:
- Are human-readable and editable
- Can be opened, modified, and run in the Bruno UI
- Support environment variable substitution
- Include test assertions

## Roadmap

### Phase 2: Enhanced Test Generation
- [ ] Support for authentication (Bearer tokens, API keys)
- [ ] Parameterized tests for multiple scenarios
- [ ] Custom assertion generation based on response schemas
- [ ] Negative test case generation (invalid inputs, edge cases)

### Phase 3: Advanced API Support
- [ ] GraphQL API support
- [ ] Webhook testing
- [ ] Async operation testing (polling, callbacks)
- [ ] Request/response transformation pipelines

### Phase 4: Developer Experience
- [ ] CLI for generating collections locally
- [ ] VS Code extension for inline test generation
- [ ] Integration with OpenAPI/Swagger specifications
- [ ] Test result aggregation and reporting

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Add tests for new functionality
4. Submit a pull request

For major changes, please open an issue first to discuss proposed changes.

## License

MIT

## Support

- **Documentation**: See `/docs` for detailed guides
- **Issues**: Report bugs and request features on GitHub
- **Discussions**: For questions and community discussion

---

## Technical Notes for Implementation

### Bruno Collection Structure
Generated collections should conform to Bruno's directory structure:
```
my-collection/
├── .bruno
│   └── bruno.json          # Collection metadata
├── endpoints/
│   ├── users/
│   │   ├── create.bru      # POST /users
│   │   ├── list.bru        # GET /users
│   │   ├── get.bru         # GET /users/{id}
│   │   ├── update.bru      # PUT /users/{id}
│   │   └── delete.bru      # DELETE /users/{id}
│   └── posts/
│       └── ...
└── environments/
    └── development.bru     # Environment variables
```

### Schema Input Format
When describing endpoints, provide:
```json
{
  "endpoint": {
    "method": "POST",
    "path": "/users",
    "description": "Create a new user",
    "requestBody": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string", "format": "email" }
      },
      "required": ["name", "email"]
    },
    "responseBody": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "email": { "type": "string" },
        "createdAt": { "type": "string", "format": "date-time" }
      }
    },
    "successStatusCode": 201
  }
}
```

### Best Practices Reference
The server should embed knowledge of Bruno testing best practices:
- Clear, descriptive request names
- Proper HTTP method usage
- Meaningful assertions (not just status codes)
- Environment variable usage for configuration
- Consistent naming conventions
- Request/response documentation in comments

---

*This README doubles as the working spec for the server. The "Technical Notes" and JSON schema examples above describe the target shape of tool inputs; the current MVP (single `generate_bruno_test` tool, see Quick Start) implements a subset of it and will grow into the rest per the Roadmap.*