go-utcp

go-utcp is the Go implementation of the Universal Tool Calling Protocol (UTCP) reimagined for Go tooling and transports. It provides a client-side library to discover, call, and manage tools across multiple transports (HTTP, Server-Sent Events, streaming HTTP, CLI tools, WebSocket, gRPC, GraphQL, TCP, UDP, WebRTC, MCP providers) using UTCP’s unified interface. This repository demonstrates how to instantiate a UTCP client, search for available tools, and perform tool calls with structured inputs. It also showcases CodeMode, a plugin-like helper that lets you write small Go-like snippets to call tools inside a sandboxed environment, enabling dynamic, multi-step tool workflows without heavy JSON planning. You can integrate UTCP into your Go projects to interact with a broad ecosystem of tools through a single, consistent API.

To use the library, you typically add the module to your Go project, create a UTCP client with a providers file or inline provider definitions, initialize transports, and then use the client to discover tools and call them. The included examples demonstrate client setup, tool discovery, and performing a tool call with a simple input payload. The library supports a variety of transports, so you can choose the transport that best fits your deployment (e.g., HTTP-based tools, CLI tools via local tooling, or remote MCP providers).

Prerequisites:

• Go 1.20+ installed on your system
• A Go module for your project (or initialize a new one)
• Optional: access to a running UTCP server or provider endpoints

Installation steps:

1. Create a new Go module (if you don’t have one):

go mod init your-module-name

2. Add go-utcp to your module:

go get github.com/universal-tool-calling-protocol/go-utcp@latest

3. (Optional) If you want to run a local example, create a small main.go that initializes the UTCP client. Example minimal usage (adjust to your provider/config):

package main

import (
  "context"
  "fmt"
  "time"

  utcp "github.com/universal-tool-calling-protocol/go-utcp"
)

func main() {
  ctx := context.Background()

  cfg := &utcp.UtcpClientConfig{
    ProvidersFilePath: "providers.json",
  }

  client, err := utcp.NewUTCPClient(ctx, cfg, nil, nil)
  if err != nil {
    fmt.Printf("failed to create UTCP client: %v\n", err)
    return
  }

  // Give the client time to initialize
  time.Sleep(500 * time.Millisecond)

  tools, err := client.SearchTools("", 10)
  if err != nil {
    fmt.Printf("search error: %v\n", err)
    return
  }
  fmt.Printf("Found %d tools.\n", len(tools))
}

4. Build and run your program:

go run .

Notes:

• If you’re consuming external providers, ensure their endpoints are accessible and that your networking allows the chosen transports (HTTP, WebSocket, gRPC, etc.).

Tips and common issues:

• Ensure you have a providers.json or equivalent provider configuration that points to the UTCP tools you want to access.
• When running via Docker, ensure the host has access to any required URLs or local tooling the container needs.
• If you encounter transport-specific errors, verify network policies, firewall rules, and CORS (for HTTP transports) are correctly configured.
• The CodeMode plugin can simplify crafting tool calls by letting you write Go-like code snippets instead of constructing large JSON payloads; use it to prototype multi-step tool workflows quickly.
• Environment variables can be used for dynamic substitution in UTCP, e.g., UTCP_PROVIDER_URL, UTCP_ENV_VARS, or any custom environment your providers rely on. Consider using a .env file with UtcpDotEnv as described in the README to manage substitutions.
• For production deployments, consider using a containerized UTCP server/provider stack and a dedicated orchestrator to manage transports and scaling.