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 network clients, including web applications.

⚠️ Important Note

This project is currently in active development and is in a Work-In-Progress (WIP) state. Features and APIs are subject to significant changes.

🚀 Quick Start

MCP Server Runner serves 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 clients and the server
• Graceful shutdown handling
• Comprehensive error logging
• Universal support for Unix/Windows platforms

📦 Installation

Prerequisites

• Rust 1.70 or higher
• An executable file for an MCP server implementation

Configuration

Environment Variables

The application can be configured via environment variables:

PROGRAM=        # Path to the MCP server executable (required if no configuration file is specified)
ARGS=           # Arguments passed to the MCP server
HOST=           # Host address to listen on, default is 0.0.0.0
PORT=           # Port number to listen on, default is 3000

Configuration File

You can generate a default configuration file with the following command:

mcp-server-runner init-config > config.yml

Usage Examples

Example of Environment Variable Configuration

export PROGRAM=/path/to/mcp-server
export ARGS=--some-argument
export HOST=127.0.0.1
export PORT=8080

Start the server:

mcp-server-runner start

Example of Command-Line Configuration

mcp-server-runner --program /path/to/mcp-server --args --some-argument --host 127.0.0.1 --port 8080 start

🔧 Technical Details

Development Status

• 🚧 In Development: The software is actively being developed.
• ⚠️ API Stability: APIs and features may change without prior notice.
• 🧪 Testing: Currently undergoing testing and optimization.
• 📝 Documentation: Documentation is being actively updated.

Architecture

MCP Server Runner consists of the following main modules:

• main.rs: The entry point of the program.
• config/: Implementation related to configuration.
• server/: The core logic of the WebSocket server.
• logger/: Logging and error handling.

Error Handling

Error Types

• ConfigurationError: Configuration-related errors.
• ConnectionError: Connection-related errors.
• ProtocolError: Protocol-related errors.

Known Limitations

• The current version only supports single-client connections.
• It does not support WebSocket protocol compression and proxying.
• The full MCP protocol specification is not implemented.

🤝 Contribution Guidelines

How to Contribute

1. Clone the repository

git clone git@github.com:your-repository.git

2. Create a feature branch

git checkout -b feature/your-feature-name

3. Commit your changes

git commit -m 'Add awesome feature'

4. Push to the remote repository

git push origin feature/your-feature-name

5. Create a pull request

Submit your changes via GitHub Pull Request.

📄 License

This project is released under the MIT License. Please refer to the LICENSE file for details.

📚 Additional Resources

• Model Context Protocol Specification
• WebSocket Protocol (RFC 6455)