**🦀 MCP in Rust: A Practical Guide using `rmcp`**

This guide demonstrates how to use the Model Context Protocol (MCP) in Rust with the `rmcp` crate. MCP allows AI systems to interact with tools via JSON-RPC 2.0. Rust's performance and safety make it a great choice for building these tools.

We'll build several example MCP servers, from simple file operations to more complex KYC tasks.

**1. Environment Setup**

First, add the necessary dependencies to your `Cargo.toml`:

[dependencies]
rmcp = { version = "0.1", features = ["server", "client"] } # Core MCP library for server/client
tokio = { version = "1", features = ["full"] }           # Async runtime
serde = { version = "1", features = ["derive"] }           # Serialization/Deserialization
schemars = "0.8"                                        # JSON Schema generation for tool inputs
anyhow = "1.0"                                          # Flexible error handling
reqwest = { version = "0.11", features = ["json"] }     # HTTP client (for examples)
serde_json = "1.0"                                      # JSON handling (for examples)
# Note: For OCR example, ensure 'tesseract' CLI tool is installed and in PATH

**2. General MCP Server Examples**

Let's create some basic tools exposed via MCP.

**2.1. File Explorer**

This tool provides functions to list directory contents and read files.

use rmcp::{tool, tool_box};
use serde::Deserialize;
use schemars::JsonSchema;
use anyhow::Result; // Using anyhow for convenient error handling

#[derive(Clone)]
struct FileServer;

// Define the structure for requests needing a path
#[derive(Deserialize, JsonSchema)]
struct PathRequest { path: String }

#[tool_box] // Exposes methods within this impl block as MCP tools
impl FileServer {
    #[tool(description = "List directory contents")] // MCP description for this tool/method
    fn list_dir(&self, #[tool(aggr)] req: PathRequest) -> Result<Vec<String>> {
        // #[tool(aggr)] indicates the 'req' struct aggregates all parameters
        Ok(std::fs::read_dir(&req.path)?
            .filter_map(Result::ok) // Iterate, filter out errors
            .map(|e| e.file_name().to_string_lossy().to_string()) // Get filenames
            .collect()) // Collect into a Vec<String>
    }

    #[tool(description = "Read a file")]
    fn read_file(&self, #[tool(aggr)] req: PathRequest) -> Result<String> {
        Ok(std::fs::read_to_string(&req.path)?) // Read file content to string
    }
}

// Note: You'd need to add server setup code (e.g., using rmcp::Server) to run this.
// See rmcp documentation for server initialization examples.

* `#[tool_box]` marks the `impl` block, making its methods discoverable MCP tools.
* `#[tool(description = "...")]` provides a human-readable description for the AI model.
* `#[derive(Deserialize, JsonSchema)]` on `PathRequest` allows `serde` to parse incoming JSON into the struct and `schemars` to generate a schema for validation/description.
* `#[tool(aggr)]` tells `rmcp` to map the incoming JSON parameters object directly to the fields of the `PathRequest` struct.
* Standard Rust `std::fs` functions are used for the core logic. `anyhow::Result` simplifies error handling.

**2.2. Currency Converter**

This tool uses an external API to convert currencies.

use rmcp::{tool, tool_box};
use serde::Deserialize;
use schemars::JsonSchema;
use anyhow::Result;
use reqwest; // HTTP client

#[derive(Clone)] // Added Clone trait
struct CurrencyServer;

#[derive(Debug, Deserialize, JsonSchema)]
struct ConvertRequest {
    from: String,
    to: String,
    amount: f64,
}

// Structure to deserialize the relevant part of the API response
#[derive(Debug, Deserialize)]
struct ApiResponse {
    result: f64,
}

#[tool_box]
impl CurrencyServer {
    #[tool(description = "Convert currency using live exchange rates from api.exchangerate.host")]
    async fn convert(&self, #[tool(aggr)] req: ConvertRequest) -> Result<String> {
        // This method is async because it performs a network request
        let url = format!(
            "https://api.exchangerate.host/convert?from={}&to={}&amount={}",
            req.from, req.to, req.amount
        );

        // Use reqwest to make the HTTP GET request and await the response
        let resp = reqwest::get(&url).await?
                      .json::<ApiResponse>().await?; // Parse JSON response into ApiResponse

        // Format the result nicely
        Ok(format!("{:.2} {}", resp.result, req.to))
    }
}

// Requires a tokio runtime to execute async functions.

* Uses `async fn` because `reqwest::get` is an asynchronous operation. Requires an async runtime like `tokio`.
* Makes an HTTP GET request to an external currency API.
* Uses `serde` to deserialize the JSON response from the API into the `ApiResponse` struct.

**2.3. Task Manager**

A stateful tool to manage a simple list of tasks.

use rmcp::{tool, tool_box};
use serde::{Deserialize, Serialize};
use schemars::JsonSchema;
use anyhow::Result;
use std::sync::{Arc, Mutex}; // For shared mutable state

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
struct Task {
    title: String,
    done: bool,
}

#[derive(Debug, Deserialize, JsonSchema)]
struct TaskRequest {
    title: String,
    done: bool, // Assuming we want to set status on add
}

#[derive(Clone)] // Clone is needed for the server state to be shared across requests
struct TaskManager {
    // Use Arc<Mutex<T>> for thread-safe shared mutable state
    tasks: Arc<Mutex<Vec<Task>>>,
}

impl TaskManager {
    // Constructor to initialize the state
    fn new() -> Self {
        TaskManager {
            tasks: Arc::new(Mutex::new(Vec::new())),
        }
    }
}

#[tool_box]
impl TaskManager {
    #[tool(description = "Add a new task")]
    fn add_task(&self, #[tool(aggr)] req: TaskRequest) -> Result<String> {
        // Lock the mutex to safely access the shared task list
        let mut tasks = self.tasks.lock().unwrap(); // .unwrap() is used for simplicity here
        tasks.push(Task { title: req.title, done: req.done });
        Ok("Task added.".to_string())
    }

    #[tool(description = "List all tasks")]
    fn list_tasks(&self) -> Result<Vec<Task>> {
        // Lock, clone the current list, and return it
        let tasks = self.tasks.lock().unwrap();
        Ok(tasks.clone()) // Clone the data to release the lock quickly
    }
}

* Demonstrates state management using `Arc<Mutex<Vec<Task>>>` for sharing the task list safely across concurrent requests (if the server runs multithreaded).
* `list_tasks` returns the list of `Task` structs directly. `rmcp` handles serializing this into the JSON-RPC response.

**2.4. Weather Forecast**

Fetches weather from the `wttr.in` service.

use rmcp::{tool, tool_box};
use serde::Deserialize;
use schemars::JsonSchema;
use anyhow::Result;
use reqwest;

#[derive(Clone)] // Added Clone trait
struct WeatherServer;

#[derive(Debug, Deserialize, JsonSchema)]
struct CityRequest {
    city: String,
}

#[tool_box]
impl WeatherServer {
    #[tool(description = "Get city weather from wttr.in")]
    async fn get_forecast(&self, #[tool(aggr)] req: CityRequest) -> Result<String> {
        // Async again due to network call
        let url = format!("https://wttr.in/{}?format=3", req.city); // format=3 gives concise output
        let forecast = reqwest::get(&url).await?
                        .text().await?; // Get response body as plain text
        Ok(forecast)
    }
}

* Similar to the currency converter, uses `async fn` and `reqwest` for an external HTTP request.
* Fetches plain text data from `wttr.in`.

**2.5. JSON Formatter**

A simple tool to prettify a JSON string.

use rmcp::{tool, tool_box};
use anyhow::Result;
use serde_json; // Use serde_json for JSON manipulation

#[derive(Clone)] // Added Clone trait
struct JsonServer;

#[tool_box]
impl JsonServer {
    #[tool(description = "Prettify a JSON string")]
    fn format_json(&self, #[tool(param)] raw: String) -> Result<String> {
        // #[tool(param)] indicates 'raw' is the single, unnamed parameter
        // expected in the JSON-RPC request's "params" field.

        // Parse the raw string into a generic JSON value
        let value: serde_json::Value = serde_json::from_str(&raw)?;

        // Serialize the value back to a prettified string
        Ok(serde_json::to_string_pretty(&value)?)
    }
}

* Uses `#[tool(param)]` for methods expecting a single unnamed parameter in the `params` field of the JSON-RPC request (e.g., `"params": "{\"key\":\"value\"}"`).
* Leverages `serde_json` to parse and then re-serialize the JSON data with pretty printing.

**3. KYC Tool Set — Servers & Client Interaction**

Now, let's look at more specialized tools, common in KYC (Know Your Customer) processes. We'll show both the server-side tool definition and how a client might call it.

*(Note: These KYC examples are illustrative and simplified.)*

**3.1. Identity OCR Tool**

**Server:** Extracts text from an image file using the external `tesseract` OCR tool.

# // --- Server Code ---
# use rmcp::{tool, tool_box};
# use serde::Deserialize;
# use schemars::JsonSchema;
# use anyhow::Result;
# use std::process::Command; // To run external processes
#
# // Assuming KycServer is defined elsewhere or combined
# #[derive(Clone)] struct KycServer;
#
# #[derive(Debug, Deserialize, JsonSchema)]
# struct OcrRequest {
#     image_path: String, // Path to the image file for OCR
# }
#
# #[tool_box]
# impl KycServer { // Assuming methods are added to a common KycServer
    #[tool(description = "Extract text from an ID document image using Tesseract OCR")]
    async fn extract_id_text(&self, #[tool(aggr)] req: OcrRequest) -> Result<String> {
        // Run the tesseract command externally
        // Assumes 'tesseract' executable is in the system's PATH
        let output = Command::new("tesseract")
            .arg(&req.image_path) // Input image file
            .arg("stdout")        // Output result to stdout
            .output()?;           // Execute and wait for completion

        if output.status.success() {
            // Convert stdout bytes to a UTF-8 string (lossy conversion handles potential errors)
            Ok(String::from_utf8_lossy(&output.stdout).to_string())
        } else {
            // If tesseract failed, return an error
            let stderr = String::from_utf8_lossy(&output.stderr);
            Err(anyhow::anyhow!("Tesseract failed: {}", stderr))
        }
    }
# }

* Uses `std::process::Command` to execute the `tesseract` command-line tool.
* Requires `tesseract` to be installed on the server machine where this Rust code runs.
* Handles potential errors from the external process.

**Client:** Example of calling this tool using `rmcp` client (raw request).

# // --- Client Code Example ---
# use rmcp::client::Client; // Assuming 'Client' is set up
# use serde_json::json;
# use anyhow::Result;
#
# async fn call_ocr_tool(client: &Client) -> Result<()> {
let request_payload = json!({
    "jsonrpc": "2.0",
    "id": 1, // Request ID
    "method": "extract_id_text", // Matches the server function name
    "params": { // Corresponds to #[tool(aggr)] req: OcrRequest
        "image_path": "./path/to/your/id_photo.png"
    }
});

// Assuming 'client' is an initialized rmcp::client::Client
let result = client.send_raw(request_payload).await?;

println!("OCR Result: {:?}", result); // Prints the raw JSON-RPC response
# Ok(())
# }

* Constructs a standard JSON-RPC 2.0 request payload using `serde_json::json!`.
* Sends the raw request using `client.send_raw`. The `result` will be the full JSON-RPC response `{ "jsonrpc": "2.0", "id": 1, "result": "extracted text..." }` or an error object.

**3.2. Bank Account Verification**

**Server:** A simplified check matching name and IBAN details.

# // --- Server Code ---
# use rmcp::{tool, tool_box};
# use serde::Deserialize;
# use schemars::JsonSchema;
# use anyhow::Result;
#
# // Assuming KycServer is defined elsewhere or combined
# #[derive(Clone)] struct KycServer;
#
#[derive(Debug, Deserialize, JsonSchema)]
struct BankCheckRequest {
    name: String,
    iban: String,
}

#[tool_box]
impl KycServer { // Assuming methods are added to a common KycServer
    #[tool(description = "Verify bank holder name and IBAN match (simplified check)")]
    async fn verify_bank(&self, #[tool(aggr)] req: BankCheckRequest) -> Result<String> {
        // Basic placeholder logic: Checks if IBAN starts with 'FR' and name contains 'test' (case-insensitive)
        // Replace with actual validation logic (e.g., API call to a verification service)
        if req.iban.starts_with("FR") && req.name.to_lowercase().contains("test") {
            Ok("Match confirmed (Test Logic).".to_string())
        } else {
            Ok("No match found (Test Logic).".to_string())
        }
    }
}

* Implements placeholder logic for demonstration. A real-world tool would integrate with a banking API or database.

**Client:** Example call.

# // --- Client Code Example ---
# use rmcp::client::Client; // Assuming 'Client' is set up
# use serde_json::json;
# use anyhow::Result;
#
# async fn call_bank_verify_tool(client: &Client) -> Result<()> {
let request_payload = json!({
    "jsonrpc": "2.0",
    "id": 2, // Different request ID
    "method": "verify_bank",
    "params": { // Corresponds to #[tool(aggr)] req: BankCheckRequest
        "name": "Test User",
        "iban": "FR7612345678901234567890123"
     }
});

let result = client.send_raw(request_payload).await?;

println!("Bank Verification Result: {:?}", result);
# Ok(())
# }

* Similar structure to the OCR client call, targeting the `verify_bank` method with appropriate parameters.

**4. Conclusion**

You've seen how to create various MCP tools in Rust using the `rmcp` crate, covering stateless and stateful servers, interaction with external APIs, and running external processes. The `#[tool_box]` and `#[tool]` attributes, combined with `serde` and `schemars`, provide a powerful way to expose Rust functions to AI models or other systems speaking JSON-RPC 2.0.