SolidMCP

A high-level Rust toolkit for building Model Context Protocol (MCP) servers with minimal boilerplate and maximum type safety.

Features

🚀 Minimal Boilerplate: Build MCP servers with just a few lines of code
🛡️ Type Safety: Compile-time guarantees with automatic JSON schema generation
🔌 Smart Transport: WebSocket and HTTP with automatic capability detection and negotiation
📚 Full MCP Support: Tools, Resources, and Prompts with a unified API
🏗️ Flexible Architecture: Generic context system for any application state
🔔 Notifications: Simple API for sending log messages and updates
🌐 Enhanced HTTP: CORS support, transport discovery, and graceful fallback
✅ Battle-tested: Comprehensive test suite covering all MCP features (99+ tests)

Quick Start

Add SolidMCP to your Cargo.toml:

[dependencies]
solidmcp = { git = "https://github.com/jupitersoftco/solidmcp.git" }
anyhow = "1.0"
schemars = "0.8"
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.0", features = ["full"] }

Create a simple MCP server:

use anyhow::Result;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use solidmcp::framework::McpServerBuilder;
use std::sync::Arc;

// Define your application context
#[derive(Debug)]
struct MyContext {
    name: String,
}

// Define input/output schemas with automatic JSON schema generation
#[derive(Debug, Serialize, Deserialize, JsonSchema)]
struct GreetInput {
    name: String,
}

#[derive(Debug, Serialize, Deserialize, JsonSchema)]
struct GreetOutput {
    message: String,
}

#[tokio::main]
async fn main() -> Result<()> {
    let context = MyContext { name: "MyApp".to_string() };

    let mut server = McpServerBuilder::new(context, "my-mcp-server", "1.0.0")
        .with_tool(
            "greet",
            "Greet someone by name",
            |input: GreetInput, ctx: Arc<MyContext>, notify| async move {
                notify.info(&format!("Greeting {}", input.name))?;

                Ok(GreetOutput {
                    message: format!("Hello, {}! Welcome to {}", input.name, ctx.name),
                })
            },
        )
        .build()
        .await?;

    server.start(3000).await?;
    Ok(())
}

That's it! Your MCP server is now running with:

Automatic JSON schema generation and validation
WebSocket and HTTP endpoints with smart transport negotiation
Built-in error handling and logging
Type-safe tool execution
CORS support for web clients

Transport Layer

SolidMCP features an intelligent transport system that automatically detects and negotiates capabilities:

🔄 Automatic Transport Detection

WebSocket Upgrade: Detects Upgrade: websocket headers and establishes WebSocket connections
HTTP JSON-RPC: Falls back to HTTP with session management for compatibility
Transport Discovery: GET requests return capability information for client negotiation
CORS Support: Full CORS headers for web-based MCP clients

🌟 Smart Capability Negotiation

// Server automatically detects client capabilities from headers:
// - Connection: upgrade + Upgrade: websocket → WebSocket transport
// - Accept: application/json → HTTP JSON-RPC transport
// - GET request → Transport capability discovery response

🔮 Planned Transport Features

Server-Sent Events (SSE): Real-time streaming support (currently disabled, marked for future implementation)
Enhanced WebSocket: Advanced WebSocket features and sub-protocols
Custom Transports: Plugin system for custom transport implementations

📡 Current Transport Support Matrix

Transport	Status	Description
WebSocket	✅ Full Support	Real-time bidirectional communication
HTTP JSON-RPC	✅ Full Support	Request/response with session management
Server-Sent Events	🔮 Future Work	Streaming responses (architecture ready)
Custom Transports	🔮 Planned	Plugin system for extensions

Complete Example

For a comprehensive example demonstrating all MCP features (tools, resources, and prompts), see the toy notes server example. It shows how to build a complete note-taking MCP server with:

Tools: Create, read, list, and delete notes
Resources: Expose notes as MCP resources with note:// URIs
Prompts: Provide templates for meeting notes, daily journals, and tasks
Persistence: File-based storage with automatic loading
Notifications: Real-time updates when notes are modified

Run the example:

cd examples/toy
cargo run

Then connect with Claude Desktop or any MCP client at ws://localhost:3002/mcp or http://localhost:3002/mcp.

MCP Protocol Support

SolidMCP implements core MCP functionality with comprehensive transport support:

✅ Fully Supported

Protocol Versions: 2025-03-26 and 2025-06-18
Transport: WebSocket and HTTP with intelligent capability detection
Session Management: HTTP session cookies and state persistence
Transport Discovery: GET endpoint for capability negotiation
CORS: Full cross-origin support for web clients
Tools: Execute functions with validated inputs and outputs (tools/list, tools/call)
Resources: Expose data with URI-based access (resources/list, resources/read)
Prompts: Provide templates with argument substitution (prompts/list, prompts/get)
Notifications: Log messages and resource change notifications
Initialization: Full handshake and capability negotiation

🚧 Planned/Partial Support

Server-Sent Events: Architecture complete, implementation planned
Client Features: Sampling, roots, and completion (server-side features not yet implemented)
Progress Tracking: Basic framework exists, needs expansion
Cancellation: Basic support for notifications/cancel
Configuration: Environment variable support, needs structured config API

❌ Not Yet Implemented

Sampling: LLM sampling requests from servers to clients
Roots: Server-initiated boundary inquiries
Completion: Advanced completion capabilities
Advanced Security: Comprehensive consent flows and access controls

SolidMCP focuses on the server-side of MCP, providing everything needed to build robust MCP servers that work with existing MCP clients like Claude Desktop, with intelligent transport negotiation for optimal compatibility.

Advanced Usage

Custom Resource Providers

Expose your application data as MCP resources:

use async_trait::async_trait;
use solidmcp::framework::ResourceProvider;
use solidmcp::handler::{ResourceContent, ResourceInfo};

struct MyResourceProvider;

#[async_trait]
impl ResourceProvider<MyContext> for MyResourceProvider {
    async fn list_resources(&self, context: Arc<MyContext>) -> Result<Vec<ResourceInfo>> {
        Ok(vec![ResourceInfo {
            uri: "data://example".to_string(),
            name: "example".to_string(),
            description: Some("Example resource".to_string()),
            mime_type: Some("text/plain".to_string()),
        }])
    }

    async fn read_resource(&self, uri: &str, context: Arc<MyContext>) -> Result<ResourceContent> {
        Ok(ResourceContent {
            uri: uri.to_string(),
            mime_type: Some("text/plain".to_string()),
            content: "Hello from resource!".to_string(),
        })
    }
}

// Add to your server
let server = McpServerBuilder::new(context, "my-server", "1.0.0")
    .with_resource_provider(Box::new(MyResourceProvider))
    .build()
    .await?;

Custom Prompt Providers

Provide dynamic templates for AI interactions:

use solidmcp::framework::PromptProvider;
use solidmcp::handler::{PromptContent, PromptInfo, PromptMessage};

struct MyPromptProvider;

#[async_trait]
impl PromptProvider<MyContext> for MyPromptProvider {
    async fn list_prompts(&self, context: Arc<MyContext>) -> Result<Vec<PromptInfo>> {
        // Return available prompts
    }

    async fn get_prompt(&self, name: &str, arguments: Option<Value>, context: Arc<MyContext>) -> Result<PromptContent> {
        // Generate prompt content based on arguments
    }
}

Configuration

The framework supports various configuration options:

// Custom port
server.start(8080).await?;

// Environment variables
// PORT=8080 - Server port
// RUST_LOG=debug - Logging level

Latest Dependencies

SolidMCP uses the latest stable versions of core dependencies for optimal performance and security:

Tokio 1.43 - Latest async runtime with performance improvements
Warp 0.3.8 - Lightweight web framework for HTTP transport
tokio-tungstenite 0.27 - Latest WebSocket implementation
Serde 1.0.217 - JSON serialization with latest optimizations
thiserror 2.0 - Enhanced error handling with latest improvements
rand 0.9 - Cryptographically secure random generation
schemars 0.8.21 - JSON schema generation for type safety

All dependencies are regularly updated and tested for compatibility.

Architecture

SolidMCP is built with a modular architecture featuring intelligent transport handling:

Framework Layer (framework.rs) - High-level builder API for easy server creation
Handler Traits (handler.rs) - Core traits for tools, resources, and prompts
Protocol Engine (shared.rs) - MCP protocol implementation and message routing
Transport Layer (websocket.rs, http.rs) - WebSocket and HTTP server implementations
Transport Capability Detection (transport.rs) - Smart transport negotiation and discovery
Core Server (core.rs) - Server lifecycle and connection management

The library abstracts away the complexity of the MCP protocol while providing full access to all its features, with automatic transport detection ensuring compatibility across different MCP clients.

Current Limitations

SolidMCP is a server-focused implementation. Some limitations to be aware of:

Server-Sent Events: Architecture is ready but implementation is marked as future work
Client Features: Does not implement client-side capabilities like sampling, roots, or completion
Progress API: Basic progress tracking exists but needs expansion for complex operations
Security Model: Basic session management, but enterprise-grade security features are planned
Config Management: Relies on environment variables; structured configuration API coming
Protocol Extensions: Focuses on core MCP; custom protocol extensions not yet supported

These limitations reflect our focus on providing an excellent server development experience. Client features and advanced capabilities are on the roadmap.

Testing

SolidMCP includes a comprehensive test suite with 99+ tests covering all functionality:

# Run all tests (99+ tests)
cargo test

# Run library tests specifically
cargo test --lib

# Run integration tests
cargo test --test "*integration*"

# Run with logging
RUST_LOG=debug cargo test

# Test transport capability detection
cargo test transport::tests

# Test HTTP functionality
cargo test http::tests

Test Coverage:

✅ Transport Detection: WebSocket, HTTP, and capability negotiation
✅ Protocol Compliance: JSON-RPC 2.0 compliance and error handling
✅ Session Management: HTTP sessions and state persistence
✅ Tool Execution: Type-safe tool calls and validation
✅ Resource Access: URI-based resource listing and reading
✅ Prompt System: Template generation and argument substitution
✅ Error Handling: Comprehensive error scenarios and recovery
✅ Concurrent Access: Multi-client and high-load scenarios

Examples

Basic Server - Minimal MCP server setup
Custom Tools - Implementing custom tools
Toy Notes Server - Complete application with all MCP features
HTTP Server - HTTP-only server configuration
WebSocket Server - WebSocket-only server

Contributing

Contributions are welcome! Please see our Contributing Guidelines for details.

License

MIT

solidmcp 0.4.0