agentcat 0.0.1 → 1.1.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/LICENSE +2 -11
- data/README.md +265 -20
- data/lib/agentcat/adapters/base.rb +98 -0
- data/lib/agentcat/adapters/official.rb +277 -0
- data/lib/agentcat/client.rb +189 -0
- data/lib/agentcat/clock.rb +16 -0
- data/lib/agentcat/custom_event.rb +215 -0
- data/lib/agentcat/delivery.rb +58 -0
- data/lib/agentcat/diagnostics.rb +434 -0
- data/lib/agentcat/error_capture.rb +117 -0
- data/lib/agentcat/event_id.rb +19 -0
- data/lib/agentcat/event_pipeline.rb +82 -0
- data/lib/agentcat/event_queue.rb +151 -0
- data/lib/agentcat/exporters/base.rb +135 -0
- data/lib/agentcat/exporters/datadog.rb +137 -0
- data/lib/agentcat/exporters/otlp.rb +157 -0
- data/lib/agentcat/exporters/posthog.rb +185 -0
- data/lib/agentcat/exporters/sentry.rb +242 -0
- data/lib/agentcat/exporters/trace_context.rb +79 -0
- data/lib/agentcat/exporters.rb +108 -0
- data/lib/agentcat/fork_safety.rb +30 -0
- data/lib/agentcat/hooks.rb +190 -0
- data/lib/agentcat/http_post.rb +61 -0
- data/lib/agentcat/interceptor.rb +728 -0
- data/lib/agentcat/log.rb +80 -0
- data/lib/agentcat/options.rb +313 -0
- data/lib/agentcat/payload_limits.rb +71 -0
- data/lib/agentcat/private_members.rb +286 -0
- data/lib/agentcat/redaction.rb +176 -0
- data/lib/agentcat/rejected_calls.rb +147 -0
- data/lib/agentcat/request_context.rb +266 -0
- data/lib/agentcat/sanitization.rb +191 -0
- data/lib/agentcat/schema/prompts.rb +44 -0
- data/lib/agentcat/server_info.rb +280 -0
- data/lib/agentcat/session_manager.rb +83 -0
- data/lib/agentcat/tags.rb +61 -0
- data/lib/agentcat/test_mode.rb +86 -0
- data/lib/agentcat/testing.rb +153 -0
- data/lib/agentcat/text.rb +68 -0
- data/lib/agentcat/token_estimate.rb +98 -0
- data/lib/agentcat/tool_call.rb +129 -0
- data/lib/agentcat/tool_handle.rb +289 -0
- data/lib/agentcat/tracker.rb +204 -0
- data/lib/agentcat/truncation.rb +265 -0
- data/lib/agentcat/unredacted_event.rb +155 -0
- data/lib/agentcat/user_identity.rb +11 -0
- data/lib/agentcat/version.rb +2 -2
- data/lib/agentcat.rb +393 -21
- metadata +194 -16
- data/agentcat.gemspec +0 -30
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# typed: strict
|
|
2
|
+
|
|
3
|
+
module AgentCat
|
|
4
|
+
# String helpers that count the way the TypeScript SDK does. Every string length limit
|
|
5
|
+
# (field caps, the 32K normalize cap, tag keys and values) is in UTF-16 code units, the
|
|
6
|
+
# unit of JavaScript's `String#length`, so a limit means the same thing in every SDK.
|
|
7
|
+
module Text
|
|
8
|
+
extend T::Sig
|
|
9
|
+
|
|
10
|
+
REPLACEMENT = "\uFFFD"
|
|
11
|
+
|
|
12
|
+
# Valid UTF-8 for any string, so JSON encoding can never fail on it. Binary
|
|
13
|
+
# (ASCII-8BIT) strings are read as UTF-8 bytes; every invalid byte becomes U+FFFD,
|
|
14
|
+
# like the PHP SDK. Other encodings are converted. Valid UTF-8 comes back as is.
|
|
15
|
+
sig { params(value: String).returns(String) }
|
|
16
|
+
def self.scrub(value)
|
|
17
|
+
return value if value.encoding == Encoding::UTF_8 && value.valid_encoding?
|
|
18
|
+
|
|
19
|
+
utf8 = if [Encoding::BINARY, Encoding::US_ASCII, Encoding::UTF_8].include?(value.encoding)
|
|
20
|
+
value.dup.force_encoding(Encoding::UTF_8)
|
|
21
|
+
else
|
|
22
|
+
begin
|
|
23
|
+
value.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: REPLACEMENT)
|
|
24
|
+
rescue EncodingError
|
|
25
|
+
value.dup.force_encoding(Encoding::UTF_8)
|
|
26
|
+
end
|
|
27
|
+
end
|
|
28
|
+
utf8.scrub(REPLACEMENT)
|
|
29
|
+
end
|
|
30
|
+
|
|
31
|
+
# Length in UTF-16 code units: one per code point, two for code points above U+FFFF.
|
|
32
|
+
sig { params(value: String).returns(Integer) }
|
|
33
|
+
def self.utf16_length(value)
|
|
34
|
+
value = scrub(value)
|
|
35
|
+
return value.bytesize if value.ascii_only?
|
|
36
|
+
|
|
37
|
+
value.length + value.each_codepoint.count { |code| code > 0xFFFF }
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
# True when `value` is longer than `max` UTF-16 code units. A string never has more
|
|
41
|
+
# UTF-16 code units (after scrubbing) than bytes, so the byte size rules most strings
|
|
42
|
+
# out cheaply.
|
|
43
|
+
sig { params(value: String, max: Integer).returns(T::Boolean) }
|
|
44
|
+
def self.exceeds_utf16?(value, max)
|
|
45
|
+
value.bytesize > max && utf16_length(value) > max
|
|
46
|
+
end
|
|
47
|
+
|
|
48
|
+
# The first `max` UTF-16 code units. A character that would be split in half at the
|
|
49
|
+
# cut (a surrogate pair) is dropped whole, like the PHP SDK, so the result is always
|
|
50
|
+
# valid UTF-8 and can be JSON encoded.
|
|
51
|
+
sig { params(value: String, max: Integer).returns(String) }
|
|
52
|
+
def self.utf16_slice(value, max)
|
|
53
|
+
value = scrub(value)
|
|
54
|
+
return T.must(value[0, max]) if value.ascii_only?
|
|
55
|
+
|
|
56
|
+
units = 0
|
|
57
|
+
chars = 0
|
|
58
|
+
value.each_codepoint do |code|
|
|
59
|
+
width = (code > 0xFFFF) ? 2 : 1
|
|
60
|
+
break if units + width > max
|
|
61
|
+
|
|
62
|
+
units += width
|
|
63
|
+
chars += 1
|
|
64
|
+
end
|
|
65
|
+
T.must(value[0, chars])
|
|
66
|
+
end
|
|
67
|
+
end
|
|
68
|
+
end
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# typed: strict
|
|
2
|
+
|
|
3
|
+
require "json"
|
|
4
|
+
|
|
5
|
+
module AgentCat
|
|
6
|
+
# Rough token counts for the `input_tokens`/`output_tokens` fields on tool-call events.
|
|
7
|
+
#
|
|
8
|
+
# Same formula as the Go/TS/Python SDKs, byte for byte: ceil(utf8_bytes / 3.5), clamped
|
|
9
|
+
# to int32 (the server's columns). 3.5 sits between what OpenAI's tokenizers (~3.7
|
|
10
|
+
# bytes/token) and Claude's (~3.15) do on real MCP responses.
|
|
11
|
+
#
|
|
12
|
+
# Input is the raw arguments the agent sent, injected params included, as compact JSON.
|
|
13
|
+
# Output is the text of the content blocks the agent reads back - images, blobs and
|
|
14
|
+
# `structuredContent` don't count unless there's nothing else to go on (see
|
|
15
|
+
# `output_tokens`).
|
|
16
|
+
#
|
|
17
|
+
# Never raises: this runs on the tool call's own path, so a value that won't encode
|
|
18
|
+
# costs the field, not the call.
|
|
19
|
+
module TokenEstimate
|
|
20
|
+
extend T::Sig
|
|
21
|
+
|
|
22
|
+
BYTES_PER_TOKEN = 3.5
|
|
23
|
+
MAX_TOKEN_COUNT = 2_147_483_647
|
|
24
|
+
|
|
25
|
+
sig { params(byte_count: Integer).returns(Integer) }
|
|
26
|
+
def self.estimate(byte_count)
|
|
27
|
+
return 0 if byte_count <= 0
|
|
28
|
+
|
|
29
|
+
[(byte_count / BYTES_PER_TOKEN).ceil, MAX_TOKEN_COUNT].min
|
|
30
|
+
end
|
|
31
|
+
|
|
32
|
+
# nil when there are no arguments at all; `{}` counts as `{}`.
|
|
33
|
+
sig { params(arguments: T.untyped).returns(T.nilable(Integer)) }
|
|
34
|
+
def self.input_tokens(arguments)
|
|
35
|
+
return nil if arguments.nil?
|
|
36
|
+
|
|
37
|
+
bytes = compact_json_bytes(arguments)
|
|
38
|
+
bytes && estimate(bytes)
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
# nil when there's no response (the tool raised). A response with no `content` list
|
|
42
|
+
# is counted whole; an empty `content` list falls back to `structuredContent`.
|
|
43
|
+
sig { params(response: T.untyped).returns(T.nilable(Integer)) }
|
|
44
|
+
def self.output_tokens(response)
|
|
45
|
+
return nil unless response.is_a?(Hash)
|
|
46
|
+
|
|
47
|
+
content = fetch(response, :content)
|
|
48
|
+
unless content.is_a?(Array)
|
|
49
|
+
bytes = compact_json_bytes(response)
|
|
50
|
+
return bytes && estimate(bytes)
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
if content.empty?
|
|
54
|
+
structured = fetch(response, :structuredContent)
|
|
55
|
+
return 0 if structured.nil?
|
|
56
|
+
|
|
57
|
+
bytes = compact_json_bytes(structured)
|
|
58
|
+
return bytes && estimate(bytes)
|
|
59
|
+
end
|
|
60
|
+
|
|
61
|
+
estimate(content.sum { |block| content_block_bytes(block) })
|
|
62
|
+
rescue
|
|
63
|
+
nil
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
# Text blocks and embedded text resources are what the agent actually reads.
|
|
67
|
+
sig { params(block: T.untyped).returns(Integer) }
|
|
68
|
+
def self.content_block_bytes(block)
|
|
69
|
+
return 0 unless block.is_a?(Hash)
|
|
70
|
+
|
|
71
|
+
text = case fetch(block, :type).to_s
|
|
72
|
+
when "text" then fetch(block, :text)
|
|
73
|
+
when "resource"
|
|
74
|
+
resource = fetch(block, :resource)
|
|
75
|
+
resource.is_a?(Hash) ? fetch(resource, :text) : nil
|
|
76
|
+
end
|
|
77
|
+
text.is_a?(String) ? text.bytesize : 0
|
|
78
|
+
end
|
|
79
|
+
|
|
80
|
+
# Ruby's JSON doesn't escape `<`, `>`, `&` or non-ASCII, so this matches what
|
|
81
|
+
# `JSON.stringify` produces in the TS SDK.
|
|
82
|
+
sig { params(value: T.untyped).returns(T.nilable(Integer)) }
|
|
83
|
+
def self.compact_json_bytes(value)
|
|
84
|
+
JSON.generate(value).bytesize
|
|
85
|
+
rescue
|
|
86
|
+
nil
|
|
87
|
+
end
|
|
88
|
+
|
|
89
|
+
# Results come back symbol-keyed from `MCP::Tool::Response#to_h`, string-keyed from a
|
|
90
|
+
# tool that returns a plain Hash.
|
|
91
|
+
sig { params(hash: T::Hash[T.untyped, T.untyped], key: Symbol).returns(T.untyped) }
|
|
92
|
+
def self.fetch(hash, key)
|
|
93
|
+
hash.key?(key) ? hash[key] : hash[key.to_s]
|
|
94
|
+
end
|
|
95
|
+
|
|
96
|
+
private_class_method :content_block_bytes, :compact_json_bytes, :fetch
|
|
97
|
+
end
|
|
98
|
+
end
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# typed: strict
|
|
2
|
+
|
|
3
|
+
module AgentCat
|
|
4
|
+
# One tool call, as the hooks in `Options` (`identify`, `resolve_session_id`,
|
|
5
|
+
# `event_tags`, `event_properties`) see it. Every hook gets this one argument.
|
|
6
|
+
#
|
|
7
|
+
# AgentCat builds it on the request thread before any hook runs, so it holds the
|
|
8
|
+
# HTTP headers of the request even though the hook itself runs on its own thread.
|
|
9
|
+
# It is frozen all the way down: `arguments`, `meta` and `headers` are deep copies,
|
|
10
|
+
# and changing them raises `FrozenError`. A hook cannot change what your tool gets
|
|
11
|
+
# or what the event records.
|
|
12
|
+
#
|
|
13
|
+
# * `tool_name` — name of the tool the client called.
|
|
14
|
+
# * `arguments` — the raw call arguments (String keys), including the parameters
|
|
15
|
+
# AgentCat injects (`session_id`, `agent_id`, `context`).
|
|
16
|
+
# * `meta` — the raw `_meta` of the call (String keys); empty when there is none.
|
|
17
|
+
# * `headers` — HTTP request headers with lower-case names, one String each
|
|
18
|
+
# (repeated values joined with ", "); empty on stdio.
|
|
19
|
+
# * `client_name`, `client_version` — the MCP client, when it is known: from the
|
|
20
|
+
# `initialize` handshake, or from the SEP-2575 `_meta` clientInfo on a stateless call.
|
|
21
|
+
# * `protocol_version` — the MCP protocol version the call itself claims (the
|
|
22
|
+
# SEP-2575 envelope or `_meta`), when it is known. nil after a plain `initialize`
|
|
23
|
+
# handshake, where the version belongs to the session, not the call.
|
|
24
|
+
# * `transport_session_id` — the `Mcp-Session-Id` of the transport session; never the
|
|
25
|
+
# AgentCat session ID. nil on stdio and on stateless HTTP.
|
|
26
|
+
# * `request` — the Rack env of the HTTP request, for details this class does not
|
|
27
|
+
# expose; nil on stdio. Not copied or frozen: treat it as read-only.
|
|
28
|
+
# * `server_context` — the `mcp` gem's server context of the call. Not copied or
|
|
29
|
+
# frozen: treat it as read-only.
|
|
30
|
+
class ToolCall
|
|
31
|
+
extend T::Sig
|
|
32
|
+
|
|
33
|
+
sig { returns(String) }
|
|
34
|
+
attr_reader :tool_name
|
|
35
|
+
|
|
36
|
+
sig { returns(T::Hash[String, T.untyped]) }
|
|
37
|
+
attr_reader :arguments
|
|
38
|
+
|
|
39
|
+
sig { returns(T::Hash[String, T.untyped]) }
|
|
40
|
+
attr_reader :meta
|
|
41
|
+
|
|
42
|
+
sig { returns(T::Hash[String, String]) }
|
|
43
|
+
attr_reader :headers
|
|
44
|
+
|
|
45
|
+
sig { returns(T.nilable(String)) }
|
|
46
|
+
attr_reader :client_name
|
|
47
|
+
|
|
48
|
+
sig { returns(T.nilable(String)) }
|
|
49
|
+
attr_reader :client_version
|
|
50
|
+
|
|
51
|
+
sig { returns(T.nilable(String)) }
|
|
52
|
+
attr_reader :protocol_version
|
|
53
|
+
|
|
54
|
+
sig { returns(T.nilable(String)) }
|
|
55
|
+
attr_reader :transport_session_id
|
|
56
|
+
|
|
57
|
+
sig { returns(T.untyped) }
|
|
58
|
+
attr_reader :request
|
|
59
|
+
|
|
60
|
+
sig { returns(T.untyped) }
|
|
61
|
+
attr_reader :server_context
|
|
62
|
+
|
|
63
|
+
sig do
|
|
64
|
+
params(
|
|
65
|
+
tool_name: String,
|
|
66
|
+
arguments: T::Hash[T.untyped, T.untyped],
|
|
67
|
+
meta: T::Hash[T.untyped, T.untyped],
|
|
68
|
+
headers: T::Hash[T.untyped, T.untyped],
|
|
69
|
+
client_name: T.nilable(String),
|
|
70
|
+
client_version: T.nilable(String),
|
|
71
|
+
protocol_version: T.nilable(String),
|
|
72
|
+
transport_session_id: T.nilable(String),
|
|
73
|
+
request: T.untyped,
|
|
74
|
+
server_context: T.untyped
|
|
75
|
+
).void
|
|
76
|
+
end
|
|
77
|
+
def initialize(
|
|
78
|
+
tool_name:,
|
|
79
|
+
arguments:,
|
|
80
|
+
meta: {},
|
|
81
|
+
headers: {},
|
|
82
|
+
client_name: nil,
|
|
83
|
+
client_version: nil,
|
|
84
|
+
protocol_version: nil,
|
|
85
|
+
transport_session_id: nil,
|
|
86
|
+
request: nil,
|
|
87
|
+
server_context: nil
|
|
88
|
+
)
|
|
89
|
+
@tool_name = T.let(frozen_copy(tool_name), String)
|
|
90
|
+
@arguments = T.let(frozen_copy(arguments.transform_keys(&:to_s)), T::Hash[String, T.untyped])
|
|
91
|
+
@meta = T.let(frozen_copy(meta.transform_keys(&:to_s)), T::Hash[String, T.untyped])
|
|
92
|
+
@headers = T.let(frozen_copy(headers.to_h { |name, value| [name.to_s.downcase, value.to_s] }), T::Hash[String, String])
|
|
93
|
+
@client_name = T.let(frozen_copy(client_name), T.nilable(String))
|
|
94
|
+
@client_version = T.let(frozen_copy(client_version), T.nilable(String))
|
|
95
|
+
@protocol_version = T.let(frozen_copy(protocol_version), T.nilable(String))
|
|
96
|
+
@transport_session_id = T.let(frozen_copy(transport_session_id), T.nilable(String))
|
|
97
|
+
@request = request
|
|
98
|
+
@server_context = server_context
|
|
99
|
+
freeze
|
|
100
|
+
end
|
|
101
|
+
|
|
102
|
+
private
|
|
103
|
+
|
|
104
|
+
# A frozen deep copy of the Hash/Array/String structure. Other leaves (numbers, true,
|
|
105
|
+
# false, nil, symbols) are immutable already; any other object is kept as is.
|
|
106
|
+
# `copies` keeps a cyclic structure from looping and shared sub-objects shared.
|
|
107
|
+
sig { params(value: T.untyped, copies: T::Hash[Integer, T.untyped]).returns(T.untyped) }
|
|
108
|
+
def frozen_copy(value, copies = {})
|
|
109
|
+
case value
|
|
110
|
+
when Hash
|
|
111
|
+
copies.fetch(value.object_id) do
|
|
112
|
+
copy = copies[value.object_id] = {}
|
|
113
|
+
value.each { |key, item| copy[frozen_copy(key, copies)] = frozen_copy(item, copies) }
|
|
114
|
+
copy.freeze
|
|
115
|
+
end
|
|
116
|
+
when Array
|
|
117
|
+
copies.fetch(value.object_id) do
|
|
118
|
+
copy = copies[value.object_id] = []
|
|
119
|
+
value.each { |item| copy << frozen_copy(item, copies) }
|
|
120
|
+
copy.freeze
|
|
121
|
+
end
|
|
122
|
+
when String
|
|
123
|
+
value.frozen? ? value : value.dup.freeze
|
|
124
|
+
else
|
|
125
|
+
value
|
|
126
|
+
end
|
|
127
|
+
end
|
|
128
|
+
end
|
|
129
|
+
end
|
|
@@ -0,0 +1,289 @@
|
|
|
1
|
+
# typed: true
|
|
2
|
+
|
|
3
|
+
require "json"
|
|
4
|
+
|
|
5
|
+
module AgentCat
|
|
6
|
+
# Wraps a tool registered on an MCP server.
|
|
7
|
+
#
|
|
8
|
+
# Exposes the same surface `MCP::Tool` does (`name_value`, `input_schema`, `title`,
|
|
9
|
+
# `annotations`, `to_h`, `call`, ...), so `MCP::Server` can list, validate and dispatch
|
|
10
|
+
# it with no idea it's wrapped.
|
|
11
|
+
class ToolHandle
|
|
12
|
+
extend T::Sig
|
|
13
|
+
|
|
14
|
+
sig { returns(String) }
|
|
15
|
+
attr_reader :name
|
|
16
|
+
|
|
17
|
+
sig { returns(T.nilable(String)) }
|
|
18
|
+
attr_reader :title
|
|
19
|
+
|
|
20
|
+
sig { returns(T.nilable(String)) }
|
|
21
|
+
attr_reader :description
|
|
22
|
+
|
|
23
|
+
sig { returns(T.untyped) }
|
|
24
|
+
attr_reader :icons
|
|
25
|
+
|
|
26
|
+
sig { returns(T.untyped) }
|
|
27
|
+
attr_reader :annotations
|
|
28
|
+
|
|
29
|
+
sig { returns(T.untyped) }
|
|
30
|
+
attr_reader :meta
|
|
31
|
+
|
|
32
|
+
sig { returns(T.untyped) }
|
|
33
|
+
attr_reader :input_schema
|
|
34
|
+
|
|
35
|
+
sig { returns(T.untyped) }
|
|
36
|
+
attr_reader :output_schema
|
|
37
|
+
|
|
38
|
+
alias_method :name_value, :name
|
|
39
|
+
alias_method :title_value, :title
|
|
40
|
+
alias_method :description_value, :description
|
|
41
|
+
alias_method :icons_value, :icons
|
|
42
|
+
alias_method :annotations_value, :annotations
|
|
43
|
+
alias_method :meta_value, :meta
|
|
44
|
+
alias_method :input_schema_value, :input_schema
|
|
45
|
+
alias_method :output_schema_value, :output_schema
|
|
46
|
+
|
|
47
|
+
# `call_fn` receives `(arguments, server_context)` where `arguments` is a string-keyed Hash.
|
|
48
|
+
sig do
|
|
49
|
+
params(
|
|
50
|
+
name: String,
|
|
51
|
+
call_fn: T.untyped,
|
|
52
|
+
input_schema: T.untyped,
|
|
53
|
+
output_schema: T.untyped,
|
|
54
|
+
title: T.nilable(String),
|
|
55
|
+
description: T.nilable(String),
|
|
56
|
+
icons: T.untyped,
|
|
57
|
+
annotations: T.untyped,
|
|
58
|
+
meta: T.untyped
|
|
59
|
+
).void
|
|
60
|
+
end
|
|
61
|
+
def initialize(name:, call_fn:, input_schema: nil, output_schema: nil, title: nil, description: nil, icons: nil, annotations: nil, meta: nil)
|
|
62
|
+
@name = name
|
|
63
|
+
@call_fn = call_fn
|
|
64
|
+
@input_schema = input_schema || {type: "object", properties: {}}
|
|
65
|
+
@output_schema = output_schema
|
|
66
|
+
@title = title
|
|
67
|
+
@description = description
|
|
68
|
+
@icons = icons
|
|
69
|
+
@annotations = annotations
|
|
70
|
+
@meta = meta
|
|
71
|
+
@interceptor = T.let(nil, T.untyped)
|
|
72
|
+
@soft_required = T.let({}, T::Hash[String, String])
|
|
73
|
+
end
|
|
74
|
+
|
|
75
|
+
sig { returns(T::Hash[Symbol, T.untyped]) }
|
|
76
|
+
def to_h
|
|
77
|
+
{
|
|
78
|
+
name: name,
|
|
79
|
+
title: title,
|
|
80
|
+
description: description,
|
|
81
|
+
icons: icons_to_h,
|
|
82
|
+
inputSchema: schema_to_h(input_schema),
|
|
83
|
+
outputSchema: schema_to_h(output_schema),
|
|
84
|
+
annotations: annotations&.to_h,
|
|
85
|
+
_meta: meta
|
|
86
|
+
}.compact
|
|
87
|
+
end
|
|
88
|
+
|
|
89
|
+
# Whether the input schema is a `oneOf`/`allOf`/`anyOf` composition rather than a
|
|
90
|
+
# plain object schema. `properties`/`required` have no defined meaning as a sibling
|
|
91
|
+
# of these keywords, so injecting into one would either do nothing or corrupt it -
|
|
92
|
+
# safer to leave composed schemas alone entirely.
|
|
93
|
+
sig { returns(T::Boolean) }
|
|
94
|
+
def composed_input_schema?
|
|
95
|
+
composed?(schema_to_h(input_schema))
|
|
96
|
+
end
|
|
97
|
+
|
|
98
|
+
sig { returns(T::Boolean) }
|
|
99
|
+
def composed_output_schema?
|
|
100
|
+
composed?(schema_to_h(output_schema))
|
|
101
|
+
end
|
|
102
|
+
|
|
103
|
+
# Adds a string property to the input schema, optionally `required` and/or with a
|
|
104
|
+
# `pattern`, unless that name is already there. Keeps the schema's original class
|
|
105
|
+
# (Hash stays Hash, `MCP::Tool::InputSchema` gets rebuilt). Safe to call twice. No-op
|
|
106
|
+
# on a composed schema - see `composed_input_schema?`.
|
|
107
|
+
#
|
|
108
|
+
# `required` here is soft, like the TS SDK's: `tools/list` shows the name under
|
|
109
|
+
# `required` so schema-aware clients fill it in, but a call that leaves it out still
|
|
110
|
+
# gets through to the interceptor instead of being bounced by the `mcp` gem's own
|
|
111
|
+
# required check (see `SoftRequired`). `placeholder` is what that check is handed in
|
|
112
|
+
# place of a missing value - it never reaches the handler or the event.
|
|
113
|
+
sig { params(name: T.any(String, Symbol), description: T.nilable(String), type: String, required: T::Boolean, pattern: T.nilable(String), placeholder: String).returns(T.self_type) }
|
|
114
|
+
def add_input_parameter(name, description: nil, type: "string", required: false, pattern: nil, placeholder: "")
|
|
115
|
+
return self if composed_input_schema?
|
|
116
|
+
|
|
117
|
+
key = name.to_sym
|
|
118
|
+
schema = T.must(schema_to_h(input_schema))
|
|
119
|
+
properties = (schema[:properties] ||= {})
|
|
120
|
+
declared = properties.key?(key)
|
|
121
|
+
properties[key] = {type: type, description: description, pattern: pattern}.compact unless declared
|
|
122
|
+
|
|
123
|
+
# Without the gem internals that make it soft (`PrivateMembers`), a required name
|
|
124
|
+
# would turn away every call that leaves it out, so it is only listed, not required.
|
|
125
|
+
required = false if required && !declared && !soft_required_supported?
|
|
126
|
+
if required
|
|
127
|
+
required_list = T.let(schema[:required] ||= [], T::Array[T.untyped])
|
|
128
|
+
required_list << key.to_s unless required_list.include?(key.to_s)
|
|
129
|
+
# Only soften what we added - a name the tool declared itself stays as strict as
|
|
130
|
+
# the tool made it (our own `get_more_tools` declares its `context`).
|
|
131
|
+
@soft_required[key.to_s] = placeholder unless declared
|
|
132
|
+
end
|
|
133
|
+
|
|
134
|
+
@input_schema = rebuild_input_schema(input_schema, schema)
|
|
135
|
+
self
|
|
136
|
+
end
|
|
137
|
+
|
|
138
|
+
# Adds a property to the output schema unless one with that name exists, the tool
|
|
139
|
+
# declares no output schema at all (nothing to extend), or that schema is composed -
|
|
140
|
+
# see `composed_output_schema?`. `schema` is a full JSON Schema property hash (type,
|
|
141
|
+
# description, nested properties, ...).
|
|
142
|
+
sig { params(name: T.any(String, Symbol), schema: T::Hash[Symbol, T.untyped]).returns(T.self_type) }
|
|
143
|
+
def add_output_parameter(name, schema)
|
|
144
|
+
return self if output_schema.nil? || composed_output_schema?
|
|
145
|
+
|
|
146
|
+
key = name.to_sym
|
|
147
|
+
hash = T.must(schema_to_h(output_schema))
|
|
148
|
+
properties = (hash[:properties] ||= {})
|
|
149
|
+
return self if properties.key?(key)
|
|
150
|
+
|
|
151
|
+
properties[key] = schema
|
|
152
|
+
@output_schema = rebuild_schema(output_schema, hash)
|
|
153
|
+
self
|
|
154
|
+
end
|
|
155
|
+
|
|
156
|
+
sig { params(name: T.any(String, Symbol)).returns(T::Boolean) }
|
|
157
|
+
def input_parameter?(name)
|
|
158
|
+
properties = T.must(schema_to_h(input_schema))[:properties] || {}
|
|
159
|
+
properties.key?(name.to_sym)
|
|
160
|
+
end
|
|
161
|
+
|
|
162
|
+
sig { params(interceptor: T.untyped).returns(T.self_type) }
|
|
163
|
+
def intercept(&interceptor)
|
|
164
|
+
@interceptor = interceptor
|
|
165
|
+
self
|
|
166
|
+
end
|
|
167
|
+
|
|
168
|
+
sig { returns(T::Boolean) }
|
|
169
|
+
def intercepted?
|
|
170
|
+
!@interceptor.nil?
|
|
171
|
+
end
|
|
172
|
+
|
|
173
|
+
# Entry point used by `MCP::Server` (`tool.call(**arguments, server_context: ctx)`).
|
|
174
|
+
# A positional Hash is accepted for direct invocation.
|
|
175
|
+
sig { params(arguments: T.nilable(T::Hash[T.untyped, T.untyped]), server_context: T.untyped, keyword_arguments: T.untyped).returns(T.untyped).checked(:tests) }
|
|
176
|
+
def call(arguments = nil, server_context: nil, **keyword_arguments)
|
|
177
|
+
arguments = keyword_arguments if arguments.nil?
|
|
178
|
+
return invoke_original(arguments, server_context) unless @interceptor
|
|
179
|
+
|
|
180
|
+
@interceptor.call(arguments, server_context, method(:invoke_original))
|
|
181
|
+
end
|
|
182
|
+
|
|
183
|
+
sig { params(arguments: T.nilable(T::Hash[T.untyped, T.untyped]), server_context: T.untyped).returns(T.untyped).checked(:tests) }
|
|
184
|
+
def invoke_original(arguments, server_context)
|
|
185
|
+
@call_fn.call((arguments || {}).transform_keys(&:to_s), server_context)
|
|
186
|
+
end
|
|
187
|
+
|
|
188
|
+
private
|
|
189
|
+
|
|
190
|
+
sig { returns(T::Boolean) }
|
|
191
|
+
def soft_required_supported?
|
|
192
|
+
input_schema.is_a?(Hash) || PrivateMembers.enabled?(PrivateMembers::INPUT_SCHEMA_MISSING_REQUIRED_ARGUMENTS.feature)
|
|
193
|
+
end
|
|
194
|
+
|
|
195
|
+
sig { returns(T.nilable(T::Array[T.untyped])) }
|
|
196
|
+
def icons_to_h
|
|
197
|
+
return nil if icons.nil? || icons.empty?
|
|
198
|
+
|
|
199
|
+
icons.map { |icon| icon.respond_to?(:to_h) ? icon.to_h : icon }
|
|
200
|
+
end
|
|
201
|
+
|
|
202
|
+
# Deep copy of a schema as a symbol-keyed Hash.
|
|
203
|
+
sig { params(schema: T.untyped).returns(T.nilable(T::Hash[Symbol, T.untyped])) }
|
|
204
|
+
def schema_to_h(schema)
|
|
205
|
+
return nil if schema.nil?
|
|
206
|
+
|
|
207
|
+
hash = schema.is_a?(Hash) ? schema : schema.to_h
|
|
208
|
+
JSON.parse(JSON.generate(hash), symbolize_names: true)
|
|
209
|
+
end
|
|
210
|
+
|
|
211
|
+
sig { params(schema: T.nilable(T::Hash[Symbol, T.untyped])).returns(T::Boolean) }
|
|
212
|
+
def composed?(schema)
|
|
213
|
+
!!(schema && (schema.key?(:oneOf) || schema.key?(:allOf) || schema.key?(:anyOf)))
|
|
214
|
+
end
|
|
215
|
+
|
|
216
|
+
# Same as `rebuild_schema`, but an `MCP::Tool::InputSchema` comes back soft about the
|
|
217
|
+
# names in `@soft_required`. A plain Hash can't carry that, so it stays as it is.
|
|
218
|
+
sig { params(original: T.untyped, hash: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
|
|
219
|
+
def rebuild_input_schema(original, hash)
|
|
220
|
+
return hash if original.is_a?(Hash)
|
|
221
|
+
return rebuild_schema(original, hash) if @soft_required.empty? || !original.respond_to?(:missing_required_arguments)
|
|
222
|
+
|
|
223
|
+
SoftRequired.build(original.class, hash, @soft_required)
|
|
224
|
+
end
|
|
225
|
+
|
|
226
|
+
# Hash stays Hash; anything else (`MCP::Tool::InputSchema`/`OutputSchema`) gets
|
|
227
|
+
# reconstructed from the mutated hash so the original wrapper class survives.
|
|
228
|
+
sig { params(original: T.untyped, hash: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
|
|
229
|
+
def rebuild_schema(original, hash)
|
|
230
|
+
original.is_a?(Hash) ? hash : original.class.new(hash)
|
|
231
|
+
end
|
|
232
|
+
end
|
|
233
|
+
|
|
234
|
+
# Makes some `required` names advisory on an `MCP::Tool::InputSchema`, by overriding two
|
|
235
|
+
# of its methods (`PrivateMembers::INPUT_SCHEMA_*`). `to_h` (what
|
|
236
|
+
# `tools/list` sends) is untouched, so those names still show as required. The two
|
|
237
|
+
# checks the `mcp` gem runs before calling a tool skip them: `missing_required_arguments`
|
|
238
|
+
# leaves them out, and `validate_arguments` (only on with `validate_tool_call_arguments`)
|
|
239
|
+
# validates as if the missing ones had their placeholder. The arguments themselves
|
|
240
|
+
# aren't touched, so the interceptor sees exactly what the agent sent.
|
|
241
|
+
module SoftRequired
|
|
242
|
+
extend T::Sig
|
|
243
|
+
|
|
244
|
+
SUBCLASSES = T.let({}, T::Hash[T.untyped, T.untyped])
|
|
245
|
+
SUBCLASSES_MUTEX = T.let(Mutex.new, Mutex)
|
|
246
|
+
|
|
247
|
+
sig { params(base: T.untyped, hash: T::Hash[Symbol, T.untyped], placeholders: T::Hash[String, String]).returns(T.untyped) }
|
|
248
|
+
def self.build(base, hash, placeholders)
|
|
249
|
+
schema = class_for(base).new(hash)
|
|
250
|
+
schema.soft_placeholders = placeholders.dup.freeze
|
|
251
|
+
schema
|
|
252
|
+
end
|
|
253
|
+
|
|
254
|
+
# One subclass per schema class, made on first use — `mcp` may not even be loaded
|
|
255
|
+
# when agentcat is. A schema that's already soft keeps its class.
|
|
256
|
+
sig { params(base: T.untyped).returns(T.untyped) }
|
|
257
|
+
def self.class_for(base)
|
|
258
|
+
return base if base < SchemaMethods
|
|
259
|
+
|
|
260
|
+
SUBCLASSES_MUTEX.synchronize do
|
|
261
|
+
SUBCLASSES[base] ||= Class.new(base) { include SchemaMethods }
|
|
262
|
+
end
|
|
263
|
+
end
|
|
264
|
+
|
|
265
|
+
module SchemaMethods
|
|
266
|
+
attr_accessor :soft_placeholders
|
|
267
|
+
|
|
268
|
+
def missing_required_arguments(arguments)
|
|
269
|
+
super - soft_placeholders.keys
|
|
270
|
+
rescue NoMethodError => e
|
|
271
|
+
Kernel.raise unless e.name == :missing_required_arguments && e.receiver.equal?(self)
|
|
272
|
+
|
|
273
|
+
AgentCat::PrivateMembers.missing!(AgentCat::PrivateMembers::INPUT_SCHEMA_MISSING_REQUIRED_ARGUMENTS)
|
|
274
|
+
[]
|
|
275
|
+
end
|
|
276
|
+
|
|
277
|
+
def validate_arguments(arguments)
|
|
278
|
+
given = arguments.keys.map(&:to_s)
|
|
279
|
+
filler = soft_placeholders.except(*given).transform_keys(&:to_sym)
|
|
280
|
+
super(filler.merge(arguments))
|
|
281
|
+
rescue NoMethodError => e
|
|
282
|
+
Kernel.raise unless e.name == :validate_arguments && e.receiver.equal?(self)
|
|
283
|
+
|
|
284
|
+
AgentCat::PrivateMembers.missing!(AgentCat::PrivateMembers::INPUT_SCHEMA_VALIDATE_ARGUMENTS)
|
|
285
|
+
nil
|
|
286
|
+
end
|
|
287
|
+
end
|
|
288
|
+
end
|
|
289
|
+
end
|