ruby_llm-code_mode 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99df9f45b17d0bfb00c9251a705350b87e17bc0d35388284b7d9968afe0945e9
-  data.tar.gz: bad8594e60eff854ad3d891a12714e1cc879f7015ea57077b28afc9920239715
+  metadata.gz: 65329e122014fe96a542cab62f9eb0bb002f3c1ac9f53fae0f5d7b384183433e
+  data.tar.gz: c9f4272b1b65da90128fb4a62d211a47606814091ee07095fe55535126aea154
 SHA512:
-  metadata.gz: 3b32708303afcbe27574ee5bf9504168e0a93021cf06f62ce0065bd44ee20a06199c21825791946bd27c394279f9bcf9e20f53f62367750942e760b14ddace7f
-  data.tar.gz: d5efdf5b03124ba97ff9ba07f0f1db87c7b5aeb2de3edd99619e294207ded741ed562635db4a2224f39acb1cd601d8cdbcd43751d7a4f6210a96cb4784dbd95e
+  metadata.gz: 7f31a40ab23606bfd6f2c5799ff90c780c514eac95bd3f63d4e4ef933c97adf38ae7d61ca65fe4dc53ba472f8ed38a8a64ae3fcf286656c7694ac2c8c9842817
+  data.tar.gz: 1316c738fba0e23e1dc0db07ea63d926cb535bd082cf649a0511c68639e86e777e9077cbe7f1a9973b05e110f023ba9d4d21df3638602956525ca33a2d8e3602

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Juneira
+Copyright (c) 2026 Marcelo Junior
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

data/README.md

@@ -50,7 +50,7 @@ a fixed description built from the declared mounts:
 - a **Read-only folders** section listing each `mount` as `` `/guest/path` — description``;
 - a **Read-write folders** section listing each `mount_rw`;
 - a **Host tools** section listing every bound `RubyLLM::Tool` with its
-  parameters, when any are bound with `tool`.
+  parameters, when any are bound with `tools` or `mcps`.
 
 The single parameter is `code` — a complete, self-contained Ruby script.
 
@@ -70,8 +70,10 @@ A JSON object sent back to the model:
 ```ruby
 mount    source: host_path, dest: guest_path, description: "..."  # read-only
 mount_rw source: host_path, dest: guest_path, description: "..." # read-write
-tool     SomeRubyLLMTool                                          # host tool
-tool     "name" => SomeRubyLLMTool                                # explicit name
+tools    SomeRubyLLMTool                                          # host tool
+tools    SomeTool, OtherTool                                      # several (or arrays)
+tools    "name" => SomeRubyLLMTool                                # explicit name(s)
+mcps     SomeMcpServer                                            # MCP server(s) (instance or class)
 ```
 
 - `source:` — folder on the host machine, relative to the process working
@@ -79,9 +81,15 @@ tool     "name" => SomeRubyLLMTool                                # explicit nam
 - `dest:` — absolute, normalized path inside the sandbox (may not overlap
   the reserved `/work`, `/usr` or `/src` trees, and must be unique).
 - `description:` — shown to the model in the tool description.
-- `tool` — a `RubyLLM::Tool` class or instance; the name inside the sandbox
-  is derived from the class-name leaf (`MyApp::Tools::Weather` → `weather`),
-  or the explicit one from the one-pair form.
+- `tools` — one or more `RubyLLM::Tool` classes/instances (or arrays of
+  them); the name inside the sandbox is derived from the class-name leaf
+  (`MyApp::Tools::Weather` → `weather`), or the explicit one from the
+  `"name" => tool` pairs. Called without arguments, it returns the bound
+  tools.
+- `mcps` — one or more `RubyLLM::MCP` instances or classes
+  (auto-instantiated, with the server's declared inputs as keywords); all of
+  each server's tools are bound under their own names. Called without
+  arguments, it returns the connected servers.
 
 Invalid declarations raise at class-definition time, so a misconfigured tool
 never reaches a live chat. Subclasses inherit their parent's mounts and tools.
@@ -103,8 +111,8 @@ end
 
 class Assistant < RubyLLM::CodeMode
   mount source: "data", dest: "/data", description: "Project data"
-  tool  Weather                 # binds as `weather`
-  tool  "forecast" => Weather   # or bind it under an explicit name
+  tools Weather                    # binds as `weather`
+  tools "forecast" => Weather      # or bind it under an explicit name
 end
 ```
 
@@ -130,6 +138,47 @@ report = SB.call("weather", city: "Porto Alegre")
   tools can be bound to one class.
 - A `RubyLLM::CodeMode` cannot be bound inside another `CodeMode`.
 
+### MCP servers
+
+The `mcps` DSL connects [RubyLLM::MCP](https://rubyllm.com/next/mcp/) servers
+and binds all their tools in one call, letting the sandboxed code reach the
+server through the host RPC channel:
+
+```ruby
+docs = RubyLLM.mcp(url: "https://learn.microsoft.com/api/mcp")
+
+class DocsResearch < RubyLLM::CodeMode
+  mcps docs                       # instance
+  # mcps MicrosoftDocs            # or the class (instantiated with .new)
+  # mcps Linear, user: current_user  # class + the server's declared inputs
+end
+```
+
+Each server tool keeps its server name and its JSON schema is rendered into
+the tool description, so inside the sandbox the model writes:
+
+```ruby
+result = SB.call("microsoft_docs_search", query: "Azure Blob Storage")
+result[:text]       # => the tool's text output
+result[:structured] # => parsed structured content, or nil
+result[:error]      # => true when the tool reported a failure
+```
+
+- A tool whose name is already bound is re-bound as `<server>_tool`
+  (`search` on server `github` → `github_search`); a name that still collides
+  after prefixing raises at definition time.
+- Servers that send `instructions` have them listed in the description under
+  a "## Server notes" section.
+- Everything fails fast: an argument that is not a `RubyLLM::MCP`, a server
+  that cannot be reached, or a stuck name collision roll the whole call back
+  and raise at definition time.
+- The class form binds the tools of one instance built at definition time —
+  for servers that act per-user, pass a ready instance instead
+  (`mcps Linear.new(user: current_user)`) where the user is available.
+
+The sandbox itself never sees the network — every `SB.call` performs the MCP
+request on the host. A runnable example lives in `sample/ruby_llm_mcp/`.
+
 ### Sandbox limits
 
 Defaults: `timeout_ms: 30_000` (wall clock), `fuel_ms: 10_000` (CPU budget).

data/lib/ruby_llm/code_mode.rb

@@ -5,14 +5,14 @@ require "security_box"
 
 module RubyLLM
   class CodeMode < Tool
-    VERSION = "0.1.2"
+    VERSION = "0.3.0"
 
     DEFAULT_TIMEOUT_MS = 30_000
     DEFAULT_FUEL_MS = 10_000
     MAX_TOOLS = SecurityBox::Rpcs::MAX_RPCS
 
-    TOOL_USAGE = "tool expects a RubyLLM::Tool class or instance, " \
-                 'or exactly one "name" => tool pair'
+    TOOL_USAGE = "tools expects RubyLLM::Tool classes or instances, " \
+                 'or "name" => tool pairs'
 
     FIXED_DESCRIPTION = <<~DESC.freeze
       Executes Ruby code inside a secure sandbox and returns what it produced.
@@ -51,6 +51,8 @@ module RubyLLM
 
     ToolEntry = Struct.new(:name, :tool, keyword_init: true)
 
+    McpEntry = Struct.new(:name, :mcp, :instructions, keyword_init: true)
+
     class << self
       def tool_name
         leaf = name.to_s.split('::').last
@@ -67,32 +69,83 @@ module RubyLLM
         add_mount(source, dest, :read_write, description)
       end
 
-      def tool(mapping = nil, **kwargs)
-        if !kwargs.empty?
-          raise ArgumentError, TOOL_USAGE unless kwargs.size == 1 && mapping.nil?
-
-          name, bound = kwargs.first
-          mapping = { name.to_s => bound }
+      # Binds RubyLLM::Tool classes/instances as host tools callable from
+      # inside the sandbox via SB.call:
+      #
+      #   tools Weather                     # class (instantiated with .new)
+      #   tools Weather, Echo               # several at once
+      #   tools [Weather, Echo]             # or arrays
+      #   tools "forecast" => Weather       # explicit sandbox name
+      #   tools forecast: Weather           # same, as kwargs
+      #
+      # Without arguments it returns the hash of bound tools. The name is
+      # derived from the class-name leaf (`MyApp::Tools::Weather` binds as
+      # `weather`). Fails fast: every item must be a RubyLLM::Tool (class or
+      # instance), names must be unique and non-empty, and if anything goes
+      # wrong nothing is bound.
+      def tools(*args, **kwargs)
+        return @tools ||= {} if args.empty? && kwargs.empty?
+
+        snapshot = @tools.dup
+        begin
+          args.flatten(1).each do |item|
+            if item.is_a?(Hash)
+              item.each { |name, bound| add_tool(bound, name.to_s) }
+            else
+              add_tool(item, nil)
+            end
+          end
+          kwargs.each { |name, bound| add_tool(bound, name.to_s) }
+        rescue StandardError
+          instance_variable_set(:@tools, snapshot)
+          raise
         end
+        tools
+      end
 
-        if mapping.is_a?(Hash)
-          raise ArgumentError, TOOL_USAGE unless mapping.size == 1
-
-          name, bound = mapping.first
-          add_tool(bound, name.to_s)
-        else
-          add_tool(mapping, nil)
+      # Connects MCP server(s) and binds all their tools into the sandbox:
+      #
+      #   docs = RubyLLM.mcp(url: "https://learn.microsoft.com/api/mcp")
+      #
+      #   class DocsResearch < RubyLLM::CodeMode
+      #     mcps docs                    # instance
+      #     mcps MicrosoftDocs           # or the class (instantiated with .new)
+      #     mcps Linear, user: current_user  # class + declared inputs
+      #     mcps Docs, Github            # several servers / arrays at once
+      #   end
+      #
+      # Without arguments it returns the array of connected servers. Server
+      # tools keep their names (`microsoft_docs_search`, ...); a tool whose
+      # name is already bound is re-bound as "<server>_tool". The servers'
+      # instructions (when the server sends them) are snapshotted at
+      # definition and listed in the description under "## Server notes".
+      # Fails fast: every argument must be a RubyLLM::MCP (class or
+      # instance), and if anything goes wrong — a server that cannot be
+      # reached, a name that stays colliding after prefixing — nothing is
+      # bound.
+      def mcps(*servers, **inputs)
+        return @mcps ||= [] if servers.empty? && inputs.empty?
+
+        flat = servers.flatten(1)
+        raise ArgumentError, "expected at least one RubyLLM::MCP server" if flat.empty?
+        unless inputs.empty? || flat.all?(Class)
+          raise ArgumentError, "inputs only apply when passing RubyLLM::MCP classes"
         end
+
+        snapshot_tools = tools.dup
+        snapshot_mcps = mcps.dup
+        normalize_mcp_servers(flat, inputs).each { |server| bind_mcp_server(server) }
+        mcps
+      rescue StandardError
+        instance_variable_set(:@tools, snapshot_tools)
+        instance_variable_set(:@mcps, snapshot_mcps)
+        raise
       end
 
       def mounts
         @mounts ||= []
       end
 
-      def tools
-        @tools ||= {}
-      end
-
       def configuration
         @configuration ||= SecurityBox::Configuration.build(
           timeout_ms: DEFAULT_TIMEOUT_MS,
@@ -108,7 +161,8 @@ module RubyLLM
           FIXED_DESCRIPTION.rstrip,
           folder_section("## Read-only folders (readable, never writable)", read_only),
           folder_section("## Read-write folders (readable and writable)", read_write),
-          tools_section
+          tools_section,
+          server_notes_section
         ].compact.join("\n\n")
       end
 
@@ -128,6 +182,7 @@ module RubyLLM
         super
         subclass.instance_variable_set(:@mounts, mounts.dup)
         subclass.instance_variable_set(:@tools, tools.dup)
+        subclass.instance_variable_set(:@mcps, mcps.dup)
         subclass.instance_variable_set(:@configuration, nil)
       end
 
@@ -153,7 +208,7 @@ module RubyLLM
           raise ArgumentError, "cannot bind a RubyLLM::CodeMode inside another CodeMode"
         end
 
-        name = (name || leaf_tool_name(instance.class)).to_s
+        name = (name || tool_binding_name(instance)).to_s
         raise ArgumentError, "tool name must be a non-empty String" if name.empty?
         raise ArgumentError, "tool name #{name.inspect} is already bound" if tools.key?(name)
         if tools.size >= MAX_TOOLS
@@ -177,8 +232,8 @@ module RubyLLM
         end
       end
 
-      # Leaf-only name derivation, like .tool_name — the guest has no use for
-      # the RubyLLM namespace ("MyApp::Tools::Search" binds as "search").
+      # Leaf-only name derivation, like .tool_name — the guest has no use
+      # for the RubyLLM namespace ("MyApp::Tools::Search" binds as "search").
       def leaf_tool_name(klass)
         leaf = klass.name.to_s.split('::').last
         return "" unless leaf
@@ -186,6 +241,14 @@ module RubyLLM
         RubyLLM::Support::Utils.underscore(leaf).delete_suffix('_tool')
       end
 
+      # Regular tools keep the leaf-only derivation; MCP tools carry their
+      # own (server) name, which is what they bind under inside the sandbox.
+      def tool_binding_name(instance)
+        return instance.name.to_s if instance.respond_to?(:server_name)
+
+        leaf_tool_name(instance.class)
+      end
+
       def build_rpcs
         tools.transform_values { |entry| ->(args) { call_bound_tool(entry, args) } }
       end
@@ -196,7 +259,54 @@ module RubyLLM
                 "tool #{entry.name.inspect} expects a hash of arguments, got #{args.class}"
         end
 
-        entry.tool.call(**args)
+        normalize_result(entry.tool.call(**args))
+      end
+
+      # MCP tools return RubyLLM::MCP::Result objects; SecurityBox JSON
+      # round-trips handler returns, so give the guest plain data instead
+      # of an inspect string.
+      def normalize_result(value)
+        return value unless defined?(RubyLLM::MCP::Result) && value.is_a?(RubyLLM::MCP::Result)
+
+        { text: value.text, structured: value.structured, error: value.error? }
+      end
+
+      def normalize_mcp_servers(servers, inputs)
+        unless defined?(RubyLLM::MCP)
+          raise ArgumentError,
+                "RubyLLM::MCP is not available; mcps needs a ruby_llm version with MCP support"
+        end
+
+        servers.map do |server|
+          case server
+          when Class
+            unless server <= RubyLLM::MCP
+              raise ArgumentError, "expected a RubyLLM::MCP (class or instance), got #{server.inspect}"
+            end
+
+            server.new(**inputs)
+          when RubyLLM::MCP
+            server
+          else
+            raise ArgumentError, "expected a RubyLLM::MCP (class or instance), got #{server.inspect}"
+          end
+        end
+      end
+
+      def bind_mcp_server(server)
+        # Fetching .tools connects to the server; snapshot the instructions
+        # right after, so description builds never touch the network.
+        tools_list = server.tools
+        mcps << McpEntry.new(
+          name: server.name.to_s, mcp: server, instructions: server.instructions.to_s
+        )
+        tools_list.each { |tool| bind_mcp_tool(server, tool) }
+      end
+
+      def bind_mcp_tool(server, tool)
+        name = tool_binding_name(tool)
+        name = "#{server.name}_#{name}" if tools.key?(name) && !server.name.to_s.empty?
+        add_tool(tool, name)
       end
 
       def folder_section(header, entries)
@@ -220,6 +330,18 @@ module RubyLLM
         ].join("\n")
       end
 
+      def server_notes_section
+        notes = mcps.filter_map do |entry|
+          instructions = entry.instructions.to_s
+          next if instructions.empty?
+
+          "- **#{entry.name}** — #{instructions}"
+        end
+        return nil if notes.empty?
+
+        ["## Server notes", *notes].join("\n")
+      end
+
       def tool_lines(entry)
         line = "- `#{entry.name}`"
         description = entry.tool.description.to_s

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-code_mode
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Juneira