rs-utcp

Universal Tool Calling Protocol Client for Rust

A powerful, async-first Rust implementation of the Universal Tool Calling Protocol (UTCP)

---

🌟 Features

• 🔌 12 Communication Protocols (formerly transports) - HTTP, MCP, WebSocket, gRPC, CLI, GraphQL, TCP, UDP, SSE, WebRTC, HTTP Streams, and Text-based
• 🚀 Async/Await Native - Built with Tokio for high-performance concurrent operations
• 📦 Config-Driven - Load tool providers from JSON with automatic discovery and registration
• 🔍 Smart Tool Discovery - Tag-based semantic search across all registered tools
• 🤖 LLM Integration - Built-in Codemode orchestrator for AI-driven workflows
• 🔄 Auto-Migration - Seamless compatibility with UTCP v0.1 and v1.0 formats
• 📝 OpenAPI Support - Automatic tool generation from OpenAPI 3.0 specifications
• 🔐 Multi-Auth - Support for API keys, Basic Auth, OAuth2, and custom authentication
• 💾 Streaming - First-class support for streaming responses across compatible communication protocols
• 🧪 Well-Tested - 90+ tests ensuring reliability and correctness

📦 Installation

Add rs-utcp to your Cargo.toml:

[dependencies]
rs-utcp = "0.1.8"
tokio = { version = "1.0", features = ["full"] }

Or use cargo add:

cargo add rs-utcp
cargo add tokio --features full

🚀 Quick Start

Basic Usage

use rs_utcp::{
    config::UtcpClientConfig,
    repository::in_memory::InMemoryToolRepository,
    tag::tag_search::TagSearchStrategy,
    UtcpClient, UtcpClientInterface,
};
use std::{collections::HashMap, sync::Arc};
#[tokio::main] async fn main() -> anyhow::Result<()> {     // 1. Configure the client     let config = UtcpClientConfig::new()         .withmanualpath("providers.json".into());          // 2. Set up repository and search     let repo = Arc::new(InMemoryToolRepository::new());     let search = Arc::new(TagSearchStrategy::new(repo.clone(), 1.0));          // 3. Create the client     let client = UtcpClient::create(config, repo, search).await?;          // 4. Discover tools     let tools = client.search_tools("weather", 10).await?;     println!("Found {} tools", tools.len());          // 5. Call a tool     let mut args = HashMap::new();     args.insert("city".tostring(), serdejson::json!("London"));          let result = client.calltool("weather.getforecast", args).await?;     println!("Result: {}", serdejson::tostring_pretty(&result)?);          Ok(()) }

Configuration File (providers.json)

{
  "manual_version": "1.0.0",
  "utcp_version": "0.3.0",
  "allowedcommunicationprotocols": ["http", "mcp"],
  "info": {
    "title": "Example UTCP Manual",
    "version": "1.0.0",
    "description": "Manual v1.0 with tools"
  },
  "tools": [
    {
      "name": "get_forecast",
      "description": "Get current weather for a city",
      "inputs": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "City name" },
          "units": { "type": "string", "enum": ["metric", "imperial"] }
        },
        "required": ["city"]
      },
      "outputs": { "type": "object" },
      "toolcalltemplate": {
        "calltemplatetype": "http",
        "name": "weather_api",
        "url": "https://api.weather.example.com/tools",
        "http_method": "GET",
        "headers": { "Accept": "application/json" }
      },
      "tags": ["weather", "demo"]
    },
    {
      "name": "read_file",
      "description": "Read a text file via MCP stdio",
      "inputs": {
        "type": "object",
        "properties": {
          "path": { "type": "string", "description": "File path" }
        },
        "required": ["path"]
      },
      "outputs": { "type": "object" },
      "toolcalltemplate": {
        "calltemplatetype": "mcp",
        "name": "file_tools",
        "command": "python3",
        "args": ["mcp_server.py"]
      },
      "tags": ["mcp", "filesystem"]
    }
  ],
  "loadvariablesfrom": [
    {
      "variableloadertype": "dotenv",
      "envfilepath": ".env"
    }
  ]
}

🔌 Supported Communication Protocols

rs-utcp supports a comprehensive range of communication protocols, each with full async support:

Production-Ready Protocols

| Protocol | Description | Status | Streaming | |-----------|-------------|--------|-----------| | HTTP | REST APIs with UTCP manifest or OpenAPI | ✅ Stable | ❌ | | MCP | Model Context Protocol (stdio & SSE) | ✅ Stable | ✅ | | WebRTC | P2P data channels with signaling | ✅ Stable | ✅ | | WebSocket | Real-time bidirectional communication | ✅ Stable | ✅ | | CLI | Execute local binaries as tools | ✅ Stable | ❌ | | gRPC | High-performance RPC with TLS & auth metadata | ✅ Stable | ✅ | | GraphQL | Query-based tool calling with type-aware variables | ✅ Stable | ❌ | | SSE | Server-Sent Events | ✅ Stable | ✅ | | HTTP Streams | Streaming HTTP responses | ✅ Stable | ✅ | | TCP | Low-level socket transport (framed JSON) | ✅ Stable | ✅ | | UDP | Low-level datagram transport | ✅ Stable | ❌ | | Text | File-based tool providers (JS/SH/Python/exe) | ✅ Stable | ❌ |

💡 Examples

HTTP Provider with OpenAPI

use rs_utcp::openapi::OpenApiConverter;
// Automatically convert OpenAPI spec to UTCP tools let converter = OpenApiConverter::newfromurl(     "https://petstore.swagger.io/v2/swagger.json",     Some("petstore".to_string()) ).await?;
let manual = converter.convert(); println!("Discovered {} tools from OpenAPI spec", manual.tools.len());

MCP Stdio Provider

let config = serde_json::json!({
    "manualcalltemplates": [{
        "calltemplatetype": "mcp",
        "name": "calculator",
        "command": "python3",
        "args": ["calculator_server.py"],
        "env_vars": {
            "DEBUG": "1"
        }
    }]
});
let client = createclientfrom_config(config).await?; let result = client.call_tool("calculator.add",      HashMap::from([         ("a".to_string(), json!(5)),         ("b".to_string(), json!(3))     ]) ).await?;

Streaming Tools

// Call a streaming tool
let mut stream = client.calltoolstream(
    "sse_provider.events",
    HashMap::new()
).await?;
// Process stream results while let Some(item) = stream.next().await {     match item {         Ok(value) => println!("Received: {}", value),         Err(e) => eprintln!("Error: {}", e),     } }
stream.close().await?;

WebRTC Peer-to-Peer

WebRTC enables direct peer-to-peer tool calling:

# Terminal 1: Start WebRTC server with signaling
cargo run --example webrtc_server
Terminal 2: Connect and call tools
cargo run --example webrtc_client

See examples/webrtc_server/ for the complete implementation.

🤖 Codemode & LLM Orchestration

rs-utcp includes a powerful Codemode feature that enables dynamic script execution with full access to registered tools. This is perfect for LLM-driven workflows.

Codemode Basics

use rs_utcp::plugins::codemode::{CodeModeUtcp, CodeModeArgs};
let codemode = CodeModeUtcp::new(client);
// Execute a Rhai script that calls tools let script = r#"     let weather = calltool("weather.getforecast", #{         "city": "Tokyo"     });          let summary = call_tool("ai.summarize", #{         "text": weather.to_string()     });          summary "#;
let result = codemode.execute(CodeModeArgs {     code: script.to_string(),     timeout: Some(30_000), }).await?;
println!("Result: {:?}", result.value);

LLM Orchestration

The CodemodeOrchestrator provides a 4-step AI-driven workflow:

• Decide - LLM determines if tools are needed
• Select - LLM chooses relevant tools
• Generate - LLM writes a Rhai script
• Execute - Script runs in sandboxed environment

use rs_utcp::plugins::codemode::CodemodeOrchestrator;
let codemode = Arc::new(CodeModeUtcp::new(client)); let llm_model = Arc::new(YourLLMModel::new()); let orchestrator = CodemodeOrchestrator::new(codemode, llm_model);
// Let the LLM figure out how to accomplish the task let result = orchestrator     .call_prompt("Get the weather in Paris and summarize it")     .await?;
match result {     Some(value) => println!("LLM completed task: {}", value),     None => println!("No tools needed for this request"), }

See the Gemini example for a complete LLM integration.

Codemode Security

Codemode executes scripts in a hardened sandbox with comprehensive security measures:

• ✅ Code Validation - Pre-execution checks for dangerous patterns and size limits
• ✅ Timeout Enforcement - Strict timeouts (5s default, 30s max) prevent runaway scripts
• ✅ Resource Limits - Memory, CPU, and output size constraints
• ✅ Sandboxed Execution - Rhai scripts run isolated from the file system and OS

See SECURITY.md for complete security documentation.

🎯 Use Cases

1. Multi-Protocol API Gateway

Call tools across HTTP, gRPC, and MCP from a single unified interface.

2. LLM Agent Toolkit

Provide language models with a consistent way to execute tools regardless of their implementation.

3. Microservices Orchestration

Coordinate calls across heterogeneous services using different protocols.

4. Plugin System

Build extensible applications where plugins can be added via configuration.

5. Testing & Mocking

Easily swap implementations (e.g., HTTP → CLI) for testing without code changes.

📚 Documentation

• API Documentation - Complete API reference
• UTCP Specification - Protocol specification
• Examples - Working examples for all transports
• SECURITY - Security features and best practices
• CHANGELOG - Version history and changes

🧪 Testing

Run the comprehensive test suite:

# Run all tests
cargo test
Run with output
cargo test -- --nocapture
Run specific test
cargo test testhttptransport
Run examples
cargo run --example basic_usage
cargo run --example all_providers

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                   UtcpClient                        │
│  (Unified interface for all tool operations)       │
└─────────────────┬───────────────────────────────────┘
                  │
         ┌────────┴──────────┐
         │                   │
  ┌──────▼──────┐   ┌────────▼────────┐
  │  Repository │   │ Communication   │
  │             │   │ Protocols       │
  │  - Tools    │   │  - HTTP         │
  │  - Search   │   │  - MCP          │
  └─────────────┘   │  - gRPC         │
                    │  - WebSocket    │
                    │  - CLI          │
                    │  - etc.         │
                    └─────────────────┘

Key Components

• UtcpClient - Main entry point for all operations
• CommunicationProtocolRegistry (was TransportRegistry) - Manages all communication protocol implementations
• Call template handlers - Registry that maps calltemplatetype to provider builders
• ToolRepository - Stores and indexes discovered tools
• SearchStrategy - Semantic search across tools
• Codemode - Script execution environment
• Loader - Configuration and provider loading

Plugin registration (custom protocols)

Register new communication protocols and call template handlers before constructing your client:

use std::sync::Arc;
use rsutcp::calltemplates::registercalltemplate_handler;
use rsutcp::transports::registercommunication_protocol;
fn myprototemplatehandler(template: serdejson::Value) -> anyhow::Result<serdejson::Value> {     // normalize/augment the template into a provider config     Ok(template) }
registercalltemplatehandler("myproto", myprototemplate_handler); registercommunicationprotocol("myproto", Arc::new(MyProtocol::new())); // implements CommunicationProtocol

🔧 Advanced Configuration

Authentication

{
  "manualcalltemplates": [{
    "calltemplatetype": "http",
    "name": "secure_api",
    "url": "https://api.example.com",
    "auth": {
      "authtype": "apikey",
      "apikey": "${APIKEY}",
      "var_name": "X-API-Key",
      "location": "header"
    }
  }]
}

Environment Variables

{
  "loadvariablesfrom": [
    {
      "variableloadertype": "dotenv",
      "envfilepath": ".env"
    }
  ],
  "variables": {
    "DEFAULT_TIMEOUT": "30000"
  }
}

Protocol Restrictions

You can restrict which communication protocols are allowed for a manual or provider using the allowedcommunicationprotocols field. This provides a secure-by-default mechanism where tools can only use their own protocol unless explicitly allowed.

{
  "manual_version": "1.0.0",
  "info": { "title": "Restricted Manual", "version": "1.0.0" },
  "allowedcommunicationprotocols": ["http", "cli"],
  "tools": [
    {
      "name": "http_tool",
      "toolcalltemplate": {
        "calltemplatetype": "http",
        "url": "http://example.com"
      }
    },
    {
      "name": "cli_tool",
      "toolcalltemplate": {
        "calltemplatetype": "cli",
        "command": "echo"
      }
    }
  ]
}

If allowedcommunicationprotocols is not specified, it defaults to only allowing the tool's own protocol type. Tools attempting to use disallowed protocols will be filtered out during registration, and calls will fail validation.

Custom Search Strategy

use rs_utcp::tools::ToolSearchStrategy;
use asynctrait::asynctrait;
struct MySearchStrategy;
#[async_trait] impl ToolSearchStrategy for MySearchStrategy {     async fn search_tools(&self, query: &str, limit: usize)          -> anyhow::Result<Vec<Tool>>      {         // Your custom search logic         Ok(vec![])     } }

🤝 Contributing

Contributions are welcome! Here's how you can help:

• Found a bug? Open an issue
• Have a feature idea? Start a discussion
• Want to contribute code? Submit a PR

Development Setup

# Clone the repository
git clone https://github.com/universal-tool-calling-protocol/rs-utcp.git
cd rs-utcp
Run tests
cargo test
Format code
cargo fmt
Run lints
cargo clippy
Build all examples
cargo build --examples

📜 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

🙏 Acknowledgments

• Inspired by go-utcp
• Built on the UTCP specification
• Powered by the amazing Rust async ecosystem

📬 Contact & Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• UTCP Community: utcp.io

---

Made with ❤️ by the UTCP community