📌Overview

Purpose: The MCP Server Runner provides a WebSocket server implementation to facilitate the interaction between WebSocket clients and Model Context Protocol (MCP) servers.

Overview: MCP Server Runner acts as a bridge that launches MCP server processes, manages WebSocket connections, and enables bidirectional communication between clients and servers, ensuring efficient integration with web applications or other network-enabled clients.

Key Features:

WebSocket Server Implementation: Offers single-client support for establishing WebSocket connections, allowing real-time communication.
Process Management: Efficiently manages the lifecycle of MCP server instances, ensuring smooth operations and resource management.
Bidirectional Message Passing: Supports seamless transmission of messages between the client and the MCP server, enhancing interactivity.
Graceful Shutdown Handling: Implements mechanisms for clean termination of the server process, preventing data loss or corruption.
Comprehensive Error Logging: Captures detailed logs of errors and standard output from the MCP server, aiding in troubleshooting and maintenance.
Cross-Platform Support: Operates seamlessly on both Unix and Windows environments, broadening deployment options.

MCP Server Runner

Note: This project is currently under active development and in WIP (Work In Progress) status. Features and APIs may change significantly.

A WebSocket server implementation for running Model Context Protocol (MCP) servers. This application enables MCP servers to be accessed via WebSocket connections, facilitating integration with web applications and other network-enabled clients.

Development Status

🚧 Work In Progress: This software is in active development
⚠️ API Stability: APIs and features may change without notice
🧪 Testing: Currently undergoing testing and refinement
📝 Documentation: Documentation is being actively updated

Overview

MCP Server Runner acts as a bridge between WebSocket clients and MCP server implementations. It:

Launches an MCP server process
Manages WebSocket connections
Handles bidirectional communication between clients and the MCP server
Supports graceful shutdown and error handling

Features

WebSocket server implementation with single-client support
Process management for MCP server instances
Bidirectional message passing between client and server
Graceful shutdown handling
Comprehensive error logging
Cross-platform support (Unix/Windows)

Prerequisites

Rust 1.70 or higher
An MCP server implementation executable

Configuration

Environment Variables

The application can be configured through environment variables:

PROGRAM=        # Path to the MCP server executable (required if no config file)
ARGS=           # Comma-separated list of arguments for the MCP server
HOST=0.0.0.0    # Host address to bind to (default: 0.0.0.0)
PORT=8080       # Port to listen on (default: 8080)
CONFIG_FILE=    # Path to JSON configuration file

Additional environment variables will be passed through to the MCP server process.

JSON Configuration

Alternatively, you can provide a JSON configuration file:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/workspace"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  },
  "default_server": "filesystem",
  "host": "0.0.0.0",
  "port": 8080
}

You can specify the configuration file in two ways:

As a command-line argument: mcp-server-runner config.json
Using the CONFIG_FILE environment variable: CONFIG_FILE=config.json mcp-server-runner

The JSON configuration allows you to define multiple server configurations and select one as the default.

Configuration Priority

Command-line specified config file
CONFIG_FILE environment variable
Environment variables (PROGRAM, ARGS, etc.)
Default values

Usage

Using environment variables:

export PROGRAM=npx
export ARGS=-y,@modelcontextprotocol/server-github
export PORT=8080
export GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_***
cargo run

Using a configuration file:

# Either specify the config file as an argument
cargo run config.json

# Or use the CONFIG_FILE environment variable
CONFIG_FILE=config.json cargo run

Connect to the WebSocket server:

const ws = new WebSocket("ws://localhost:8080");

Docker Support

A Dockerfile and docker-compose.yml are provided for containerized deployment:

docker-compose up --build

Development

Build the project:

cargo build

Run tests:

cargo test

Run with debug logging:

RUST_LOG=debug cargo run

Architecture

The application follows a modular architecture:

main.rs: Application entry point and server setup
config/: Configuration loading and management
process/: Process management and I/O handling
websocket/: WebSocket connection management
state.rs: Global state management
shutdown.rs: Graceful shutdown handling

Error Handling

Standard error output from the MCP server is logged but not forwarded to clients
WebSocket connection errors are handled gracefully
Process errors are logged with detailed information

Limitations

Supports only one client connection at a time
Does not support WebSocket SSL/TLS (use a reverse proxy for secure connections)
No built-in authentication mechanism

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Additional Resources

Model Context Protocol Specification: https://github.com/modelcontextprotocol/specification
WebSocket Protocol (RFC 6455): https://tools.ietf.org/html/rfc6455

mcp-server-runner