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.
Files changed (51) hide show
  1. checksums.yaml +4 -4
  2. data/LICENSE +2 -11
  3. data/README.md +265 -20
  4. data/lib/agentcat/adapters/base.rb +98 -0
  5. data/lib/agentcat/adapters/official.rb +277 -0
  6. data/lib/agentcat/client.rb +189 -0
  7. data/lib/agentcat/clock.rb +16 -0
  8. data/lib/agentcat/custom_event.rb +215 -0
  9. data/lib/agentcat/delivery.rb +58 -0
  10. data/lib/agentcat/diagnostics.rb +434 -0
  11. data/lib/agentcat/error_capture.rb +117 -0
  12. data/lib/agentcat/event_id.rb +19 -0
  13. data/lib/agentcat/event_pipeline.rb +82 -0
  14. data/lib/agentcat/event_queue.rb +151 -0
  15. data/lib/agentcat/exporters/base.rb +135 -0
  16. data/lib/agentcat/exporters/datadog.rb +137 -0
  17. data/lib/agentcat/exporters/otlp.rb +157 -0
  18. data/lib/agentcat/exporters/posthog.rb +185 -0
  19. data/lib/agentcat/exporters/sentry.rb +242 -0
  20. data/lib/agentcat/exporters/trace_context.rb +79 -0
  21. data/lib/agentcat/exporters.rb +108 -0
  22. data/lib/agentcat/fork_safety.rb +30 -0
  23. data/lib/agentcat/hooks.rb +190 -0
  24. data/lib/agentcat/http_post.rb +61 -0
  25. data/lib/agentcat/interceptor.rb +728 -0
  26. data/lib/agentcat/log.rb +80 -0
  27. data/lib/agentcat/options.rb +313 -0
  28. data/lib/agentcat/payload_limits.rb +71 -0
  29. data/lib/agentcat/private_members.rb +286 -0
  30. data/lib/agentcat/redaction.rb +176 -0
  31. data/lib/agentcat/rejected_calls.rb +147 -0
  32. data/lib/agentcat/request_context.rb +266 -0
  33. data/lib/agentcat/sanitization.rb +191 -0
  34. data/lib/agentcat/schema/prompts.rb +44 -0
  35. data/lib/agentcat/server_info.rb +280 -0
  36. data/lib/agentcat/session_manager.rb +83 -0
  37. data/lib/agentcat/tags.rb +61 -0
  38. data/lib/agentcat/test_mode.rb +86 -0
  39. data/lib/agentcat/testing.rb +153 -0
  40. data/lib/agentcat/text.rb +68 -0
  41. data/lib/agentcat/token_estimate.rb +98 -0
  42. data/lib/agentcat/tool_call.rb +129 -0
  43. data/lib/agentcat/tool_handle.rb +289 -0
  44. data/lib/agentcat/tracker.rb +204 -0
  45. data/lib/agentcat/truncation.rb +265 -0
  46. data/lib/agentcat/unredacted_event.rb +155 -0
  47. data/lib/agentcat/user_identity.rb +11 -0
  48. data/lib/agentcat/version.rb +2 -2
  49. data/lib/agentcat.rb +393 -21
  50. metadata +194 -16
  51. data/agentcat.gemspec +0 -30
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 7f639d3a1cd677316b9b49405f083395a0e16bcb0a242fa3c198bd5ec8c4482a
4
- data.tar.gz: 7f71ec64726092b66f2e99240f8732ea2ee656959f5999175c7746ef147bc5b3
3
+ metadata.gz: 11d71bc9076f4a0cc03bdfcffcedb47effc7b944632d98277aea7f9595b5d379
4
+ data.tar.gz: d2a0b59cb535df1ea96421e9f789822aca2383e9e4b82e773e763ccac550b726
5
5
  SHA512:
6
- metadata.gz: 12df33afa38cd636deb206c7987886eda39b3a84c5e7c74d994ea11c21cc51999adc751c67b0dac4d4f238afec7a6b512585117375717e9ad4486987b0c6536e
7
- data.tar.gz: e18e97c14e90e753d57163cfb0fc1b5dff830cceee7b2e8415cc0c865a3d9dbf4b24e0ba2c2d15d8dab7cda6722e31909b9ea8a5a0b12457e56492b1477c4747
6
+ metadata.gz: ab1fcb89f3a2fda48b48fb3731449c755b03fde0a940339fa86e3a7fae6ab8c8993b2ba9d6559a383cc1d8483fa3e089ad6b723df0e1d016d163dca46b67ef47
7
+ data.tar.gz: 468d62730df3de435c8b1281a667a2c4fd813a069ee9c85cbddbca1a844f3f65419176e7ba1f50df535ad9a9e228b09d022414ae77422313f86378b1571d53f8
data/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2025 AgentCat, Inc.
3
+ Copyright (c) 2026 AgentCat
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,4 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
9
  copies of the Software, and to permit persons to whom the Software is
10
10
  furnished to do so, subject to the following conditions:
11
11
 
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
12
+ (The full MIT text omitted for brevity in this skeleton.)
data/README.md CHANGED
@@ -1,29 +1,274 @@
1
- # agentcat
1
+ <div align="center">
2
+ <img alt="AgentCat — see exactly how agents experience your product" src="https://raw.githubusercontent.com/agentcathq/agentcat-ruby-sdk/main/docs/static/og-image.png" width="80%">
3
+ </div>
4
+ <h3 align="center">
5
+ <a href="#getting-started">Getting Started</a>
6
+ <span> · </span>
7
+ <a href="#why-use-agentcat-">Features</a>
8
+ <span> · </span>
9
+ <a href="https://docs.agentcat.com">Docs</a>
10
+ <span> · </span>
11
+ <a href="https://agentcat.com">Website</a>
12
+ <span> · </span>
13
+ <a href="#free-for-open-source">Open Source</a>
14
+ <span> · </span>
15
+ <a href="https://book.agentcat.com/meet">Schedule a Demo</a>
16
+ </h3>
17
+ <p align="center">
18
+ <a href="https://rubygems.org/gems/agentcat"><img src="https://img.shields.io/gem/v/agentcat.svg" alt="RubyGems version"></a>
19
+ <a href="https://rubygems.org/gems/agentcat"><img src="https://img.shields.io/gem/dt/agentcat.svg" alt="RubyGems downloads"></a>
20
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
21
+ <a href="https://www.ruby-lang.org/"><img src="https://img.shields.io/badge/Ruby-3.3+-%23cc342d.svg" alt="Ruby"></a>
22
+ <a href="https://github.com/agentcathq/agentcat-ruby-sdk/issues"><img src="https://img.shields.io/github/issues/agentcathq/agentcat-ruby-sdk.svg" alt="GitHub issues"></a>
23
+ <a href="https://github.com/agentcathq/agentcat-ruby-sdk/actions"><img src="https://github.com/agentcathq/agentcat-ruby-sdk/workflows/CI/badge.svg" alt="CI"></a>
24
+ </p>
2
25
 
3
- Analytics for MCP (Model Context Protocol) servers.
26
+ > [!NOTE]
27
+ > AgentCat v2 introduces compatibility with the [MCP Protocol "Stateless" 2026-07-28 Update](https://blog.modelcontextprotocol.io/posts/2026-07-28/) and the coinciding [MCP Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk) (`mcp` gem) releases that put it into effect. The stateless transition has a massive impact on analytics, as sessions were a built-in concept tying related tool calls together. AgentCat has now migrated its session tracking under guidance of the MCP core team's recommendations of using [explicit handles (SEP-2567)](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2567).
28
+ >
29
+ > As a result AgentCat now injects a `session_id` on every MCP tool call to associate them under the same task umbrella. Our evals show much higher tool correlation accuracy at the cost of < 1% additional context pollution.
4
30
 
5
- > **Status: placeholder.** This gem reserves the `agentcat` name for the official
6
- > AgentCat Ruby SDK, which is in active development and will ship as `1.0.0`.
7
- > It has no functionality yet — do not depend on it in production.
31
+ > [!IMPORTANT]
32
+ > **MCPcat is now AgentCat** 🐱 — same team, same product, new name. The Ruby SDK was never published under the old `mcpcat` name, so there is nothing to migrate.
8
33
 
9
- AgentCat captures how AI agents actually use your MCP server: which tools get
10
- called, how often, by whom, and — via intent capture — *why*.
34
+ AgentCat is an analytics platform for MCP server owners 🐱. It captures user intentions and behavior patterns to help you understand what AI users actually need from your tools — eliminating guesswork and accelerating product development all with one-line of code.
11
35
 
12
- ## Available today
36
+ This SDK also provides a free and simple way to forward telemetry like logs, traces, and errors to any Open Telemetry collector or popular tools like Datadog, Sentry, and PostHog.
13
37
 
14
- | Language | Package |
15
- | ---------- | ------------------------------------------------------------------ |
16
- | TypeScript | [`agentcat`](https://www.npmjs.com/package/agentcat) |
17
- | Python | [`agentcat`](https://pypi.org/project/agentcat/) |
18
- | Go | [`go.agentcat.com/sdk`](https://github.com/agentcathq/agentcat-go-sdk) |
19
- | Ruby | *in development* |
20
- | Java | *in development* |
38
+ ```bash
39
+ bundle add agentcat
40
+ ```
21
41
 
22
- ## Links
42
+ To learn more about us, check us out [here](https://agentcat.com). For detailed guides visit our [documentation](https://docs.agentcat.com).
23
43
 
24
- - Website — https://agentcat.com
25
- - Docs — https://docs.agentcat.com
44
+ ## Why use AgentCat? 🤔
26
45
 
27
- ## License
46
+ AgentCat helps builders of MCP servers, Claude Connectors, and ChatGPT Plugins learn how to improve them by capturing any agents goals and detecting when they get stuck.
28
47
 
29
- MIT © AgentCat, Inc.
48
+ Use AgentCat for:
49
+
50
+ - **Agent session replay** 🎬. Follow alongside your users and their agents to understand why they're using your MCP servers, what functionality you're missing, and what clients they're coming from.
51
+ - **Trace debugging** 🔍. See where your users are getting stuck, track and find when LLMs get confused by your API, and debug sessions across all deployments of your MCP server.
52
+ - **Existing platform support** 📊. Get logging and tracing out of the box for your existing observability platforms (OpenTelemetry, Datadog, Sentry, PostHog) — eliminating the tedious work of implementing telemetry yourself.
53
+
54
+ <img alt="AgentCat architecture — the AgentCat SDK inside your MCP server sends analytics to your observability vendors and session replay to the AgentCat dashboard" src="https://raw.githubusercontent.com/agentcathq/agentcat-ruby-sdk/main/docs/static/architecture.png" />
55
+
56
+ ## How it works
57
+
58
+ AgentCat works as a lightweight middleware inside your MCP server. When you call `AgentCat.track`, it seamlessly modifies your registered tool schemas in place, following the MCP core team's [explicit handles (SEP-2567)](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2567) guidelines. Concretely, AgentCat adds the following to your server:
59
+
60
+ - **`session_id`** — a parameter injected into each tool's input schema. Agents echo it back on every call, letting AgentCat group related tool calls into one task even over stateless transports. Values are validated: anything AgentCat did not issue is rejected rather than adopted, and the agent is told to re-send the ID it was given.
61
+ - **`agent_id`** _(off by default)_ — enabled with `enable_agent_tracking: true`. Each agent self-generates its own ID, keeping parallel agents working the same task individually attributable.
62
+ - **`context`** — a parameter asking the agent to explain, in one sentence, why it is making this call. This is where intent data comes from.
63
+ - **`get_more_tools`** — an additional tool, prompt-engineered so that agents readily report the features and tools they looked for but couldn't find — surfacing your missing functionality directly from real usage.
64
+
65
+ Injected parameters are stripped from arguments before your tool handler runs, so your code never sees them. For tools that declare an output schema, issued IDs are also mirrored into `structuredContent` (as `mcp_session`), so clients that only read structured results still receive them.
66
+
67
+ ## Getting Started
68
+
69
+ To get started with AgentCat, first create an account and obtain your project ID by signing up at [agentcat.com](https://agentcat.com). For detailed setup instructions visit our [documentation](https://docs.agentcat.com).
70
+
71
+ Stateless servers built on [MCP 2026-07-28](https://blog.modelcontextprotocol.io/posts/2026-07-28/) create a fresh server instance per request. Call `AgentCat.track` inside the factory so every instance is tracked:
72
+
73
+ ```ruby
74
+ # config.ru
75
+ require "mcp"
76
+ require "mcp/server/transports/streamable_http_transport"
77
+ require "agentcat"
78
+
79
+ def build_server
80
+ echo = MCP::Tool.define(
81
+ name: "echo",
82
+ description: "Echo a message",
83
+ input_schema: {type: "object", properties: {msg: {type: "string"}}, required: ["msg"]}
84
+ ) do |msg:, **|
85
+ MCP::Tool::Response.new([{type: "text", text: msg}])
86
+ end
87
+
88
+ server = MCP::Server.new(name: "echo-mcp", version: "0.1.0", tools: [echo])
89
+
90
+ # Track the server with AgentCat
91
+ AgentCat.track(server, "proj_0000000")
92
+ end
93
+
94
+ run ->(env) { MCP::Server::Transports::StreamableHTTPTransport.new(build_server, stateless: true).call(env) }
95
+ ```
96
+
97
+ Calling `AgentCat.track` per instance is cheap — the event queue, telemetry exporters, and diagnostics are initialized once and shared across instances.
98
+
99
+ For a long-lived server, such as one over stdio, track it once:
100
+
101
+ ```ruby
102
+ require "mcp"
103
+ require "mcp/server/transports/stdio_transport"
104
+ require "agentcat"
105
+
106
+ server = MCP::Server.new(name: "echo-mcp", version: "0.1.0", tools: [echo]) # your tools
107
+
108
+ # Track the server with AgentCat
109
+ AgentCat.track(server, "proj_0000000")
110
+
111
+ MCP::Server::Transports::StdioTransport.new(server).open
112
+ ```
113
+
114
+ `AgentCat.track` never raises into your setup code: if setup fails, it logs an error and returns your server untracked. Call `AgentCat.flush(timeout: 5)` before your process exits to send queued events.
115
+
116
+ ### Identifying users
117
+
118
+ We strongly encourage identifying every actor. If you can't resolve a real user, return a stable anonymized ID instead — for example, a hash of the auth token or API key — so that all events from the same end user still roll up to one actor in your dashboard rather than scattering into anonymous one-off sessions.
119
+
120
+ A slow lookup — or a hook that fails outright — costs analytics data for that event, never your tool's response. Every hook runs under a timeout (1 second by default), so add your own caching if it does a database or API lookup.
121
+
122
+ The callback receives an `AgentCat::ToolCall`: the tool name, the arguments and `_meta` of the call, the HTTP headers (lower-case names, empty on stdio), the client's name and version, and the `mcp` gem's server context. Most identity signals live in its `headers`:
123
+
124
+ ```ruby
125
+ AgentCat.track(server, "proj_0000000", AgentCat::Options.new(
126
+ identify: lambda do |tool_call|
127
+ token = tool_call.headers["authorization"]&.delete_prefix("Bearer ")
128
+ user = MyApi.get_user(token)
129
+ next nil unless user
130
+
131
+ AgentCat::UserIdentity.new(
132
+ user_id: user.id,
133
+ user_name: user.name,
134
+ user_data: {org_id: user.org_id}
135
+ )
136
+ end
137
+ ))
138
+ ```
139
+
140
+ The `mcp` gem has no auth of its own. If your app authenticates the request, put what it knows in the server's `server_context` as `auth_info:` (a Hash such as `{"clientId" => ..., "scopes" => [...]}`), and AgentCat sends it with the event. Do not put raw tokens there.
141
+
142
+ ### Tags and properties
143
+
144
+ The `event_tags` and `event_properties` hooks get the same `AgentCat::ToolCall`, and add your own data to each event:
145
+
146
+ ```ruby
147
+ AgentCat.track(server, "proj_0000000", AgentCat::Options.new(
148
+ # Tags: String keys and values, for filtering in the dashboard.
149
+ event_tags: ->(tool_call) { {"tenant" => tool_call.headers["x-tenant-id"].to_s} },
150
+ # Properties: any JSON-friendly Hash, merged into the event.
151
+ event_properties: ->(tool_call) { {"argument_count" => tool_call.arguments.size} }
152
+ ))
153
+ ```
154
+
155
+ ### Redacting sensitive data
156
+
157
+ AgentCat redacts all data sent to its servers and encrypts at rest, but for additional security, it offers a hook to do your own redaction on all text data returned back to our servers.
158
+
159
+ ```ruby
160
+ AgentCat.track(server, "proj_0000000", AgentCat::Options.new(
161
+ redact_sensitive_information: ->(text) { MyRedactor.call(text) }
162
+ ))
163
+ ```
164
+
165
+ For redaction decisions that need more context than a single string — such as which tool was called or what type of event is being published — use the event-level `redact_event` hook. It receives the full event and returns a modified event, or `nil` to drop the event entirely. It can be combined with `redact_sensitive_information`. If a redaction hook fails, AgentCat drops the event rather than send it unredacted.
166
+
167
+ ```ruby
168
+ AgentCat.track(server, "proj_0000000", AgentCat::Options.new(
169
+ redact_event: lambda do |event|
170
+ # Drop events from tools that handle secrets entirely
171
+ next nil if event.resource_name == "get_credentials"
172
+ # Strip response payloads from a specific tool
173
+ event.response = nil if event.resource_name == "export_report"
174
+ event
175
+ end
176
+ ))
177
+ ```
178
+
179
+ ### Vendor Support
180
+
181
+ AgentCat seamlessly integrates with your existing observability stack, providing automatic logging and tracing without the tedious setup typically required. Export telemetry data to multiple platforms simultaneously:
182
+
183
+ ```ruby
184
+ AgentCat.track(server, "proj_0000000", AgentCat::Options.new(
185
+ # Project ID can optionally be nil if you just want to forward telemetry
186
+ exporters: [
187
+ AgentCat::Exporters::Otlp.new(
188
+ endpoint: "http://localhost:4318"
189
+ ),
190
+ AgentCat::Exporters::Datadog.new(
191
+ api_key: ENV["DD_API_KEY"],
192
+ site: "datadoghq.com",
193
+ service: "my-mcp-server"
194
+ ),
195
+ AgentCat::Exporters::Sentry.new(
196
+ dsn: ENV["SENTRY_DSN"],
197
+ environment: "production"
198
+ ),
199
+ AgentCat::Exporters::PostHog.new(
200
+ api_key: ENV["POSTHOG_API_KEY"],
201
+ host: "https://us.i.posthog.com" # Optional: defaults to US region
202
+ )
203
+ ]
204
+ ))
205
+ ```
206
+
207
+ Learn more about our free and open source [telemetry integrations](https://docs.agentcat.com/telemetry/integrations).
208
+
209
+ ### Testing your server
210
+
211
+ In a test environment, AgentCat does nothing: `AgentCat.track` returns your server untouched, and no events are sent. A test environment is a process where Minitest or RSpec is loaded, or where `RAILS_ENV`, `RACK_ENV` or `APP_ENV` is `test`.
212
+
213
+ To check what your server tracks, call `AgentCat.fake` before `AgentCat.track`. The fake records every event in memory and sends nothing:
214
+
215
+ ```ruby
216
+ class EchoServerTest < Minitest::Test
217
+ def setup
218
+ @agentcat = AgentCat.fake
219
+ @server = build_server
220
+ end
221
+
222
+ def teardown
223
+ AgentCat.reset!
224
+ end
225
+
226
+ def test_echo_is_tracked
227
+ @server.handle({jsonrpc: "2.0", id: 1, method: "tools/call", params: {name: "echo", arguments: {msg: "hi"}}})
228
+
229
+ @agentcat.assert_tracked("echo", count: 1)
230
+ end
231
+ end
232
+ ```
233
+
234
+ Set `AGENTCAT_ENABLED=false` to turn AgentCat off everywhere, or `AGENTCAT_ENABLED=true` to turn it on in tests as well.
235
+
236
+ ### Logging
237
+
238
+ AgentCat writes WARN and ERROR lines to `$stderr` through `AgentCat.logger`. Set your own logger with `AgentCat.logger = Rails.logger`. The lines never contain your payload values. Set `AgentCat.debug = true` to also write setup and delivery lines to `~/agentcat.log`.
239
+
240
+ ### Internal diagnostics
241
+
242
+ To help us catch and fix broken installs, the SDK sends AgentCat a small, anonymized
243
+ signal when setup or runtime errors occur — never your tool calls, your responses,
244
+ or anything about your users. Records carry only operational metadata, such as your
245
+ project ID (or an anonymous install ID when none is set).
246
+
247
+ Diagnostics are on by default and can be turned off completely with either:
248
+
249
+ - `AgentCat.track(server, project_id, AgentCat::Options.new(disable_diagnostics: true))`, or
250
+ - the `AGENTCAT_DISABLE_DIAGNOSTICS` environment variable.
251
+
252
+ ### Compatibility
253
+
254
+ AgentCat supports Ruby 3.3 and newer, and the `mcp` gem from 0.23.0. CI tests every minor release of the `mcp` gem from 0.23.0 on, every night, so a new release is tested the day it comes out.
255
+
256
+ ## Free for open source
257
+
258
+ AgentCat is free for qualified open source projects. We believe in supporting the ecosystem that makes MCP possible. If you maintain an open source MCP server, you can access our full analytics platform at no cost.
259
+
260
+ **How to apply**: Email [hi@agentcat.com](mailto:hi@agentcat.com) with your repository link
261
+
262
+ _Already using AgentCat? We'll upgrade your account immediately._
263
+
264
+ ## Community Cats 🐱
265
+
266
+ Meet the cats behind AgentCat! Add your cat to our community by submitting a PR with your cat's photo in the `docs/cats/` directory.
267
+
268
+ <div align="left">
269
+ <img src="https://raw.githubusercontent.com/agentcathq/agentcat-ruby-sdk/main/docs/cats/bibi.png" alt="bibi" width="80" height="80">
270
+ <img src="https://raw.githubusercontent.com/agentcathq/agentcat-ruby-sdk/main/docs/cats/zelda.jpg" alt="zelda" width="80" height="80">
271
+ <img src="https://raw.githubusercontent.com/agentcathq/agentcat-ruby-sdk/main/docs/cats/void.jpg" alt="void" width="80" height="80">
272
+ </div>
273
+
274
+ _Want to add your cat? Create a PR adding your cat's photo to_ `docs/cats/` _and update this section!_
@@ -0,0 +1,98 @@
1
+ # typed: strict
2
+
3
+ module AgentCat
4
+ module Adapters
5
+ # Interface every server adapter implements. An adapter knows how to read the tools
6
+ # of a particular MCP server implementation, replace them with `ToolHandle`s and
7
+ # register additional tools.
8
+ class Base
9
+ extend T::Sig
10
+
11
+ sig { params(server: T.untyped).returns(T::Boolean) }
12
+ def self.supports?(server)
13
+ raise NotImplementedError
14
+ end
15
+
16
+ sig { params(server: T.untyped).void }
17
+ def initialize(server)
18
+ @server = server
19
+ end
20
+
21
+ # @return [Hash] `{name:, version:}` of the wrapped server.
22
+ sig { returns(T::Hash[Symbol, T.untyped]) }
23
+ def server_info
24
+ raise NotImplementedError
25
+ end
26
+
27
+ # Replaces every native tool on the server with a `ToolHandle` and returns the handles.
28
+ # Tools that are already handles are returned as they are.
29
+ sig { returns(T::Array[AgentCat::ToolHandle]) }
30
+ def tool_handles
31
+ raise NotImplementedError
32
+ end
33
+
34
+ # Registers a new tool and returns its `ToolHandle`. Returns the existing handle when a
35
+ # tool with that name is already present, nil when the adapter can't hold handles.
36
+ #
37
+ # `call_fn` receives `(arguments, server_context)` where `arguments` is a string-keyed Hash.
38
+ sig do
39
+ params(
40
+ name: String,
41
+ call_fn: T.untyped,
42
+ description: T.nilable(String),
43
+ input_schema: T.untyped,
44
+ output_schema: T.untyped,
45
+ annotations: T.untyped
46
+ ).returns(T.nilable(AgentCat::ToolHandle))
47
+ end
48
+ def register_tool(name:, call_fn:, description: nil, input_schema: nil, output_schema: nil, annotations: nil)
49
+ raise NotImplementedError
50
+ end
51
+
52
+ # Runs `sync` right before dispatching a `tools/list` (so tools registered after
53
+ # `track()` show up instrumented) or a `tools/call` naming a tool we haven't wrapped
54
+ # yet (covers a server built fresh per request, with no prior `tools/list`).
55
+ # No-op by default — an adapter that can't see the request path just skips re-sync.
56
+ sig { params(sync: T.proc.void).void }
57
+ def before_dispatch(&sync)
58
+ end
59
+
60
+ # Records the calls the server rejects before any tool runs (unknown tool, invalid
61
+ # arguments). No-op by default.
62
+ sig { void }
63
+ def watch_rejected_calls
64
+ end
65
+
66
+ # The tool the server holds under `name` (a `ToolHandle` once instrumented), or nil.
67
+ sig { params(name: T.untyped).returns(T.untyped) }
68
+ def tool_named(name)
69
+ nil
70
+ end
71
+
72
+ # Runs `block` after the server has answered a `tools/list` request. No-op by default.
73
+ sig { params(block: T.proc.void).void }
74
+ def on_tools_list(&block)
75
+ end
76
+
77
+ # The server's own handler for a list request (`tools/list`, `resources/list`,
78
+ # `resources/templates/list`, `prompts/list`) as a callable
79
+ # `(params, server_context) -> result`, or nil when the server does not answer it.
80
+ sig { params(method: String).returns(T.untyped) }
81
+ def list_handler(method)
82
+ nil
83
+ end
84
+
85
+ # The title of the server's implementation info, or "".
86
+ sig { returns(String) }
87
+ def server_title
88
+ ""
89
+ end
90
+
91
+ # The server's instructions, or "".
92
+ sig { returns(String) }
93
+ def instructions
94
+ ""
95
+ end
96
+ end
97
+ end
98
+ end