pulseengine-mcp-protocol

Core types and validation for the Model Context Protocol in Rust

This crate provides the fundamental types and validation logic for building MCP (Model Context Protocol) servers and clients in Rust. It's been developed as part of a working Loxone home automation MCP server and handles the protocol details so you can focus on your application logic.

What This Crate Provides

• Core MCP types - Request, Response, Tool, Resource, and other protocol structures
• JSON-RPC 2.0 support - Proper message formatting and parsing
• Input validation - Schema validation for tool parameters and responses
• Error handling - Standard MCP error types and conversion utilities
• Protocol compliance - Follows MCP specification version 2024-11-05

Quick Example

use pulseengine_mcp_protocol::{Tool, Content, CallToolResult};
use serde_json::json;

// Define a tool with proper schema
let tool = Tool {
    name: "get_weather".to_string(),
    description: "Get current weather for a location".to_string(),
    input_schema: json!({
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City name or coordinates"
            }
        },
        "required": ["location"]
    }),
};

// Create a tool response
let result = CallToolResult {
    content: vec![Content::text("Current weather: 22°C, sunny".to_string())],
    is_error: Some(false),
};

Real-World Usage

This crate is currently used in production by:

• Loxone MCP Server - A home automation server with 30+ tools that successfully integrates with MCP Inspector and Claude Desktop

Current Status

Stable core functionality - The basic protocol types and validation work well. We've tested this with real MCP clients and it handles the protocol correctly.

What works:

• ✅ All core MCP types (Tool, Resource, Prompt, etc.)
• ✅ JSON-RPC 2.0 message handling
• ✅ Schema validation for tool inputs
• ✅ Error types that map to MCP specification
• ✅ Compatibility with MCP Inspector and Claude Desktop

What's still developing:

• 📝 API documentation could be more comprehensive
• 🧪 Test coverage could be broader
• 🔧 Some edge cases in validation might need refinement

Installation

Add this to your Cargo.toml:

[dependencies]
pulseengine-mcp-protocol = "0.2.0"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

Basic Usage

Defining Tools

use pulseengine_mcp_protocol::Tool;
use serde_json::json;

let tool = Tool {
    name: "calculate".to_string(),
    description: "Perform basic calculations".to_string(),
    input_schema: json!({
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "Mathematical expression to evaluate"
            }
        },
        "required": ["expression"]
    }),
};

Handling Requests and Responses

use pulseengine_mcp_protocol::{CallToolRequestParam, CallToolResult, Content};

// Parse a tool call request
let request = CallToolRequestParam {
    name: "calculate".to_string(),
    arguments: Some(json!({"expression": "2 + 2"})),
};

// Create a response
let response = CallToolResult {
    content: vec![Content::text("4".to_string())],
    is_error: Some(false),
};

Error Handling

use pulseengine_mcp_protocol::Error;

// Create standard MCP errors
let error = Error::invalid_params("Missing required parameter: location");
let internal_error = Error::internal_error("Database connection failed");

Integration with Other Framework Crates

This crate works well with other parts of the MCP framework:

• pulseengine-mcp-server - Uses these types for the backend trait
• pulseengine-mcp-transport - Handles serialization of these types over HTTP/WebSocket
• pulseengine-mcp-auth - Validates requests using these error types

Contributing

This crate is part of the larger MCP framework for Rust. The Loxone MCP server serves as our main testing ground for new features and improvements.

If you find issues or have suggestions:

1. Check if it works with the Loxone implementation first
2. Open an issue with a minimal reproduction case
3. Consider how changes might affect existing users

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Repository: https://github.com/avrabe/mcp-loxone

Note: This crate is part of a larger MCP framework that will be published as a separate repository.