Yonaka15 MCP Server Runner

🚀 MCP Server Runner

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 clients and web applications.

🚀 Quick Start

Prerequisites

• Rust 1.70 or higher
• MCP server implementation executable

Configuration

Configure the application through environment variables:

PROGRAM=        # Path to the MCP server executable (Required)
ARGS=           # Arguments for the MCP server, as a comma-separated list
HOST=0.0.0.0    # Host address to bind to (Default: 0.0.0.0)
PORT=8080       # Port to listen on (Default: 8080)

Other environment variables will be passed to the MCP server process.

Usage

1. Set environment variables:

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

2. Run the server:

cargo run

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

✨ Features

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

📚 Documentation

Overview

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

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

Development Status

• 🚧 In Progress: The software is under active development.
• ⚠️ API Stability: The API and features may change without prior notice.
• 🧪 Testing: Currently undergoing testing and improvement.
• 📝 Documentation: The documentation is being actively updated.

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 in detail.

Limitations

• Only supports one client connection.
• Does not support WebSocket SSL/TLS (use a reverse proxy for secure connections).
• No built-in authentication mechanism.

Contribution

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. 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
• WebSocket Protocol (RFC 6455)

⚠️ Important Note

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