portage-ucp-client 0.7.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +11 -0
- data/lib/portage/ucp/client/session.rb +5 -1
- data/lib/portage/ucp/client/transports/rest.rb +103 -0
- data/lib/portage/ucp/client/version.rb +1 -1
- data/lib/portage/ucp/client.rb +41 -21
- metadata +4 -7
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: be5ef7d67c34c11b54f60611b6dd6fabd97e2721f62ac41667261e8c41fdf505
|
|
4
|
+
data.tar.gz: 6d4da870ffec123ee561f1423573279caa14b8d4aea94fa50a66fb7cdbf86639
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: b81cb1592180fe79c724c717ef4674b24aa772845c494bf80a580551ca38352e37165bbfc4cf1b2e002ea7a5d7e51d0ed5ce1ee1bb1ed5f003af7382a5b99f1a
|
|
7
|
+
data.tar.gz: 600d1c4f691ddd89ffdef9f923d1c882e72a277c9257469b2878d69ac7328bc6bd63a5c49df4df5f7ff2e7cedcc8540c02b16941e13d49e1bd62510f4f6f2883
|
data/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,17 @@ pre-1.0, so APIs may still shift between minor versions.
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
## [0.8.0] - 2026-11-18
|
|
10
|
+
|
|
11
|
+
- **Added: REST transport.** `Client.discover` now falls back to a store's
|
|
12
|
+
`rest` service entry when it has no `mcp` one (MCP still wins when both are
|
|
13
|
+
offered; the newest `version` wins within a transport), so REST-only stores
|
|
14
|
+
such as issue #178's sandbox can be driven. `Client.connect(url:, transport:
|
|
15
|
+
:rest)` builds a `Transports::Rest` session; `:mcp` stays the default and
|
|
16
|
+
other values raise `ArgumentError`. `Session#transport_name` returns `:mcp`
|
|
17
|
+
or `:rest`. A manifest with neither raises `ManifestShapeError` listing the
|
|
18
|
+
transports it saw.
|
|
19
|
+
|
|
9
20
|
## [0.7.0] - 2026-10-22
|
|
10
21
|
|
|
11
22
|
- **Changed: requires `mcp` `~> 1.8`** (was `~> 0.24`), which serves MCP 2026-07-28 through `server/discover` and keeps `initialize` for 2025-11-25 and earlier. Minor bump because the `mcp` requirement moved from 0.x to 1.x; no API change and no changes under `lib/`. `portage-ucp` stays at `~> 0.8`: the client calls nothing newer, and the shared `mcp` `~> 1.8` requirement makes resolution pick `portage-ucp` 0.17.0 or later.
|
|
@@ -24,13 +24,17 @@ module Portage
|
|
|
24
24
|
# names advertised by the server, when known upfront (Client.discover
|
|
25
25
|
# populates this from the manifest; Client.for_adapter/.connect leave
|
|
26
26
|
# it nil since nothing was fetched to populate it from).
|
|
27
|
-
def initialize(transport:, capabilities: nil)
|
|
27
|
+
def initialize(transport:, capabilities: nil, transport_name: :mcp)
|
|
28
28
|
@transport = transport
|
|
29
|
+
@transport_name = transport_name
|
|
29
30
|
@capabilities = capabilities
|
|
30
31
|
end
|
|
31
32
|
|
|
32
33
|
attr_reader :capabilities
|
|
33
34
|
|
|
35
|
+
# @return [Symbol] `:rest` over the REST transport, `:mcp` otherwise.
|
|
36
|
+
attr_reader :transport_name
|
|
37
|
+
|
|
34
38
|
# @return [Boolean, nil] nil when capabilities weren't known upfront
|
|
35
39
|
# (see #capabilities) — callers with a nil result can't tell either
|
|
36
40
|
# way and should just attempt the call.
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
require "faraday"
|
|
2
|
+
require "json"
|
|
3
|
+
require "erb"
|
|
4
|
+
require_relative "../errors"
|
|
5
|
+
require_relative "ucp_wire_shape"
|
|
6
|
+
|
|
7
|
+
module Portage
|
|
8
|
+
module Ucp
|
|
9
|
+
module Client
|
|
10
|
+
module Transports
|
|
11
|
+
# Connects to a UCP server's REST service (2026-08-25's core
|
|
12
|
+
# transport) — the same Session seam as Http, a different wire. REST
|
|
13
|
+
# bodies are the bare capability object, so this reuses UcpWireShape
|
|
14
|
+
# to build the MCP body and drops the capability wrapper key; ids go
|
|
15
|
+
# in the path; `meta` becomes headers instead of body fields.
|
|
16
|
+
class Rest
|
|
17
|
+
include UcpWireShape
|
|
18
|
+
|
|
19
|
+
# action => [verb, path (`{id}` is the action's identifying
|
|
20
|
+
# argument), wrapper key of the body — nil for no body].
|
|
21
|
+
ROUTES = {
|
|
22
|
+
"search_catalog" => ["POST", "/catalog/search", "catalog"],
|
|
23
|
+
"lookup_catalog" => ["POST", "/catalog/lookup", "catalog"],
|
|
24
|
+
"get_product" => ["POST", "/catalog/product", "catalog"],
|
|
25
|
+
"create_cart" => ["POST", "/carts", "cart"],
|
|
26
|
+
"get_cart" => ["GET", "/carts/{id}", nil],
|
|
27
|
+
"update_cart" => ["PUT", "/carts/{id}", "cart"],
|
|
28
|
+
"cancel_cart" => ["POST", "/carts/{id}/cancel", nil],
|
|
29
|
+
"create_checkout" => ["POST", "/checkout-sessions", "checkout"],
|
|
30
|
+
"get_checkout" => ["GET", "/checkout-sessions/{id}", nil],
|
|
31
|
+
"update_checkout" => ["PUT", "/checkout-sessions/{id}", "checkout"],
|
|
32
|
+
"complete_checkout" => ["POST", "/checkout-sessions/{id}/complete", "checkout"],
|
|
33
|
+
"cancel_checkout" => ["POST", "/checkout-sessions/{id}/cancel", nil],
|
|
34
|
+
"get_order" => ["GET", "/orders/{id}", nil]
|
|
35
|
+
}.freeze
|
|
36
|
+
|
|
37
|
+
# @param url [String] the service entry's `endpoint`; paths are
|
|
38
|
+
# appended to it, keeping any version prefix.
|
|
39
|
+
# @param proxy [String, Hash, URI, nil] as for Http.
|
|
40
|
+
def initialize(url:, headers: {}, proxy: nil)
|
|
41
|
+
@base = url.to_s.chomp("/")
|
|
42
|
+
@connection = Faraday.new(headers: Client.with_user_agent(headers), proxy: proxy)
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
# Returns the response body as a string-keyed Hash, like Http.
|
|
46
|
+
def call_tool(name:, arguments:, meta: nil)
|
|
47
|
+
verb, path, wrapper = ROUTES.fetch(name) do
|
|
48
|
+
raise UnsupportedWireShapeError, "#{name} has no REST operation in UCP 2026-08-25"
|
|
49
|
+
end
|
|
50
|
+
idempotency_key = arguments[:idempotency_key] || arguments["idempotency_key"]
|
|
51
|
+
wire = wire_arguments(name, arguments)
|
|
52
|
+
headers = request_headers(meta, idempotency_key)
|
|
53
|
+
body = wrapper && JSON.generate(wire.fetch(wrapper))
|
|
54
|
+
response = @connection.run_request(verb.downcase.to_sym, url_for(path, wire["id"]), body, headers)
|
|
55
|
+
handle(response, name)
|
|
56
|
+
end
|
|
57
|
+
|
|
58
|
+
private
|
|
59
|
+
|
|
60
|
+
def url_for(path, id)
|
|
61
|
+
@base + path.sub("{id}") { ERB::Util.url_encode(id.to_s) }
|
|
62
|
+
end
|
|
63
|
+
|
|
64
|
+
def request_headers(meta, idempotency_key)
|
|
65
|
+
profile = meta && (meta[:agent_profile] || meta["agent_profile"])
|
|
66
|
+
unless profile
|
|
67
|
+
raise MissingAgentProfileError,
|
|
68
|
+
"meta: { agent_profile: <url> } is required for REST calls — real UCP servers fetch " \
|
|
69
|
+
"and verify this URL to identify the calling agent"
|
|
70
|
+
end
|
|
71
|
+
|
|
72
|
+
headers = { "UCP-Agent" => %(profile="#{profile}"),
|
|
73
|
+
"Content-Type" => "application/json", "Accept" => "application/json" }
|
|
74
|
+
headers["Idempotency-Key"] = idempotency_key if idempotency_key
|
|
75
|
+
headers
|
|
76
|
+
end
|
|
77
|
+
|
|
78
|
+
def handle(response, name)
|
|
79
|
+
payload = parse(response.body)
|
|
80
|
+
return payload if response.success? && payload
|
|
81
|
+
|
|
82
|
+
error = ServerError.new("HTTP #{response.status}: #{detail(payload, response.body)}", payload: payload)
|
|
83
|
+
raise permission_error(error) if name == "complete_checkout" && permission_refusal?(error.message)
|
|
84
|
+
|
|
85
|
+
raise error
|
|
86
|
+
end
|
|
87
|
+
|
|
88
|
+
def detail(payload, body)
|
|
89
|
+
contents = Array(payload && payload["messages"]).filter_map { |m| m["content"] if m.is_a?(Hash) }
|
|
90
|
+
contents.empty? ? body : contents.join("; ")
|
|
91
|
+
end
|
|
92
|
+
|
|
93
|
+
def parse(body)
|
|
94
|
+
parsed = JSON.parse(body.to_s)
|
|
95
|
+
parsed.is_a?(Hash) ? parsed : nil
|
|
96
|
+
rescue JSON::ParserError
|
|
97
|
+
nil
|
|
98
|
+
end
|
|
99
|
+
end
|
|
100
|
+
end
|
|
101
|
+
end
|
|
102
|
+
end
|
|
103
|
+
end
|
data/lib/portage/ucp/client.rb
CHANGED
|
@@ -12,6 +12,7 @@ require_relative "client/transports/local_arguments"
|
|
|
12
12
|
require_relative "client/transports/loopback"
|
|
13
13
|
require_relative "client/transports/stdio"
|
|
14
14
|
require_relative "client/transports/http"
|
|
15
|
+
require_relative "client/transports/rest"
|
|
15
16
|
|
|
16
17
|
module Portage
|
|
17
18
|
module Ucp
|
|
@@ -38,24 +39,33 @@ module Portage
|
|
|
38
39
|
Session.new(transport: Transports::Loopback.new(adapter: adapter, **server_opts))
|
|
39
40
|
end
|
|
40
41
|
|
|
41
|
-
# Connects over stdio (a subprocess)
|
|
42
|
-
# exactly one of `command:` or `url:`.
|
|
42
|
+
# Connects over stdio (a subprocess), Streamable HTTP (a URL) or REST (a
|
|
43
|
+
# URL with `transport: :rest`) — pass exactly one of `command:` or `url:`.
|
|
44
|
+
# @param transport [Symbol] `:mcp` (default) or `:rest`; only for `url:`.
|
|
43
45
|
# @param proxy [String, Hash, nil] forwarded to Transports::Http (a
|
|
44
46
|
# `url:` connection only) — see its own doc comment.
|
|
45
|
-
def self.connect(command: nil, args: [], env: nil, url: nil, headers: {}, capabilities: nil, proxy: nil
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
47
|
+
def self.connect(command: nil, args: [], env: nil, url: nil, headers: {}, capabilities: nil, proxy: nil,
|
|
48
|
+
transport: :mcp)
|
|
49
|
+
unless %i[mcp rest].include?(transport)
|
|
50
|
+
raise ArgumentError, "transport must be :mcp or :rest, got #{transport.inspect}"
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
raise ArgumentError, "transport: :rest needs url:, not command:" if command && transport == :rest
|
|
54
|
+
|
|
55
|
+
wire = if command
|
|
56
|
+
Transports::Stdio.new(command: command, args: args, env: env)
|
|
57
|
+
elsif url
|
|
58
|
+
(transport == :rest ? Transports::Rest : Transports::Http).new(url: url, headers: headers,
|
|
59
|
+
proxy: proxy)
|
|
60
|
+
else
|
|
61
|
+
raise ArgumentError, "connect requires either command: or url:"
|
|
62
|
+
end
|
|
63
|
+
Session.new(transport: wire, capabilities: capabilities, transport_name: transport)
|
|
54
64
|
end
|
|
55
65
|
|
|
56
66
|
# GETs `<url>/.well-known/ucp`, parses the manifest, and connects to the
|
|
57
|
-
# `mcp`-transport endpoint it advertises in `services` (
|
|
58
|
-
# Portage::Ucp::Manifest#services — the core-gem fix this client
|
|
67
|
+
# `mcp`-transport endpoint it advertises in `services` (else its `rest`
|
|
68
|
+
# one; see Portage::Ucp::Manifest#services — the core-gem fix this client
|
|
59
69
|
# depends on to know where to connect).
|
|
60
70
|
# @return [Session] scoped to the manifest's advertised capabilities.
|
|
61
71
|
# @param headers [Hash{String => String}] sent with the manifest GET
|
|
@@ -65,7 +75,9 @@ module Portage
|
|
|
65
75
|
# connection this discovers into — see Transports::Http.
|
|
66
76
|
def self.discover(url, headers: {}, proxy: nil)
|
|
67
77
|
manifest = fetch_manifest(url, headers)
|
|
68
|
-
|
|
78
|
+
transport, endpoint = service_endpoint(manifest)
|
|
79
|
+
connect(url: endpoint, headers: headers, capabilities: capability_names(manifest), proxy: proxy,
|
|
80
|
+
transport: transport)
|
|
69
81
|
end
|
|
70
82
|
|
|
71
83
|
def self.fetch_manifest(url, headers = {})
|
|
@@ -105,17 +117,25 @@ module Portage
|
|
|
105
117
|
end
|
|
106
118
|
private_class_method :ucp_section
|
|
107
119
|
|
|
108
|
-
|
|
120
|
+
# MCP when the store offers it, else REST; the newest `version` wins
|
|
121
|
+
# within a transport.
|
|
122
|
+
# @return [Array(Symbol, String)] `[:mcp | :rest, endpoint]`
|
|
123
|
+
def self.service_endpoint(manifest)
|
|
109
124
|
services = ucp_section(manifest)["services"]
|
|
110
125
|
entries = services.is_a?(Hash) ? services.values.flatten : Array(services)
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
126
|
+
%w[mcp rest].each do |transport|
|
|
127
|
+
endpoint = newest_endpoint(entries, transport)
|
|
128
|
+
return [transport.to_sym, endpoint] if endpoint
|
|
129
|
+
end
|
|
130
|
+
seen = entries.map { |s| s["transport"] }.compact.uniq
|
|
131
|
+
raise ManifestShapeError, "manifest has no mcp or rest service entry to connect to (saw: #{seen.join(', ')})"
|
|
132
|
+
end
|
|
133
|
+
private_class_method :service_endpoint
|
|
115
134
|
|
|
116
|
-
|
|
135
|
+
def self.newest_endpoint(entries, transport)
|
|
136
|
+
entries.select { |s| s["transport"] == transport }.max_by { |s| s["version"].to_s }&.fetch("endpoint", nil)
|
|
117
137
|
end
|
|
118
|
-
private_class_method :
|
|
138
|
+
private_class_method :newest_endpoint
|
|
119
139
|
|
|
120
140
|
def self.capability_names(manifest)
|
|
121
141
|
capabilities = ucp_section(manifest)["capabilities"]
|
metadata
CHANGED
|
@@ -1,14 +1,13 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: portage-ucp-client
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.8.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Tom Whitbread
|
|
8
|
-
autorequire:
|
|
9
8
|
bindir: bin
|
|
10
9
|
cert_chain: []
|
|
11
|
-
date:
|
|
10
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
12
11
|
dependencies:
|
|
13
12
|
- !ruby/object:Gem::Dependency
|
|
14
13
|
name: faraday
|
|
@@ -115,7 +114,6 @@ description: 'Every other portage-ucp gem lets a Ruby program expose a commerce
|
|
|
115
114
|
Adapter, stdio, Streamable HTTP) — callers never know which they got. Depends only
|
|
116
115
|
on portage-ucp, the mcp gem''s client half, and faraday (the HTTP transport''s backend);
|
|
117
116
|
no adapter gem is a dependency.'
|
|
118
|
-
email:
|
|
119
117
|
executables: []
|
|
120
118
|
extensions: []
|
|
121
119
|
extra_rdoc_files: []
|
|
@@ -131,6 +129,7 @@ files:
|
|
|
131
129
|
- lib/portage/ucp/client/transports/http/complete_checkout_wire_shape.rb
|
|
132
130
|
- lib/portage/ucp/client/transports/local_arguments.rb
|
|
133
131
|
- lib/portage/ucp/client/transports/loopback.rb
|
|
132
|
+
- lib/portage/ucp/client/transports/rest.rb
|
|
134
133
|
- lib/portage/ucp/client/transports/stdio.rb
|
|
135
134
|
- lib/portage/ucp/client/transports/ucp_wire_shape.rb
|
|
136
135
|
- lib/portage/ucp/client/version.rb
|
|
@@ -141,7 +140,6 @@ metadata:
|
|
|
141
140
|
source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-ucp-client
|
|
142
141
|
changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-ucp-client/CHANGELOG.md
|
|
143
142
|
rubygems_mfa_required: 'true'
|
|
144
|
-
post_install_message:
|
|
145
143
|
rdoc_options: []
|
|
146
144
|
require_paths:
|
|
147
145
|
- lib
|
|
@@ -156,8 +154,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
156
154
|
- !ruby/object:Gem::Version
|
|
157
155
|
version: '0'
|
|
158
156
|
requirements: []
|
|
159
|
-
rubygems_version:
|
|
160
|
-
signing_key:
|
|
157
|
+
rubygems_version: 4.0.20
|
|
161
158
|
specification_version: 4
|
|
162
159
|
summary: Client-side SDK for portage-ucp — act as the shopper's agent against any
|
|
163
160
|
UCP/MCP server
|