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

The application is configured through environment variables:

PROGRAM=        # Path to the MCP server executable (required)
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)

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

Usage

Set up the environment variables:

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

Run the server:
```
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
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.

MCP Server Runner