# MCP Burst
**An Express app with AI capabilities powered by MCP (Model Context Protocol)**
MCP Burst supports multiple server types and includes a built-in chat interface for testing. In a way acting as a bridge for MCP Clients to an array of tools and MCP servers/server gateways.
## What it does
- **Chat Integration**: Works with Ollama, OpenAI, and Docker Model Runner
- **MCP Server Support**: Runs streamablehttp servers, stdio servers such as Docker MCP Gateway server, and n8n MCP trigger node URLs
- **Custom Tools**: Create discoverable tools at the `/mcp` endpoint
- **Multi-Client Support**: Use `MCP_BURST_CLIENT=true` in .env to serve multiple clients simultaneously
## Quick Status Check
- **Session debugging**: `curl http://localhost:4000/status`
- **Note**: Multi-client sessions are still being thoroughly tested
**NOTE: You might have to upgrade the security if you want to use this in production. Otherwise, test and be patient until a secure merge**
## Running MCP Burst in MCP Clients
**VSCode**:
1. In your MCP Burst folder, run the hub:
```bash
npm run start:hub
```
2. Create .vscode/mcp.json in your workspces for example, using this config:
```json
{
"servers": {
"mcp-burst": {
"type": "http",
"url": "http://127.0.0.1:4000",
}
}
}
```
**Claude Desktop**: Update your claude_desktop_config.json to include:
```json
{
"mcpServers": {
"mcp-burst": {
"command": "node",
"args": ["/path/to/mcpburst/hub/stdio-client-hub-entry.js"]
}
}
}
```
## Prebuilt Demo Chatbot Agent App
In your MCP Burst folder, run these commands:
1.
```bash
npm run start:hub
```
2.
```bash
npm run start:server
```
## Table of Contents
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Directory Structure](#directory-structure)
- [Scripts](#scripts)
- [License](#license)
## Features
- Streamable HTTP MCP transport server built on Model Context Protocol SDK
- Serve MCP Burst as an http and/or stdio client *(tested with Claude Desktop, VS Code)*
- Built-in demo tools: 'echo' and 'update_session_planner'
- Express façade handling JSON-RPC at `/mcp` and health checks at `/health`
- Built in Planner Tool (Required for built in chatbot, but not necessarily for MCP Clients.)
- OPTIONAL: Built in Gamification (ie positive reinforcement for successfully completing tasks, worked well with Claude Desktop so I kept it in the repo)
- Demo Chatbot Agent App to test MCP integration, and now session planner resource to execute multiple tools.
## Prerequisites
- Node.js v16 or higher
- npm (included with Node.js)
## Installation
1. Clone the repository:
```sh
git clone https://github.com/arberrexhepi/mcpburst.git
cd mcpburst
```
2. Install root dependencies in root:
```sh
npm install
```
3. Install hub and server dependencies:
```sh
cd hub && npm install && cd ..
```
## Configuration
Create environment variable files in both `hub/` and `server/` directories:
### hub/.env
```ini
PORT=4000
HOST=localhost
MCP_REQUIRE_AUTH=false # set to 'true' to require Bearer auth NOTE:
MCP_BURST_CLIENT=true #set to false if you don't want it to be discoverable
```
### server/.env
```ini
OPENAI_API_KEY=your_openai_api_key
MCP_ENDPOINT=http://127.0.0.1:4000/mcp
PORT = 3500
STRATEGY=DMR
DOCKER_MODEL_RUNNER_URL=http://localhost:12434/engines/llama.cpp/v1/chat/completions
OLLAMA_URL=http://localhost:11434/v1/chat/completions
```
## Usage
1. Build and start the MCP hub server:
```sh
npm run start:hub
```
2. Start the front-end proxy server:
```sh
npm run start:server
```
3. Open your browser at [http://localhost:3000](http://localhost:3000) to access the chat UI.
4. The hub JSON-RPC endpoint is available at `http://localhost:4000/mcp`.
## Directory Structure
```
├── LICENSE
├── package.json # root package config and scripts
├── README.md
├── hub/ # MCP hub server
│ ├── package.json
│ ├── tsconfig.json
│ ├── dist/ # TypeScript sources output to dist/
│ ├── installToolsFeature.ts
│ ├── installResourcesFeature.ts
│ ├── stdio-client-hub-entry.js
│ ├── bridgeBuilder.ts
│ ├── bridgeHttp.ts
│ ├── bridgeStdio.ts
│ ├── hub.ts
│ └── bridges/ # sample tool definitions
│ └── hub.yaml
└── server/ # proxy and front-end assets
├── index.js
├── extractContent.js
├── public/
│ ├── index.html
│ ├── css/
│ │ └── styles.css
│ └── js/
│ └── chat.js
└── agent_functions/
├── index.js
├── llmClient.js
├── mcpClient.js
├── planExecutor.js
└── README.MD
```
## Scripts
All scripts are defined in the root `package.json`:
- `npm run build` : Compile TypeScript in `hub` and copy bridge files
- `npm run copy:bridges`: Copy bridge YAML definitions to `hub/dist`
- `npm run start:hub` : Build then run the MCP hub server
- `npm run start:server`: Run the Express static server with chat UI
## License
- This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.
