Skip to content

Send every sampling content block when the protocol allows an array - #2

Open
jordan-brough wants to merge 6 commits into
crmne:ruby-llm-2-compatibilityfrom
jordan-brough:pr161-sampling-content-array
Open

jordan-brough wants to merge 6 commits into
crmne:ruby-llm-2-compatibilityfrom
jordan-brough:pr161-sampling-content-array

Conversation

@jordan-brough

@jordan-brough jordan-brough commented Sep 22, 2026 •

Copy link
Copy Markdown

Stacked on #1, which should merge first. Once it does, GitHub will show only the one commit here.

The problem

Sampling is when an MCP server asks the client, meaning this gem, to run a model on its behalf and send back the answer.

The model's answer can have two parts: some text, and one or more images or audio clips. For example, "Here is the chart you asked for" plus the chart image.

The gem has to package that answer into the MCP wire format to send it back to the server. The current code can only send one part. If the answer has text and an image, the text is sent and the image is dropped. Half the answer is lost.

The fix

Newer versions of the MCP protocol, from 2025-11-25 on, let the answer be a list of parts, so the gem can send the text and every image together. Older versions only allow a single part.

The change builds the list of all parts. If there is only one, it is sent exactly as before, so nothing changes for today's common cases. If there are several and the server negotiated a protocol version that allows lists, the whole list is sent. If the server is on an older version, the first part is sent, which is the best that version allows.

To know which version was negotiated, Native::Client#sampling_create_message_response passes the client's negotiated @protocol_version into Responses.sampling_create_message. That is the only place the version is threaded. The check lives in Native::Protocol.sampling_content_array_supported?, with SAMPLING_CONTENT_ARRAY_MIN_VERSION = "2025-11-25".

Only image and audio parts are valid sampling content in MCP. Any other attachment kind is skipped with a warning instead of being sent as an invalid block.

Verification

Run with both RUBY_LLM_VERSION="~> 1.0" and "~> 2.0". The new examples in native/messages_spec.rb build real RubyLLM::Message objects on whichever version is installed, validate the three-part list against the 2025-11-25 schema, and validate the single-part fallback against the 2025-06-18 schema. protocol_spec.rb covers the version check, and the compatibility spec gains one example. On RubyLLM 1 the sampling specs were also run against the fixture servers with no failures.

RubyLLM 2's Chat#complete returns the existing assistant message when the
conversation already ends with one, so an MCP prompt or sampling request
that ends with assistant text echoed that text back without calling the
provider. Add RubyLLM::MCP.generate_response, which calls Chat#generate
when the installed RubyLLM defines it and then Chat#complete, and use it
from Prompt#ask, Sample#chat, and SamplingActions#default_chat_completion.
RubyLLM 1 has no Chat#generate and its Chat#complete always generates, so
only Chat#complete is called there.
RubyLLM 2 messages carry a finish_reason (:stop, :max_tokens, :tool_calls,
:content_filter) instead of a stop_reason, so sampling responses always
reported endTurn even when the model was cut off by its token limit. Map
finish_reason to the MCP stop reason names when the message provides one,
camelizing unknown values as before, and keep the existing stop_reason
handling and the endTurn default for RubyLLM 1 messages.
Prompt#include raised when a required argument was supplied and let a
missing one through, and it built the error with a positional string that
BaseError#initialize rejects, so any required argument produced an
ArgumentError. Raise only when a required argument is absent, accepting
String or Symbol keys, and construct the error with its message keyword.
…on RubyLLM 2

Sample#create_message and the SamplingActions message builders passed an
MCP::Content object as the content of a RubyLLM::Message. RubyLLM 2 only
accepts a String there, so every sampling request raised an ArgumentError
before the model was called. Build these messages from
Content#message_options, as Prompt and Resource already do, which yields
the Content itself on RubyLLM 1 and separate text and attachments on
RubyLLM 2.
…nstalled

RubyLLM 1 declares tool parameters with Tool.param(desc:) and RubyLLM 2
with Tool.parameter(description:). spec_helper loads SimpleMultiplyTool,
so the regular spec suite could not start under RubyLLM 2. Pick the method
the installed RubyLLM provides so the suite loads on both.
A sampled assistant message can carry text and one or more image or audio
attachments, but the response builder emitted a single content block and
silently dropped the rest. MCP 2025-11-25 lets CreateMessageResult.content
be an array of blocks, so the client now threads the negotiated protocol
version into the builder and sends every block on that track, while older
tracks and unnegotiated sessions still receive only the first block and the
single block cases keep their existing output.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant