ExUtcp

Elixir implementation of the Universal Tool Calling Protocol (UTCP).

Introduction

The Universal Tool Calling Protocol (UTCP) is a standard for defining and interacting with tools across communication protocols. UTCP emphasizes scalability, interoperability, and ease of use.

Key characteristics:

• Scalability: Handles large numbers of tools and providers without performance degradation
• Interoperability: Supports multiple provider types including HTTP, WebSockets, gRPC, and CLI tools
• Ease of Use: Built on simple, well-defined patterns

Features

• Transports: HTTP, CLI, WebSocket, gRPC, GraphQL, MCP
• Streaming support across all transports
• OpenAPI Converter: Automatic API discovery and tool generation
• Variable substitution via environment variables or .env files
• In-memory repository for providers and tools
• Authentication: API Key, Basic, OAuth2
• Connection pooling and lifecycle management
• Comprehensive test suite with 272+ tests

Installation

Add ex_utcp to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_utcp, "~> 0.2.0"}
  ]
end

Getting Started

Basic Usage

alias ExUtcp.{Client, Config}

# Create a client configuration
config = Config.new(providers_file_path: "providers.json")

# Start a UTCP client
{:ok, client} = Client.start_link(config)

# Search for tools
{:ok, tools} = Client.search_tools(client, "", 10)

# Call a tool
{:ok, result} = Client.call_tool(client, "provider.tool_name", %{"arg" => "value"})

Programmatic Provider Registration

alias ExUtcp.{Client, Config, Providers}

# Create a client
config = Config.new()
{:ok, client} = Client.start_link(config)

# Create an HTTP provider
provider = Providers.new_http_provider([
  name: "my_api",
  url: "https://api.example.com/tools",
  http_method: "POST"
])

# Register the provider
{:ok, tools} = Client.register_tool_provider(client, provider)

# Call a discovered tool
{:ok, result} = Client.call_tool(client, "my_api.echo", %{"message" => "Hello!"})

CLI Provider Example

alias ExUtcp.{Client, Config, Providers}

# Create a client
config = Config.new()
{:ok, client} = Client.start_link(config)

# Create a CLI provider
provider = Providers.new_cli_provider([
  name: "my_script",
  command_name: "python my_script.py",
  working_dir: "/path/to/script"
])

# Register the provider
{:ok, tools} = Client.register_tool_provider(client, provider)

# Call a tool
{:ok, result} = Client.call_tool(client, "my_script.greet", %{"name" => "World"})

Configuration

Provider Configuration File

Create a providers.json file to define your providers:

{
  "providers": [
    {
      "name": "http_api",
      "type": "http",
      "http_method": "POST",
      "url": "https://api.example.com/tools",
      "content_type": "application/json",
      "headers": {
        "User-Agent": "ExUtcp/0.2.0"
      },
      "auth": {
        "type": "api_key",
        "api_key": "${API_KEY}",
        "location": "header",
        "var_name": "Authorization"
      }
    },
    {
      "name": "cli_tool",
      "type": "cli",
      "command_name": "python my_tool.py",
      "working_dir": "/opt/tools",
      "env_vars": {
        "PYTHONPATH": "/opt/tools"
      }
    }
  ]
}

Variable Substitution

UTCP supports variable substitution using ${VAR} or $VAR syntax:

# Load variables from .env file
{:ok, env_vars} = Config.load_from_env_file(".env")

config = Config.new(
  variables: env_vars,
  providers_file_path: "providers.json"
)

OpenAPI Converter

The OpenAPI Converter automatically discovers and converts OpenAPI specifications into UTCP tools.

Basic Usage

alias ExUtcp.{Client, Config}

# Create a client
{:ok, client} = Client.start_link(%{providers_file_path: nil, variables: %{}})

# Convert OpenAPI spec from URL
{:ok, tools} = Client.convert_openapi(client, "https://api.example.com/openapi.json")

# Convert OpenAPI spec from file
{:ok, tools} = Client.convert_openapi(client, "path/to/spec.yaml")

# Convert with options
{:ok, tools} = Client.convert_openapi(client, spec, %{
  prefix: "my_api",
  auth: %{type: "api_key", api_key: "Bearer ${API_KEY}"}
})

Supported Formats

• OpenAPI 2.0 (Swagger)
• OpenAPI 3.0
• JSON and YAML specifications
• URL and file-based specifications

Authentication Mapping

The converter automatically maps OpenAPI security schemes to UTCP authentication:

• API Key authentication
• HTTP Basic authentication
• HTTP Bearer authentication
• OAuth2 flows
• OpenID Connect

Architecture

The library is organized into several main components:

• ExUtcp.Client - Main client interface
• ExUtcp.Config - Configuration management
• ExUtcp.Providers - Provider implementations for different protocols
• ExUtcp.Transports - Transport layer implementations
• ExUtcp.Tools - Tool definitions and management
• ExUtcp.Repository - Tool and provider storage
• ExUtcp.OpenApiConverter - OpenAPI specification conversion

Implementation Status

Gap Analysis: UTCP Implementations Comparison

Priority Recommendations

High Priority

• OpenAPI Converter: Automatic API discovery and tool generation
• Advanced Search: Sophisticated search algorithms
• TCP/UDP Transport: Low-level network protocols

Medium Priority

• Monitoring: Metrics and health checks
• Batch Operations: Multiple tool calls
• WebRTC Transport: Peer-to-peer communication

Low Priority

• Custom Variable Loaders: Beyond .env files
• API Documentation Generation

Implementation Status

Completed Features

• 6 transports: HTTP, CLI, WebSocket, gRPC, GraphQL, MCP
• Streaming support across all transports
• OpenAPI Converter: Automatic API discovery and tool generation
• Authentication: API Key, Basic, OAuth2
• Connection pooling and lifecycle management
• Error recovery with retry logic
• 272+ tests with comprehensive coverage
• Production examples for all transports

Missing Features

• Advanced Search: Sophisticated search algorithms
• TCP/UDP Transport: Low-level network protocols
• WebRTC Transport: Peer-to-peer communication
• Monitoring: Metrics and health checks
• Batch Operations: Multiple tool calls

Roadmap

Phase 1: Core Transports (Completed)

• HTTP/HTTPS, CLI, WebSocket, gRPC, GraphQL, MCP

Phase 2: Enhanced Features

• OpenAPI Converter
• Advanced Search
• Monitoring and Metrics

Phase 3: Extended Protocols

• TCP/UDP Transport
• WebRTC Transport

Phase 4: Enterprise Features

• Batch Operations
• Custom Variable Loaders
• API Documentation Generation

Supported Transports

Implemented

• HTTP/HTTPS: REST API integration with OpenAPI support
• CLI: Command-line tool integration
• WebSocket: Real-time communication
• gRPC: High-performance RPC calls with Protocol Buffers
• GraphQL: GraphQL API integration with HTTP/HTTPS
• MCP: Model Context Protocol integration with JSON-RPC 2.0

Planned

• TCP/UDP: Low-level network protocols
• WebRTC: Peer-to-peer communication

Examples

See examples/ directory:

• http_client.exs - HTTP provider
• cli_client.exs - CLI provider
• websocket_client.exs - WebSocket provider
• grpc_client.exs - gRPC provider
• graphql_example.exs - GraphQL provider
• mcp_example.exs - MCP provider
• streaming_examples.exs - Streaming examples
• openapi_example.exs - OpenAPI Converter examples

Testing

# All tests
mix test

# Unit tests only
mix test --exclude integration

# Integration tests only
mix test --only integration

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Links

• UTCP Website
• Go Implementation
• Python Implementation
• Hex Package
• HexDocs