r402_mcp/lib.rs
1#![cfg_attr(docsrs, feature(doc_cfg))]
2
3//! MCP (Model Context Protocol) integration for the x402 payment protocol.
4//!
5//! This crate enables paid tool calls in MCP servers and automatic payment
6//! handling in MCP clients, following the x402 payment protocol specification.
7//!
8//! # Architecture
9//!
10//! The crate provides framework-agnostic types and utilities that work with
11//! any MCP SDK implementation via [`serde_json::Value`]-based interfaces.
12//!
13//! # Client Usage
14//!
15//! Wrap an MCP session with automatic x402 payment handling:
16//!
17//! ```rust,ignore
18//! use r402_mcp::client::{X402McpClient, ClientOptions};
19//!
20//! let mcp_client = X402McpClient::builder(my_mcp_caller)
21//! .scheme_client(evm_scheme_client)
22//! .build();
23//!
24//! // Tool calls automatically handle 402 payment flows
25//! let result = mcp_client.call_tool("get_weather", args).await?;
26//! ```
27//!
28//! # Server Usage
29//!
30//! Wrap tool handlers with payment verification and settlement:
31//!
32//! ```rust,ignore
33//! use r402_mcp::server::{PaymentWrapper, PaymentWrapperConfig};
34//!
35//! let wrapper = PaymentWrapper::new(facilitator, PaymentWrapperConfig {
36//! accepts: payment_requirements,
37//! resource: Some(resource_info),
38//! ..Default::default()
39//! });
40//!
41//! // Process tool calls with automatic payment enforcement
42//! let result = wrapper.process(request, |req| async { handle_tool(req).await }).await;
43//! ```
44//!
45//! # Utility Functions
46//!
47//! The [`extract`] module provides low-level helpers for working with
48//! x402 payment data in MCP `_meta` fields:
49//!
50//! - [`extract::extract_payment_from_meta`] - Extract payment payload from request meta
51//! - [`extract::attach_payment_to_meta`] - Attach payment payload to request meta
52//! - [`extract::extract_payment_response_from_meta`] - Extract settlement response from result meta
53//! - [`extract::extract_payment_required_from_result`] - Extract 402 info from error results
54//!
55//! # Feature Flags
56//!
57//! - `rmcp` — Built-in integration with the official [`rmcp`](https://docs.rs/rmcp) Rust MCP SDK
58//! - `telemetry` — Enables tracing instrumentation for debugging and monitoring
59
60pub mod client;
61pub mod error;
62pub mod extract;
63pub mod server;
64pub mod types;
65
66#[cfg(feature = "rmcp")]
67#[cfg_attr(docsrs, doc(cfg(feature = "rmcp")))]
68pub mod rmcp_compat;
69
70/// MCP `_meta` key for sending payment payloads (client → server).
71pub const PAYMENT_META_KEY: &str = "x402/payment";
72
73/// MCP `_meta` key for settlement responses (server → client).
74pub const PAYMENT_RESPONSE_META_KEY: &str = "x402/payment-response";
75
76/// JSON-RPC error code for payment required (x402).
77pub const PAYMENT_REQUIRED_CODE: i32 = 402;
78
79/// MCP error envelope key for x402 payment errors (TS SDK compatibility).
80///
81/// The `@x402/mcp` TS SDK wraps 402 errors as:
82/// ```json
83/// { "x402/error": { "code": 402, "data": { /* PaymentRequired */ } } }
84/// ```
85pub const PAYMENT_ERROR_KEY: &str = "x402/error";