samagotchi 0.182.0 → 0.183.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 (161) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +68 -1
  3. data/bin/chi +3 -1
  4. data/docs/architecture.md +16 -6
  5. data/docs/bundle-authoring.md +1 -1
  6. data/docs/bundles.md +103 -4
  7. data/docs/cli.md +28 -6
  8. data/docs/configuration.md +2 -1
  9. data/docs/guardrails.md +16 -1
  10. data/docs/internals/block-renderers.md +58 -3
  11. data/docs/internals/bridge.md +13 -5
  12. data/docs/internals/bundles.md +21 -4
  13. data/docs/internals/engine.md +18 -8
  14. data/docs/internals/remote-sessions.md +24 -5
  15. data/docs/internals/web-frontend.md +88 -28
  16. data/docs/internals/working-set.md +1 -1
  17. data/docs/mcp-server.md +80 -0
  18. data/docs/plugins.md +308 -21
  19. data/docs/sessions.md +3 -3
  20. data/docs/sub-agent.md +9 -0
  21. data/docs/testing.md +3 -1
  22. data/docs/thin-clients.md +146 -0
  23. data/lib/samagotchi/bridge/pending_card.rb +4 -3
  24. data/lib/samagotchi/bridge/sse_writer.rb +16 -15
  25. data/lib/samagotchi/bridge.rb +59 -68
  26. data/lib/samagotchi/bundle_command/api_calls.rb +1 -1
  27. data/lib/samagotchi/bundle_command/check.rb +36 -19
  28. data/lib/samagotchi/bundle_command.rb +50 -21
  29. data/lib/samagotchi/bundle_manifest.rb +101 -4
  30. data/lib/samagotchi/bundles/dev/manifest.yml +2 -2
  31. data/lib/samagotchi/bundles/mcp/client.rb +260 -0
  32. data/lib/samagotchi/bundles/mcp/content.rb +107 -0
  33. data/lib/samagotchi/bundles/mcp/http_client.rb +407 -0
  34. data/lib/samagotchi/bundles/mcp/manifest.yml +13 -5
  35. data/lib/samagotchi/bundles/mcp/oauth.rb +814 -0
  36. data/lib/samagotchi/bundles/mcp/plugin.rb +556 -574
  37. data/lib/samagotchi/bundles/mcp/tools.rb +232 -0
  38. data/lib/samagotchi/bundles/system/config_modification_protocol.md +10 -2
  39. data/lib/samagotchi/bundles/system/manifest.yml +2 -2
  40. data/lib/samagotchi/cli/parent_wait.rb +5 -3
  41. data/lib/samagotchi/command_intake.rb +7 -0
  42. data/lib/samagotchi/commands/registry.rb +8 -3
  43. data/lib/samagotchi/continue_offer.rb +24 -15
  44. data/lib/samagotchi/engine/block_fix.rb +4 -4
  45. data/lib/samagotchi/engine/cards.rb +14 -5
  46. data/lib/samagotchi/engine/events.rb +10 -15
  47. data/lib/samagotchi/engine/models.rb +1 -1
  48. data/lib/samagotchi/engine/plugins.rb +3 -0
  49. data/lib/samagotchi/engine/recap.rb +1 -1
  50. data/lib/samagotchi/engine/side_requests.rb +1 -1
  51. data/lib/samagotchi/engine/sign_in.rb +142 -0
  52. data/lib/samagotchi/engine/turn_end.rb +3 -3
  53. data/lib/samagotchi/engine.rb +43 -27
  54. data/lib/samagotchi/engine_snapshots.rb +1 -1
  55. data/lib/samagotchi/guardrail_wiring.rb +3 -1
  56. data/lib/samagotchi/guardrails/protected_paths.rb +51 -2
  57. data/lib/samagotchi/guardrails/verdict.rb +3 -2
  58. data/lib/samagotchi/hold_stop.rb +4 -4
  59. data/lib/samagotchi/idle_recap.rb +19 -11
  60. data/lib/samagotchi/idle_reminders.rb +7 -5
  61. data/lib/samagotchi/idle_scheduler.rb +7 -10
  62. data/lib/samagotchi/installed_bundles/dir.rb +37 -0
  63. data/lib/samagotchi/installed_bundles/manifest.rb +7 -1
  64. data/lib/samagotchi/installed_bundles/plugin_ref.rb +9 -5
  65. data/lib/samagotchi/installed_bundles/record.rb +3 -2
  66. data/lib/samagotchi/installed_bundles/standing.rb +3 -1
  67. data/lib/samagotchi/llm/http.rb +96 -5
  68. data/lib/samagotchi/mcp_command.rb +110 -0
  69. data/lib/samagotchi/mcp_server/http.rb +112 -0
  70. data/lib/samagotchi/mcp_server/protocol.rb +244 -0
  71. data/lib/samagotchi/mcp_server/stdio.rb +92 -0
  72. data/lib/samagotchi/mcp_server/text.rb +155 -0
  73. data/lib/samagotchi/mcp_server/tools.rb +245 -0
  74. data/lib/samagotchi/memory_bundle/asset_installer.rb +40 -12
  75. data/lib/samagotchi/memory_bundle/builder.rb +20 -2
  76. data/lib/samagotchi/memory_bundle/installed_copy.rb +1 -1
  77. data/lib/samagotchi/memory_bundle/installer.rb +16 -3
  78. data/lib/samagotchi/memory_bundle/provenance.rb +18 -1
  79. data/lib/samagotchi/memory_bundle/shas.rb +6 -4
  80. data/lib/samagotchi/memory_bundle/shipped_update.rb +7 -3
  81. data/lib/samagotchi/memory_bundle/status.rb +15 -6
  82. data/lib/samagotchi/memory_bundle/uninstaller.rb +9 -4
  83. data/lib/samagotchi/plugin/api.rb +6 -1
  84. data/lib/samagotchi/plugin/card.rb +36 -11
  85. data/lib/samagotchi/plugin/context.rb +63 -6
  86. data/lib/samagotchi/plugin/http.rb +40 -15
  87. data/lib/samagotchi/plugin/http_errors.rb +15 -0
  88. data/lib/samagotchi/plugin/http_stream.rb +86 -0
  89. data/lib/samagotchi/plugin/http_transport.rb +58 -16
  90. data/lib/samagotchi/plugin/loader.rb +18 -11
  91. data/lib/samagotchi/plugin/secrets.rb +266 -0
  92. data/lib/samagotchi/plugin/sign_in.rb +392 -0
  93. data/lib/samagotchi/plugin/sse_reader.rb +103 -0
  94. data/lib/samagotchi/queued_command.rb +28 -4
  95. data/lib/samagotchi/recap_setup.rb +13 -4
  96. data/lib/samagotchi/ref.rb +3 -2
  97. data/lib/samagotchi/relay_verifier.rb +8 -7
  98. data/lib/samagotchi/relay_watcher.rb +4 -4
  99. data/lib/samagotchi/run_options.rb +2 -1
  100. data/lib/samagotchi/send_command.rb +54 -41
  101. data/lib/samagotchi/session_access/ask.rb +244 -0
  102. data/lib/samagotchi/session_access/contract.rb +5 -0
  103. data/lib/samagotchi/session_access/exchange/token.rb +101 -0
  104. data/lib/samagotchi/session_access/exchange.rb +173 -0
  105. data/lib/samagotchi/session_access/local.rb +25 -6
  106. data/lib/samagotchi/session_access/remote.rb +4 -1
  107. data/lib/samagotchi/session_command_catalog.rb +10 -0
  108. data/lib/samagotchi/session_commands.rb +17 -0
  109. data/lib/samagotchi/session_config.rb +4 -4
  110. data/lib/samagotchi/session_observer.rb +27 -0
  111. data/lib/samagotchi/steer_cut.rb +4 -3
  112. data/lib/samagotchi/terminal_ui/attached_loop/sending.rb +4 -1
  113. data/lib/samagotchi/terminal_ui/formatting.rb +15 -0
  114. data/lib/samagotchi/testing/boundary.rb +4 -0
  115. data/lib/samagotchi/testing/bundle.rb +48 -2
  116. data/lib/samagotchi/testing/fake_http.rb +60 -15
  117. data/lib/samagotchi/testing/host.rb +4 -1
  118. data/lib/samagotchi/testing/recorder.rb +45 -5
  119. data/lib/samagotchi/tools/tool_index.rb +14 -3
  120. data/lib/samagotchi/version.rb +1 -1
  121. data/lib/samagotchi/web/app.rb +8 -6
  122. data/lib/samagotchi/web/ask_routes.rb +292 -0
  123. data/lib/samagotchi/web/mcp_route.rb +88 -0
  124. data/lib/samagotchi/web/public/app.js +2 -3
  125. data/lib/samagotchi/web/public/block_frame.js +72 -11
  126. data/lib/samagotchi/web/public/block_host.js +44 -8
  127. data/lib/samagotchi/web/public/block_regions.js +126 -0
  128. data/lib/samagotchi/web/public/card.js +22 -9
  129. data/lib/samagotchi/web/public/card_actions.js +21 -0
  130. data/lib/samagotchi/web/public/card_kinds.js +1 -1
  131. data/lib/samagotchi/web/public/card_registry.js +3 -2
  132. data/lib/samagotchi/web/public/data.js +15 -12
  133. data/lib/samagotchi/web/public/delete_sheet.js +222 -162
  134. data/lib/samagotchi/web/public/diagram_wiring.js +28 -0
  135. data/lib/samagotchi/web/public/format.js +3 -0
  136. data/lib/samagotchi/web/public/index.html +52 -7
  137. data/lib/samagotchi/web/public/more_sheet.js +6 -4
  138. data/lib/samagotchi/web/public/picture_regions.js +243 -0
  139. data/lib/samagotchi/web/public/picture_viewer.js +113 -12
  140. data/lib/samagotchi/web/public/refs.js +5 -3
  141. data/lib/samagotchi/web/public/region_hit.js +144 -0
  142. data/lib/samagotchi/web/public/removal_sheet_model.js +275 -0
  143. data/lib/samagotchi/web/public/running_tasks.js +6 -4
  144. data/lib/samagotchi/web/public/session_actions.js +105 -100
  145. data/lib/samagotchi/web/session_access_routes.rb +14 -11
  146. data/lib/samagotchi/web/session_control.rb +31 -9
  147. data/lib/samagotchi/web/session_create.rb +2 -2
  148. data/lib/samagotchi/worker/child_side.rb +3 -2
  149. data/lib/samagotchi/worker/command_queue.rb +13 -13
  150. data/lib/samagotchi/worker/leave.rb +3 -3
  151. data/lib/samagotchi/worker/scratch.rb +6 -6
  152. data/lib/samagotchi/worker/signal_grace.rb +6 -5
  153. data/lib/samagotchi/worker/startup.rb +3 -3
  154. data/lib/samagotchi/worker/wake_turns.rb +4 -4
  155. data/lib/samagotchi/worker.rb +32 -21
  156. data/lib/samagotchi/worker_exit_claim.rb +1 -1
  157. data/lib/samagotchi/worker_idle_exit.rb +18 -9
  158. data/lib/samagotchi/worker_inbound.rb +12 -7
  159. data/lib/samagotchi/worker_participant_gate.rb +9 -7
  160. data/lib/samagotchi/worker_task_wakes.rb +7 -5
  161. metadata +31 -1
@@ -1,8 +1,9 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  # The mcp bundle (docs/bundles.md, The mcp bundle): tools from MCP servers.
4
- # Each server in config.yml runs as a child process (stdio only in v1) for
5
- # the session's life. Its tools aren't declared one by one: the bundle
4
+ # Each server in config.yml runs as a child process (stdio) for the
5
+ # session's life, or is a remote one reached over HTTP (url:, HttpClient).
6
+ # Its tools aren't declared one by one: the bundle
6
7
  # publishes them into chi's tool index (chi.tool_source, a group per
7
8
  # server), and the model has the index's two fixed tools, find_tools (a
8
9
  # keyword search that answers each match's inputSchema) and call_tool (calls
@@ -23,6 +24,17 @@
23
24
  # timeout: 120 # optional: this server's per-call timeout
24
25
  # attach_image_paths: true # default: an image path in the text, in the
25
26
  # # temp dir or cwd, attaches it
27
+ # context7:
28
+ # url: https://mcp.context7.com/mcp # a remote server: url instead of command
29
+ # bearer_token_env: CONTEXT7_TOKEN # optional: Authorization: Bearer <its value>
30
+ # headers: {X-Example: "1"} # optional, sent as given (not for secrets)
31
+ # linear:
32
+ # url: https://mcp.linear.app/mcp # no static token: a 401 offers sign-in
33
+ # oauth: {client_id: x, issuer: https://id.example} # optional: a client of yours
34
+ # client_metadata_url: https://…/client.json # default: chi's own client document (CIMD); false: none
35
+ #
36
+ # A remote server with no static token that answers 401 needs sign-in:
37
+ # /mcp login NAME signs in (OAuth, oauth.rb), /mcp logout NAME forgets it.
26
38
  #
27
39
  # Image blocks in a result go to the model as images (the text keeps
28
40
  # "[image 1: image/png]"); so does an image file named in a text block,
@@ -36,16 +48,20 @@
36
48
  # servers and their tools, with an estimate of the tokens their
37
49
  # definitions take (only a search's answer carries them) and of what the
38
50
  # two tools take in every request.
51
+ # Its parts (manifest.yml plugin: parts:, loaded first, in this order):
52
+ # client.rb (Client, the stdio JSON-RPC client), http_client.rb (HttpClient),
53
+ # oauth.rb (sign-in: OAuth::Login, OAuth::Token),
54
+ # tools.rb (the tools/list cache and the tool index) and content.rb (a
55
+ # tools/call answer's text and images).
39
56
  require "digest"
40
57
  require "json"
41
- require "open3"
42
- require "samagotchi/process_group"
43
58
  require "samagotchi/token_usage"
44
59
  require "samagotchi/tools/tool_index"
45
60
  require "samagotchi/tool_declarations"
46
61
  require "time"
47
62
  require "shellwords"
48
63
  require "tmpdir"
64
+ require "uri"
49
65
 
50
66
  class Plugin
51
67
  PROTOCOL_VERSION = "2025-06-18"
@@ -60,240 +76,6 @@ class Plugin
60
76
  # The states whose server's tools call_tool can reach (a cached or exited
61
77
  # server starts on the call).
62
78
  OFFERED = %i[running cached exited].freeze
63
- IMAGE_EXT = { "image/png" => "png", "image/jpeg" => "jpg", "image/gif" => "gif", "image/webp" => "webp" }.freeze
64
-
65
- # A JSON-RPC client for one MCP server over stdio: newline-delimited JSON
66
- # on the process's stdin and stdout; stderr goes to the log.
67
- class Client
68
- # The request failed: an error answer, a timeout, or the server is gone.
69
- class Error < StandardError; end
70
- class Timeout < Error; end
71
- class Cancelled < Error; end
72
- # The server's process ended (or never started).
73
- class Dead < Error; end
74
-
75
- POLL_SECONDS = 0.1
76
- # How long close waits for the server after closing its stdin, after
77
- # TERM, and after KILL.
78
- STOP_GRACE_SECONDS = 1
79
- # The server's watchdog (#start_watchdog), a shell in its process group
80
- # whose stdin is a pipe only chi holds. A line on it (#close) lets it
81
- # go; EOF means chi ended without closing the server (kill -9, a crash
82
- # past Ruby), whose stdin then hit EOF too: a grace for the server to
83
- # leave by itself, then TERM and KILL to the group, the way #close stops
84
- # it. `kill 0` signals the shell's own group: while it runs, that group
85
- # (and so its id) can't be anyone else's.
86
- WATCHDOG = "trap '' TERM; read -r _ && exit 0; sleep #{STOP_GRACE_SECONDS}; " \
87
- "kill -TERM 0; sleep #{STOP_GRACE_SECONDS}; kill -KILL 0".freeze
88
-
89
- attr_reader :pid
90
-
91
- # @param command [Array<String>]
92
- # @param env [Hash] added to the environment
93
- # @param cwd [String]
94
- # @param log [#call] (event, fields) for stderr lines and protocol noise
95
- # @param on_exit [#call, nil] called once, with the reason, when the
96
- # process ends while the client is open
97
- # @param on_notification [#call, nil] (method, params) for each
98
- # notification from the server, on the reader thread: it must not
99
- # wait for an answer there
100
- def initialize(command, env: {}, cwd: Dir.pwd, log: ->(*) {}, on_exit: nil, on_notification: nil)
101
- @log = log
102
- @on_exit = on_exit
103
- @on_notification = on_notification
104
- @mutex = Mutex.new
105
- @write_mutex = Mutex.new
106
- @pending = {}
107
- @next_id = 0
108
- @dead = nil
109
- @closing = false
110
- @stdin, @stdout, @stderr, @wait = Open3.popen3(env.to_h { |k, v| [k.to_s, v&.to_s] }, *command,
111
- chdir: cwd, pgroup: true)
112
- @pid = @wait.pid
113
- start_watchdog
114
- @reader = Thread.new { read_loop }
115
- @err_reader = Thread.new { stderr_loop }
116
- rescue SystemCallError => e
117
- raise Dead, "can't start #{command.first}: #{e.message.sub(/ - .*\z/m, "")}"
118
- end
119
-
120
- # @return [String, nil] why the server is gone, or nil while it runs
121
- def dead = @mutex.synchronize { @dead }
122
-
123
- # Send a request and wait for its answer.
124
- # @param cancelled [#call, nil] polled while waiting; true sends
125
- # notifications/cancelled and raises Cancelled
126
- # @return [Hash] the result
127
- def request(method, params = nil, timeout:, cancelled: nil)
128
- queue = Queue.new
129
- id = @mutex.synchronize do
130
- raise Dead, @dead if @dead
131
-
132
- @next_id += 1
133
- @pending[@next_id] = queue
134
- @next_id
135
- end
136
- write({ jsonrpc: "2.0", id: id, method: method, params: params }.compact)
137
- deadline = monotonic + timeout
138
- loop do
139
- left = deadline - monotonic
140
- if left <= 0
141
- cancel(id, "timed out")
142
- raise Timeout, "#{method} timed out after #{format("%g", timeout)}s"
143
- end
144
- if cancelled&.call
145
- cancel(id, "cancelled by the user")
146
- raise Cancelled, "#{method} was cancelled"
147
- end
148
- message = queue.pop(timeout: [left, POLL_SECONDS].min)
149
- next unless message
150
- raise Dead, message[:dead] if message[:dead]
151
- if (error = message["error"])
152
- raise Error, "#{error["message"] || "error"} (#{error["code"]})"
153
- end
154
-
155
- return message["result"] || {}
156
- end
157
- ensure
158
- @mutex.synchronize { @pending.delete(id) } if id
159
- end
160
-
161
- def notify(method, params = nil)
162
- write({ jsonrpc: "2.0", method: method, params: params }.compact)
163
- end
164
-
165
- # End the process: stdin closed first (most servers leave then), then
166
- # TERM and KILL to its process group (chi's ProcessGroup), a second's
167
- # grace each. Then the watchdog is let go.
168
- def close
169
- @mutex.synchronize { @closing = true }
170
- [@stdin].each { |io| io.close unless io.closed? }
171
- unless @wait.join(STOP_GRACE_SECONDS)
172
- Samagotchi::ProcessGroup.stop(@pid, grace: STOP_GRACE_SECONDS, poll: STOP_GRACE_SECONDS,
173
- stopped: -> { !@wait.alive? }, wait: ->(seconds) { @wait.join(seconds) })
174
- @wait.join(STOP_GRACE_SECONDS)
175
- end
176
- release_watchdog
177
- [@stdout, @stderr].each { |io| io.close unless io.closed? }
178
- [@reader, @err_reader].each { |t| t.join(1) }
179
- nil
180
- rescue IOError
181
- nil
182
- end
183
-
184
- private
185
-
186
- # A server outlives a chi killed without #close when it ignores its
187
- # stdin's EOF (a Node server with another live handle does): the
188
- # watchdog (WATCHDOG) stops its group then. One that can't start (the
189
- # server already left its group) is logged and skipped.
190
- def start_watchdog
191
- reader, @watchdog_pipe = IO.pipe
192
- watchdog = Process.spawn("/bin/sh", "-c", WATCHDOG, in: reader, out: File::NULL, err: File::NULL, pgroup: @pid)
193
- @watchdog = Process.detach(watchdog)
194
- rescue SystemCallError => e
195
- @log.call("watchdog_failed", error: e.class.name)
196
- @watchdog_pipe&.close
197
- @watchdog_pipe = nil
198
- ensure
199
- reader&.close
200
- end
201
-
202
- # A line tells the watchdog chi stopped the server itself.
203
- def release_watchdog
204
- return unless @watchdog_pipe
205
-
206
- begin
207
- @watchdog_pipe.write("\n")
208
- rescue IOError, SystemCallError # gone already: the group's KILL reached it
209
- nil
210
- end
211
- @watchdog_pipe.close unless @watchdog_pipe.closed?
212
- @watchdog&.join(STOP_GRACE_SECONDS)
213
- end
214
-
215
- def write(message)
216
- line = JSON.generate(message)
217
- @write_mutex.synchronize do
218
- @stdin.write(line, "\n")
219
- @stdin.flush
220
- end
221
- rescue IOError, SystemCallError => e
222
- raise Dead, dead || "the server's stdin is closed (#{e.class})"
223
- end
224
-
225
- def cancel(id, reason)
226
- notify("notifications/cancelled", { requestId: id, reason: reason })
227
- rescue Dead
228
- nil
229
- end
230
-
231
- def read_loop
232
- @stdout.each_line do |line|
233
- next if line.strip.empty?
234
-
235
- message = begin
236
- JSON.parse(line)
237
- rescue JSON::ParserError
238
- @log.call("bad_line", line: line[0, 200])
239
- next
240
- end
241
- dispatch(message) if message.is_a?(Hash)
242
- end
243
- rescue IOError
244
- nil
245
- ensure
246
- ended
247
- end
248
-
249
- def dispatch(message)
250
- if message.key?("method")
251
- # A request from the server (ping, roots/list, …): ping is answered,
252
- # the rest aren't supported. A notification is logged and handed on.
253
- unless message.key?("id")
254
- @log.call("server_notification", method: message["method"])
255
- return @on_notification&.call(message["method"], message["params"])
256
- end
257
-
258
- answer = if message["method"] == "ping"
259
- { jsonrpc: "2.0", id: message["id"], result: {} }
260
- else
261
- { jsonrpc: "2.0", id: message["id"], error: { code: -32_601, message: "not supported by chi" } }
262
- end
263
- begin
264
- write(answer)
265
- rescue Dead
266
- nil
267
- end
268
- else
269
- queue = @mutex.synchronize { @pending[message["id"]] }
270
- queue&.push(message)
271
- end
272
- end
273
-
274
- def stderr_loop
275
- @stderr.each_line { |line| @log.call("stderr", line: line.chomp[0, 500]) }
276
- rescue IOError
277
- nil
278
- end
279
-
280
- def ended
281
- status = @wait.value
282
- reason = if status.nil?
283
- "the server exited"
284
- else
285
- "the server exited (#{status.exitstatus ? "status #{status.exitstatus}" : "signal #{status.termsig}"})"
286
- end
287
- waiting, closing = @mutex.synchronize do
288
- @dead ||= reason
289
- [@pending.values, @closing]
290
- end
291
- waiting.each { |queue| queue.push({ dead: reason }) }
292
- @on_exit&.call(reason) unless closing
293
- end
294
-
295
- def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
296
- end
297
79
 
298
80
  # One tool of a server in the index (the tools: filter applied): +name+
299
81
  # is the server's, +chi_name+ mcp_<server>_<tool> (what guardrail rules
@@ -309,13 +91,27 @@ class Plugin
309
91
  # their definitions' estimated size (#definition_tokens).
310
92
  # +client+ is the running process's (a restart replaces it; the
311
93
  # service's stop closes the current one), +restarts+ how many it had.
94
+ # +url+, +headers+ and +token_env+ are a remote server's (nil for stdio),
95
+ # +oauth+ its oauth: map as given (nil without one). +signs_in+: a remote
96
+ # server with no static token (bearer_token_env, an Authorization
97
+ # header), whose 401 offers sign-in; +token+ the token its HttpClient
98
+ # sends (OAuth::Token, else HttpClient::StaticToken); +card_shown+ its
99
+ # "needs sign-in" card was shown in this worker; +refused+ the digest of
100
+ # the kept token it last needed sign-in with (not tried again).
312
101
  Server = Struct.new(:name, :config, :service, :state, :error, :tools, :listed, :timeout, :cwd, :command, :env,
313
- :digest, :cached_at, :relist, :relisting, :client, :restarts, :tokens, :info, keyword_init: true) do
314
- # Its state and tools, never the env (values often a token) or the
315
- # command's args (which may carry a token too): a failing spec or a
316
- # debugger would print those. `command` and `env` are nil before the
317
- # server is resolved.
318
- def inspect = "#<Server #{name} state=#{state} command=#{Array(command).first} env=#{(env || {}).keys.join(",")} tools=#{Array(tools).size}>"
102
+ :digest, :cached_at, :relist, :relisting, :client, :restarts, :tokens, :info, :url, :headers,
103
+ :token_env, :oauth, :signs_in, :token, :card_shown, :refused, keyword_init: true) do
104
+ # Its state and tools, never the env (values often a token), the
105
+ # command's args (which may carry a token too), a URL's path or query
106
+ # or a header's value: a failing spec or a debugger would print those.
107
+ # `command` and `env` are nil before the server is resolved.
108
+ def inspect
109
+ where = url ? "url=#{HttpClient.origin(url)} headers=#{(headers || {}).keys.join(",")}" : "command=#{Array(command).first}"
110
+ "#<Server #{name} state=#{state} #{where} env=#{(env || {}).keys.join(",")} tools=#{Array(tools).size}>"
111
+ end
112
+
113
+ # How a start that failed is said: a remote server didn't connect.
114
+ def failed_word = url ? "didn't connect" : "didn't start"
319
115
 
320
116
  def pretty_print(printer) = printer.text(inspect)
321
117
  end
@@ -332,6 +128,15 @@ class Plugin
332
128
  @left_out = []
333
129
  @left_out_lock = Mutex.new
334
130
  @publish = Mutex.new
131
+ # Sign-ins: each server's waiting /mcp login thread, the "needs sign-in"
132
+ # cards a participant's turn held back, the providers that refused
133
+ # chi's client document (this worker only), and the controller the
134
+ # sign-ins' threads stop on (the plugin's shutdown).
135
+ @sign_ins = {}
136
+ @sign_in_lock = Mutex.new
137
+ @held_cards = []
138
+ @cimd_refused = {}
139
+ @sign_in_cancel = Samagotchi::CancellationController.new
335
140
  end
336
141
 
337
142
  # The servers' names, never @settings (the raw servers config, env values
@@ -367,15 +172,17 @@ class Plugin
367
172
  restarts: 0, tokens: 0)
368
173
  server.timeout = positive(server.config["timeout"]) || @timeout
369
174
  resolve(server, ctx)
175
+ server.token = token_of(server, ctx) if server.url
370
176
  server.service = chi.service(name) { |svc| start(server, svc, ctx) }
371
177
  server
372
178
  end
373
- # Two startup_timeouts: initialize, then tools/list.
374
- wait = @startup_timeout * 2
375
179
  @servers.each do |server|
180
+ # Two startup_timeouts: initialize, then tools/list; four for a remote
181
+ # server (discover, initialize, initialized, tools/list).
182
+ wait = @startup_timeout * (server.url ? 4 : 2)
376
183
  # A failure's card title, short: the card shows "mcp" beside it and
377
184
  # the error in its body.
378
- failed = "#{server.name} didn't start"
185
+ failed = "#{server.name} #{server.failed_word}"
379
186
  if load_cache(server, ctx)
380
187
  index(server, ctx)
381
188
  if server.config["start"].to_s == "eager"
@@ -395,18 +202,302 @@ class Plugin
395
202
  end
396
203
  end
397
204
  publish
398
- chi.command "/mcp", "list the MCP servers, their state and their tools", anytime: true do |_args, command_ctx|
399
- command_ctx.card(title: "MCP servers", body: listing, id: "mcp-servers")
400
- nil
205
+ # The sign-ins' stop seat: chi stops its services as it leaves.
206
+ chi.service("(sign-ins)", eager: true) { |svc| svc.on_stop { stop_sign_ins } }
207
+ chi.on(:after_turn) { |_event, hook_ctx| show_held_cards(hook_ctx) unless hook_ctx.turn_author }
208
+ chi.command "/mcp", "list the MCP servers (login NAME, logout NAME: sign in to or out of a remote one)",
209
+ anytime: true do |args, command_ctx|
210
+ mcp_command(args, command_ctx)
401
211
  end
402
212
  end
403
213
 
214
+ # chi's client metadata document (CIMD: its client_id at a provider that
215
+ # takes one), pages/oauth/client.json in chi's repository as GitHub Pages
216
+ # serves it, at the owner's custom domain (github.io redirects there, and
217
+ # a client_id must equal the fetched address exactly). The default:
218
+ # bundles: mcp: client_metadata_url: sets another (your own), false none
219
+ # (a provider that takes one gets a registration instead).
220
+ CLIENT_METADATA_DOCUMENT = "https://dmitry.it/samagotchi/oauth/client.json"
221
+ CLIENT_METADATA_URL = CLIENT_METADATA_DOCUMENT
222
+
223
+ # /mcp's one line for a word it doesn't know.
224
+ USAGE = "usage: /mcp (lists the servers), /mcp login NAME, /mcp logout NAME"
225
+
404
226
  private
405
227
 
228
+ # /mcp: no word lists the servers (a card); login / logout NAME sign in
229
+ # to or out of a remote server; another word answers USAGE.
230
+ def mcp_command(args, ctx)
231
+ show_held_cards(ctx)
232
+ word, name, extra = args.to_s.split(/\s+/, 3)
233
+ case word
234
+ when nil
235
+ ctx.card(title: "MCP servers", body: listing, id: "mcp-servers")
236
+ nil
237
+ when "login", "logout"
238
+ return "usage: /mcp #{word} NAME" if name.nil? || extra
239
+
240
+ word == "login" ? login(name, ctx) : logout(name, ctx)
241
+ else USAGE
242
+ end
243
+ end
244
+
245
+ # ── Sign-in (the OAuth in oauth.rb; here its wiring) ──────────────────
246
+
247
+ # Why /mcp login|logout can't act on server +name+, nil when it can.
248
+ def sign_in_refusal(name)
249
+ server = @servers.find { |s| s.name == name }
250
+ return "no MCP server #{name}#{" (#{@servers.map(&:name).join(", ")})" unless @servers.empty?}" unless server
251
+ return "#{name} is a local server: sign-in is for remote ones (url:)" unless server.url
252
+ return "#{name} has a static token (bearer_token_env: or an Authorization header): it doesn't sign in" unless server.signs_in
253
+ return "#{name}'s url: has a query: chi can't sign in to it (it would go out with the sign-in)" if URI.parse(server.url).query
254
+
255
+ config_error(server)
256
+ end
257
+
258
+ # /mcp login NAME: answers at once; discovery, the client, the flow and
259
+ # the exchange run on a thread of the plugin's (OAuth::Login), whose
260
+ # result or error replaces the flow's card.
261
+ def login(name, ctx)
262
+ refusal = sign_in_refusal(name)
263
+ return refusal if refusal
264
+ return "sign-in needs the web or a terminal: this run is one-shot" if ctx.frontend == :one_shot
265
+ if @settings.key?("client_metadata_url") && @settings["client_metadata_url"] != false && client_metadata_url.nil?
266
+ return "bundles: mcp: client_metadata_url: must be an https address with a path (chi's client document)"
267
+ end
268
+ return "this chi can't sign in (it has no ctx.sign_in)" unless ctx.respond_to?(:sign_in) && ctx.respond_to?(:secrets)
269
+
270
+ server = @servers.find { |s| s.name == name }
271
+ return "#{name} is signed in already (from another session): connected." if signed_in_elsewhere?(server, ctx)
272
+
273
+ started = @sign_in_lock.synchronize do
274
+ next false if @sign_ins[name]&.alive? || @sign_in_cancel.cancelled?
275
+
276
+ @sign_ins[name] = Thread.new { sign_in(server, ctx) }
277
+ end
278
+ return "a sign-in to #{name} is already waiting: finish it in the browser, or let it time out" unless started
279
+
280
+ "Opening sign-in for #{name}…"
281
+ end
282
+
283
+ # The login's thread: every error ends on a card, never raised into nothing.
284
+ def sign_in(server, ctx)
285
+ login = OAuth::Login.new(ctx: ctx, server: server, secret_lookup: ->(name) { env_value(server, name) },
286
+ client_metadata_url: client_metadata_url, cimd_refused: @cimd_refused, cancel: @sign_in_cancel,
287
+ log: ->(event, **fields) { ctx.log.info("mcp_#{event}", **fields) })
288
+ card_id = login.run
289
+ signed_in(server, card_id, ctx) if card_id
290
+ rescue OAuth::Refusal => e
291
+ ctx.log.warn("mcp_sign_in_failed", server: server.name, error: e.class.name)
292
+ ctx.card(id: e.card_id, title: "Sign-in to #{server.name} failed", body: e.message, level: :warn, between_turns: true)
293
+ rescue StandardError => e
294
+ ctx.log.warn("mcp_sign_in_failed", server: server.name, error: e.class.name)
295
+ ctx.card(title: "Sign-in to #{server.name} failed", body: "chi's sign-in broke (#{e.class.name}); the debug log has it",
296
+ level: :warn, between_turns: true)
297
+ end
298
+
299
+ # Kept: the server connects as a lazy start does (handshake, tools/list,
300
+ # the cache), with spawn directly when its service already runs (a 401
301
+ # met during a call, a sign-out), then the flow's card says so.
302
+ def signed_in(server, card_id, ctx)
303
+ server.token.forget
304
+ begin
305
+ reconnect(server, ctx)
306
+ count = offered(server).size
307
+ ctx.card(id: card_id, title: "Signed in to #{server.name}", body: "#{count} tool#{"s" unless count == 1}, ready to use.",
308
+ between_turns: true)
309
+ rescue StandardError => e
310
+ if needs_sign_in?(server, e)
311
+ signed_out(server, ctx, e)
312
+ return
313
+ end
314
+
315
+ ctx.log.warn("mcp_server_failed", server: server.name, error: e.class.name, msg: e.message, signed_in: true)
316
+ ctx.card(id: card_id, title: "Signed in, but #{server.name} didn't connect", body: e.message, level: :warn,
317
+ between_turns: true)
318
+ end
319
+ end
320
+
321
+ # Connect a server that has a sign-in now (spawn when its service
322
+ # already runs, else its first start), then it runs; its "needs sign-in"
323
+ # card loses its button (a later refusal shows it again).
324
+ def reconnect(server, ctx)
325
+ @restart.synchronize do
326
+ if server.service.state == :running
327
+ old = server.client
328
+ spawn(server, ctx, cancelled: @sign_in_cancel)
329
+ old.close unless old.equal?(server.client)
330
+ else
331
+ server.service.value
332
+ end
333
+ @sign_in_lock.synchronize do
334
+ server.state = :running
335
+ server.error = nil
336
+ end
337
+ end
338
+ publish
339
+ return unless @sign_in_lock.synchronize { server.card_shown.tap { server.card_shown = false } }
340
+
341
+ ctx.card(id: "mcp-sign-in-#{server.name}", title: "#{server.name} needs sign-in", body: "Signed in since.", between_turns: true)
342
+ end
343
+
344
+ # A server that needs sign-in, signed in to meanwhile from another
345
+ # session (the kept token, read again): connected now. False when there
346
+ # is no kept token, or it doesn't connect.
347
+ def signed_in_elsewhere?(server, ctx)
348
+ return false unless server.state == :needs_sign_in && server.token.respond_to?(:kept)
349
+
350
+ server.token.forget
351
+ kept = kept_digest(server)
352
+ return false if kept.nil? || kept == server.refused
353
+
354
+ reconnect(server, ctx)
355
+ ctx.log.info("mcp_signed_in_elsewhere", server: server.name)
356
+ true
357
+ rescue StandardError => e
358
+ server.refused = kept_digest(server) # what it holds after a renew, too: not tried again
359
+ ctx.log.warn("mcp_server_failed", server: server.name, error: e.class.name, msg: e.message, signed_in_elsewhere: true)
360
+ false
361
+ end
362
+
363
+ # 16 hex of the SHA-256 of the kept access token, nil without one.
364
+ def kept_digest(server)
365
+ kept = server.token.respond_to?(:kept) && server.token.kept
366
+ kept ? Digest::SHA256.hexdigest(kept["access_token"])[0, 16] : nil
367
+ rescue StandardError
368
+ nil
369
+ end
370
+
371
+ # Whether the kept sign-in is newer than the token +error+ refused (or,
372
+ # none sent, whether there is one now): another session or a login
373
+ # signed in after the request went out.
374
+ def newer_sign_in?(server, error)
375
+ kept = server.token.respond_to?(:kept) && server.token.kept
376
+ return false unless kept
377
+
378
+ error.sent_digest.nil? || Digest::SHA256.hexdigest(kept["access_token"])[0, 16] != error.sent_digest
379
+ rescue StandardError
380
+ false
381
+ end
382
+
383
+ # /mcp logout NAME: the kept token goes (the provider's revocation asked,
384
+ # best effort), the client closes, the server needs sign-in. chi's
385
+ # registration with the provider stays.
386
+ def logout(name, ctx)
387
+ refusal = sign_in_refusal(name)
388
+ return refusal if refusal
389
+
390
+ server = @servers.find { |s| s.name == name }
391
+ kept = server.token.kept
392
+ ctx.secrets.delete(server.token.name)
393
+ server.token.forget
394
+ OAuth.revoke(ctx.http, kept, log: ->(event, **fields) { ctx.log.info("mcp_#{event}", server: name, **fields) }) if kept
395
+ server.client&.close
396
+ server.state = :needs_sign_in
397
+ publish
398
+ "Signed out of #{name}."
399
+ rescue Samagotchi::Plugin::Secrets::Unavailable, Samagotchi::Plugin::Secrets::Busy => e
400
+ "#{name}'s sign-in wasn't forgotten: #{e.message}"
401
+ end
402
+
403
+ # Whether +error+ means the server wants a sign-in: a 401 from one that signs in.
404
+ def needs_sign_in?(server, error) = server.signs_in && error.is_a?(HttpClient::Refused) && error.status == 401
405
+
406
+ # The server needs sign-in: its state (said once), its card, and the
407
+ # line its call answers.
408
+ # Nil when +error+ (the 401) was for an older token than the kept one: the
409
+ # state stays, the next request sends the new token.
410
+ def signed_out(server, ctx, error = nil)
411
+ if error && newer_sign_in?(server, error)
412
+ server.token.forget
413
+ return nil
414
+ end
415
+
416
+ first = @sign_in_lock.synchronize { server.state == :needs_sign_in ? false : (server.state = :needs_sign_in) }
417
+ if first
418
+ server.refused = kept_digest(server)
419
+ server.error = nil
420
+ publish
421
+ ctx.log.info("mcp_needs_sign_in", server: server.name)
422
+ end
423
+ offer_sign_in(server, ctx)
424
+ "Error: #{sign_in_line(server, ctx.turn_author)}"
425
+ end
426
+
427
+ # What a call of a server that needs sign-in answers: the owner's
428
+ # command, or (a participant's turn) who signs in, no command.
429
+ def sign_in_line(server, author = nil)
430
+ return "#{server.name} needs sign-in: the session's owner signs in" if author
431
+
432
+ "#{server.name} needs sign-in: the user runs /mcp login #{server.name}"
433
+ end
434
+
435
+ # The "needs sign-in" card, once per server per worker, never a turn's;
436
+ # none on a one-shot; on a participant's turn held for the owner's next
437
+ # turn end or command.
438
+ def offer_sign_in(server, ctx)
439
+ return if ctx.frontend == :one_shot
440
+
441
+ if ctx.turn_author
442
+ @sign_in_lock.synchronize { @held_cards << server.name unless @held_cards.include?(server.name) }
443
+ return
444
+ end
445
+ first = @sign_in_lock.synchronize { server.card_shown ? false : (server.card_shown = true) }
446
+ return unless first
447
+
448
+ ctx.card(id: "mcp-sign-in-#{server.name}", title: "#{server.name} needs sign-in",
449
+ body: "The server asks chi to sign in. Sign in opens its provider's page in your browser.",
450
+ actions: [{ label: "Sign in", command: "/mcp login #{server.name}" }], between_turns: true)
451
+ end
452
+
453
+ def show_held_cards(ctx)
454
+ names = @sign_in_lock.synchronize { @held_cards.slice!(0..) }
455
+ names.each do |name|
456
+ server = @servers.find { |s| s.name == name }
457
+ offer_sign_in(server, ctx) if server&.state == :needs_sign_in
458
+ end
459
+ end
460
+
461
+ # chi's client document's address (bundles: mcp: client_metadata_url:,
462
+ # else CLIENT_METADATA_URL): an https address with a path, else nil
463
+ # (false: none, never a CIMD client_id).
464
+ def client_metadata_url
465
+ value = @settings.fetch("client_metadata_url", CLIENT_METADATA_URL)
466
+ return nil if value == false
467
+
468
+ uri = URI.parse(value.to_s)
469
+ uri.is_a?(URI::HTTPS) && !uri.host.to_s.empty? && uri.path.to_s.length > 1 && uri.userinfo.nil? ? value.to_s : nil
470
+ rescue URI::Error
471
+ nil
472
+ end
473
+
474
+ # The service's stop: the waiting sign-ins end (core stops their flows
475
+ # too), their threads get a moment to put their cards right.
476
+ def stop_sign_ins
477
+ @sign_in_cancel.cancel!
478
+ threads = @sign_in_lock.synchronize { @sign_ins.values }
479
+ threads.each { |thread| thread.join(2) }
480
+ end
481
+
482
+ # A remote server's token object: OAuth::Token for one that signs in
483
+ # (with this chi's ctx.secrets), else the static one.
484
+ def token_of(server, ctx)
485
+ return token_lookup(server) unless server.signs_in && ctx.respond_to?(:secrets)
486
+
487
+ oauth = server.oauth.is_a?(Hash) ? server.oauth : {}
488
+ variable = oauth["client_secret_env"]
489
+ client = oauth["client_id"] ? { id: oauth["client_id"], issuer: oauth["issuer"] } : nil
490
+ OAuth::Token.new(secrets: ctx.secrets, resource: URI.parse(server.url).query ? nil : OAuth.canonical(server.url),
491
+ http: ctx.http, client: client, client_secret: -> { variable && env_value(server, variable) },
492
+ log: ->(event, **fields) { ctx.log.info("mcp_#{event}", server: server.name, **fields) })
493
+ end
494
+
406
495
  # The command, env and cwd the server runs with, and their digest (the
407
496
  # cache's key: command, args, env names and values, and the cwd; the
408
497
  # env itself is never stored).
409
498
  def resolve(server, ctx)
499
+ return resolve_url(server) if server.config.key?("url")
500
+
410
501
  command = server.config["command"]
411
502
  command = Shellwords.split(command) if command.is_a?(String)
412
503
  server.command = Array(command).map(&:to_s)
@@ -416,10 +507,162 @@ class Plugin
416
507
  server.digest = Digest::SHA256.hexdigest(JSON.generate([server.command, server.env.sort, server.cwd]))
417
508
  end
418
509
 
510
+ # A remote server's url, headers, token variable and oauth: map, and
511
+ # their digest (never the token's value: a rotated token isn't a changed
512
+ # config). The oauth: map joins the digest only when it is set: a server
513
+ # without one keeps the digest it had before sign-in came (its cache).
514
+ def resolve_url(server)
515
+ server.command = []
516
+ server.env = server.config["env"].is_a?(Hash) ? server.config["env"].to_h { |k, v| [k.to_s, v.to_s] } : {}
517
+ server.url = server.config["url"].to_s
518
+ server.headers = server.config["headers"].is_a?(Hash) ? server.config["headers"] : {}
519
+ server.token_env = server.config["bearer_token_env"]&.to_s
520
+ server.oauth = server.config["oauth"] if server.config.key?("oauth")
521
+ server.signs_in = server.token_env.nil? && server.headers.keys.none? { |name| name.to_s.casecmp?("authorization") }
522
+ digested = [server.url, server.headers.map { |k, v| [k.to_s, v.to_s] }.sort, server.token_env]
523
+ digested << (server.oauth.is_a?(Hash) ? server.oauth.map { |k, v| [k.to_s, v] }.sort_by(&:first) : server.oauth) if server.config.key?("oauth")
524
+ server.digest = Digest::SHA256.hexdigest(JSON.generate(digested))
525
+ end
526
+
527
+ # The headers chi sets itself on a remote server's requests.
528
+ # The wire's own (host, content-length…) too: one set in config.yml would break every request.
529
+ OWN_HEADERS = %w[accept content-type mcp-protocol-version mcp-method mcp-name mcp-session-id
530
+ host content-length connection transfer-encoding].freeze
531
+
532
+ # Why the server's config can't start it, nil when it can.
533
+ def config_error(server)
534
+ where = "bundles: mcp: servers: #{server.name}"
535
+ if server.url && server.config.key?("command")
536
+ return "set command: (a local server) or url: (a remote one), not both (#{where})"
537
+ end
538
+ return url_error(server, where) if server.url
539
+
540
+ "no command (#{where}: command: [...] or url: ...)" if server.command.empty?
541
+ end
542
+
543
+ def url_error(server, where)
544
+ uri = begin
545
+ URI.parse(server.url)
546
+ rescue URI::Error
547
+ nil
548
+ end
549
+ return "url: must be an http(s) URL (#{where})" unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
550
+ return "bearer_token_env: must name an environment variable (#{where})" if server.token_env&.strip&.empty?
551
+ return "headers: must be a map of names to values (#{where})" unless server.config["headers"].nil? || server.config["headers"].is_a?(Hash)
552
+
553
+ server.headers.each do |name, value|
554
+ unless name.is_a?(String) && value.is_a?(String) && name.match?(/\A[!#$%&'*+\-.^_`|~0-9A-Za-z]+\z/) &&
555
+ !value.match?(/[\r\n\0]/)
556
+ return "headers: #{name.to_s[0, 40].inspect} must be a name and a one-line text value (#{where})"
557
+ end
558
+ if OWN_HEADERS.include?(name.downcase) || (server.token_env && name.casecmp?("authorization"))
559
+ return "headers: #{name} is chi's to set (#{where})"
560
+ end
561
+ end
562
+ oauth_error(server, where) if server.config.key?("oauth")
563
+ end
564
+
565
+ # The oauth: map's keys (all optional).
566
+ OAUTH_KEYS = %w[client_id issuer client_secret_env scopes redirect_port].freeze
567
+
568
+ # Why a remote server's oauth: map can't be used, nil when it can: a
569
+ # client registered by hand is bound to its provider (issuer:), and a
570
+ # server signs in or has a static token, never both.
571
+ def oauth_error(server, where)
572
+ oauth = server.oauth
573
+ return "oauth: must be a map (#{where})" unless oauth.is_a?(Hash)
574
+ return "oauth: and bearer_token_env: are one or the other (#{where})" if server.token_env
575
+ if server.headers.keys.any? { |name| name.to_s.casecmp?("authorization") }
576
+ return "oauth: and an Authorization header are one or the other (#{where})"
577
+ end
578
+
579
+ unknown = oauth.keys.map(&:to_s) - OAUTH_KEYS
580
+ return "oauth: #{unknown.first[0, 40]} isn't one of #{OAUTH_KEYS.join(", ")} (#{where})" unless unknown.empty?
581
+
582
+ id = oauth["client_id"]
583
+ return "oauth: client_id: must be a text (#{where})" if oauth.key?("client_id") && !(id.is_a?(String) && !id.strip.empty?)
584
+ return "oauth: issuer: is required with client_id: (#{where})" if id && !oauth.key?("issuer")
585
+ return "oauth: issuer: goes with client_id: (#{where})" if oauth.key?("issuer") && !id
586
+ return "oauth: issuer: must be an https address (#{where})" if id && !issuer_address?(oauth["issuer"])
587
+
588
+ secret_env = oauth["client_secret_env"]
589
+ if oauth.key?("client_secret_env")
590
+ return "oauth: client_secret_env: must name an environment variable (#{where})" unless secret_env.is_a?(String) && !secret_env.strip.empty?
591
+ return "oauth: client_secret_env: goes with client_id: (#{where})" unless id
592
+ end
593
+ scopes = oauth["scopes"]
594
+ if oauth.key?("scopes") && !(scopes.is_a?(Array) && scopes.all? { |scope| scope.is_a?(String) && scope.match?(/\A[!#-\[\]-~]+\z/) })
595
+ return "oauth: scopes: must be a list of scope names (#{where})"
596
+ end
597
+
598
+ port = oauth["redirect_port"]
599
+ "oauth: redirect_port: must be a port, 1024 to 65535 (#{where})" if oauth.key?("redirect_port") && !(port.is_a?(Integer) && port.between?(1024, 65_535))
600
+ end
601
+
602
+ # An https address with a host (http only on a loopback host: local
603
+ # development), no query or fragment: what an issuer is.
604
+ def issuer_address?(value)
605
+ uri = URI.parse(value.to_s)
606
+ return false unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty? && uri.query.nil? && uri.fragment.nil? && uri.userinfo.nil?
607
+
608
+ uri.scheme == "https" || loopback_host?(uri.host)
609
+ rescue URI::Error
610
+ false
611
+ end
612
+
613
+ def loopback_host?(host) = %w[127.0.0.1 ::1 [::1] localhost].include?(host.to_s.downcase)
614
+
615
+ # A remote server's bearer token (HttpClient's token:), looked up at each
616
+ # request (never kept): the env a stdio server would get (its env:, then
617
+ # the project env: #server_env), then the worker's.
618
+ # @return [HttpClient::StaticToken]
619
+ def token_lookup(server)
620
+ return HttpClient::StaticToken.new { nil } unless server.token_env
621
+
622
+ HttpClient::StaticToken.new do
623
+ value = env_value(server, server.token_env).to_s
624
+ raise HttpClient::Refused, "#{server.token_env} is not set" if value.empty?
625
+ # An env file saved with CRLF line ends; a header can't carry it.
626
+ raise HttpClient::Refused, "#{server.token_env} holds a line break: set it on one line" if value.match?(/[\r\n\0]/)
627
+
628
+ value
629
+ end
630
+ end
631
+
632
+ # +variable+'s value for the server: its env:, the project env, then the
633
+ # worker's; nil when unset or empty.
634
+ def env_value(server, variable)
635
+ value = server_env(server)[variable].to_s
636
+ value = ENV[variable].to_s if value.empty?
637
+ value.empty? ? nil : value
638
+ end
639
+
640
+ # A client's cancelled:, read on the thread that does the work (an init
641
+ # task's own Stop, else the turn's; a thread of the client's own would
642
+ # read the turn's): a remote server's ctx.http cancel:, a poll for stdio.
643
+ def stop_of(server, ctx) = server.url ? ctx.cancel_controller : -> { ctx.cancelled? }
644
+
645
+ # The log fields that say which client: its pid, or a remote one's origin.
646
+ def where(client) = client.is_a?(HttpClient) ? { where: client.label } : { pid: client.pid }
647
+
648
+ # The one place a server's client is built (spawn's and refresh's); it
649
+ # is the caller's, never assigned here.
650
+ def connect(server, ctx, **callbacks)
651
+ if server.url
652
+ return HttpClient.new(server.url, headers: server.headers, token: server.token || token_lookup(server), http: ctx.http,
653
+ log: ->(event, **fields) { ctx.log.debug("mcp_#{event}", server: server.name, **fields) })
654
+ end
655
+
656
+ Client.new(server.command, env: server_env(server), cwd: server.cwd,
657
+ log: ->(event, **fields) { ctx.log.debug("mcp_#{event}", server: server.name, **fields) },
658
+ **callbacks)
659
+ end
660
+
419
661
  # The service's start: spawn (#spawn). Its stop closes the server's
420
662
  # current process, a restarted one too.
421
663
  def start(server, svc, ctx)
422
- raise Client::Error, "no command (bundles: mcp: servers: #{server.name}: command: [...])" if server.command.empty?
664
+ error = config_error(server)
665
+ raise Client::Error, error if error
423
666
 
424
667
  svc.on_stop { server.client&.close }
425
668
  spawn(server, ctx)
@@ -430,20 +673,13 @@ class Plugin
430
673
  # it), then cache the list and its info when either changed, and index
431
674
  # the tools.
432
675
  # @return [Client]
433
- def spawn(server, ctx)
434
- cancelled = -> { ctx.cancelled? }
435
- client = server.client = Client.new(
436
- server.command, env: server_env(server), cwd: server.cwd,
437
- log: ->(event, **fields) { ctx.log.debug("mcp_#{event}", server: server.name, **fields) },
438
- on_exit: ->(reason) { exited(server, reason, ctx) },
439
- on_notification: lambda { |method, _params|
440
- tools_changed(server, ctx) if method == "notifications/tools/list_changed"
441
- }
442
- )
443
- initialized = client.request("initialize", { protocolVersion: PROTOCOL_VERSION, capabilities: {},
444
- clientInfo: { name: "chi", version: Samagotchi::VERSION } },
445
- timeout: @startup_timeout, cancelled: cancelled)
446
- client.notify("notifications/initialized")
676
+ def spawn(server, ctx, cancelled: stop_of(server, ctx))
677
+ client = server.client = connect(server, ctx,
678
+ on_exit: ->(reason) { exited(server, reason, ctx) },
679
+ on_notification: lambda { |method, _params|
680
+ tools_changed(server, ctx) if method == "notifications/tools/list_changed"
681
+ })
682
+ initialized = client.handshake(timeout: @startup_timeout, cancelled: cancelled)
447
683
  listed = list_tools(client, cancelled)
448
684
  info = info_of(initialized)
449
685
  changed = listed != server.listed || info != server.info
@@ -480,20 +716,32 @@ class Plugin
480
716
  # the index (or come for the first time: #spawn indexes them).
481
717
  # @return [String] the task's summary
482
718
  # @raise [Client::Error] it didn't start (the task's warn card says why;
483
- # the index keeps its tools, marked failed)
719
+ # the index keeps its tools, marked failed; a remote server's from the
720
+ # cache stay cached, as #not_connected leaves them)
484
721
  def boot(server, ctx)
722
+ cached = server.state == :cached
485
723
  client = server.service.value
486
724
  server.state = :running
487
725
  publish
488
- ctx.log.info("mcp_server_started", server: server.name, pid: client.pid, tools: server.listed.size)
726
+ ctx.log.info("mcp_server_started", server: server.name, **where(client), tools: server.listed.size)
489
727
  count = server.listed.size
490
728
  "#{server.name} ready, #{count} tool#{"s" unless count == 1}"
491
729
  rescue StandardError => e
730
+ if needs_sign_in?(server, e)
731
+ return "#{server.name} was signed in to meanwhile: its next call connects" unless signed_out(server, ctx, e)
732
+
733
+ return "#{server.name} needs sign-in (/mcp login #{server.name})"
734
+ end
735
+ if cached && server.url
736
+ ctx.log.warn("mcp_server_failed", server: server.name, error: e.class.name, msg: e.message)
737
+ server.error = e.message # its first call failing the same way says nothing new
738
+ raise Client::Error, "MCP server #{server.name} didn't connect: #{e.message}; its next call tries again"
739
+ end
492
740
  server.state = :failed
493
741
  server.error = e.message
494
742
  publish
495
743
  ctx.log.warn("mcp_server_failed", server: server.name, error: e.class.name, msg: e.message)
496
- raise Client::Error, "MCP server #{server.name} didn't start: #{e.message}; its calls fail until chi restarts"
744
+ raise Client::Error, "MCP server #{server.name} #{server.failed_word}: #{e.message}; its calls fail until chi restarts"
497
745
  end
498
746
 
499
747
  # The quiet daily refresh of a cached server's list: a server of its own
@@ -505,14 +753,10 @@ class Plugin
505
753
  File.open("#{cache_path(server, ctx)}.lock", File::CREAT | File::RDWR) do |lock|
506
754
  return nil unless lock.flock(File::LOCK_EX | File::LOCK_NB)
507
755
 
508
- cancelled = -> { ctx.cancelled? }
509
- client = Client.new(server.command, env: server_env(server), cwd: server.cwd,
510
- log: ->(event, **fields) { ctx.log.debug("mcp_#{event}", server: server.name, **fields) })
756
+ cancelled = stop_of(server, ctx)
757
+ client = connect(server, ctx)
511
758
  begin
512
- initialized = client.request("initialize", { protocolVersion: PROTOCOL_VERSION, capabilities: {},
513
- clientInfo: { name: "chi", version: Samagotchi::VERSION } },
514
- timeout: @startup_timeout, cancelled: cancelled)
515
- client.notify("notifications/initialized")
759
+ initialized = client.handshake(timeout: @startup_timeout, cancelled: cancelled)
516
760
  listed = list_tools(client, cancelled)
517
761
  ensure
518
762
  client.close
@@ -528,6 +772,11 @@ class Plugin
528
772
  index(server, ctx) if changed
529
773
  end
530
774
  nil
775
+ rescue HttpClient::Refused => e
776
+ raise unless needs_sign_in?(server, e)
777
+
778
+ signed_out(server, ctx, e) if server.state == :cached
779
+ nil
531
780
  end
532
781
 
533
782
  # notifications/tools/list_changed from a running server: list its tools
@@ -584,162 +833,6 @@ class Plugin
584
833
  tools
585
834
  end
586
835
 
587
- # ── The tools/list cache ──────────────────────────────────────────────
588
-
589
- # Where the server's cache is: tools-<server>.json, the name sanitized.
590
- def cache_path(server, ctx)
591
- File.join(ctx.data_dir, "tools-#{server.name.gsub(/[^A-Za-z0-9_.-]+/, "_")}.json")
592
- end
593
-
594
- # Take the server's tools from its cache: true when it holds this
595
- # config's list (the server is then :cached, not started).
596
- def load_cache(server, ctx)
597
- data = JSON.parse(File.read(cache_path(server, ctx)))
598
- return false unless data.is_a?(Hash) && data["digest"] == server.digest && data["tools"].is_a?(Array)
599
-
600
- server.listed = data["tools"].select { |tool| tool.is_a?(Hash) && tool["name"] }
601
- server.info = data["info"].is_a?(String) ? data["info"] : nil
602
- server.cached_at = begin
603
- Time.iso8601(data["saved_at"].to_s)
604
- rescue ArgumentError
605
- nil
606
- end
607
- server.state = :cached
608
- true
609
- rescue SystemCallError, JSON::ParserError
610
- false
611
- end
612
-
613
- # Written aside and renamed: workers share the dir.
614
- def save_cache(server, ctx)
615
- Samagotchi::AtomicFile.write(cache_path(server, ctx),
616
- JSON.generate({ digest: server.digest, saved_at: Time.now.utc.iso8601, info: server.info,
617
- tools: server.listed }.compact))
618
- rescue SystemCallError => e
619
- ctx.log.warn("mcp_cache_not_written", server: server.name, msg: e.message)
620
- end
621
-
622
- # ── Tools ─────────────────────────────────────────────────────────────
623
-
624
- # Index the server's tools, the tools: filter applied: each named, its
625
- # schema checked (a bad one is kept, marked, and said once). The whole
626
- # list is built, then swapped in: a search on another thread never sees
627
- # half a list. Their estimated tokens go to the log when they changed.
628
- def index(server, ctx)
629
- wanted = server.config["tools"] && Array(server.config["tools"]).map(&:to_s)
630
- listed = server.listed || []
631
- listed = listed.select { |tool| wanted.any? { |w| File.fnmatch(w, tool["name"], File::FNM_EXTGLOB) } } if wanted
632
- tokens = 0
633
- tools = listed.map do |listed_tool|
634
- tool = McpTool.new(server: server.name, name: listed_tool["name"].to_s,
635
- chi_name: tool_name(server.name, listed_tool["name"]), description: description(listed_tool),
636
- schema: listed_tool["inputSchema"] || { "type" => "object", "properties" => {} }, error: nil)
637
- tokens += definition_tokens(tool.chi_name, tool.description, tool.schema)
638
- tool
639
- rescue StandardError => e # a schema chat_schemas can't read raises more than ArgumentError
640
- error = e.message.sub(/\Atool \S+: /, "")
641
- left_out("MCP tool #{server.name}/#{tool.name} can't be called: #{error}", ctx)
642
- tool.with(error: error)
643
- end
644
- server.tools = tools.freeze
645
- say_clashes(ctx)
646
- publish
647
- return if tokens == server.tokens
648
-
649
- server.tokens = tokens
650
- ctx.log.info("mcp_tools_estimated", server: server.name, tools: offered(server).size, tokens: tokens)
651
- end
652
-
653
- # Said once (a notice and the log), not at each index.
654
- def left_out(text, ctx)
655
- first = @left_out_lock.synchronize { @left_out.include?(text) ? false : (@left_out << text) }
656
- return unless first
657
-
658
- ctx.log.warn("mcp_tool_left_out", msg: text)
659
- ctx.notify(text, level: :warn)
660
- end
661
-
662
- # Tools of every server whose mcp_<server>_<tool> another tool has too
663
- # (two servers, git-hub and git_hub; names alike up to NAME_CHARS):
664
- # guardrail rules and approvals key on that name, so neither is called.
665
- # Said once per clash; checked after each server's index, so whichever
666
- # server comes second says it.
667
- def say_clashes(ctx)
668
- @servers.flat_map(&:tools).group_by(&:chi_name).each do |chi_name, same|
669
- next if same.size < 2
670
-
671
- left_out("MCP tools #{same.map { |t| "#{t.server}/#{t.name}" }.join(" and ")} can't be called: " \
672
- "both are #{chi_name} to guardrail rules", ctx)
673
- end
674
- end
675
-
676
- # The other indexed tools with +tool+'s mcp_<server>_<tool>.
677
- def clashes(tool)
678
- @servers.flat_map(&:tools).select { |t| t.chi_name == tool.chi_name && [t.server, t.name] != [tool.server, tool.name] }
679
- end
680
-
681
- # Why call_tool refuses +tool+, nil when it can call it.
682
- def refusal(tool)
683
- return tool.error if tool.error
684
-
685
- others = clashes(tool)
686
- "name clash with #{others.map { |t| "#{t.server}/#{t.name}" }.join(", ")} (#{tool.chi_name})" unless others.empty?
687
- end
688
-
689
- # The server's tools call_tool can call (no bad schema, no name clash).
690
- def offered(server) = server.tools.reject { |tool| refusal(tool) }
691
-
692
- # The marks a search and /mcp give a tool call_tool refuses.
693
- def mark(tool)
694
- return "(bad schema)" if tool.error
695
-
696
- others = clashes(tool)
697
- "(name clash with #{others.map { |t| "#{t.server}/#{t.name}" }.join(", ")})" unless others.empty?
698
- end
699
-
700
- # A tool's definition as the chat path sends it (LLM::ChatLoop#tool_definitions:
701
- # the chat schema, wrapped as a function), in estimated tokens
702
- # (TokenUsage::CHARS_PER_TOKEN). The native prompts (Gemma, Qwen) render a
703
- # flatter schema, so it is an upper bound there.
704
- # @raise [ArgumentError] a bad schema
705
- def definition_tokens(name, description, schema)
706
- Samagotchi::Tools::ToolIndex.spec_tokens(Samagotchi::Plugin::Api.tool_spec(name, description, schema: schema) { nil })
707
- end
708
-
709
- # Every server's tools into chi's index, a group each: its state (what a
710
- # search's notes say), its summary line, and its tools with the marks
711
- # and refusals of now (a clash with another server's tool too, so all of
712
- # them each time). After each index and each state change a note reads;
713
- # one at a time, so the last one published is the newest.
714
- def publish
715
- return unless @source
716
-
717
- @publish.synchronize do
718
- groups = @servers.map do |server|
719
- state = { starting: :starting, failed: :failed }.fetch(server.state, :ready)
720
- tools = Array(server.tools).map do |tool|
721
- Samagotchi::Tools::ToolIndex::Tool.new(group: tool.server, name: tool.name, description: tool.description,
722
- schema: tool.schema, acts_as: tool.chi_name, refusal: refusal(tool),
723
- mark: mark(tool))
724
- end
725
- Samagotchi::Tools::ToolIndex::Group.new(name: server.name, summary: server_summary(server), state: state,
726
- error: state == :failed ? server.error : nil, tools: tools)
727
- end
728
- @source.publish(groups)
729
- end
730
- end
731
-
732
- # The server's line in find_tools: its description: from config, else the first
733
- # sentence of its instructions, else nothing (its line has the tool
734
- # count). Never its tool names: a model that knows them calls them
735
- # blind, without a search (a smoke run's Splash did).
736
- def server_summary(server)
737
- given = server.config["description"].to_s.strip
738
- return given unless given.empty?
739
-
740
- server.info
741
- end
742
-
743
836
  # ── Calls ─────────────────────────────────────────────────────────────
744
837
 
745
838
  # A call the index looked up and checked (call_tool): +tool+ a
@@ -754,6 +847,8 @@ class Plugin
754
847
  # Wait for a first-run server's start (its init task's); a failure is
755
848
  # its init card's.
756
849
  def wait_started(server)
850
+ return signed_in_elsewhere?(server, @ctx) if server&.state == :needs_sign_in
851
+
757
852
  server&.service&.value
758
853
  rescue StandardError
759
854
  nil
@@ -774,7 +869,8 @@ class Plugin
774
869
  # server starts here, on its first call. The server's isError and a
775
870
  # JSON-RPC error answer the tool's inputSchema too (ToolIndex.schema_note).
776
871
  def call(server, tool, args, ctx)
777
- return "Error: MCP server #{server.name} didn't start: #{server.error}" if server.state == :failed
872
+ return "Error: MCP server #{server.name} #{server.failed_word}: #{server.error}" if server.state == :failed
873
+ return signed_out(server, ctx) if server.state == :needs_sign_in && !signed_in_elsewhere?(server, ctx)
778
874
 
779
875
  client = case server.state
780
876
  when :cached then lazy_start(server, ctx)
@@ -786,14 +882,21 @@ class Plugin
786
882
  return client if client.is_a?(String)
787
883
 
788
884
  result = client.request("tools/call", { name: tool.name, arguments: args }, timeout: server.timeout,
789
- cancelled: -> { ctx.cancelled? })
885
+ cancelled: stop_of(server, ctx))
790
886
  text, images = content(result, server, tool.name)
791
887
  return "Error: #{text.empty? ? "the tool failed" : text}#{Samagotchi::Tools::ToolIndex.schema_note(tool)}" if result["isError"]
792
888
 
793
889
  images.empty? ? text : Samagotchi::Plugin::ToolResult.new(text, images: images)
794
890
  rescue Client::Dead => e
795
- "Error: MCP server #{server.name} is not running (#{e.message})"
796
- rescue Client::Timeout, Client::Cancelled, Samagotchi::Plugin::Service::Stopped => e
891
+ "Error: MCP server #{server.name} is #{server.url ? "not reachable" : "not running"} (#{e.message})"
892
+ rescue HttpClient::Refused => e
893
+ return "Error: #{e.message}" unless needs_sign_in?(server, e)
894
+
895
+ # A sign-in that came while it was on the wire: the call again, once.
896
+ line = signed_out(server, ctx, e)
897
+ retry if line.nil? && (resent = !resent)
898
+ line || "Error: MCP server #{server.name} refused the call (401)"
899
+ rescue Client::Timeout, Client::Cancelled, Client::Unavailable, Samagotchi::Plugin::Service::Stopped => e
797
900
  "Error: #{e.message}"
798
901
  rescue Client::Error => e
799
902
  "Error: #{e.message}#{Samagotchi::Tools::ToolIndex.schema_note(tool)}"
@@ -807,8 +910,9 @@ class Plugin
807
910
  client = server.service.value
808
911
  started = server.state == :cached
809
912
  server.state = :running
913
+ server.error = nil if server.url # the next failure is said again
810
914
  publish
811
- ctx.log.info("mcp_server_started", server: server.name, pid: client.pid, tools: server.listed.size, lazy: true) if started
915
+ ctx.log.info("mcp_server_started", server: server.name, **where(client), tools: server.listed.size, lazy: true) if started
812
916
  client
813
917
  rescue Client::Cancelled => e
814
918
  "Error: #{e.message}"
@@ -816,6 +920,10 @@ class Plugin
816
920
  "Error: #{e.message}"
817
921
  rescue StandardError => e
818
922
  raise unless server.state == :cached
923
+ if needs_sign_in?(server, e)
924
+ return signed_out(server, ctx, e) || "Error: MCP server #{server.name} was signed in to meanwhile: call it again"
925
+ end
926
+ return not_connected(server, e, ctx) if server.url
819
927
 
820
928
  server.state = :failed
821
929
  server.error = e.message
@@ -825,6 +933,18 @@ class Plugin
825
933
  "Error: MCP server #{server.name} didn't start: #{e.message}"
826
934
  end
827
935
 
936
+ # A remote server that didn't connect stays cached: a network blip or a
937
+ # token the user is about to fix. One notice per distinct message; the
938
+ # next call tries again (the service's start raised, so its next value
939
+ # starts it again).
940
+ def not_connected(server, error, ctx)
941
+ ctx.log.warn("mcp_server_failed", server: server.name, error: error.class.name, msg: error.message, lazy: true)
942
+ text = "MCP server #{server.name} didn't connect: #{error.message}"
943
+ first = @left_out_lock.synchronize { server.error == error.message ? false : (server.error = error.message) }
944
+ ctx.notify("#{text}; its next call tries again", level: :warn) if first
945
+ "Error: #{text}"
946
+ end
947
+
828
948
  # Start a server that exited again, for a call: at most MAX_RESTARTS
829
949
  # times a session. A start that fails or is cancelled leaves it exited
830
950
  # (the next call tries again, while restarts are left).
@@ -854,96 +974,6 @@ class Plugin
854
974
  end
855
975
  end
856
976
 
857
- # The answer's text, and the images to attach: its image blocks, and a
858
- # text block that is only an image's path (#image_path).
859
- # @return [Array(String, Array<Hash>)]
860
- def content(result, server, tool)
861
- blocks = Array(result["content"])
862
- return [JSON.generate(result["structuredContent"]), []] if blocks.empty? && result["structuredContent"]
863
-
864
- images = []
865
- text = blocks.map do |block|
866
- case block["type"]
867
- when "text"
868
- line = block["text"].to_s
869
- paths = image_paths(line, server).reject { |path| images.any? { |image| image[:path] == path } }
870
- next line if paths.empty?
871
-
872
- notes = paths.map do |path|
873
- images << { path: path, name: File.basename(path) }
874
- "[image #{images.size}: #{File.basename(path)}]"
875
- end
876
- [line, *notes].join("\n")
877
- when "image"
878
- mime = block["mimeType"] || "unknown type"
879
- bytes = block["data"].to_s.unpack1("m")
880
- next "[image: #{mime}, empty]" if bytes.empty?
881
-
882
- images << { bytes: bytes, name: "#{tool}-#{images.size + 1}.#{IMAGE_EXT.fetch(mime, "img")}" }
883
- "[image #{images.size}: #{mime}]"
884
- when "audio" then "[audio: #{block["mimeType"] || "unknown type"}]"
885
- when "resource"
886
- resource = block["resource"] || {}
887
- mime = resource["mimeType"].to_s
888
- blob = resource["blob"].to_s
889
- if mime.start_with?("image/") && !blob.empty?
890
- bytes = blob.unpack1("m")
891
- next "[image: #{mime}, empty]" if bytes.empty?
892
-
893
- images << { bytes: bytes, name: "#{tool}-#{images.size + 1}.#{IMAGE_EXT.fetch(mime, "img")}" }
894
- "[image #{images.size}: #{mime}]"
895
- else
896
- resource["text"] || "[resource: #{resource["uri"]}]"
897
- end
898
- when "resource_link" then "[resource link: #{block["uri"]}]"
899
- else "[#{block["type"] || "unknown"} content]"
900
- end
901
- end.join("\n")
902
- [text, images]
903
- end
904
-
905
- # An absolute path ending in an image extension, inside a sentence
906
- # ("Saved screenshot to /tmp/shot.png."): no spaces, quotes or brackets.
907
- IMAGE_PATH_IN_TEXT = %r{(?<![\w/.~-])/[^\s"'`<>()\[\]{},;]+?\.(?:png|jpe?g|gif|webp)(?![\w/-])}i
908
-
909
- # The images +text+ names, when the server's attach_image_paths isn't
910
- # off: the whole text when it is one absolute path (any name), else each
911
- # absolute path in it that ends in an image extension. Each must be an
912
- # image file (by its bytes) under the system temp dir or the server's
913
- # cwd: a server's text can't pull in any image on disk.
914
- # @return [Array<String>] real paths, each once
915
- def image_paths(text, server)
916
- return [] if server.config["attach_image_paths"] == false
917
-
918
- whole = text.strip
919
- candidates = if whole.start_with?("/") && !whole.include?("\n") && File.file?(whole)
920
- [whole]
921
- else
922
- text.scan(IMAGE_PATH_IN_TEXT)
923
- end
924
- candidates.filter_map { |path| image_path(path, server) }.uniq
925
- end
926
-
927
- # +path+'s real path when it is an image file under a root, else nil.
928
- def image_path(path, server)
929
- return nil unless File.file?(path)
930
-
931
- real = File.realpath(path)
932
- roots = [Dir.tmpdir, server.cwd].compact.map { |dir| File.realpath(dir) rescue nil }.compact
933
- return nil unless roots.any? { |root| real.start_with?(root.end_with?("/") ? root : "#{root}/") }
934
-
935
- image_magic?(real) ? real : nil
936
- rescue SystemCallError
937
- nil
938
- end
939
-
940
- # png, jpeg, gif or webp by the file's first bytes.
941
- def image_magic?(path)
942
- head = File.binread(path, 12).to_s.b
943
- head.start_with?("\x89PNG\r\n\x1a\n".b, "\xFF\xD8\xFF".b, "GIF87a", "GIF89a") ||
944
- (head.start_with?("RIFF") && head[8, 4] == "WEBP")
945
- end
946
-
947
977
  # The process ended while chi runs: one notice; its next call starts it
948
978
  # again (#restart) while restarts are left.
949
979
  def exited(server, reason, ctx)
@@ -961,54 +991,6 @@ class Plugin
961
991
  ctx.notify("MCP server #{server.name} stopped: #{reason}; #{after}", level: :warn)
962
992
  end
963
993
 
964
- def listing
965
- return "No servers. Add them in config.yml under `bundles: mcp: servers:` (docs/bundles.md, The mcp bundle)." if @servers.empty?
966
-
967
- servers = @servers.map do |server|
968
- marker = if @source && !@source.declared_groups.include?(server.name)
969
- " (not in toolkit #{@ctx.toolkit})"
970
- end
971
- head = "**#{server.name}**: #{state_text(server)}#{marker}"
972
- # Sorted: a server lists its tools in its own (often grouped) order.
973
- tools = server.tools.sort_by(&:name).map { |t| ["- `#{t.server}/#{t.name}`", mark(t)].compact.join(" ") }
974
- tools.empty? ? head : "#{head}\n#{tools.join("\n")}"
975
- end
976
- [*servers, totals_text].join("\n\n")
977
- end
978
-
979
- # /mcp's last line: what every request carries, and the servers' tools'
980
- # tokens. When another tool took both names (chi's tool index left its
981
- # tools out: a load warning), that the model can't reach them.
982
- def totals_text
983
- if @source.declared_names.empty?
984
- return "The search and call tools aren't declared in this session (other tools have their names; see the " \
985
- "load warnings), so the model can't reach the tools above."
986
- end
987
-
988
- total = @servers.sum { |server| OFFERED.include?(server.state) ? server.tokens : 0 }
989
- "Every request carries #{@source.declared_names.join(" and ")}: ~#{thousands(@source.declared_tokens)} tokens. " \
990
- "The tools above, ~#{thousands(total)} tokens, reach the model only in a search's answer " \
991
- "(estimated: their JSON as the chat API gets it, ÷ #{format("%g", Samagotchi::TokenUsage::CHARS_PER_TOKEN)})."
992
- end
993
-
994
- def state_text(server)
995
- count = offered(server).size
996
- tools = "#{count} tool#{"s" unless count == 1}"
997
- case server.state
998
- when :cached then "cached (not started), #{tools}, #{tokens_text(server)}"
999
- when :running then "running (pid #{server.client.pid}), #{tools}, #{tokens_text(server)}"
1000
- when :starting then "starting"
1001
- when :failed then server.tools.empty? ? "failed: #{server.error}" : "failed (#{tools}): #{server.error}"
1002
- else "stopped: #{server.error}"
1003
- end
1004
- rescue Samagotchi::Plugin::Service::Stopped
1005
- "stopped"
1006
- end
1007
-
1008
- def tokens_text(server) = "~#{thousands(server.tokens)} tokens"
1009
-
1010
- def thousands(number) = number.to_s.reverse.scan(/\d{1,3}/).join(",").reverse
1011
-
1012
994
  def positive(value)
1013
995
  number = Float(value.to_s, exception: false)
1014
996
  number&.positive? ? number : nil