mcp: implement sampling with tools #699
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
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
Contributor
Author
|
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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