Shared JSON, JSON-RPC, error, cancellation, and progress model types. More...

#include <cmath>
#include <cstddef>
#include <cstdint>
#include <initializer_list>
#include <nlohmann/json.hpp>
#include <optional>
#include <string>
#include <string_view>
#include <unordered_map>
#include <utility>
#include <variant>
#include <vector>

Classes
struct	mcp::protocol::PaginatedRequestParams
	Shared pagination params for MCP list requests that use `cursor`. More...

struct	mcp::protocol::ErrorObject
	JSON-RPC error object. More...

struct	mcp::protocol::JsonRpcRequest
	JSON-RPC request envelope carrying an MCP method invocation. More...

struct	mcp::protocol::JsonRpcResponse
	JSON-RPC response envelope for either success or failure. More...

struct	mcp::protocol::JsonRpcNotification
	JSON-RPC notification envelope for one-way MCP messages. More...

struct	mcp::protocol::Icon
	Icon descriptor used by tools, resources, resource templates, and prompts. More...

struct	mcp::protocol::CancelledNotificationParams
	Parameters for `notifications/cancelled`. More...

struct	mcp::protocol::ProgressNotificationParams
	Parameters for `notifications/progress`. More...

Typedefs
using	mcp::protocol::Json = nlohmann::json
	JSON value type used by all protocol DTOs.

using	mcp::protocol::Meta = Json
	Protocol `_meta` object used by request params, results, and notifications.

using	mcp::protocol::RequestId = std::variant< std::int64_t, std::string >
	JSON-RPC request or response identifier.

using	mcp::protocol::JsonRpcMessage = std::variant< JsonRpcRequest, JsonRpcResponse, JsonRpcNotification >
	Variant over the JSON-RPC message shapes accepted by MCP transports.

using	mcp::protocol::ProgressToken = std::variant< std::int64_t, std::string >
	Identifier used to associate progress notifications with a request.

Enumerations
enum class	mcp::protocol::ErrorCode : int { ParseError = -32700 , InvalidRequest = -32600 , MethodNotFound = -32601 , InvalidParams = -32602 , InternalError = -32603 , ToolNotFound = -32000 , ResourceNotFound = -32002 , PermissionDenied = -32005 , RateLimited = -32003 , UrlElicitationRequired = -32042 }
	JSON-RPC and MCP-specific error codes used in ErrorObject. More...

enum class	mcp::protocol::IconTheme { Light , Dark }
	Preferred icon variant for clients with light or dark surfaces. More...

Functions
bool	mcp::protocol::protocol_number_is_finite (double value) noexcept
	Returns true for finite JSON floating-point values accepted by MCP.

Json	mcp::protocol::request_id_to_json (const RequestId &id)
	Converts a RequestId to the JSON scalar used by JSON-RPC.

std::optional< RequestId >	mcp::protocol::request_id_from_json (const Json &json)
	Parses a JSON-RPC request id.

std::string_view	mcp::protocol::icon_theme_to_string (IconTheme theme) noexcept
	Converts an icon theme enum to the lowercase wire value.

std::optional< IconTheme >	mcp::protocol::icon_theme_from_string (std::string_view value) noexcept
	Parses a lowercase icon theme wire value.

Json	mcp::protocol::progress_token_to_json (const ProgressToken &token)
	Converts a progress token to the JSON scalar form used in metadata.

std::optional< ProgressToken >	mcp::protocol::progress_token_from_json (const Json &json)
	Parses a progress token from JSON.

bool	mcp::protocol::meta_is_object (const Json &meta) noexcept
	Returns true when a value is a valid protocol `_meta` object.

bool	mcp::protocol::json_key_is_known (std::string_view key, std::initializer_list< std::string_view > known_keys)
	Returns true when a JSON object key is part of a typed DTO shape.

Json	mcp::protocol::collect_json_extensions (const Json &json, std::initializer_list< std::string_view > known_keys)
	Collects unknown object members so typed DTOs can preserve future protocol fields and vendor extensions.

Json	mcp::protocol::collect_json_extensions (const Json &json, const std::vector< std::string > &known_keys)
	Overload accepting a vector of string keys.

void	mcp::protocol::append_json_extensions (Json &json, const Json &extensions)
	Flattens extension members into a JSON object without overwriting typed fields.

Json	mcp::protocol::paginated_request_params_to_json (const PaginatedRequestParams &params)
	Serializes shared pagination params for MCP list requests.

std::optional< PaginatedRequestParams >	mcp::protocol::paginated_request_params_from_json (const Json &json)
	Parses shared pagination params for MCP list requests.

Meta	mcp::protocol::meta_with_progress_token (ProgressToken token)
	Creates a metadata object carrying a progress token.

std::optional< ProgressToken >	mcp::protocol::meta_progress_token (const Json &meta)
	Reads `progressToken` from a metadata object.

bool	mcp::protocol::set_meta_progress_token (Json &meta, ProgressToken token)
	Sets `progressToken` on an existing metadata object.

Detailed Description

Shared JSON, JSON-RPC, error, cancellation, and progress model types.

These declarations describe the transport-level envelopes that carry MCP method payloads. Feature-specific headers define the params and result objects used inside these JSON-RPC messages.

Typedef Documentation

◆ Meta

using mcp::protocol::Meta = typedef Json

Protocol _meta object used by request params, results, and notifications.

The SDK keeps metadata as JSON for forward compatibility, while helper functions below provide typed access to well-known MCP metadata members.

◆ RequestId

using mcp::protocol::RequestId = typedef std::variant<std::int64_t, std::string>

JSON-RPC request or response identifier.

JSON-RPC permits string and integer ids. Notifications intentionally do not carry a RequestId because they never receive a response.

Enumeration Type Documentation

◆ ErrorCode

enum class mcp::protocol::ErrorCode : int

strong

JSON-RPC and MCP-specific error codes used in ErrorObject.

Values in the JSON-RPC reserved range keep their standard meaning. Negative MCP-specific values represent SDK-level protocol failures such as missing tools, permission failures, or URL elicitation requirements.

Aligned with the MCP 2025-11-25 specification for standard error codes.

Enumerator
ParseError	Invalid JSON text was received.
InvalidRequest	The JSON value was not a valid JSON-RPC request.
MethodNotFound	The JSON-RPC method name is unknown to the peer.
InvalidParams	The request `params` object failed protocol validation.
InternalError	The peer failed while handling an otherwise valid request.
ToolNotFound	The named tool does not exist or is not available.
ResourceNotFound	The requested resource URI does not exist or is not available.
PermissionDenied	The caller is not allowed to perform the requested operation.
RateLimited	The request was rejected by rate limiting policy.
UrlElicitationRequired	The operation requires URL-based elicitation before it can continue.

◆ IconTheme

enum class mcp::protocol::IconTheme

strong

Preferred icon variant for clients with light or dark surfaces.

Enumerator
Light	Icon intended for a light UI theme.
Dark	Icon intended for a dark UI theme.

Function Documentation

◆ meta_progress_token()

std::optional< ProgressToken > mcp::protocol::meta_progress_token ( const Json & meta )

inline

Reads progressToken from a metadata object.

Invalid metadata shapes or invalid token values return nullopt.

◆ paginated_request_params_from_json()

std::optional< PaginatedRequestParams > mcp::protocol::paginated_request_params_from_json ( const Json & json )

inline

Parses shared pagination params for MCP list requests.

Returns nullopt when params is not an object, cursor is not a string, or _meta is present but is not an object.

◆ progress_token_from_json()

std::optional< ProgressToken > mcp::protocol::progress_token_from_json ( const Json & json )

inline

Parses a progress token from JSON.

Parameters

json	JSON value to inspect.

Returns: A ProgressToken when the value is an integer or string; otherwise nullopt.

◆ progress_token_to_json()

Json mcp::protocol::progress_token_to_json ( const ProgressToken & token )

inline

Converts a progress token to the JSON scalar form used in metadata.

Parameters

token Progress token to encode.

Returns: A JSON integer or string.

◆ request_id_from_json()

std::optional< RequestId > mcp::protocol::request_id_from_json ( const Json & json )

inline

Parses a JSON-RPC request id.

Parameters

json	JSON value to inspect.

Returns: A RequestId when the value is an integer or string; otherwise nullopt.

◆ request_id_to_json()

Json mcp::protocol::request_id_to_json ( const RequestId & id )

inline

Converts a RequestId to the JSON scalar used by JSON-RPC.

Parameters

id	Request id to encode.

Returns: A JSON integer or string.

◆ set_meta_progress_token()

bool mcp::protocol::set_meta_progress_token	(	Json &	meta,
		ProgressToken	token
	)

inline

Sets progressToken on an existing metadata object.

Returns: False if meta is not an object.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ Meta

◆ RequestId

Enumeration Type Documentation

◆ ErrorCode

◆ IconTheme

Function Documentation

◆ meta_progress_token()

◆ paginated_request_params_from_json()

◆ progress_token_from_json()

◆ progress_token_to_json()

◆ request_id_from_json()

◆ request_id_to_json()

◆ set_meta_progress_token()