MCP Hub

# 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.