ruby_llm-code_mode 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99df9f45b17d0bfb00c9251a705350b87e17bc0d35388284b7d9968afe0945e9
-  data.tar.gz: bad8594e60eff854ad3d891a12714e1cc879f7015ea57077b28afc9920239715
+  metadata.gz: b92ccf0470dc8d3563eafa55662e7aa0db058095d8ac12a0d60a062547474f81
+  data.tar.gz: c2955740ee6b04b1a38279b25f63703194df752fa51f3d4f49166bab3f318ac3
 SHA512:
-  metadata.gz: 3b32708303afcbe27574ee5bf9504168e0a93021cf06f62ce0065bd44ee20a06199c21825791946bd27c394279f9bcf9e20f53f62367750942e760b14ddace7f
-  data.tar.gz: d5efdf5b03124ba97ff9ba07f0f1db87c7b5aeb2de3edd99619e294207ded741ed562635db4a2224f39acb1cd601d8cdbcd43751d7a4f6210a96cb4784dbd95e
+  metadata.gz: 7fb1029e393ec6c0041d91d5a45fbef2acdc253fe28427986d0832a73eb33b43becfa42d97983212ac7a3312a771e9506765c271bd4bd2ebcf68968b7adf467e
+  data.tar.gz: 52e9aa1bf43f9dcedf0a6e50deb9578c86716bdd5ae353da6717a6553b7f5170f3773f5c40a4229779589be9686e0a3274788d3dc658cdb084fcc5ff862c206a

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 `tool` or `mcp`.
 
 The single parameter is `code` — a complete, self-contained Ruby script.
 
@@ -72,6 +72,7 @@ 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
+mcp      SomeMcpServer                                            # MCP server (instance or class)
 ```
 
 - `source:` — folder on the host machine, relative to the process working
@@ -82,6 +83,9 @@ tool     "name" => SomeRubyLLMTool                                # explicit nam
 - `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.
+- `mcp` — a `RubyLLM::MCP` instance or class (auto-instantiated, with the
+  server's declared inputs as keywords); all of the server's tools are bound
+  under their own names.
 
 Invalid declarations raise at class-definition time, so a misconfigured tool
 never reaches a live chat. Subclasses inherit their parent's mounts and tools.
@@ -130,6 +134,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 `mcp` 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
+  mcp docs                       # instance
+  # mcp MicrosoftDocs            # or the class (instantiated with .new)
+  # mcp 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
+  (`mcp 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,7 +5,7 @@ require "security_box"
 
 module RubyLLM
   class CodeMode < Tool
-    VERSION = "0.1.2"
+    VERSION = "0.2.0"
 
     DEFAULT_TIMEOUT_MS = 30_000
     DEFAULT_FUEL_MS = 10_000
@@ -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
@@ -85,6 +87,42 @@ module RubyLLM
         end
       end
 
+      # 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
+      #     mcp docs                    # instance
+      #     mcp MicrosoftDocs           # or the class (instantiated with .new)
+      #     mcp Linear, user: current_user  # class + declared inputs
+      #     mcp Docs, Github            # several servers / arrays at once
+      #   end
+      #
+      # 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 mcp(*servers, **inputs)
+        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
@@ -93,6 +131,10 @@ module RubyLLM
         @tools ||= {}
       end
 
+      def mcps
+        @mcps ||= []
+      end
+
       def configuration
         @configuration ||= SecurityBox::Configuration.build(
           timeout_ms: DEFAULT_TIMEOUT_MS,
@@ -108,7 +150,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 +171,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 +197,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 +221,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 +230,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 +248,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; mcp 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 +319,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.2.0
 platform: ruby
 authors:
 - Juneira