Crate turul_mcp_derive 

MCP Derive Macros

Procedural macros for zero-configuration MCP tool and resource creation.

Transform regular Rust structs and functions into full-featured MCP tools, resources, and protocol handlers with automatic schema generation and method dispatch.

Features

• Tool Creation: #[derive(McpTool)], #[mcp_tool], tool! macro
• Resource Handling: #[derive(McpResource)], #[mcp_resource], resource! macro
• Schema Generation: Automatic JSON schema from Rust types
• Zero Configuration: Framework auto-determines method strings
• Type Safety: Compile-time validation of MCP protocols
• Full Protocol: Tools, resources, prompts, notifications, sampling

Installation

[dependencies]
turul-mcp-derive = "0.4"
turul-mcp-server = "0.4"  # For server-side usage

Quick Start

Function Tool (Level 1 - Simplest)

use turul_mcp_derive::mcp_tool;
use turul_mcp_server::McpResult;

#[mcp_tool(name = "add", description = "Add two numbers")]
async fn add(
    #[param(description = "First number")] a: f64,
    #[param(description = "Second number")] b: f64,
) -> McpResult<f64> {
    Ok(a + b)
}

Derive Tool (Level 2 - Most Common)

use turul_mcp_derive::McpTool;
use turul_mcp_server::{McpResult, SessionContext};

#[derive(McpTool, Clone)]
#[tool(name = "calculator", description = "Multi-operation calculator")]
struct Calculator {
    #[param(description = "First operand")]
    a: f64,
    #[param(description = "Second operand")]
    b: f64,
    #[param(description = "Operation to perform")]
    operation: String,
}

impl Calculator {
    async fn execute(&self, _session: Option<SessionContext>) -> McpResult<f64> {
        match self.operation.as_str() {
            "add" => Ok(self.a + self.b),
            "subtract" => Ok(self.a - self.b),
            "multiply" => Ok(self.a * self.b),
            "divide" => {
                if self.b != 0.0 {
                    Ok(self.a / self.b)
                } else {
                    Err("Division by zero".into())
                }
            }
            _ => Err("Unknown operation".into()),
        }
    }
}

Resource Handler

use turul_mcp_derive::mcp_resource;
use turul_mcp_protocol::resources::ResourceContent;
use turul_mcp_server::McpResult;

#[mcp_resource(
    uri = "file:///data/{filename}.json",
    description = "Dynamic JSON data files"
)]
async fn data_file(filename: String) -> McpResult<Vec<ResourceContent>> {
    let content = format!(r#"{{"filename": "{}", "data": "example"}}"#, filename);
    Ok(vec![ResourceContent::text(
        &format!("file:///data/{}.json", filename),
        &content
    )])
}

Available Macros

Macro	Purpose	Usage
#[derive(McpTool)]	Struct-based tools	Most flexible
#[mcp_tool]	Function-based tools	Quick & simple
#[derive(McpResource)]	Resource handlers	Static resources
#[mcp_resource]	Function resources	Dynamic resources
tool!	Declarative tools	Runtime creation
resource!	Declarative resources	Runtime creation

Examples

Complete examples available at: github.com/aussierobots/turul-mcp-framework/tree/main/examples

• Calculator Tools - Math operations with derive macros
• File Resources - Static and dynamic resource handlers
• Function Tools - Simple function-based tools
• Builder Pattern - Runtime tool creation
• Schema Generation - JSON schema from Rust types

Related Crates

• turul-mcp-server - Server framework
• turul-mcp-protocol - Protocol types
• turul-mcp-builders - Runtime builders

Macros

completion

Declarative macro for creating MCP completion handlers with concise syntax.

elicitation

Declarative macro for creating MCP elicitation handlers with concise syntax.

logging

Declarative macro for creating MCP logging handlers with concise syntax.

notification

Declarative macro for creating MCP notifications with concise syntax.

prompt

Declarative macro for creating simple prompts

resource

Declarative macro for creating simple resources

roots

Declarative macro for creating MCP root handlers with concise syntax.

sampling

Declarative macro for creating sampling configurations

schema_for

Generate a JSON schema for a Rust type

tool

Declarative macro for creating simple tools

Attribute Macros

mcp_resource

Function attribute macro for creating MCP resources

mcp_tool

Function attribute macro for creating MCP tools

param

Helper attribute for parameter metadata in function macros

Derive Macros

McpCompletion

Derive macro for automatically implementing McpCompletion

McpElicitation

Derive macro for automatically implementing McpElicitation

McpLogger

Derive macro for automatically implementing McpLogger

McpNotification

Derive macro for automatically implementing McpNotification

McpPrompt

Derive macro for automatically implementing McpPrompt

McpResource

Derive macro for automatically implementing MCP resource handlers

McpRoot

Derive macro for automatically implementing McpRoot

McpSampling

Derive macro for automatically implementing McpSampling

McpTool

Derive macro for automatically implementing McpTool