Tool definition, call, and result payloads. More...

#include <algorithm>
#include <cctype>
#include <cstdint>
#include <optional>
#include <string>
#include <string_view>
#include <unordered_map>
#include <unordered_set>
#include <utility>
#include <vector>
#include "cxxmcp/core/result.hpp"
#include "cxxmcp/protocol/annotations.hpp"
#include "cxxmcp/protocol/resource.hpp"
#include "cxxmcp/protocol/schema.hpp"
#include "cxxmcp/protocol/task.hpp"
#include "cxxmcp/protocol/types.hpp"
#include "cxxmcp/protocol/types_reflect.hpp"

Classes
struct	mcp::protocol::ToolExecution
	Execution configuration advertised with a tool definition. More...

struct	mcp::protocol::Reflect< ToolExecution >

struct	mcp::protocol::JsonFieldTraits< ToolExecution >

struct	mcp::protocol::ContentBlock
	A single content item returned by a tool or embedded in prompts. More...

struct	mcp::protocol::ToolDefinition
	Metadata describing a callable MCP tool. More...

class	mcp::protocol::ToolDefinitionBuilder
	Fluent builder for advertised MCP tool metadata. More...

struct	mcp::protocol::ToolCall
	Parameters for `tools/call`. More...

struct	mcp::protocol::Reflect< ToolCall >

struct	mcp::protocol::ToolsListResult
	Result object for `tools/list`. More...

struct	mcp::protocol::ToolResult
	Result object for `tools/call`. More...

struct	mcp::protocol::JsonFieldTraits< TaskSupport >

struct	mcp::protocol::XHeaderEntry
	One x-mcp-header annotation extracted from a tool input schema. More...

Enumerations
enum class	mcp::protocol::TaskSupport { Forbidden , Optional , Required }
	Per-tool support mode for task-based invocation. More...

Functions
	mcp::protocol::CXXMCP_REFLECT_CHECK (ToolExecution, 1)

ToolDefinitionBuilder	mcp::protocol::tool_definition (std::string name)
	Creates a fluent builder for advertised MCP tool metadata.

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

std::string_view	mcp::protocol::task_support_to_string (TaskSupport support) noexcept
	Converts a task support mode to the lowercase wire value.

std::optional< TaskSupport >	mcp::protocol::task_support_from_string (std::string_view value) noexcept
	Parses a lowercase task support wire value.

bool	mcp::protocol::is_valid_base64 (std::string_view value) noexcept
	Returns true when value is canonical RFC 4648 base64 with padding.

Json	mcp::protocol::tool_execution_to_json (const ToolExecution &execution)
	Serializes tool execution configuration.

core::Result< ToolExecution >	mcp::protocol::tool_execution_from_json (const Json &json)
	Parses tool execution configuration.

Json	mcp::protocol::content_block_to_json (const ContentBlock &block)
	Serializes a content block.

core::Result< std::string >	mcp::protocol::required_content_string (const Json &json, std::string_view member, std::string message)
	Reads a required string member from a content object.

core::Result< ContentBlock >	mcp::protocol::content_block_from_json (const Json &json)
	Parses a content block from JSON.

Json	mcp::protocol::tool_definition_to_json (const ToolDefinition &definition)
	Serializes a tool definition as returned by tool discovery.

core::Result< ToolDefinition >	mcp::protocol::tool_definition_from_json (const Json &json)
	Parses a tool definition from JSON.

Json	mcp::protocol::tools_list_result_to_json (const ToolsListResult &result)
	Serializes a `tools/list` result.

core::Result< ToolsListResult >	mcp::protocol::tools_list_result_from_json (const Json &json)
	Parses a `tools/list` result.

Json	mcp::protocol::tool_call_to_json (const ToolCall &call)
	Serializes `tools/call` params.

core::Result< ToolCall >	mcp::protocol::tool_call_from_json (const Json &json)
	Parses `tools/call` params.

Json	mcp::protocol::tool_result_to_json (const ToolResult &result)
	Serializes a tool result.

core::Result< ToolResult >	mcp::protocol::tool_result_from_json (const Json &json)
	Parses a tool result.

std::vector< XHeaderEntry >	mcp::protocol::extract_x_mcp_headers (const Json &input_schema)
	Extracts x-mcp-header annotations from a tool inputSchema.

bool	mcp::protocol::validate_tool_x_headers (const std::vector< XHeaderEntry > &entries)
	Validates x-mcp-header annotations per SEP-2243 constraints.

bool	mcp::protocol::needs_base64_encoding (std::string_view value)
	Checks if a string value needs Base64 encoding per SEP-2243.

std::string	mcp::protocol::base64_encode (std::string_view input)
	Standard RFC 4648 base64 encoding.

std::string	mcp::protocol::encode_header_value (std::string_view value)
	Encodes a string value for an Mcp-Param-* header per SEP-2243.

std::string	mcp::protocol::number_to_header_string (const Json &value)
	Converts a JSON number to its string representation.

std::unordered_map< std::string, std::string >	mcp::protocol::build_tool_param_headers (const Json &arguments, const std::vector< XHeaderEntry > &entries)
	Builds Mcp-Param-* transport headers from tool arguments and schema.

Detailed Description

Tool definition, call, and result payloads.

Tools are server-advertised operations invoked through tools/call. Definitions are returned by listing or lookup methods, calls carry JSON arguments, and results return content blocks plus optional structured data.

Enumeration Type Documentation

◆ TaskSupport

enum class mcp::protocol::TaskSupport

strong

Per-tool support mode for task-based invocation.

Enumerator
Forbidden	Clients must not invoke this tool as a task.
Optional	Clients may invoke this tool normally or as a task.
Required	Clients must invoke this tool as a task.

Function Documentation

◆ build_tool_param_headers()

std::unordered_map< std::string, std::string > mcp::protocol::build_tool_param_headers	(	const Json &	arguments,
		const std::vector< XHeaderEntry > &	entries
	)

inline

Builds Mcp-Param-* transport headers from tool arguments and schema.

Inspects the tool inputSchema for x-mcp-header annotations and converts matching argument values to HTTP header values per SEP-2243.

◆ content_block_from_json()

core::Result< ContentBlock > mcp::protocol::content_block_from_json ( const Json & json )

inline

Parses a content block from JSON.

Returns: Parsed block or validation error.

◆ tool_call_from_json()

core::Result< ToolCall > mcp::protocol::tool_call_from_json ( const Json & json )

inline

Parses tools/call params.

Returns: Parsed call or validation error.

◆ tool_definition_from_json()

core::Result< ToolDefinition > mcp::protocol::tool_definition_from_json ( const Json & json )

inline

Parses a tool definition from JSON.

Returns: Parsed definition or validation error.

◆ tool_execution_from_json()

core::Result< ToolExecution > mcp::protocol::tool_execution_from_json ( const Json & json )

inline

Parses tool execution configuration.

Returns: Parsed execution configuration or validation error.

◆ tool_json_error()

core::Error mcp::protocol::tool_json_error ( std::string message )

inline

Builds an InvalidRequest error for tool JSON validation failures.

Parameters

message Validation diagnostic.

Returns: Core error carrying the MCP invalid-request code.

◆ tool_result_from_json()

core::Result< ToolResult > mcp::protocol::tool_result_from_json ( const Json & json )

inline

Parses a tool result.

Returns: Parsed result or validation error.

◆ tools_list_result_from_json()

core::Result< ToolsListResult > mcp::protocol::tools_list_result_from_json ( const Json & json )

inline

Parses a tools/list result.

Returns: Parsed result or validation error.

◆ validate_tool_x_headers()

bool mcp::protocol::validate_tool_x_headers ( const std::vector< XHeaderEntry > & entries )

inline

Validates x-mcp-header annotations per SEP-2243 constraints.

Returns true if all headers are valid (tool should be kept).

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ TaskSupport

Function Documentation

◆ build_tool_param_headers()

◆ content_block_from_json()

◆ tool_call_from_json()

◆ tool_definition_from_json()

◆ tool_execution_from_json()

◆ tool_json_error()

◆ tool_result_from_json()

◆ tools_list_result_from_json()

◆ validate_tool_x_headers()