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 setupprocess/: Process management and I/O handlingwebsocket/: WebSocket connection managementstate.rs: Global state managementshutdown.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
