mcp-schema

A Rust implementation of the Model Context Protocol (MCP) schema, providing type-safe definitions for building MCP clients and servers.

What is MCP?

Model Context Protocol (MCP) is an open protocol that enables secure, bidirectional communication between Large Language Model (LLM) applications and external data sources or tools.

Key Features

Tool Integration: Expose tools and functions that can be called by language models
Bidirectional Communication: Enable two-way interaction between AI systems and external services
Type Safety: Strong typing for all protocol messages and data structures
Extensible Architecture: Support for custom tools, prompts, and resources

Use Cases

Building AI-enhanced development environments
Creating intelligent chat interfaces with external tool access
Developing custom AI workflows with multiple tool integrations
Enabling LLMs to interact with databases, APIs, and file systems

Why Rust?

This Rust implementation provides several advantages:

Type Safety: Catch errors at compile time with Rust's strong type system
Performance: Zero-cost abstractions and efficient memory management
Reliability: Memory safety guarantees without garbage collection
Serde Integration: Seamless JSON serialization/deserialization
Cross-Platform: Build native MCP servers and clients for any platform

Installation

Add mcp-schema to your project:

cargo add mcp-schema

Or add to your Cargo.toml:

[dependencies]
mcp-schema = "0.2.0"

Usage

Basic Example

use mcp_schema::*;
use serde_json::json;

// Create a tool with annotations
let tool = Tool {
    name: "calculate".to_string(),
    title: Some("Calculator".to_string()),
    description: Some("Perform calculations".to_string()),
    input_schema: json!({
        "type": "object",
        "properties": {
            "expression": {"type": "string"}
        }
    }),
    output_schema: Some(json!({
        "type": "object",
        "properties": {
            "result": {"type": "number"}
        }
    })),
    annotations: Some(ToolAnnotations {
        read_only_hint: Some(true),
        destructive_hint: Some(false),
        idempotent_hint: Some(true),
        open_world_hint: Some(false),
    }),
};

// Handle tool results with structured content
let result = CallToolResult {
    content: vec![
        ContentBlock::Text(TextContent {
            text: "Calculation complete".to_string(),
        })
    ],
    structured_content: Some(json!({
        "result": 42,
        "confidence": 0.95
    })),
    is_error: Some(false),
};

Elicitation API Example

use mcp_schema::*;
use serde_json::json;

// Request user input with schema validation
let elicitation = ElicitationCreateParams {
    message: "Please provide your preferences".to_string(),
    requested_schema: json!({
        "type": "object",
        "properties": {
            "theme": {
                "type": "string",
                "enum": ["light", "dark", "auto"]
            }
        },
        "required": ["theme"]
    }),
};

// Handle user response
let response = ElicitationCreateResult {
    action: ElicitationAction::Accept,
    content: Some(json!({
        "theme": "dark"
    })),
};

Features (v0.2.0)

Tool Extensions

Title: Human-readable tool names
Output Schema: JSON Schema validation for tool outputs
Annotations: Behavioral hints for tools
- readOnlyHint: Tool doesn't modify state
- destructiveHint: Tool performs destructive operations
- idempotentHint: Tool can be called multiple times safely
- openWorldHint: Tool may return different results over time

Structured Content

Support for machine-readable data alongside human-readable content
Enables rich data exchange between tools and LLMs

Elicitation API

Request structured input from users
Schema validation for user responses
Support for accept/reject/edit actions

Full Type Coverage

Complete implementation of MCP protocol types
JSON-RPC 2.0 message handling
Server capabilities and client information
Resource management and prompts

Project Structure

mcp-schema/
├── src/
│   ├── lib.rs      # Public API exports
│   └── types.rs    # Core MCP type definitions
├── tests/
│   └── test_latest_spec.rs  # Comprehensive test suite
├── Cargo.toml      # Project configuration
└── README.md       # This file

Testing

Run the test suite:

cargo test

Tests cover:

Tool annotations and extensions
Structured content serialization
Elicitation API functionality
Backward compatibility
JSON serialization/deserialization

Development

# Build the library
cargo build

# Run tests
cargo test

# Check formatting
cargo fmt --check

# Run linter
cargo clippy

# Generate documentation
cargo doc --open

Contributing

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

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Resources

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

The Model Context Protocol team for the original TypeScript implementation
The Rust community for excellent serialization tools (serde)
Contributors and users of this library

mcp-schema 0.2.0