rs-utcp 0.2.0

Rust implementation of the Universal Tool Calling Protocol (UTCP).
Documentation

🌟 Features

  • 🔌 12 Transport Protocols - 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 transports
  • 🧪 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()
        .with_manual_path("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".to_string(), serde_json::json!("London"));
    
    let result = client.call_tool("weather.get_forecast", args).await?;
    println!("Result: {}", serde_json::to_string_pretty(&result)?);
    
    Ok(())
}

Configuration File (providers.json)

{
  "manual_call_templates": [
    {
      "call_template_type": "http",
      "name": "weather_api",
      "url": "https://api.weather.example.com/tools",
      "http_method": "GET"
    },
    {
      "call_template_type": "mcp",
      "name": "file_tools",
      "command": "python3",
      "args": ["mcp_server.py"]
    }
  ],
  "load_variables_from": [
    {
      "variable_loader_type": "dotenv",
      "env_file_path": ".env"
    }
  ]
}

🔌 Supported Transports

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

Production-Ready Transports

Transport 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::new_from_url(
    "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!({
    "manual_call_templates": [{
        "call_template_type": "mcp",
        "name": "calculator",
        "command": "python3",
        "args": ["calculator_server.py"],
        "env_vars": {
            "DEBUG": "1"
        }
    }]
});

let client = create_client_from_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.call_tool_stream(
    "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 = call_tool("weather.get_forecast", #{
        "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:

  1. Decide - LLM determines if tools are needed
  2. Select - LLM chooses relevant tools
  3. Generate - LLM writes a Rhai script
  4. 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.

🎯 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

🧪 Testing

Run the comprehensive test suite:

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_http_transport

# Run examples
cargo run --example basic_usage
cargo run --example all_providers

🏗️ Architecture

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

Key Components

  • UtcpClient - Main entry point for all operations
  • TransportRegistry - Manages all transport implementations
  • ToolRepository - Stores and indexes discovered tools
  • SearchStrategy - Semantic search across tools
  • Codemode - Script execution environment
  • Loader - Configuration and provider loading

🔧 Advanced Configuration

Authentication

{
  "manual_call_templates": [{
    "call_template_type": "http",
    "name": "secure_api",
    "url": "https://api.example.com",
    "auth": {
      "auth_type": "api_key",
      "api_key": "${API_KEY}",
      "var_name": "X-API-Key",
      "location": "header"
    }
  }]
}

Environment Variables

{
  "load_variables_from": [
    {
      "variable_loader_type": "dotenv",
      "env_file_path": ".env"
    }
  ],
  "variables": {
    "DEFAULT_TIMEOUT": "30000"
  }
}

Custom Search Strategy

use rs_utcp::tools::ToolSearchStrategy;
use async_trait::async_trait;

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:

  1. Found a bug? Open an issue
  2. Have a feature idea? Start a discussion
  3. 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:

at your option.

🙏 Acknowledgments

📬 Contact & Support