ruby-utcp 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4a695abfcf37112217be77067218db124af0ea02490ea1811ecafc5f6cf2ab30
+  data.tar.gz: 8ef4eb2d484d370820f9c10cfc95c00c36e66675770e49ac848790ba3bf1678c
+SHA512:
+  metadata.gz: 703e659df46fcd3574bd377debd7623b808e4b57334da07a9a6a28461ad25ad5468b97e81aff53b066178de43184f24117a0ccd7ab75d97241cbaabf0dd26574
+  data.tar.gz: 0661067b9c78f93f140a130d7e4d21dc1c1debe50e0dcbfcddee1c70e5bb67186b14d4a57433a29b61505fed4e85dcf77a1a0dfd38a7cb669fb784867bccdf36

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 1.1.0
+
+- Initial Ruby implementation of the UTCP 1.1 client and data model.
+- All 12 reference transports: HTTP, SSE, Streamable HTTP, CLI, WebSocket, gRPC,
+  GraphQL, TCP, UDP, WebRTC, MCP, and text; plus a Ruby file extension.
+- Streaming enumerators, GraphQL introspection/subscriptions, socket framing,
+  MCP stdio/HTTP sessions, RFC 6455 WebSockets, and optional native gRPC/WebRTC backends.
+- Secure-by-default `allowed_communication_protocols` enforcement.
+- Migration helpers for UTCP v0.1 configuration and manuals.

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 ruby-utcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/Makefile

@@ -0,0 +1,226 @@
+SHELL := /bin/bash
+.DEFAULT_GOAL := demo
+
+RUBY ?= ruby
+RUBY_RUN := $(RUBY) -Ilib
+PYTHON ?= python3
+PYTHON_GRPC_PORT ?= 50051
+PYTHON_GRPC := $(if $(wildcard .venv-grpc/bin/python),.venv-grpc/bin/python,$(PYTHON))
+
+STANDARD_SERVER_SCRIPTS := \
+	examples/servers/http_server.rb \
+	examples/servers/sse_server.rb \
+	examples/servers/streamable_http_server.rb \
+	examples/servers/websocket_server.rb \
+	examples/servers/graphql_server.rb \
+	examples/servers/tcp_server.rb \
+	examples/servers/udp_server.rb
+
+STANDARD_CLIENT_SCRIPTS := \
+	examples/http.rb \
+	examples/sse.rb \
+	examples/streamable_http.rb \
+	examples/cli.rb \
+	examples/websocket.rb \
+	examples/graphql.rb \
+	examples/tcp.rb \
+	examples/udp.rb \
+	examples/mcp.rb \
+	examples/text.rb
+
+GRPC_AVAILABLE := $(shell $(RUBY) -e 'require "grpc"; print "yes"' 2>/dev/null)
+WEBRTC_AVAILABLE := $(shell $(RUBY) -e 'gem "webrtc-ruby", ">= 1.0.0"; require "webrtc"; abort unless defined?(WebRTC::RTCPeerConnection); print "yes"' 2>/dev/null)
+
+AVAILABLE_SERVER_SCRIPTS := $(STANDARD_SERVER_SCRIPTS)
+AVAILABLE_CLIENT_SCRIPTS := $(STANDARD_CLIENT_SCRIPTS)
+AVAILABLE_PORTS := 8080 8081 8082 8083 8085 9000
+
+ifneq ($(DISABLE_OPTIONAL),1)
+ifeq ($(GRPC_AVAILABLE),yes)
+AVAILABLE_SERVER_SCRIPTS += examples/servers/grpc_server.rb
+AVAILABLE_CLIENT_SCRIPTS += examples/grpc.rb
+AVAILABLE_PORTS += 50051
+endif
+ifeq ($(WEBRTC_AVAILABLE),yes)
+AVAILABLE_SERVER_SCRIPTS += examples/servers/webrtc_server.rb
+AVAILABLE_CLIENT_SCRIPTS += examples/webrtc.rb
+AVAILABLE_PORTS += 8084
+endif
+endif
+
+.PHONY: all demo full-demo servers full-servers examples full-examples \
+	check-base-dependencies check-ruby-grpc check-python-grpc check-python-grpc-tools \
+	check-dependencies dependency-report grpc-python-setup grpc-python-generate \
+	grpc-python-server grpc-python-client grpc-python-demo test standard-demo
+
+all: demo
+
+check-base-dependencies:
+	@$(RUBY) -e 'require "webrick"' || { \
+		echo "WEBrick is required by the local HTTP example servers." >&2; \
+		echo "Install it with: $$(ruby -e 'print RbConfig.ruby') -S gem install webrick" >&2; \
+		exit 1; \
+	}
+
+check-ruby-grpc:
+	@$(RUBY) -e 'require "grpc"' || { \
+		echo "The Ruby gRPC client requires the grpc gem." >&2; \
+		echo "Install it with Ruby 3.1+: gem install grpc" >&2; \
+		exit 1; \
+	}
+
+check-python-grpc:
+	@$(PYTHON_GRPC) -c 'import grpc' || { \
+		echo "The Python gRPC server requires grpcio." >&2; \
+		echo "Install them with: make grpc-python-setup" >&2; \
+		exit 1; \
+	}
+
+check-python-grpc-tools: check-python-grpc
+	@$(PYTHON_GRPC) -c 'from grpc_tools import protoc' || { \
+		echo "Stub generation requires grpcio-tools." >&2; \
+		echo "Install it with: make grpc-python-setup" >&2; \
+		exit 1; \
+	}
+
+check-dependencies: check-base-dependencies check-ruby-grpc
+	@$(RUBY) -e 'abort "Ruby 3.1+ is required by webrtc-ruby (current: #{RUBY_VERSION})" if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.1"); gem "webrtc-ruby", ">= 1.0.0"; require "webrtc"; abort "webrtc-ruby did not load WebRTC::RTCPeerConnection" unless defined?(WebRTC::RTCPeerConnection)' || { \
+		echo "Install webrtc-ruby and libdatachannel before running the full demo." >&2; \
+		exit 1; \
+	}
+
+dependency-report:
+	@if [[ "$(DISABLE_OPTIONAL)" != "1" && "$(GRPC_AVAILABLE)" != "yes" ]]; then \
+		echo "[skip] gRPC example: install the grpc gem (Ruby 3.1+ recommended)"; \
+	fi
+	@if [[ "$(DISABLE_OPTIONAL)" != "1" && "$(WEBRTC_AVAILABLE)" != "yes" ]]; then \
+		echo "[skip] WebRTC example: requires Ruby 3.1+, webrtc-ruby, and libdatachannel"; \
+	fi
+
+servers: check-base-dependencies dependency-report
+	@set -euo pipefail; \
+	pids=(); \
+	cleanup() { \
+		if (($${#pids[@]})); then \
+			kill "$${pids[@]}" 2>/dev/null || true; \
+			wait "$${pids[@]}" 2>/dev/null || true; \
+		fi; \
+	}; \
+	trap cleanup EXIT INT TERM; \
+	for script in $(AVAILABLE_SERVER_SCRIPTS); do \
+		echo "[server] $$script"; \
+		$(RUBY_RUN) "$$script" & \
+		pids+=("$$!"); \
+	done; \
+	echo "All network servers are running. Press Ctrl-C to stop them."; \
+	wait
+
+full-servers: check-dependencies
+	@$(MAKE) --no-print-directory servers
+
+examples: dependency-report
+	@set -euo pipefail; \
+	for script in $(AVAILABLE_CLIENT_SCRIPTS); do \
+		echo; \
+		echo "[example] $$script"; \
+		$(RUBY_RUN) "$$script"; \
+	done
+
+full-examples: check-dependencies
+	@$(MAKE) --no-print-directory examples
+
+demo: check-base-dependencies dependency-report
+	@set -euo pipefail; \
+	pids=(); \
+	cleanup() { \
+		if (($${#pids[@]})); then \
+			kill "$${pids[@]}" 2>/dev/null || true; \
+			wait "$${pids[@]}" 2>/dev/null || true; \
+		fi; \
+	}; \
+	wait_for_port() { \
+		local host="$$1" port="$$2" attempt; \
+		for attempt in $$(seq 1 100); do \
+			if (exec 3<>"/dev/tcp/$$host/$$port") 2>/dev/null; then \
+				exec 3>&-; \
+				exec 3<&-; \
+				return 0; \
+			fi; \
+			sleep 0.1; \
+		done; \
+		echo "Timed out waiting for $$host:$$port" >&2; \
+		return 1; \
+	}; \
+	trap cleanup EXIT INT TERM; \
+	for script in $(AVAILABLE_SERVER_SCRIPTS); do \
+		echo "[server] $$script"; \
+		$(RUBY_RUN) "$$script" & \
+		pids+=("$$!"); \
+	done; \
+	for port in $(AVAILABLE_PORTS); do \
+		wait_for_port 127.0.0.1 "$$port"; \
+	done; \
+	sleep 0.2; \
+	$(MAKE) --no-print-directory examples
+
+full-demo: check-dependencies
+	@$(MAKE) --no-print-directory demo
+
+# Runs every pair that only needs Ruby's standard library (plus WEBrick).
+standard-demo:
+	@$(MAKE) --no-print-directory demo DISABLE_OPTIONAL=1
+
+grpc-python-setup:
+	@$(PYTHON) -m venv .venv-grpc
+	@.venv-grpc/bin/python -m pip install -r examples/servers/requirements-grpc.txt
+	@$(MAKE) --no-print-directory grpc-python-generate PYTHON_GRPC=.venv-grpc/bin/python
+
+grpc-python-generate: check-python-grpc-tools
+	@mkdir -p examples/generated
+	@$(PYTHON_GRPC) -m grpc_tools.protoc \
+		-I proto \
+		--python_out=examples/generated \
+		--grpc_python_out=examples/generated \
+		proto/utcp.proto
+
+grpc-python-server: check-python-grpc
+	@PORT="$(PYTHON_GRPC_PORT)" $(PYTHON_GRPC) examples/servers/grpc_server.py
+
+grpc-python-client: check-python-grpc
+	@UTCP_GRPC_PORT="$(PYTHON_GRPC_PORT)" $(PYTHON_GRPC) examples/grpc_python.py
+
+grpc-python-demo: check-python-grpc check-ruby-grpc
+	@set -euo pipefail; \
+	if (exec 3<>"/dev/tcp/127.0.0.1/$(PYTHON_GRPC_PORT)") 2>/dev/null; then \
+		exec 3>&-; exec 3<&-; \
+		echo "Port $(PYTHON_GRPC_PORT) is already in use." >&2; \
+		exit 1; \
+	fi; \
+	server_pid=""; \
+	cleanup() { \
+		if [[ -n "$$server_pid" ]]; then \
+			kill "$$server_pid" 2>/dev/null || true; \
+			wait "$$server_pid" 2>/dev/null || true; \
+		fi; \
+	}; \
+	trap cleanup EXIT INT TERM; \
+	PORT="$(PYTHON_GRPC_PORT)" $(PYTHON_GRPC) examples/servers/grpc_server.py & \
+	server_pid="$$!"; \
+	ready=0; \
+	for attempt in $$(seq 1 100); do \
+		if (exec 3<>"/dev/tcp/127.0.0.1/$(PYTHON_GRPC_PORT)") 2>/dev/null; then \
+			exec 3>&-; exec 3<&-; ready=1; break; \
+		fi; \
+		if ! kill -0 "$$server_pid" 2>/dev/null; then \
+			wait "$$server_pid"; exit 1; \
+		fi; \
+		sleep 0.1; \
+	done; \
+	if [[ "$$ready" != "1" ]]; then \
+		echo "Timed out waiting for Python gRPC server." >&2; exit 1; \
+	fi; \
+	UTCP_GRPC_PORT="$(PYTHON_GRPC_PORT)" $(RUBY_RUN) examples/grpc.rb; \
+	UTCP_GRPC_PORT="$(PYTHON_GRPC_PORT)" $(PYTHON_GRPC) examples/grpc_python.py
+
+test:
+	$(RUBY_RUN) -S rake test

data/README.md

@@ -0,0 +1,331 @@
+# ruby-utcp
+
+`ruby-utcp` is a Ruby implementation of the Universal Tool Calling Protocol (UTCP) 1.1. It discovers tools from UTCP manuals, stores and searches them locally, and calls them directly over their native protocol.
+
+The implementation follows the UTCP [v0.1 to v1.0 migration guide](https://www.utcp.io/migration-v0.1-to-v1.0) and [v1.0 to v1.1 migration guide](https://www.utcp.io/migration-v1.0-to-v1.1). It includes the v1 plugin architecture, structured data models, authentication, variable loading, protocol-specific errors, and the v1.1 secure-by-default protocol allow-list.
+
+## Installation
+
+Add the gem to your bundle:
+
+```ruby
+gem "ruby-utcp"
+```
+
+Or build this checkout:
+
+```sh
+gem build ruby-utcp.gemspec
+gem install ./ruby-utcp-1.1.0.gem
+```
+
+Ruby 2.6 or newer is supported for the core and 11 transports. The WebRTC default backend uses the optional `webrtc-ruby` gem, which requires Ruby 3.1 and `libdatachannel`; an application can instead inject its own peer adapter. The gRPC transport similarly loads the optional `grpc` gem only when used. There are no mandatory runtime dependencies outside Ruby's standard library.
+
+## Quick start
+
+```ruby
+require "utcp"
+
+client = UTCP::Client.create(
+  config: {
+    manual_call_templates: [
+      {
+        name: "weather_service",
+        call_template_type: "http",
+        url: "https://weather.example.com/utcp",
+        http_method: "GET"
+      }
+    ],
+    variables: {
+      WEATHER_API_KEY: ENV.fetch("WEATHER_API_KEY")
+    }
+  }
+)
+
+client.list_tools.each { |tool| puts tool.name }
+result = client.call_tool("weather_service.get_weather", location: "Warsaw")
+```
+
+`Client.create` registers the configured manuals before returning. Ruby calls are synchronous; `register_manual`, `search_tools`, and `call_tool` return their results directly.
+
+## UTCP 1.1 manuals
+
+A manual describes tools and gives each tool its own call template:
+
+```json
+{
+  "manual_version": "1.0.0",
+  "utcp_version": "1.1.0",
+  "info": {
+    "title": "Weather API",
+    "version": "1.0.0"
+  },
+  "tools": [
+    {
+      "name": "get_weather",
+      "description": "Get current weather",
+      "inputs": {
+        "type": "object",
+        "properties": {
+          "location": { "type": "string" }
+        },
+        "required": ["location"]
+      },
+      "outputs": { "type": "object" },
+      "tags": ["weather"],
+      "tool_call_template": {
+        "call_template_type": "http",
+        "url": "https://api.example.com/weather/{location}",
+        "http_method": "GET"
+      }
+    }
+  ]
+}
+```
+
+Registered names are qualified as `manual_name.tool_name`.
+
+## Secure-by-default protocol rules
+
+UTCP 1.1 limits tools to the protocol used to discover their manual. An HTTP manual therefore registers HTTP tools by default and filters out CLI, text, and other tools.
+
+Mixed-protocol manuals must opt in explicitly:
+
+```ruby
+{
+  name: "mixed_tools",
+  call_template_type: "http",
+  url: "https://example.com/utcp",
+  allowed_communication_protocols: %w[http cli]
+}
+```
+
+The client checks this policy during both registration and every call. An omitted or empty allow-list means only the manual's own protocol is allowed.
+
+## All 12 transports
+
+The gem registers all twelve transports present in the UTCP reference implementations. `file` remains available as an additional Ruby extension.
+
+| Type | Call template | Behavior |
+| --- | --- | --- |
+| `http` | `HttpCallTemplate` | REST, OpenAPI discovery, redirects, auth |
+| `sse` | `SseCallTemplate` | filtered Server-Sent Events and streaming enumeration |
+| `streamable_http` | `StreamableHttpCallTemplate` | NDJSON, JSON Sequence, JSON, and binary chunks |
+| `cli` | `CliCallTemplate` | safe argument interpolation and multi-step shell calls |
+| `websocket` | `WebSocketCallTemplate` | RFC 6455 client, WSS security, persistent connections |
+| `grpc` | `GrpcCallTemplate` | UTCP protobuf `GetManual`, `CallTool`, and server streaming |
+| `graphql` | `GraphQLCallTemplate` | introspection, queries, mutations, and subscriptions |
+| `tcp` | `TcpCallTemplate` | length-prefix, delimiter, fixed-size, and stream framing |
+| `udp` | `UdpCallTemplate` | zero, one, or multiple response datagrams |
+| `webrtc` | `WebRtcCallTemplate` | signaling plus request-correlated DataChannel messages |
+| `mcp` | `McpCallTemplate` | MCP JSON-RPC over stdio or Streamable HTTP |
+| `text` | `TextCallTemplate` | inline UTCP/OpenAPI documents and static text tools |
+
+Complete runnable/configuration examples are in [examples/README.md](examples/README.md), with one file per transport.
+
+Run `make` to start every available matching local server, execute its clients, and cleanly stop the servers. Missing optional gRPC/WebRTC backends are reported and skipped. `make full-demo` is the strict 12/12 target; `make standard-demo` always runs only the pairs that do not need native backends.
+
+### HTTP, SSE, and Streamable HTTP
+
+HTTP templates support URL path parameters, query parameters, JSON or text bodies, input-to-header mapping, API keys, Basic auth, and OAuth2 client credentials.
+
+```ruby
+{
+  call_template_type: "http",
+  url: "https://api.example.com/users/{user_id}",
+  http_method: "PATCH",
+  body_field: "body",
+  header_fields: ["X-Request-ID"],
+  auth: {
+    auth_type: "api_key",
+    api_key: "${API_TOKEN}",
+    var_name: "Authorization",
+    location: "header"
+  }
+}
+```
+
+Remote HTTP endpoints must use HTTPS. Plain HTTP is accepted only for loopback hosts, which keeps local development convenient. Redirect targets are checked again and credentials are removed on cross-origin redirects.
+
+An HTTP, text, or file manual may also contain an OpenAPI 3 or Swagger 2 document. It is converted into UTCP tools automatically.
+
+SSE and Streamable HTTP reuse the same URL, header, body, and auth conventions. Their streaming forms expose ordinary Ruby enumerators:
+
+```ruby
+client.call_tool_streaming("events.watch", topic: "builds").each do |event|
+  puts event.inspect
+end
+```
+
+`streamable_http` is the v1 call-template discriminator. `http_stream` is also accepted as a compatibility alias for the Go reference implementation.
+
+### CLI
+
+```ruby
+{
+  call_template_type: "cli",
+  commands: [
+    { command: "prepare-data", append_to_final_output: false },
+    { command: "weather UTCP_ARG_city_UTCP_END", append_to_final_output: true }
+  ],
+  env_vars: { "MODE" => "production" },
+  inherit_env_vars: ["PATH"],
+  working_dir: "/srv/tools"
+}
+```
+
+Commands run in one `/bin/sh` process, so working-directory changes and `$CMD_0_OUTPUT` references persist. Tool arguments are passed through dedicated environment variables after the shell parses the trusted command template, preventing argument values from injecting shell syntax. The child receives only a small default environment allow-list unless `inherit_env_vars` is set.
+
+Only register CLI tools from manuals you trust: the command template itself is executable code.
+
+### WebSocket and GraphQL
+
+WebSocket is implemented directly on Ruby sockets with RFC 6455 masking, fragmentation, ping/pong, TLS certificate verification, handshake verification, Basic/API-key/OAuth2 auth, and configurable JSON/text/binary responses. Plain `ws://` is restricted to literal loopback hosts.
+
+GraphQL registration introspects query, mutation, and subscription roots. A discovered operation gets input/output schemas and a generated query; set `query`, `variable_types`, or `selection_set` on an explicit call template when the endpoint needs a custom selection:
+
+```ruby
+{
+  call_template_type: "graphql",
+  url: "https://api.example.com/graphql",
+  operation_type: "query",
+  operation_name: "user",
+  query: "query User($id: ID!) { user(id: $id) { id name } }"
+}
+```
+
+Subscriptions use the `graphql-transport-ws` subprotocol through `call_tool_streaming`.
+
+### TCP and UDP
+
+Socket templates can send JSON arguments or a text template containing `UTCP_ARG_name_UTCP_ARG`. TCP supports `length_prefix`, `delimiter`, `fixed_length`, and `stream` framing. UDP supports a configurable number of response datagrams, including zero for fire-and-forget calls. Timeouts are expressed in milliseconds in both templates.
+
+### gRPC
+
+The gRPC transport interoperates with the reference `grpcpb.UTCPService`:
+
+- `GetManual(Empty) returns (Manual)`
+- `CallTool(ToolCallRequest) returns (ToolCallResponse)`
+- `CallToolStream(ToolCallRequest) returns (stream ToolCallResponse)`
+
+Add `gem "grpc"` to the consuming application. The protocol uses a tiny built-in protobuf codec for these UTCP messages, so generated Ruby classes are not required. A custom RPC adapter can be passed as `UTCP::GRPCProtocol.new(rpc_client_factory: ...)`.
+
+The checked-in contract is [`proto/utcp.proto`](proto/utcp.proto). Its committed Python stubs are generated by `make grpc-python-generate` and shared by [`examples/servers/grpc_server.py`](examples/servers/grpc_server.py) and [`examples/grpc_python.py`](examples/grpc_python.py). Run both the Ruby and Python clients against the Python server with `make grpc-python-demo`.
+
+### MCP
+
+MCP sessions implement initialization, notifications, `tools/list`, `tools/call`, optional `resources/list`/`resources/read`, session IDs, and both stdio and Streamable HTTP transports. With several servers, registered names use `manual.server.tool`:
+
+```ruby
+{
+  name: "bridge",
+  call_template_type: "mcp",
+  config: {
+    mcpServers: {
+      local: { command: "ruby", args: ["server.rb"] },
+      remote: { transport: "http", url: "https://mcp.example.com/mcp" }
+    }
+  }
+}
+```
+
+### WebRTC
+
+WebRTC follows the reference signaling contract: `POST /connect` exchanges SDP and returns `sdp`, `candidates`, and `tools`; `POST /candidate` exchanges ICE candidates. DataChannel requests are JSON envelopes containing `id`, `tool`, and `args`, and responses correlate the same `id` with `result`.
+
+The built-in peer uses `webrtc-ruby` and `libdatachannel`. For another native stack, pass `peer_factory:` to `UTCP::WebRTCProtocol`; the adapter contract is demonstrated by the protocol tests.
+
+### Text and file
+
+Text templates parse a manual supplied directly in `content`. File templates read JSON or safe YAML relative to the client's `root_dir`.
+
+```ruby
+UTCP::Client.create(config: {
+  manual_call_templates: [
+    { name: "local", call_template_type: "file", file_path: "tools.json" }
+  ]
+})
+```
+
+## Variables and `.env` files
+
+`${NAME}` and `$NAME` placeholders are resolved in this order:
+
+1. `config.variables`
+2. configured variable loaders
+3. the process environment
+
+```yaml
+variables:
+  HOST: api.example.com
+load_variables_from:
+  - variable_loader_type: dotenv
+    env_file_path: .env
+```
+
+Manual-specific names are tried first. For a manual named `weather_api`, `${TOKEN}` first looks for `weather__api_TOKEN`, then `TOKEN`. Use `get_required_variables_for_manual_and_tools` or `get_required_variables_for_registered_tool` to inspect requirements without exposing values.
+
+## Migrating v0.1 documents
+
+The helpers are non-destructive and return string-keyed hashes ready for `Client.create` or `Manual.from_h`:
+
+```ruby
+config_1_1 = UTCP::Migration.config_v0_1_to_v1_1(old_config)
+manual_1_1 = UTCP::Migration.manual_v0_1_to_v1_1(old_manual)
+
+client = UTCP::Client.create(config: config_1_1)
+manual = UTCP::Manual.from_h(manual_1_1)
+```
+
+They rename `providers` to `manual_call_templates`, `provider_type` to `call_template_type`, `parameters` to `inputs`, `provider` to `tool_call_template`, and convert legacy CLI command arguments to `UTCP_ARG_name_UTCP_END` placeholders.
+
+## Search and repositories
+
+The default thread-safe in-memory repository supports tool and manual lookup. Search ranks tag, name, and description matches:
+
+```ruby
+client.search_tools("weather forecast", limit: 5, any_of_tags_required: ["weather"])
+```
+
+Pass objects that implement the repository or search interfaces through `tool_repository` and `tool_search_strategy` to replace the defaults.
+
+## Custom protocol plugins
+
+Register a call-template class and a protocol implementation before creating a client:
+
+```ruby
+class QueueTemplate < UTCP::CallTemplate
+  attr_reader :queue
+
+  def initialize(queue:, call_template_type: "queue", **options)
+    super(call_template_type: call_template_type, **options)
+    @queue = queue
+  end
+
+  def to_h
+    super.merge("queue" => queue)
+  end
+end
+
+class QueueProtocol < UTCP::CommunicationProtocol
+  def register_manual(client, template)
+    # Return UTCP::RegisterManualResult
+  end
+
+  def deregister_manual(client, template); end
+
+  def call_tool(client, name, arguments, template)
+    # Invoke the queue's native API
+  end
+end
+
+UTCP.register_call_template("queue", QueueTemplate)
+UTCP.register_protocol("queue", QueueProtocol.new)
+```
+
+## Development
+
+```sh
+rake test
+gem build ruby-utcp.gemspec
+```

data/examples/basic.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "utcp"
+
+manual = {
+  manual_version: "1.0.0",
+  utcp_version: "1.1.0",
+  tools: [
+    {
+      name: "greeting",
+      description: "Return a greeting",
+      inputs: { type: "object" },
+      tool_call_template: {
+        call_template_type: "text",
+        content: "Hello from UTCP"
+      }
+    }
+  ]
+}
+
+client = UTCP::Client.create(config: {
+  manual_call_templates: [
+    {
+      name: "demo",
+      call_template_type: "text",
+      content: JSON.generate(manual)
+    }
+  ]
+})
+
+puts client.call_tool("demo.greeting")
+

data/examples/cli.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "rbconfig"
+require "utcp"
+
+# A CLI manual is itself discovered by executing a command. The discovered tool also uses CLI.
+manual = {
+  utcp_version: "1.1.0",
+  manual_version: "1.0.0",
+  tools: [{
+    name: "greet",
+    inputs: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
+    tool_call_template: {
+      call_template_type: "cli",
+      commands: [{ command: "printf 'Hello, %s!' UTCP_ARG_name_UTCP_END" }]
+    }
+  }]
+}
+encoded = Base64.strict_encode64(JSON.generate(manual))
+discovery = "#{RbConfig.ruby} -rbase64 -e 'print Base64.decode64(ARGV.fetch(0))' #{encoded}"
+
+client = UTCP::Client.create(config: {
+  manual_call_templates: [{
+    name: "shell",
+    call_template_type: "cli",
+    commands: [{ command: discovery }]
+  }]
+})
+
+puts client.call_tool("shell.greet", name: "Ruby")

data/examples/generated/__init__.py

@@ -0,0 +1 @@
+"""Python modules generated from proto/utcp.proto."""