rb-utcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f149ed8c39f7f9204dedf270af330dfca4a2a81af20da405e96c04b9b5102968
+  data.tar.gz: 4ba6c0e77734d204553d4d5de568870e1cdcab6e95057d185e1f3b653137fda1
+SHA512:
+  metadata.gz: fc94f91b7227c7fef8d3a38532ead92eeb8360bcbc5ae8216c31e072f4e5de389121d93ffd1af284cfdcd81a166de159279e5b8d5d2a1739d465365a9c5883ea
+  data.tar.gz: 4e6b711fb478658fe17ed4acbe9148b2f25b60e901e3424561a5e55d9488117dbc9e69a4772d7f58de2c241af268a43565bcd701a6591afc1df04af7acad3fdb

data/LICENSE

@@ -0,0 +1,6 @@
+Mozilla Public License Version 2.0
+==================================
+
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.

data/README.md

@@ -0,0 +1,129 @@
+# ruby-utcp (alpha)
+
+A small, dependency-light Ruby implementation of the **Universal Tool Calling Protocol (UTCP)**.
+It mirrors the core models — **Manual**, **Tool**, **Providers**, and **Auth** — and lets you
+discover tools and call them over HTTP, SSE, and HTTP chunked streams.
+
+> Status: early alpha, but usable for simple demos. Standard library only.
+
+## Features
+- Load one or more "manual providers" from `providers.json` (HTTP or local file).
+- Store discovered tools in an in-memory repository.
+- Call tools via HTTP (`GET/POST/PUT/PATCH/DELETE`), SSE, or HTTP chunked streaming.
+- API Key, Basic, and OAuth2 Client Credentials auth (token cached in memory).
+- Simple variable substitution for `${VAR}` using values from environment and `.env` files.
+- Tiny search helper scoring tags + description to find relevant tools.
+
+## Install
+This is a vanilla Ruby project. No external gems are required.
+```bash
+ruby -v   # Ruby 3.x recommended
+```
+
+## Quickstart
+```bash
+# 1) Unzip, cd in
+cd ruby-utcp
+
+# 2) (Optional) create a .env file with secrets
+echo 'OPEN_WEATHER_API_KEY=replace-me' > .env
+
+# 3) Run the example (uses httpbin.org)
+ruby examples/basic_call.rb
+```
+
+## Layout
+```
+lib/utcp.rb
+lib/utcp/version.rb
+lib/utcp/client.rb
+lib/utcp/tool.rb
+lib/utcp/errors.rb
+lib/utcp/utils/env_loader.rb
+lib/utcp/utils/subst.rb
+lib/utcp/auth.rb
+lib/utcp/tool_repository.rb
+lib/utcp/search.rb
+lib/utcp/providers/base_provider.rb
+lib/utcp/providers/http_provider.rb
+lib/utcp/providers/sse_provider.rb
+lib/utcp/providers/http_stream_provider.rb
+bin/utcp
+examples/providers.json
+examples/tools_weather.json
+examples/basic_call.rb
+```
+
+## Example manual (local file)
+See `examples/tools_weather.json` for a minimal UTCP manual that exposes two tools:
+- `echo` (POST JSON to httpbin.org)
+- `stream_http` (stream 20 JSON lines from httpbin.org)
+
+## CLI
+```bash
+# List all discovered tools
+ruby bin/utcp list examples/providers.json
+
+# Call a tool (args as JSON)
+ruby bin/utcp call examples/providers.json echo --args '{"message":"hello"}'
+```
+
+## License
+MPL-2.0
+
+
+## New transports (alpha)
+- **WebSocket**: minimal RFC6455 text-only client; great for echo/testing.
+- **GraphQL**: POST query + variables to any GraphQL endpoint.
+- **TCP/UDP**: raw sockets with simple `${var}` templating; includes local echo servers under `examples/dev/`.
+- **CLI**: call local commands (use carefully!).
+
+### Try them
+Start local echo servers (optional, for TCP/UDP):
+```bash
+ruby examples/dev/echo_tcp_server.rb 5001
+ruby examples/dev/echo_udp_server.rb 5002
+```
+
+Use the extra providers file:
+```bash
+ruby bin/utcp list examples/providers_extra.json
+ruby bin/utcp call examples/providers_extra.json ws_demo.ws_echo --args '{"text":"hello ws"}' --stream
+ruby bin/utcp call examples/providers_extra.json cli_demo.shell_echo --args '{"msg":"hi from shell"}'
+ruby bin/utcp call examples/providers_extra.json sock_demo.tcp_echo --args '{"name":"kamil"}'
+ruby bin/utcp call examples/providers_extra.json gql_demo.country_by_code --args '{"code":"DE"}'
+```
+
+
+## MCP provider
+This adds a minimal HTTP-based MCP bridge.
+
+### Discovery
+Manual discovery expects the server to return a UTCP manual at `{url}/manual` (configurable via `discovery_path`). Point a manual provider to `"provider_type": "mcp"` in `providers.json` to fetch tools.
+
+### Calls
+Tools with `"provider_type": "mcp"` will POST to `{url}/call` with:
+```json
+{ "tool": "<name>", "arguments": { "...": "..." } }
+```
+If the response is `text/event-stream` we parse SSE and yield each `data:` line; otherwise we stream raw chunks when `--stream` is used.
+
+### Example
+```bash
+# assuming an MCP test server on http://localhost:8220/mcp
+ruby bin/utcp list examples/providers_mcp.json
+ruby bin/utcp call examples/providers_mcp.json mcp_demo.hello --args '{"name":"Kamil"}'
+```
+
+
+## Tests
+This project uses **Minitest** (stdlib only).
+
+Run all tests:
+```bash
+ruby bin/test
+```
+or
+```bash
+ruby -Ilib -Itest -rminitest/autorun test/*_test.rb
+```

data/bin/utcp

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "json"
+require "utcp"
+
+usage = <<~TXT
+Usage:
+  ruby bin/utcp list <providers.json>
+  ruby bin/utcp call <providers.json> <provider.tool> --args '<json>' [--stream]
+TXT
+
+cmd = ARGV.shift
+if !cmd || %w[--help -h help].include?(cmd)
+  puts usage
+  exit 0
+end
+
+providers_path = ARGV.shift or abort usage
+
+client = Utcp::Client.create({ "providers_file_path" => providers_path })
+
+case cmd
+when "list"
+  client.repo.providers.each do |p|
+    puts "Provider: #{p}"
+  end
+  client.repo.all_tools.each do |t|
+    # We don't store full_name on the tool, so reconstruct from repo map if needed
+    # For CLI simplicity, print provider + tool name by scanning repo mapping
+    # (small overhead acceptable here)
+    client.repo.providers.each do |prov|
+      begin
+        if client.repo.find("#{prov}.#{t.name}") == t
+          puts "  - #{prov}.#{t.name} :: #{t.description}"
+        end
+      rescue
+      end
+    end
+  end
+when "call"
+  tool = ARGV.shift or abort usage
+  args = {}
+  while a = ARGV.shift
+    if a == "--args"
+      args = JSON.parse(ARGV.shift || "{}") rescue {}
+    elsif a == "--stream"
+      stream = true
+    end
+  end
+  if stream
+    client.call_tool(tool, args, stream: true) do |chunk|
+      puts chunk
+    end
+  else
+    res = client.call_tool(tool, args)
+    puts JSON.pretty_generate(res) rescue puts(res.to_s)
+  end
+else
+  abort usage
+end

data/lib/utcp/auth.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+require "base64"
+require "json"
+require "uri"
+require "net/http"
+require_relative "errors"
+require_relative "utils/subst"
+
+module Utcp
+  module Auth
+    class Base
+      def apply_headers(h) = h
+      def apply_query(uri) = uri
+    end
+
+    class ApiKey < Base
+      def initialize(api_key:, var_name: "Authorization", location: "header")
+        @api_key = Utils::Subst.apply(api_key)
+        @var_name = var_name
+        @location = location
+      end
+
+      def apply_headers(h)
+        return h unless @location == "header"
+        h[@var_name] = @api_key
+        h
+      end
+
+      def apply_query(uri)
+        return uri unless @location == "query"
+        q = URI.decode_www_form(uri.query || "") << [@var_name, @api_key]
+        uri.query = URI.encode_www_form(q)
+        uri
+      end
+
+      def apply_cookies(existing = "")
+        return existing unless @location == "cookie"
+        cookie = "#{@var_name}=#{@api_key}"
+        existing.to_s.empty? ? cookie : "#{existing}; #{cookie}"
+      end
+    end
+
+    class Basic < Base
+      def initialize(username:, password:)
+        @cred = Base64.strict_encode64("#{Utils::Subst.apply(username)}:#{Utils::Subst.apply(password)}")
+      end
+
+      def apply_headers(h)
+        h["Authorization"] = "Basic #{@cred}"
+        h
+      end
+    end
+
+    class OAuth2 < Base
+      def initialize(token_url:, client_id:, client_secret:, scope: nil)
+        @token_url = Utils::Subst.apply(token_url)
+        @client_id = Utils::Subst.apply(client_id)
+        @client_secret = Utils::Subst.apply(client_secret)
+        @scope = scope && Utils::Subst.apply(scope)
+        @cached = nil
+        @expires_at = Time.at(0)
+      end
+
+      def apply_headers(h)
+        token = fetch_token
+        h["Authorization"] = "Bearer #{token}"
+        h
+      end
+
+      private
+
+      def fetch_token
+        return @cached if Time.now < @expires_at && @cached
+        uri = URI(@token_url)
+        req = Net::HTTP::Post.new(uri)
+        req["Content-Type"] = "application/x-www-form-urlencoded"
+        form = { "grant_type" => "client_credentials", "client_id" => @client_id, "client_secret" => @client_secret }
+        form["scope"] = @scope if @scope && !@scope.empty?
+        req.body = URI.encode_www_form(form)
+
+        http = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https")
+        begin
+          res = http.request(req)
+          raise AuthError, "OAuth2 token request failed: #{res.code} #{res.body}" unless res.is_a?(Net::HTTPSuccess)
+          data = JSON.parse(res.body)
+          @cached = data["access_token"] || data["token"] || data["id_token"]
+          ttl = (data["expires_in"] || 3600).to_i
+          @expires_at = Time.now + ttl - 30
+          @cached or raise AuthError, "OAuth2 response missing token"
+        ensure
+          http.finish if http.active?
+        end
+      end
+    end
+
+    def self.from_hash(h)
+      return nil unless h.is_a?(Hash)
+      type = (h["auth_type"] || h["type"] || "").downcase
+      case type
+      when "api_key", "apikey"
+        ApiKey.new(api_key: h["api_key"] || h["key"] || "", var_name: h["var_name"] || "Authorization", location: (h["location"] || "header"))
+      when "basic"
+        Basic.new(username: h["username"] || "", password: h["password"] || "")
+      when "oauth2"
+        OAuth2.new(token_url: h["token_url"] || h["tokenUrl"] || "", client_id: h["client_id"] || "", client_secret: h["client_secret"] || "", scope: h["scope"])
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/utcp/client.rb

@@ -0,0 +1,166 @@
+# lib/utcp/client.rb
+# frozen_string_literal: true
+require "json"
+require "uri"
+require_relative "errors"
+require_relative "utils/env_loader"
+require_relative "utils/subst"
+require_relative "tool_repository"
+require_relative "search"
+require_relative "auth"
+require_relative "providers/base_provider"
+require_relative "providers/http_provider"
+require_relative "providers/sse_provider"
+require_relative "providers/http_stream_provider"
+require_relative "providers/websocket_provider"
+require_relative "providers/graphql_provider"
+require_relative "providers/tcp_provider"
+require_relative "providers/udp_provider"
+require_relative "providers/cli_provider"
+require_relative "providers/mcp_provider"
+
+module Utcp
+  class Client
+    def self.create(config = {})
+      new(config).tap(&:load_providers!)
+    end
+
+    def initialize(config = {})
+      @config = config || {}
+      @repo = ToolRepository.new
+      env_files = Array(@config["load_variables_from"] || @config[:load_variables_from] || [".env"])
+      env_files.each { |f| Utils::EnvLoader.load_file(f) }
+    end
+
+    attr_reader :repo
+
+    def load_providers!
+      path = @config["providers_file_path"] || @config[:providers_file_path]
+      raise ConfigError, "providers_file_path required" unless path && File.file?(path)
+      arr = JSON.parse(File.read(path))
+      arr.each { |prov| register_manual_provider(prov) }
+      self
+    end
+
+    def register_manual_provider(prov)
+      name = prov["name"] || prov[:name] || "provider"
+      type = (prov["provider_type"] || prov[:provider_type] || "http").downcase
+      auth = Auth.from_hash(prov["auth"] || prov[:auth])
+
+      tools = case type
+      when "http"
+        Providers::HttpProvider
+          .new(name: name,
+               url: prov["url"] || prov[:url],
+               http_method: prov["http_method"] || prov[:http_method] || "GET",
+               content_type: prov["content_type"] || "application/json",
+               headers: prov["headers"] || {},
+               manual: true,
+               auth: auth)
+          .discover_tools!
+      when "mcp"
+        Providers::McpProvider
+          .new(name: name,
+               url: prov["url"] || prov[:url],
+               headers: prov["headers"] || {},
+               auth: auth,
+               manual: true,
+               discovery_path: prov["discovery_path"] || "/manual")
+          .discover_tools!
+      when "text"
+        manual_path = prov["file_path"] || prov[:file_path]
+        raise ConfigError, "text provider missing file_path" unless manual_path && File.file?(manual_path)
+        manual = JSON.parse(File.read(manual_path))
+        to_tools(manual)
+      else
+        raise ConfigError, "Unsupported manual provider type: #{type}"
+      end
+
+      @repo.save_provider_with_tools(name, tools)
+      tools
+    end
+
+    def call_tool(full_tool_name, arguments = {}, stream: false, &block)
+      t = @repo.find(full_tool_name)
+      p = t.provider || {}
+      type = (p["provider_type"] || "http").downcase
+      auth = Auth.from_hash(p["auth"])
+
+      case type
+      when "http"
+        exec = Providers::HttpProvider.new(
+          name: full_tool_name,
+          url: p["url"],
+          http_method: p["http_method"] || "GET",
+          content_type: p["content_type"] || "application/json",
+          headers: p["headers"] || {},
+          manual: false,
+          auth: auth,
+          body_field: p["body_field"]
+        )
+        exec.call_tool(t, arguments)
+
+      when "sse"
+        raise ConfigError, "Streaming requires a block for SSE" if stream && !block_given?
+        exec = Providers::SseProvider.new(name: full_tool_name, auth: auth)
+        exec.call_tool(t, arguments, &block)
+
+      when "http_stream"
+        raise ConfigError, "Streaming requires a block for http_stream" if stream && !block_given?
+        exec = Providers::HttpStreamProvider.new(name: full_tool_name, auth: auth)
+        exec.call_tool(t, arguments, &block)
+
+      when "websocket"
+        exec = Providers::WebSocketProvider.new(name: full_tool_name, auth: auth)
+        exec.call_tool(t, arguments, &block)
+
+      when "graphql"
+        exec = Providers::GraphQLProvider.new(name: full_tool_name, auth: auth)
+        exec.call_tool(t, arguments, &block)
+
+      when "tcp"
+        exec = Providers::TcpProvider.new(name: full_tool_name)
+        exec.call_tool(t, arguments, &block)
+
+      when "udp"
+        exec = Providers::UdpProvider.new(name: full_tool_name)
+        exec.call_tool(t, arguments, &block)
+
+      when "cli"
+        exec = Providers::CliProvider.new(name: full_tool_name)
+        exec.call_tool(t, arguments, &block)
+
+      when "mcp"
+        exec = Providers::McpProvider.new(
+          name: full_tool_name,
+          url: p["url"],
+          headers: p["headers"] || {},
+          auth: auth
+        )
+        exec.call_tool(t, arguments, &block)
+
+      else
+        raise ConfigError, "Unsupported execution provider type: #{type}"
+      end
+    end
+
+    def search_tools(query, limit: 5)
+      Search.new(@repo).search(query, limit: limit)
+    end
+
+    private
+
+    def to_tools(manual)
+      (manual["tools"] || []).map do |t|
+        Utcp::Tool.new(
+          name: t["name"],
+          description: t["description"],
+          inputs: t["inputs"],
+          outputs: t["outputs"],
+          tags: t["tags"] || [],
+          provider: t["tool_provider"] || {}
+        )
+      end
+    end
+  end
+end

data/lib/utcp/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+module Utcp
+  class Error < StandardError; end
+  class ConfigError < Error; end
+  class NotFoundError < Error; end
+  class AuthError < Error; end
+  class ProviderError < Error; end
+end

data/lib/utcp/providers/base_provider.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+module Utcp
+  module Providers
+    class BaseProvider
+      attr_reader :name, :type, :auth
+
+      def initialize(name:, provider_type:, auth: nil)
+        @name = name
+        @type = provider_type
+        @auth = auth
+      end
+
+      # Returns [Array<Tool>]
+      def discover_tools!
+        raise NotImplementedError
+      end
+
+      # Execute a tool, possibly streaming chunks via &block
+      def call_tool(tool, arguments = {}, &block)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/utcp/providers/cli_provider.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+require "open3"
+require_relative "../utils/subst"
+require_relative "../errors"
+require_relative "base_provider"
+
+module Utcp
+  module Providers
+    # CLI provider for executing local commands (use with caution)
+    # tool.provider: { "provider_type":"cli", "command":["echo","hello ${name}"] }
+    class CliProvider < BaseProvider
+      def initialize(name:)
+        super(name: name, provider_type: "cli", auth: nil)
+      end
+
+      def discover_tools!
+        raise ProviderError, "CLI is an execution provider only"
+      end
+
+      def call_tool(tool, arguments = {}, &block)
+        p = tool.provider
+        cmd = p["command"]
+        raise ConfigError, "cli provider requires 'command' array" unless cmd.is_a?(Array) && !cmd.empty?
+        args = Utils::Subst.apply(arguments || {})
+
+        expanded = cmd.map do |part|
+          part.to_s.gsub(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/) { |m| args[$1] || ENV[$1] || m }
+        end
+
+        stdout, stderr, status = Open3.capture3(*expanded)
+        {
+          "ok" => status.success?,
+          "exit_code" => status.exitstatus,
+          "stdout" => stdout,
+          "stderr" => stderr
+        }
+      end
+    end
+  end
+end

data/lib/utcp/providers/graphql_provider.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+require "uri"
+require "json"
+require "net/http"
+require_relative "../utils/subst"
+require_relative "../errors"
+require_relative "../auth"
+require_relative "base_provider"
+
+module Utcp
+  module Providers
+    # Simple GraphQL over HTTP
+    # tool.provider: { "provider_type":"graphql", "url":"https://...",
+    #                  "query":"query ($code:String!) { country(code:$code){name}}",
+    #                  "operationName": "...optional..." }
+    class GraphQLProvider < BaseProvider
+      def initialize(name:, auth: nil, headers: {})
+        super(name: name, provider_type: "graphql", auth: auth)
+        @headers = headers || {}
+      end
+
+      def discover_tools!
+        raise ProviderError, "GraphQL is an execution provider only"
+      end
+
+      def call_tool(tool, arguments = {}, &block)
+        p = tool.provider
+        url = Utils::Subst.apply(p["url"])
+        uri = URI(url)
+        body = {
+          "query" => Utils::Subst.apply(p["query"]),
+          "variables" => Utils::Subst.apply(arguments || {})
+        }
+        body["operationName"] = p["operationName"] if p["operationName"]
+
+        req = Net::HTTP::Post.new(uri)
+        headers = { "Content-Type" => "application/json" }.merge(@headers)
+        @auth&.apply_headers(headers)
+        headers.each { |k, v| req[k] = v }
+        req.body = JSON.dump(body)
+
+        http = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https")
+        begin
+          res = http.request(req)
+          JSON.parse(res.body) rescue res.body
+        ensure
+          http.finish if http.active?
+        end
+      end
+    end
+  end
+end