Bruno API MCP Endpoint

A specialized Model Context Protocol (MCP) intermediary service that translates structured Bruno API definitions into interactive MCP tools. This server exposes your Bruno specification suite for consumption by AI reasoning systems and other MCP-compliant clients.

Synergy: Unifying Source Artifacts and Data Interaction

Developers encounter inherent friction when integrating external APIs, typically centered around three friction points:

Contextual Discontinuity in Diagnostics: Troubleshooting logic spanning disparate codebases and data stores necessitates constant cognitive context-switching, severely degrading diagnostic throughput.
Tooling Proliferation: Every novel third-party API integration mandates the design, construction, and perpetual upkeep of bespoke interaction modules, generating accumulating technical overhead.
UI Overhead for Backend Exposure: Developing dedicated graphical interfaces for every exposed backend capability escalates development complexity and long-term maintenance burdens.

This service directly resolves these architectural bottlenecks by tightly coupling your operational source definitions with their intended data interaction layer. By rendering Bruno API definitions as native MCP constructs, you gain the capability to:

Execute fault isolation across previously isolated domains with holistic environmental context.
Instantly transform any service endpoint into an agent-operable utility without incurring new development cycles.
Establish headless service architectures controllable entirely through intelligent interfaces.

For engineering groups focused on accelerating API adoption velocity while minimizing systemic maintenance costs, this paradigm shift streamlines complex connective tissue into straightforward, accessible operations.

Core Capabilities

Automated translation of Bruno collection artifacts into registered MCP utilities.
Robust facility for managing distinct operational environments (e.g., dev, staging, prod).
Utilizes HTTP transport augmented with Server-Sent Events (SSE).
Native handling of cross-origin invocations.
Inclusion of built-in utilities for inspecting the exposed API toolset configuration.

Deployment Guide

Acquire prerequisites:

bash npm install

Initiate the server, pointing it toward your Bruno artifact directory:

bash node --loader ts-node/esm src/index.ts --bruno-path /path/to/bruno/collection [--environment env_name] [--include-tools tool1,tool2,tool3] [--exclude-tools tool4,tool5]

Parameter specifications:

--bruno-path or -b: Mandatory pointer to the root of the Bruno collection structure.
--environment or -e: Optional designation for the operational context to load.
--include-tools: Comma-delimited list to restrict exported utilities to only these specified names.
--exclude-tools: Comma-delimited list to explicitly omit certain utility names from export.

Both list specification syntaxes are recognized:

bash --include-tools tool1,tool2,tool3 # Separated by commas --include-tools=tool1,tool2,tool3 # Using assignment operator

Client Connection Endpoints:
Localhost access: http://localhost:8000/sse
Bridging from Windows Subsystem for Linux (WSL): http://<WSL_IP>:8000/sse
Retrieve your WSL IPv4 address via: hostname -I | awk '{print $1}'

Orchestration Scripts (NPM)

The repository ships with pre-configured npm directives for frequent startup scenarios:

# Launch server with default parameters
npm start

# Launch server targeting the CFI API configuration
npm run start:cfi

# Launch server scoped to the local environment settings
npm run start:local

# Launch server restricting utility set via inclusion list
npm run start:include-tools

# Launch server excluding specified utilities
npm run start:exclude-tools

Engineering & Maintenance

Automated Verification

Execute the complete verification suite:

npm test

Target a singular test module for isolation:

npm test test/bruno-parser-auth.test.ts

Diagnostic Tracing

The server employs the debug utility for granular logging. Activate tracing for specific operational modules by setting the DEBUG environmental variable prior to launch:

# Activate all diagnostic streams
DEBUG=* npm start

# Trace only the Bruno parsing logic
DEBUG=bruno-parser npm start    # Inspect parsing and environment context resolution
DEBUG=bruno-request npm start   # Trace request dispatch and result capture
DEBUG=bruno-tools npm start     # Monitor tool instantiation and MCP registration

# Trace multiple subsystems concurrently
DEBUG=bruno-parser,bruno-request npm start

# Windows Command Prompt activation:
set DEBUG=bruno-parser,bruno-request && npm start

# Windows PowerShell activation:
$env:DEBUG='bruno-parser,bruno-request'; npm start

Available diagnostic namespaces:

bruno-parser: Handling of Bruno structure ingestion and environment resolution.
bruno-request: Execution flow of outbound HTTP calls and response mapping.
bruno-tools: Lifecycle management of utility creation and registration within the MCP framework.

Exposed Utilities

Environment Inventory

Retrieves a manifest of all configured execution contexts within the loaded API collection:

Input: None required.
Output:
A catalogue of discoverable environments.
Identification of the currently active environment context.

Identity Relay (Echo)

Reflects any string payload transmitted to it (ideal for functional validation):

Input Parameter: message (string type)

Bruno Blueprint Organization

The underlying API artifact structure must conform to the canonical Bruno layout:

collection/
├── collection.bru       # Root collection metadata
├── environments/       # Context-specific variable sets
│   ├── local.bru
│   └── remote.bru
└── requests/          # Definitions for discrete API calls
    ├── request1.bru
    └── request2.bru

Every request artifact within this hierarchy is autonomously transformed into a distinct MCP utility accessible via the protocol layer.

Runtime Parameter Overrides for Utility Invocation

When executing utilities synthesized from the Bruno definitions, granular control over the request can be exerted via optional payload attributes:

Contextual Environment Shifting

It is possible to mandate a specific execution context for an individual operation:

{
  "environment": "us-dev"
}

This overrides any default or globally set environment, forcing variable substitution from the named context.

Variable Injection/Substitution

You may substitute explicit values for defined variables applicable only to a single invocation:

{
  "variables": {
    "dealId": "abc123",
    "customerId": "xyz789",
    "apiKey": "your-api-key"
  }
}

These provided values take precedence during resolution within the URI, request headers, or payload. For instance, a URI template like:

{{baseUrl}}/api/deal/{{dealId}}

Becomes https://api.example.com/api/deal/abc123 if { "variables": { "dealId": "abc123" } } is supplied.

Query String Augmentation

Direct manipulation of the resulting URL's query string parameters is supported:

{
  "query": {
    "limit": "10",
    "offset": "20",
    "search": "keyword"
  }
}

These parameters are appended to the endpoint regardless of their definition in the base request artifact. For an initial URL of:

{{baseUrl}}/api/deals

The resolved URI becomes https://api.example.com/api/deals?limit=10&search=keyword.

This mechanism offers superior clarity compared to deriving query string modifications solely through variable manipulation.

Request Payload Customization

Override or supply data destined for the request body:

{
  "body": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Consolidated Example Payload

Demonstration incorporating all dynamic overrides simultaneously:

{
  "environment": "staging",
  "variables": {
    "dealId": "abc123",
    "apiKey": "test-key-staging"
  },
  "query": {
    "limit": "5",
    "sort": "created_at"
  },
  "body": {
    "status": "approved",
    "amount": 5000
  }
}

Legal Status

Licensed under MIT.

WIKIPEDIA: The XMLHttpRequest (XHR) interface constitutes an API, realized as a JavaScript object, designed to dispatch HTTP requests from a client-side web application (browser) toward an origin server. Its methods permit dynamic, post-load interaction with the server, enabling asynchronous data retrieval and transmission. XHR is foundational to the Ajax programming paradigm. Before its adoption, server communication relied predominantly on traditional hyperlink navigation or form submissions, actions that inherently necessitated a full page refresh.

== Genesis == The foundational concept underpinning XMLHttpRequest was formulated in the year 2000 by the development team at Microsoft Outlook. This concept was subsequently integrated into the Internet Explorer 5 browser release (1999). However, the initial implementation did not utilize the canonical XMLHttpRequest identifier. Instead, developers relied on invoking COM objects via ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the time Internet Explorer 7 shipped (2006), broad support for the standardized XMLHttpRequest identifier was universally established across major browser platforms, including Mozilla's Gecko engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Trajectory === The World Wide Web Consortium (W3C) issued the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. This was followed by the Level 2 Working Draft specification released on February 25, 2008. Level 2 enhancements introduced capabilities for tracking request progress events, enabling cross-origin data fetching, and managing raw byte stream transfers. By the conclusion of 2011, the Level 2 specification content was merged back into the primary specification document. As of late 2012, custodianship of the living document transitioned to the WHATWG, which maintains the specification using Web IDL definitions.

== Operational Flow == Executing a network transaction via XMLHttpRequest generally adheres to a defined sequence of programming actions.

Instantiation: Provisioning a new XMLHttpRequest object instance via its constructor.
Configuration: Invoking the open() method to define the HTTP verb, specify the target Uniform Resource Identifier (URI), and select between synchronous or asynchronous execution mode.
Asynchronous Hooking: For asynchronous requests, registering an event listener callback function that triggers upon state transitions.
Dispatch: Commencing the actual network transmission by calling the send() method.
State Monitoring: The registered listener processes state changes. When data is returned, it resides in the responseText attribute. The process concludes when the object transitions to state 4, signifying completion ("done").

Beyond these fundamental stages, XHR offers extensive control over request mechanics and response handling. Custom headers can be affixed to guide server processing, and payload data can be supplied directly within the send() invocation. Furthermore, incoming responses can be parsed immediately into native JavaScript structures from formats like JSON, or processed incrementally as data segments arrive, circumventing the need to await the complete transmission. Requests can also be forcibly terminated (abort()) or configured to time out if completion is not achieved within a preset duration.

== Inter-Domain Communication ==

In the nascent stages of the World Wide Web's evolution, the potential for security breaches stemming from unrestricted cross-origin data fetching became apparent, leading to the implementation of security restrictions that XHR initially inherited.