mcp: implement sampling with tools#699
mcp: implement sampling with tools#699findleyr wants to merge 2 commits intomodelcontextprotocol:mainfrom
Conversation
|
Good stuff @findleyr. |
findleyr
force-pushed
the
toolsampling
branch
from
7640e70 to
d3c9a52
Compare
Add support for tool use within sampling requests, as described in the MCP spec's sampling.tools capability. New content types: ToolUseContent and ToolResultContent for sampling messages. New capability types: SamplingCapabilities gains Tools and Context sub-fields, plus ToolChoice for controlling tool invocation. Following the TypeScript SDK's pattern, tool-enabled sampling uses separate types from basic sampling for backward compatibility: - CreateMessageWithToolsParams with SamplingMessageV2 (array content) - CreateMessageWithToolsResult (array content) - ServerSession.CreateMessageWithTools and ClientOptions.CreateMessageWithToolsHandler The basic CreateMessage/CreateMessageResult API is unchanged. Both paths share the same wire method (sampling/createMessage) and go through the method info table: the table uses the broader WithTools result type, and CreateMessage downconverts (erroring if multiple content blocks are returned). Setting CreateMessageWithToolsHandler infers the sampling.tools capability. It is a panic to set both CreateMessageHandler and CreateMessageWithToolsHandler.
findleyr
force-pushed
the
toolsampling
branch
from
d3c9a52 to
41908dd
Compare
|
If you skim over the tests, this change isn't actually that large. Unfortunately, we needed to add new APIs to work around the spec change, but what we've chosen is consistent with typescript. Notably, the new |
- Add CreateMessageWithToolsParams, SamplingMessageV2, and CreateMessageWithToolsResult types for tool-enabled sampling with array content support (parallel tool calls) - Add ServerSession.CreateMessageWithTools and ClientOptions.CreateMessageWithToolsHandler - Remove Tools/ToolChoice from CreateMessageParams (moved to WithTools) - Infer sampling.tools capability from CreateMessageWithToolsHandler - Panic if both CreateMessageHandler and CreateMessageWithToolsHandler are set - CreateMessage errors if client returns multiple content blocks - Reject JSON null in unmarshalContent; return non-nil empty slice for empty arrays - Remove tool_result from result allow-list (only valid in user messages) - Rename wireContent.ToolResultContent to NestedContent - Fix clone() to deep-copy Sampling sub-fields - Fix typo "maximyum" and doubled phrase in IncludeContext doc - Add rough_edges.src.md note for v2 unification
maciej-kisiel
left a comment
maciej-kisiel
left a comment
There was a problem hiding this comment.
Sharing the comments without looking at the test file to expedite the process. I will look at the remaining file soon.
| if caps.Sampling == nil { | ||
| caps.Sampling = &SamplingCapabilities{} | ||
| } | ||
| if c.opts.CreateMessageWithToolsHandler != nil && caps.Sampling.Tools == nil { |
There was a problem hiding this comment.
Shouldn't this be inside the caps.Sampling == nil if body? Otherwise, it may override manually set sampling capabilities, which would be slightly contrary to the doc comment above.
| // Content holds the unstructured result of the tool call. | ||
| Content []Content | ||
| // StructuredContent holds an optional structured result as a JSON object. | ||
| StructuredContent any |
There was a problem hiding this comment.
For my own education: why the same logic as to ToolUseContent.Input doesn't apply here? They are both defined the same way in the specification.
| Meta Meta `json:"_meta,omitempty"` | ||
| Annotations *Annotations `json:"annotations,omitempty"` | ||
| Icons []Icon `json:"icons,omitempty"` | ||
| // Fields for ToolUseContent (type: "tool_use") |
There was a problem hiding this comment.
Should we add similar comments for other fields, for completeness? I assume that the above fields are not universal based on the comment you removed from line 230.
| Input map[string]any `json:"input,omitempty"` | ||
| // Fields for ToolResultContent (type: "tool_result") | ||
| ToolUseID string `json:"toolUseId,omitempty"` | ||
| NestedContent []*wireContent `json:"content,omitempty"` // nested content for tool_result |
There was a problem hiding this comment.
Unnecessary comment at the end of the line.
| for _, m := range p.Messages { | ||
| var content Content | ||
| if len(m.Content) > 0 { | ||
| content = m.Content[0] |
There was a problem hiding this comment.
Wouldn't this behavior be a bit confusing that the remaining content blocks are ignored? Shouldn't we return an error?
| // returning a [CreateMessageWithToolsResult] that supports array content | ||
| // (for parallel tool calls). Use this instead of [ServerSession.CreateMessage] | ||
| // when the request includes tools. | ||
| func (ss *ServerSession) CreateMessageWithTools(ctx context.Context, params *CreateMessageWithToolsParams) (*CreateMessageWithToolsResult, error) { |
There was a problem hiding this comment.
Should these check if the client has the capability?
3 participants
Summary
Add support for tool use within sampling requests, as described in the MCP 2025-11-25 spec's sampling.tools capability.
New types
Content types:
Capability types:
Tool-enabled sampling (parallel tool calls):
Design
Following the TypeScript SDK's pattern, tool-enabled sampling uses separate types from basic sampling to avoid breaking the existing API. The basic CreateMessage/CreateMessageResult path
is unchanged.
Both paths share the same wire method (sampling/createMessage) and go through the method info table. The table uses the broader CreateMessageWithToolsResult type internally;
CreateMessage downconverts (erroring if multiple content blocks are returned). This is documented as a rough edge to unify in v2.
Setting CreateMessageWithToolsHandler automatically infers the sampling.tools capability. It is a panic to set both CreateMessageHandler and CreateMessageWithToolsHandler.
References