ExUtcp

Hex.pmHex.pmHex.pmHexDocs.pm

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

ex_utcp-2

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:

Features

Installation

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

def deps do

  [

    {:ex_utcp, "~> 0.3.2"}

  ]

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

Authentication Mapping

The converter automatically maps OpenAPI security schemes to UTCP authentication:

Architecture

The library is organized into several main components:

Implementation Status

Gap Analysis: UTCP Implementations Comparison

Feature CategoryPython UTCPGo UTCPElixir UTCPElixir Coverage
Core Architecture
Core ClientCompleteCompleteComplete100%
ConfigurationCompleteCompleteEnhanced100%
Variable SubstitutionCompleteCompleteComplete100%
Transports
HTTP/HTTPSCompleteCompleteComplete100%
CLICompleteCompleteComplete100%
WebSocketCompleteCompleteComplete100%
gRPCCompleteCompleteComplete100%
GraphQLCompleteCompleteComplete100%
MCPCompleteCompleteComplete100%
SSECompleteCompleteComplete100%
Streamable HTTPCompleteCompleteComplete100%
TCP/UDPCompleteCompleteComplete100%
WebRTCCompleteCompleteComplete100%
Authentication
API KeyCompleteCompleteComplete100%
Basic AuthCompleteCompleteComplete100%
OAuth2CompleteCompleteComplete100%
Advanced Features
StreamingCompleteCompleteComplete100%
Connection PoolingCompleteCompleteComplete100%
Error RecoveryCompleteCompleteComplete100%
OpenAPI ConverterCompleteCompleteComplete100%
Tool DiscoveryCompleteCompleteComplete100%
SearchAdvancedAdvancedComplete100%
Testing
Unit TestsCompleteCompleteComplete100%
Integration TestsCompleteCompleteComplete100%
Mock TestingCompleteCompleteComplete100%
Test CoverageHighHighHigh100%
Performance
Connection ManagementOptimizedOptimizedOptimized100%
Memory UsageOptimizedOptimizedOptimized100%
ThroughputHighHighHigh100%
Monitoring
TelemetryCompleteCompleteComplete100%
MetricsCompleteCompleteComplete100%
Health ChecksCompleteCompleteComplete100%
Performance MonitoringCompleteCompleteComplete100%
Documentation
API DocsCompleteCompleteComplete100%
ExamplesCompleteCompleteComplete100%
GuidesCompleteCompleteComplete100%

Priority Recommendations

High Priority

Medium Priority

Low Priority

Implementation Status

Completed Features

Missing Features

Roadmap

Phase 1: Core Transports (Completed)

Phase 2: Enhanced Features (Completed)

Phase 3: Extended Protocols (Completed)

Phase 4: Enterprise Features

Supported Transports

Implemented

Planned

Examples

See examples/ directory:

Testing

# Unit tests only (default - excludes integration tests)

mix test



# All tests including integration tests

mix test --include integration



# Integration tests only

mix test --only integration

The test suite is configured to exclude integration tests by default for faster development cycles. Integration tests require external services and are run separately.

Advanced Search

ExUtcp provides sophisticated search capabilities for discovering tools and providers:

Search Algorithms

Search Features

Basic Usage

# Start client

{:ok, client} = ExUtcp.Client.start_link()



# Search with different algorithms

exact_results = ExUtcp.Client.search_tools(client, "get_user", %{algorithm: :exact})

fuzzy_results = ExUtcp.Client.search_tools(client, "get_usr", %{algorithm: :fuzzy, threshold: 0.6})

semantic_results = ExUtcp.Client.search_tools(client, "user management", %{algorithm: :semantic})



# Advanced search with filters and security scanning

advanced_results = ExUtcp.Client.search_tools(client, "api", %{

  algorithm: :combined,

  filters: %{transports: [:http, :websocket], providers: ["my_api"]},

  security_scan: true,

  filter_sensitive: true,

  limit: 10

})



# Get search suggestions

suggestions = ExUtcp.Client.get_search_suggestions(client, "us", limit: 5)



# Find similar tools

similar_tools = ExUtcp.Client.find_similar_tools(client, "get_user", limit: 3)

Monitoring and Metrics

ExUtcp provides comprehensive monitoring capabilities for production deployments:

Monitoring Features

Telemetry Events

ExUtcp emits telemetry events for:

Basic Usage

# Start monitoring system

ExUtcp.Monitoring.start()



# Get system metrics

metrics = ExUtcp.Client.get_monitoring_metrics(client)



# Get health status

health = ExUtcp.Client.get_health_status(client)



# Get performance summary

performance = ExUtcp.Client.get_performance_summary(client)



# Record custom metrics

ExUtcp.Monitoring.Performance.record_custom_metric("api_requests", :counter, 1, %{endpoint: "/users"})

Prometheus Integration

Configure PromEx in your application:

# config/config.exs

config :ex_utcp, ExUtcp.Monitoring.PromEx,

  disabled: false,

  manual_metrics_start_delay: :no_delay,

  drop_metrics_groups: [],

  grafana: [

    host: "http://localhost:3000",

    username: "admin",

    password: "admin"

  ]

Comparison with Python UTCP

ExUtcp is an independent Elixir implementation of the UTCP specification.

Key Differences:

Both implementations follow the UTCP specification and excel in different areas.

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