ExUtcp

Hex.pm Hex.pm Hex.pm HexDocs.pm

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

Introduction

The Universal Tool Calling Protocol (UTCP) is a modern, flexible, and scalable standard for defining and interacting with tools across a wide variety of communication protocols. It is designed to be easy to use, interoperable, and extensible, making it a powerful choice for building and consuming tool-based services.

In contrast to other protocols like MCP, UTCP places a strong emphasis on:

Features

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"

)

Architecture

The library is organized into several main components:

Implementation Status

Gap Analysis: Elixir UTCP vs Go UTCP

Feature Category Go Implementation Elixir Implementation Coverage
Core Client Complete Complete 100%
Configuration Complete Enhanced 85%
Transports 12 types 5 types 42%
Providers 12 types 5 types 42%
Authentication 3 types 3 types 100%
Tool Management Complete Complete 100%
Streaming Complete Production Ready 100%
Search Advanced Enhanced 75%
Performance Optimized Production Ready 95%
Error Handling Robust Production Ready 100%

Priority Recommendations

High Priority (Core Functionality)

Medium Priority (Enhanced Features)

Low Priority (Nice to Have)

Current Implementation Status

Major Achievements

Completed Features

In Progress

Planned

Roadmap

Phase 1: Complete Core Transports (Current)

Phase 2: Enhanced Features

Phase 3: Extended Protocol Support

Phase 4: Enterprise Features

Supported Transports

Implemented

In Progress

Planned

Examples

Check the examples/ directory for complete working examples:

Testing

Run the test suite:

mix test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MPL-2.0 License - see the LICENSE file for details.

Links