Client-side model sampling request and response payloads. More...

#include <algorithm>
#include <cmath>
#include <optional>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
#include "cxxmcp/core/result.hpp"
#include "cxxmcp/protocol/task.hpp"
#include "cxxmcp/protocol/tool.hpp"
#include "cxxmcp/protocol/types.hpp"

Classes
struct	mcp::protocol::ToolChoice
	Tool selection behavior supplied to `sampling/createMessage`. More...

struct	mcp::protocol::ToolUseContent
	Assistant-side tool call request embedded in sampling content. More...

struct	mcp::protocol::ToolResultContent
	User-side result for a prior sampling tool call. More...

struct	mcp::protocol::SamplingMessageContent
	One sampling message content item. More...

struct	mcp::protocol::SamplingMessage
	Input message supplied to a sampling request. More...

struct	mcp::protocol::ModelHint
	Soft model name hint for sampling. More...

struct	mcp::protocol::Reflect< ModelHint >

struct	mcp::protocol::ModelPreferences
	Preferences used by the client when choosing a model. More...

struct	mcp::protocol::CreateMessageParams
	Parameters for `sampling/createMessage`. More...

struct	mcp::protocol::CreateMessageResult
	Result object for `sampling/createMessage`. More...

struct	mcp::protocol::JsonFieldTraits< ToolChoiceMode >

Enumerations
enum class	mcp::protocol::ContextInclusion { AllServers , None , ThisServer }
	Context inclusion mode for sampling requests. More...

enum class	mcp::protocol::Role { User , Assistant }
	Message role for sampling messages. More...

enum class	mcp::protocol::ToolChoiceMode { Auto , Required , None }
	Tool selection mode for SEP-1577 sampling requests. More...

Functions
std::string_view	mcp::protocol::to_string (Role role) noexcept
	Converts a Role to its lowercase wire representation.

std::optional< Role >	mcp::protocol::from_string_role (std::string_view value) noexcept
	Parses a Role from its wire string.

core::Error	mcp::protocol::sampling_json_error (std::string message)
	Builds an InvalidRequest error for sampling JSON validation failures.

bool	mcp::protocol::sampling_role_is_valid (std::string_view role) noexcept
	Returns true for the MCP sampling message roles.

bool	mcp::protocol::sampling_role_is_valid (Role) noexcept
	Returns true for the MCP sampling message roles (enum overload).

std::string_view	mcp::protocol::context_inclusion_to_string (ContextInclusion mode)
	Converts a context-inclusion mode to the camelCase wire value.

std::optional< ContextInclusion >	mcp::protocol::context_inclusion_from_string (std::string_view value)
	Parses a context-inclusion mode string.

bool	mcp::protocol::sampling_include_context_is_valid (std::string_view value) noexcept
	Returns true for the MCP sampling includeContext values.

bool	mcp::protocol::sampling_number_is_finite (double value) noexcept
	Returns true for finite JSON numbers accepted by sampling.

core::Result< core::Unit >	mcp::protocol::validate_sampling_message_content_roles (const SamplingMessage &message)
	Validates SEP-1577 tool-use/tool-result placement for one message.

core::Result< core::Unit >	mcp::protocol::validate_sampling_tool_use_result_balance (const std::vector< SamplingMessage > &messages)
	Validates that every sampling tool result answers a prior tool use.

std::string	mcp::protocol::tool_choice_mode_to_string (ToolChoiceMode mode)
	Converts a tool-choice mode to the lowercase wire value.

std::optional< ToolChoiceMode >	mcp::protocol::tool_choice_mode_from_string (const std::string &value)
	Parses a tool-choice mode string.

Json	mcp::protocol::tool_choice_to_json (const ToolChoice &choice)
	Serializes tool-choice behavior.

core::Result< ToolChoice >	mcp::protocol::tool_choice_from_json (const Json &json)
	Parses tool-choice behavior.

Json	mcp::protocol::tool_use_content_to_json (const ToolUseContent &content)
	Serializes assistant-side sampling tool use content.

core::Result< ToolUseContent >	mcp::protocol::tool_use_content_from_json (const Json &json)
	Parses assistant-side sampling tool use content.

Json	mcp::protocol::tool_result_content_to_json (const ToolResultContent &content)
	Serializes user-side sampling tool result content.

core::Result< ToolResultContent >	mcp::protocol::tool_result_content_from_json (const Json &json)
	Parses user-side sampling tool result content.

Json	mcp::protocol::sampling_message_content_to_json (const SamplingMessageContent &content)
	Serializes one sampling message content item.

core::Result< SamplingMessageContent >	mcp::protocol::sampling_message_content_from_json (const Json &json)
	Parses one sampling message content item.

Json	mcp::protocol::sampling_message_to_json (const SamplingMessage &message)
	Serializes a sampling message.

core::Result< SamplingMessage >	mcp::protocol::sampling_message_from_json (const Json &json)
	Parses a sampling message.

Json	mcp::protocol::model_hint_to_json (const ModelHint &hint)
	Serializes a model hint.

core::Result< ModelHint >	mcp::protocol::model_hint_from_json (const Json &json)
	Parses a model hint.

Json	mcp::protocol::model_preferences_to_json (const ModelPreferences &preferences)
	Serializes model preferences.

core::Result< ModelPreferences >	mcp::protocol::model_preferences_from_json (const Json &json)
	Parses model preferences.

Json	mcp::protocol::create_message_params_to_json (const CreateMessageParams &params)
	Serializes `sampling/createMessage` params.

core::Result< CreateMessageParams >	mcp::protocol::create_message_params_from_json (const Json &json)
	Parses `sampling/createMessage` params.

Json	mcp::protocol::create_message_result_to_json (const CreateMessageResult &result)
	Serializes a `sampling/createMessage` result.

core::Result< CreateMessageResult >	mcp::protocol::create_message_result_from_json (const Json &json)
	Parses a `sampling/createMessage` result.

Detailed Description

Client-side model sampling request and response payloads.

Sampling lets a server ask a capable client to create a model message through sampling/createMessage. The request carries chat-like messages, optional model preferences, and generation controls; the response carries one generated message and the model that produced it.

Enumeration Type Documentation

◆ ContextInclusion

enum class mcp::protocol::ContextInclusion

strong

Context inclusion mode for sampling requests.

Enumerator
AllServers	Include context from all servers.
None	Do not include any server context.
ThisServer	Include context only from the requesting server.

◆ Role

enum class mcp::protocol::Role

strong

Message role for sampling messages.

Enumerator
User	The human/user participant.
Assistant	The model/assistant participant.

◆ ToolChoiceMode

enum class mcp::protocol::ToolChoiceMode

strong

Tool selection mode for SEP-1577 sampling requests.

Enumerator
Auto	Let the model decide whether to use tools.
Required	Require at least one tool use.
None	Do not allow tool use.

Function Documentation

◆ create_message_params_from_json()

core::Result< CreateMessageParams > mcp::protocol::create_message_params_from_json ( const Json & json )

inline

Parses sampling/createMessage params.

Returns: Parsed params or validation error.

◆ create_message_result_from_json()

core::Result< CreateMessageResult > mcp::protocol::create_message_result_from_json ( const Json & json )

inline

Parses a sampling/createMessage result.

Returns: Parsed result or validation error.

◆ from_string_role()

std::optional< Role > mcp::protocol::from_string_role ( std::string_view value )

inlinenoexcept

Parses a Role from its wire string.

Returns: Parsed role, or nullopt for unrecognized strings.

◆ model_hint_from_json()

core::Result< ModelHint > mcp::protocol::model_hint_from_json ( const Json & json )

inline

Parses a model hint.

Returns: Parsed hint or validation error.

◆ model_preferences_from_json()

core::Result< ModelPreferences > mcp::protocol::model_preferences_from_json ( const Json & json )

inline

Parses model preferences.

Returns: Parsed preferences or validation error.

◆ sampling_message_from_json()

core::Result< SamplingMessage > mcp::protocol::sampling_message_from_json ( const Json & json )

inline

Parses a sampling message.

Returns: Parsed message or validation error.

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ContextInclusion

◆ Role

◆ ToolChoiceMode

Function Documentation

◆ create_message_params_from_json()

◆ create_message_result_from_json()

◆ from_string_role()

◆ model_hint_from_json()

◆ model_preferences_from_json()

◆ sampling_message_from_json()