asterism 0.7.0 → 0.8.0

data/lib/asterism/cli/mcp.rb

@@ -0,0 +1,272 @@
+# `asterism mcp`: Asterism as tools of an MCP client (an AI assistant),
+# over stdio, with the mcp gem (an optional dependency: `gem install mcp`;
+# the rest of the command line does not need it).
+#
+#   asterism mcp --router tcp/192.0.2.2:7447 --allow 'games/othello1.*'
+#
+# Tools:
+#   asterism_nodes     the nodes, their applications (with their statuses)
+#                      and objects                         (always; reads)
+#   asterism_objects   the objects and their methods (meta) (always; reads)
+#   asterism_status    the applications' statuses           (always; reads)
+#   <node>.<app>.<object>.<method>
+#                      one per method that an --allow pattern names, made
+#                      from the object's meta: the arguments' names the
+#                      meta tells (docs/protocol.md 5) are the inputs and
+#                      its doc the description; without names, arity n
+#                      gives arg1 .. argN (any JSON value), arity -1 an
+#                      array "args"; "kwargs" (an object) is the keyword
+#                      arguments. Nothing is callable without --allow.
+#
+# The call tools follow the network: when objects appear or go, the list is
+# made again and the client is told (notifications/tools/list_changed).
+require "mcp"
+
+module Asterism
+  class CLI
+    class MCPBridge
+      REFRESH_S = 2.0
+      INSTRUCTIONS = <<~TEXT.freeze
+        These tools look at an Asterism network: Ruby programs and boards that expose objects to each other over
+        Zenoh. Paths are <node>/<app>/<object>. asterism_nodes lists the nodes and their applications (with the
+        status each application tells about itself, a JSON object of its own), asterism_objects the objects and
+        their methods, asterism_status the statuses. The other tools call one method each, on the object their
+        name says (<node>.<app>.<object>.<method>); only the methods this server was started to allow are there.
+        A call's answer is {"value": ...}; an error says its kind (raised, not_exposed, arguments, ...).
+      TEXT
+
+      def initialize(net, survey, allow:, log: $stderr)
+        @net = net
+        @survey = survey
+        @allow = Allow.new(allow)
+        @log = log
+        @call_tools = {}  # tool name => [path, method, arity, meta entry]
+        @signature = nil
+        @lock = Mutex.new
+      end
+
+      def run
+        @server = ::MCP::Server.new(name: "asterism", version: ::Asterism::VERSION, instructions: INSTRUCTIONS,
+                                    tools: read_tools)
+        @transport = ::MCP::Server::Transports::StdioTransport.new(@server)
+        @server.transport = @transport
+        refresh
+        @log.puts "asterism mcp: #{@net.node_id}/#{@net.app}; #{@call_tools.size} call tools" \
+                  "#{@allow.empty? ? ' (no --allow: read-only)' : ''}"
+        @refresher = Thread.new { refresh_loop }
+        @transport.open
+      ensure
+        @refresher&.kill
+      end
+
+      # ------------------------------------------------------------ the list
+
+      def refresh_loop
+        loop do
+          sleep REFRESH_S
+          refresh
+        rescue StandardError => e
+          @log.puts "asterism mcp: refresh: #{e.class}: #{e.message}"
+        end
+      end
+
+      # Makes the call tools again when the objects changed; tells the
+      # client when the list did.
+      def refresh
+        return if @allow.empty?
+        paths = @survey.objects.select { @allow.object?(_1) }
+        sig = paths.sort
+        return if sig == @signature
+        metas = @survey.metas(paths)
+        tools = {}
+        metas.sort.each do |path, methods|
+          methods.each do |m|
+            next unless @allow.method?(path, m["name"])
+            name = unique_name(tool_name(path, m["name"]), tools)
+            tools[name] = [path, m["name"], m["arity"], m]
+          end
+        end
+        # Keep trying the objects whose meta did not come.
+        @signature = (paths - metas.keys).empty? ? sig : nil
+        changed = @lock.synchronize do
+          next false if tools == @call_tools
+          @call_tools = tools
+          list = read_tools + tools.map { |name, (path, _method, _arity, m)| call_tool(name, path, m) }
+          @server.tools = list.to_h { [_1.name_value, _1] }
+          @server.instance_variable_set(:@tool_names, @server.tools.keys)
+          true
+        end
+        return unless changed
+        @log.puts "asterism mcp: call tools: #{tools.keys.join(', ')}"
+        @server.notify_tools_list_changed
+      end
+
+      def tool_name(path, method)
+        "#{path.tr('/', '.')}.#{method}".gsub(/[^A-Za-z0-9_.-]/, "_")[0, 120]
+      end
+
+      def unique_name(name, taken)
+        return name unless taken.key?(name)
+        n = 2
+        n += 1 while taken.key?("#{name}_#{n}")
+        "#{name}_#{n}"
+      end
+
+      # ------------------------------------------------------------ tools
+
+      def read_tools
+        sv = @survey
+        bridge = self
+        [
+          ::MCP::Tool.define(
+            name: "asterism_nodes",
+            description: "The nodes of the Asterism network, each with its profile (what runs it, a display name), " \
+                         "its applications with their statuses, and the names of their objects.",
+            input_schema: { properties: {} },
+            annotations: { read_only_hint: true }
+          ) do |server_context:|
+            bridge.answer { sv.tree(meta: false) }
+          end,
+          ::MCP::Tool.define(
+            name: "asterism_objects",
+            description: "The exposed objects (<node>/<app>/<object>) and their methods with the number of " \
+                         "arguments (-1: any), and the arguments' names and what each method does when the object " \
+                         "tells them (args, doc). callable_as names the tool that calls a method, when this server " \
+                         "allows it.",
+            input_schema: { properties: { pattern: { type: "string",
+                                                     description: "node/app/object with * (one part) and ** " \
+                                                                  "(any parts); default **" } } },
+            annotations: { read_only_hint: true }
+          ) do |server_context:, pattern: "**"|
+            bridge.answer { bridge.objects(pattern) }
+          end,
+          ::MCP::Tool.define(
+            name: "asterism_status",
+            description: "The statuses the applications tell about themselves (asterism/<node>/<app>/@status): " \
+                         "{\"<node>/<app>\": {...}}. An application without one is not listed.",
+            input_schema: { properties: { node: { type: "string" }, app: { type: "string" } } },
+            annotations: { read_only_hint: true }
+          ) do |server_context:, node: nil, app: nil|
+            bridge.answer do
+              sv.statuses.select do |k, _|
+                n, a = k.split("/")
+                (node.nil? || node == n) && (app.nil? || app == a)
+              end
+            end
+          end
+        ]
+      end
+
+      def objects(pattern)
+        paths = @survey.objects(pattern)
+        metas = @survey.metas(paths)
+        by = @lock.synchronize { @call_tools.to_h { |name, (path, m, _)| [[path, m], name] } }
+        paths.map do |p|
+          methods = metas[p]&.map do |m|
+            name = by[[p, m["name"]]]
+            name ? m.merge("callable_as" => name) : m
+          end
+          h = { "path" => p, "methods" => methods }
+          h["doc"] = @survey.object_doc(p) if @survey.object_doc(p)
+          h
+        end
+      end
+
+      def call_tool(name, path, meta)
+        method = meta["name"]
+        arity = meta["arity"]
+        names = input_names(meta)
+        props = {}
+        required = []
+        if names
+          names.each do |n|
+            props[n.to_sym] = { description: "the argument #{n}" }
+            required << n if arity >= 0
+          end
+          props[:args] = { type: "array", description: "more positional arguments, if any" } if arity.negative?
+        elsif arity.negative?
+          props[:args] = { type: "array", description: "the positional arguments (any number)" }
+        else
+          arity.times do |i|
+            props[:"arg#{i + 1}"] = { description: "argument #{i + 1} (any JSON value)" }
+            required << "arg#{i + 1}"
+          end
+        end
+        props[:kwargs] = { type: "object", description: "keyword arguments, if the method takes any" }
+        schema = { properties: props }
+        schema[:required] = required unless required.empty?
+        about = [meta["doc"], (d = @survey.object_doc(path)) && "(#{path}: #{d})"].compact
+        count = names ? "" : " (#{arity.negative? ? 'any number of' : arity} arguments)"
+        bridge = self
+        ::MCP::Tool.define(
+          name: name,
+          description: "#{about.empty? ? '' : "#{about.join(' ')}\n"}Calls #{method} on the Asterism object " \
+                       "#{path}#{count} and returns {\"value\": ...}.",
+          input_schema: schema
+        ) do |server_context:, **args|
+          bridge.invoke(path, method, arity, args, names)
+        end
+      end
+
+      # The meta's argument names as inputs, or nil (none, or a name the
+      # inputs cannot take: "args", "kwargs", a repeated one).
+      def input_names(meta)
+        names = meta["args"]
+        return nil unless names.is_a?(Array) && !names.empty?
+        return nil if names.uniq.size != names.size || names.any? { %w[args kwargs].include?(_1) }
+        names
+      end
+
+      # A call tool's call.
+      def invoke(path, method, arity, args, names = nil)
+        pos = if names
+                names.map { args[_1.to_sym] } + (arity.negative? ? Array(args[:args]) : [])
+              elsif arity.negative?
+                Array(args[:args])
+              else
+                (1..arity).map { args[:"arg#{_1}"] }
+              end
+        if names && arity.negative?
+          # Optional named arguments: the trailing ones not given are left out.
+          pos.pop while !pos.empty? && pos.last.nil? && args[:args].nil?
+        end
+        kw = (args[:kwargs] || {}).to_h.transform_keys(&:to_sym)
+        unless @lock.synchronize { @call_tools.any? { |_, t| t[0] == path && t[1] == method } }
+          return error("#{path}.#{method} is not callable here (not allowed, or gone)")
+        end
+        v = ::Asterism[path, timeout: @survey.timeout].asterism_call(method, *pos, **kw)
+        text({ "value" => v })
+      rescue ::Asterism::RemoteError => e
+        error({ "error" => { "kind" => e.remote_kind, "class" => e.remote_class, "message" => e.remote_message } })
+      rescue ::Asterism::Error => e
+        error({ "error" => { "kind" => "asterism", "class" => e.class.name, "message" => e.message } })
+      end
+
+      # The value of the block as a JSON text; an Asterism error as an
+      # error result.
+      def answer
+        text(yield)
+      rescue ::Asterism::Error => e
+        error("#{e.class}: #{e.message}")
+      end
+
+      def text(v)
+        ::MCP::Tool::Response.new([{ type: "text", text: JSON.generate(json_safe(v)) }])
+      end
+
+      def error(v)
+        ::MCP::Tool::Response.new([{ type: "text", text: v.is_a?(String) ? v : JSON.generate(json_safe(v)) }],
+                                  error: true)
+      end
+
+      def json_safe(v)
+        case v
+        when Hash then v.to_h { |k, x| [k.to_s, json_safe(x)] }
+        when Array then v.map { json_safe(_1) }
+        when String then v.encoding == Encoding::BINARY && !v.ascii_only? ? "(#{v.bytesize} bytes)" : v
+        else v
+        end
+      end
+    end
+  end
+end

data/lib/asterism/cli/survey.rb

@@ -0,0 +1,204 @@
+# What `asterism nodes / objects / tree` and the MCP bridge read from the
+# network, on a connection that is already open (Asterism.connect): the
+# applications and objects from the liveliness tokens, then the meta of
+# the objects, the nodes' profiles and the applications' statuses
+# (docs/protocol.md 5, 7, 8) with one get for each node or application.
+#
+# Not one wildcard get for all (asterism/*/*/@status): behind a router's
+# access control a query must fit the rules of every node it would reach
+# (a game host may answer asterism/games/*/@status, not asterism/*/*/@status),
+# so a wildcard over the nodes is refused where the plain keys pass. The
+# gets go out at once and are read as their replies come (zenoh-c fills
+# them on its own threads), so a listing costs one time limit at most,
+# whatever the number of nodes. What a router refuses is simply not there,
+# and the listing says so instead of calling a node gone.
+module Asterism
+  class CLI
+    class Survey
+      # What watch subscribes to (puts are routed per subscriber, so the
+      # wildcards pass where the rules let them through).
+      PROFILES_ALL = "asterism/*/@profile"
+      STATUS_ALL = "asterism/*/*/@status"
+      STEP = 0.005
+
+      attr_reader :timeout
+
+      # own: this connection's "<node>/<app>", left out of the listings.
+      def initialize(timeout: 2.0, own: nil)
+        @timeout = timeout
+        @own = own || "#{::Asterism.node_id}/#{::Asterism.app}"
+        @object_docs = {}
+      end
+
+      # Waits for the tokens alive at connect to come in (they come in one
+      # burst from the router): until the applications stop changing for
+      # quiet seconds, at most max seconds.
+      def settle(max = 1.5, quiet: 0.3)
+        t0 = now
+        last = nil
+        since = now
+        loop do
+          cur = [::Asterism.apps, ::Asterism.each("**").size]
+          if cur != last
+            last = cur
+            since = now
+          end
+          break if now - since >= quiet || now - t0 >= max
+          sleep 0.02
+        end
+      end
+
+      # The applications alive, "<node>/<app>", sorted (this one left out).
+      def apps(pattern = "*/*")
+        (::Asterism.apps(pattern) - [@own]).sort
+      end
+
+      # The nodes that have an application or an object alive (sorted).
+      def nodes
+        (apps.map { _1.split("/")[0] } + objects.map { _1.split("/")[0] }).uniq.sort
+      end
+
+      # The objects alive, "<node>/<app>/<object>", sorted (this
+      # application's own left out).
+      def objects(pattern = "**")
+        ::Asterism.each(pattern).map(&:asterism_path).reject { _1.start_with?("#{@own}/") }.sort
+      end
+
+      # {path => [{"name", "arity"}, ...]} for the paths given (an object
+      # that does not answer its meta in time is left out). One get per
+      # application (asterism/<node>/<app>/*/meta), then one for each object
+      # it did not bring.
+      def metas(paths)
+        return {} if paths.empty?
+        out = {}
+        apps = paths.map { _1.split("/")[0, 2].join("/") }.uniq
+        gets(apps.map { "asterism/#{_1}/*/meta" }).each_value do |replies|
+          replies.each do |key, payload|
+            path = key.delete_prefix("asterism/").delete_suffix("/meta")
+            m = meta_list(payload, path)
+            out[path] = m if m && paths.include?(path)
+          end
+        end
+        missing = paths - out.keys
+        unless missing.empty?
+          gets(missing.map { "asterism/#{_1}/meta" }).each do |key, replies|
+            path = key.delete_prefix("asterism/").delete_suffix("/meta")
+            m = replies.first && meta_list(replies.first[1], path)
+            out[path] = m if m
+          end
+        end
+        out
+      end
+
+      # {node => profile without the icon} of the nodes that answered (one
+      # get per node, all at once).
+      def profiles(list = nodes)
+        out = {}
+        gets(list.map { "asterism/#{_1}/@profile" }, params: "icon=0").each do |key, replies|
+          pr = replies.first && ::Asterism::Profile.check(::Asterism::Codec.unpack(replies.first[1]))
+          out[key.split("/")[1]] = pr if pr
+        end
+        out
+      end
+
+      # {"<node>/<app>" => status} of the applications that answered (one
+      # get per application, all at once).
+      def statuses(list = apps)
+        out = {}
+        gets(list.map { "asterism/#{_1}/@status" }).each do |key, replies|
+          st = replies.first && ::Asterism::Status.check(::Asterism::Codec.unpack(replies.first[1]))
+          parts = key.split("/")
+          out["#{parts[1]}/#{parts[2]}"] = st if st
+        end
+        out
+      end
+
+      # The tree: [{"node", "profile", "apps" => [{"app", "status",
+      # "objects" => [{"name", "methods"}]}]}]. meta: false leaves the
+      # methods out (no meta gets).
+      def tree(meta: true)
+        objs = objects
+        app_list = apps
+        threads = []
+        node_list = (app_list.map { _1.split("/")[0] } + objs.map { _1.split("/")[0] }).uniq
+        threads << Thread.new { profiles(node_list) }
+        threads << Thread.new { statuses(app_list) }
+        threads << Thread.new { meta ? metas(objs) : {} }
+        prof, stat, met = threads.map(&:value)
+        by_node = Hash.new { |h, k| h[k] = {} }
+        app_list.each { |a| n, ap = a.split("/"); by_node[n][ap] ||= [] }
+        objs.each do |o|
+          n, ap, name = o.split("/")
+          (by_node[n][ap] ||= []) << name
+        end
+        by_node.keys.sort.map do |n|
+          apps = by_node[n].keys.sort.map do |ap|
+            h = { "app" => ap }
+            h["status"] = stat["#{n}/#{ap}"] if stat.key?("#{n}/#{ap}")
+            h["objects"] = by_node[n][ap].sort.map do |name|
+              e = { "name" => name }
+              e["methods"] = met["#{n}/#{ap}/#{name}"] if met.key?("#{n}/#{ap}/#{name}")
+              d = object_doc("#{n}/#{ap}/#{name}")
+              e["doc"] = d if d
+              e
+            end
+            h
+          end
+          h = { "node" => n }
+          h["profile"] = prof[n] if prof[n]
+          h["apps"] = apps
+          h
+        end
+      end
+
+      # Sends a get on each key at once and waits for all of them (at most
+      # the time limit): {key => [[reply key, payload], ...]}.
+      def gets(keys, params: nil)
+        s = ::Asterism.session
+        ms = (@timeout * 1000).round
+        pending = keys.to_h { |k| [k, s.get(k, timeout_ms: ms, params: params)] }
+        out = keys.to_h { [_1, []] }
+        until pending.empty?
+          pending.delete_if do |k, g|
+            ended = g.done?
+            out[k].concat(g.each_reply.map { |r| [r[0], r[1]] })
+            ended
+          end
+          sleep STEP unless pending.empty?
+        end
+        out
+      rescue ::Asterism::Zenoh::Error => e
+        raise ::Asterism::Disconnected, e.message
+      end
+
+      # A meta reply's methods: [{"name", "arity"} and, when the object
+      # tells them (docs/protocol.md 5), "args" (names) and "doc"]. Fields
+      # of another shape are left out, unknown ones ignored.
+      def meta_list(payload, path = nil)
+        m = ::Asterism::Codec.unpack(payload)
+        list = m.is_a?(Hash) ? m["methods"] : nil
+        return nil unless list.is_a?(Array)
+        @object_docs[path] = m["doc"] if path && m["doc"].is_a?(String)
+        list.filter_map do |e|
+          next unless e.is_a?(Hash) && e["name"]
+          h = { "name" => e["name"].to_s, "arity" => e["arity"].to_i }
+          args = e["args"]
+          h["args"] = args if args.is_a?(Array) && args.all? { _1.is_a?(String) } &&
+                              (h["arity"].negative? || args.size == h["arity"])
+          h["doc"] = e["doc"] if e["doc"].is_a?(String)
+          h
+        end
+      end
+
+      # The text an object tells about itself in its meta (read by metas),
+      # or nil.
+      def object_doc(path)
+        @object_docs[path]
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end