HAL 9000 MCP Server

An intelligent MCP (Model Context Protocol) server implementation in Rust

📋 Overview

HAL 9000 is a Model Context Protocol server built with Rust, designed to provide intelligent tool capabilities through the MCP standard. The project demonstrates a production-ready implementation of an MCP server with proper error handling, logging, and configuration management.

🚀 Features

• MCP Protocol Implementation: Full support for MCP 2024-11-05 protocol specification
• Multiple Transport Layers: Supports STDIO, SSE, and streamable HTTP transport
• Robust Error Handling: Comprehensive error types with tracing support
• Flexible Configuration: CLI-based configuration with environment variable support
• Async Runtime: Built on Tokio for high-performance async operations
• Type-Safe Tools: Strongly-typed tool definitions with JSON Schema validation

🛠️ Available Tools

say_hello

A simple greeting tool that responds with a personalized message.

Parameters:

• name (string): Name of the person to greet

Response:

• message (string): Greeting message

Example:

{
  "name": "say_hello",
  "arguments": {
    "name": "Nicolas"
  }
}

📦 Installation

Prerequisites

• Rust 1.75+ (2024 edition)
• Cargo

Build from Source

# Clone the repository
git clone https://github.com/nesimer/hal9000.git
cd hal9000

# Build the project
cargo build --release

# Run the server
cargo run --release

🔧 Usage

Running the Server

# Run with default configuration
cargo run

# Run with custom log level
RUST_LOG=debug cargo run

# Run in quiet mode
cargo run --quiet

VS Code Integration

The project includes a VS Code MCP configuration file (.vscode/mcp.json) for seamless integration:

{
    "servers": {
        "hal9000": {
            "type": "stdio",
            "command": "cargo",
            "args": ["run", "--quiet"],
            "cwd": "${workspaceFolder}",
            "env": {
                "RUST_LOG": "info"
            }
        }
    }
}

Testing with stdio

You can test the server using the included demo.json file:

cargo run < demo.json

🏗️ Architecture

Project Structure

hal9000/
├── src/
│   ├── main.rs       # Application entry point
│   ├── server.rs     # MCP server implementation
│   ├── config.rs     # Configuration management
│   ├── error.rs      # Error types and handling
│   └── types.rs      # Request/Response type definitions
├── Cargo.toml        # Project dependencies
├── demo.json         # Example MCP requests
└── .vscode/
    └── mcp.json      # VS Code MCP configuration

Key Components

1. Server Handler: Implements the ServerHandler trait to define server capabilities
2. Tool Router: Manages tool registration and dispatching
3. Configuration: CLI-based configuration with clap
4. Error Management: Structured error types with tracing integration
5. Type System: Strongly-typed requests/responses with JSON Schema support

📚 Dependencies

Core Dependencies

• rmcp (0.8.5): Rust MCP implementation with server, transport, and auth support
• tokio (1.x): Async runtime
• serde (1.x): Serialization/deserialization
• clap (4.x): CLI argument parsing

Utilities

• tracing: Structured logging
• thiserror: Error handling
• anyhow: Error management
• reqwest: HTTP client with rustls
• chrono: Date/time handling

🔍 Development

Adding New Tools

1. Define request/response types in src/types.rs:

#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
pub struct MyToolRequest {
    #[schemars(description = "Parameter description")]
    pub param: String,
}

2. Add tool handler in src/server.rs:

#[tool(
    name = "my_tool",
    description = "Tool description"
)]
async fn my_tool(&self, Parameters(request): Parameters<MyToolRequest>) 
    -> Result<Json<MyToolResponse>, String> {
    // Implementation
}

Running Tests

cargo test

Code Formatting

cargo fmt

Linting

cargo clippy

📝 License

This project is available under the MIT License.

👥 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Contact

• Author: Nesimer
• Repository: github.com/nesimer/hal9000

🙏 Acknowledgments

• Built with rmcp - Rust implementation of the Model Context Protocol
• Inspired by the HAL 9000 from 2001: A Space Odyssey

---

"I'm sorry, Dave. I'm afraid I can do that." - HAL 9000 (Friendly Edition)