feat: add ledgerflow-mcp crate for x402 verification and settlement tools

- Introduced a new crate `ledgerflow-mcp` with a complete implementation of an MCP server.
- Added dependencies for ultrafast-mcp and x402-rs to facilitate the server's functionality.
- Implemented tool handlers for `x402_supported`, `x402_verify`, and `x402_settle` methods.
- Configured the server to run over stdio or as an HTTP server based on command-line arguments.
- Updated the README with usage instructions and tool descriptions.
- Refactored existing code in `ledgerflow-facilitator` to accommodate the new structure and dependencies.

Author: Akagi201

Cargo.lock

@@ -10,6 +10,7 @@ members = [
     "ledgerflow-aptos-cli",
     "ledgerflow-sui-cli",
     "ledgerflow-facilitator",
+    "ledgerflow-mcp",
 ]
 resolver = "2"
 

Cargo.toml

@@ -1,4 +1,5 @@
 //! Axum handlers wrapping x402-rs facilitator logic.
+#![allow(dead_code)]
 
 use axum::{http::StatusCode, response::IntoResponse, Extension, Json};
 use tracing::instrument;

ledgerflow-facilitator/src/handlers.rs

@@ -1,7 +1,7 @@
-#[path = "handlers.rs"]
-pub mod handlers;
 #[path = "config.rs"]
 pub mod config;
+#[path = "handlers.rs"]
+pub mod handlers;
 use axum::{
     http::Method,
     routing::{get, post},

ledgerflow-facilitator/src/lib.rs

@@ -9,20 +9,15 @@
 
 use std::net::SocketAddr;
 
-use axum::Router;
 use clap::Parser;
 use color_eyre::Result;
 use dotenvy::dotenv;
+use ledgerflow_facilitator::config::{load_config, ServerConfig};
 use tower_http::trace::TraceLayer;
 use tracing::level_filters::LevelFilter;
 use tracing_subscriber::EnvFilter;
 use x402_rs::{facilitator_local::FacilitatorLocal, provider_cache::ProviderCache};
 
-mod config;
-mod handlers;
-
-use crate::config::{load_config, ServerConfig};
-
 #[tokio::main]
 async fn main() -> Result<()> {
     color_eyre::install()?;

ledgerflow-facilitator/src/main.rs

@@ -1,7 +1,5 @@
-use axum::http::StatusCode;
-use axum::Router;
-use x402_rs::facilitator_local::FacilitatorLocal;
-use x402_rs::provider_cache::ProviderCache;
+use axum::{http::StatusCode, Router};
+use x402_rs::{facilitator_local::FacilitatorLocal, provider_cache::ProviderCache};
 
 // Tiny helper to build app with a ProviderCache that may read env; for CI we allow missing RPCs
 async fn test_app() -> eyre::Result<Router> {
@@ -78,7 +76,10 @@ async fn post_verify_rejects_invalid_payload() -> eyre::Result<()> {
         .await;
 
     // Either BAD_REQUEST for parse errors or 200 with invalid schema mapping; both are acceptable minimal checks
-    assert!(matches!(res.status_code(), StatusCode::OK | StatusCode::BAD_REQUEST));
+    assert!(matches!(
+        res.status_code(),
+        StatusCode::OK | StatusCode::BAD_REQUEST
+    ));
     Ok(())
 }
 
@@ -97,6 +98,9 @@ async fn post_settle_rejects_invalid_payload() -> eyre::Result<()> {
         .post("/settle")
         .json(&serde_json::json!({"foo":"bar"}))
         .await;
-    assert!(matches!(res.status_code(), StatusCode::OK | StatusCode::BAD_REQUEST));
+    assert!(matches!(
+        res.status_code(),
+        StatusCode::OK | StatusCode::BAD_REQUEST
+    ));
     Ok(())
 }

ledgerflow-facilitator/tests/integration.rs

@@ -0,0 +1,31 @@
+[package]
+name = "ledgerflow-mcp"
+version = "0.1.0"
+edition = "2021"
+license = "Apache-2.0 OR MIT"
+repository = "https://github.com/longcipher/ledgerflow"
+description = "MCP server exposing x402 verify/settle/supported tools for LedgerFlow"
+
+[dependencies]
+ultrafast-mcp = { version = "202506018.1.0", features = ["full"] }
+serde_json = { workspace = true }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true, features = ["env-filter"] }
+clap = { workspace = true, features = ["derive"] }
+eyre = { workspace = true }
+color-eyre = { workspace = true }
+tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
+async-trait = "0.1"
+
+# Use the facilitator crate we just built to reuse ProviderCache + handlers
+x402-rs = { git = "https://github.com/x402-rs/x402-rs", package = "x402-rs" }
+
+dotenvy = "0.15"
+
+[features]
+default = []
+# Enable HTTP transport by enabling ultrafast-mcp's HTTP feature set
+http = ["ultrafast-mcp/http-with-auth"]
+
+[package.metadata.docs.rs]
+all-features = true

ledgerflow-mcp/Cargo.toml

@@ -0,0 +1,25 @@
+# ledgerflow-mcp
+
+An MCP (Model Context Protocol) server that exposes x402 verification and settlement tools for LedgerFlow using `ultrafast-mcp`.
+
+## Tools
+
+- x402_supported: list supported networks and schemes
+- x402_verify: verify a payment intent (Exact scheme)
+- x402_settle: settle a verified intent (Exact scheme)
+
+## Run
+
+By default the server runs over stdio.
+
+```sh
+cargo run -p ledgerflow-mcp -- --stdio
+```
+
+To run as an HTTP server:
+
+```sh
+cargo run -p ledgerflow-mcp -- --http --host 127.0.0.1 --port 8765
+```
+
+Configure RPC endpoints and signer via env vars (same as `ledgerflow-facilitator`). See `ledgerflow-facilitator/README.md`.

ledgerflow-mcp/README.md

@@ -0,0 +1,193 @@
+use std::sync::Arc;
+
+use clap::Parser;
+use color_eyre::Result;
+use tracing::info;
+use ultrafast_mcp::{
+    prelude::*, ListToolsRequest, ListToolsResponse, MCPError, MCPResult, ToolCall, ToolContent,
+    ToolsCapability,
+};
+use x402_rs::{
+    facilitator::Facilitator,
+    facilitator_local::FacilitatorLocal,
+    network::Network,
+    provider_cache::ProviderCache,
+    types::{
+        Scheme, SettleRequest, SettleResponse, SupportedPaymentKind, VerifyRequest, VerifyResponse,
+        X402Version,
+    },
+};
+
+#[derive(Parser, Debug)]
+#[command(name = "ledgerflow-mcp")]
+#[command(about = "MCP server exposing x402 verify/settle/supported tools", long_about = None)]
+pub struct Args {
+    /// Run over stdio (default)
+    #[arg(long)]
+    stdio: bool,
+
+    /// Run HTTP server instead of stdio
+    #[arg(long)]
+    http: bool,
+
+    /// Host for HTTP server
+    #[arg(long, default_value = "127.0.0.1")]
+    host: String,
+
+    /// Port for HTTP server
+    #[arg(long, default_value_t = 8765)]
+    port: u16,
+}
+
+#[derive(Clone)]
+struct X402ToolHandler {
+    facilitator: FacilitatorLocal,
+}
+
+#[async_trait::async_trait]
+impl ToolHandler for X402ToolHandler {
+    async fn handle_tool_call(&self, call: ToolCall) -> MCPResult<ToolResult> {
+        match call.name.as_str() {
+            "x402_supported" => {
+                let kinds: Vec<SupportedPaymentKind> = Network::variants()
+                    .iter()
+                    .copied()
+                    .map(|n| SupportedPaymentKind {
+                        x402_version: X402Version::V1,
+                        scheme: Scheme::Exact,
+                        network: n,
+                    })
+                    .collect();
+                let payload = serde_json::json!({ "supported": kinds });
+                Ok(ToolResult {
+                    content: vec![ToolContent::text(payload.to_string())],
+                    is_error: Some(false),
+                })
+            }
+            "x402_verify" => {
+                let req_value = call.arguments.unwrap_or_default();
+                let req: VerifyRequest = serde_json::from_value(req_value)
+                    .map_err(|e| MCPError::invalid_params(format!("invalid arguments: {e}")))?;
+                let res: VerifyResponse = self
+                    .facilitator
+                    .verify(&req)
+                    .await
+                    .map_err(|e| MCPError::internal_error(e.to_string()))?;
+                Ok(ToolResult {
+                    content: vec![ToolContent::text(
+                        serde_json::to_string(&res).unwrap_or_else(|_| "{}".into()),
+                    )],
+                    is_error: Some(false),
+                })
+            }
+            "x402_settle" => {
+                let req_value = call.arguments.unwrap_or_default();
+                let req: SettleRequest = serde_json::from_value(req_value)
+                    .map_err(|e| MCPError::invalid_params(format!("invalid arguments: {e}")))?;
+                let res: SettleResponse = self
+                    .facilitator
+                    .settle(&req)
+                    .await
+                    .map_err(|e| MCPError::internal_error(e.to_string()))?;
+                Ok(ToolResult {
+                    content: vec![ToolContent::text(
+                        serde_json::to_string(&res).unwrap_or_else(|_| "{}".into()),
+                    )],
+                    is_error: Some(false),
+                })
+            }
+            _ => Err(MCPError::method_not_found(format!(
+                "tool '{}' not found",
+                call.name
+            ))),
+        }
+    }
+
+    async fn list_tools(&self, _request: ListToolsRequest) -> MCPResult<ListToolsResponse> {
+        Ok(ListToolsResponse {
+            tools: vec![
+                Tool {
+                    name: "x402_supported".to_string(),
+                    description: "List supported payment kinds (networks + schemes)".to_string(),
+                    input_schema: serde_json::json!({"type":"object","properties":{}}),
+                    output_schema: None,
+                    annotations: None,
+                },
+                Tool {
+                    name: "x402_verify".to_string(),
+                    description: "Verify a payment intent using x402 Exact scheme".to_string(),
+                    input_schema: serde_json::json!({"type":"object"}),
+                    output_schema: None,
+                    annotations: None,
+                },
+                Tool {
+                    name: "x402_settle".to_string(),
+                    description: "Settle a verified payment intent".to_string(),
+                    input_schema: serde_json::json!({"type":"object"}),
+                    output_schema: None,
+                    annotations: None,
+                },
+            ],
+            next_cursor: None,
+        })
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    color_eyre::install()?;
+    tracing_subscriber::fmt()
+        .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
+        .init();
+
+    let args = Args::parse();
+
+    // Prepare providers/signers from env (shared with facilitator crate)
+    dotenvy::dotenv().ok();
+    let providers = ProviderCache::from_env()
+        .await
+        .map_err(|e| eyre::eyre!(format!("{e}")))?;
+    let facilitator = FacilitatorLocal::new(providers);
+
+    let handler = X402ToolHandler { facilitator };
+
+    // Server info and capabilities
+    let info = ServerInfo {
+        name: "ledgerflow-mcp".to_string(),
+        version: env!("CARGO_PKG_VERSION").to_string(),
+        description: Some("MCP server exposing x402 verify/settle/supported".to_string()),
+        authors: None,
+        homepage: None,
+        license: None,
+        repository: None,
+    };
+
+    let capabilities = ServerCapabilities {
+        tools: Some(ToolsCapability {
+            list_changed: Some(true),
+        }),
+        ..Default::default()
+    };
+    let server = UltraFastServer::new(info, capabilities).with_tool_handler(Arc::new(handler));
+
+    if args.http {
+        #[cfg(feature = "http")]
+        {
+            let addr = SocketAddr::from_str(&format!("{}:{}", args.host, args.port))?;
+            info!(%addr, "Starting HTTP MCP server");
+            server
+                .run_streamable_http(addr.ip().to_string().as_str(), addr.port())
+                .await?;
+        }
+        #[cfg(not(feature = "http"))]
+        {
+            info!("HTTP feature not enabled; falling back to stdio");
+            server.run_stdio().await?;
+        }
+    } else {
+        info!("Starting stdio MCP server");
+        server.run_stdio().await?;
+    }
+
+    Ok(())
+}