JSON-RPC method names and message construction/parsing helpers. More...

#include <array>
#include <optional>
#include <string>
#include <string_view>
#include <variant>
#include "cxxmcp/core/result.hpp"
#include "cxxmcp/core/string_constant.hpp"
#include "cxxmcp/protocol/types.hpp"

Macros
#define	CXXMCP_PROTOCOL_STRING_CONSTANT(name, value) inline constexpr core::StringConstant name { value }

Functions
	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (JsonRpcVersion, "2.0")
	JSON-RPC protocol version string placed in message envelopes.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (McpProtocolVersion2025_11_25, "2025-11-25")

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (McpProtocolVersion2025_06_18, "2025-06-18")

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (McpProtocolVersion2025_03_26, "2025-03-26")

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (McpProtocolVersion2024_11_05, "2024-11-05")

bool	mcp::protocol::is_supported_protocol_version (std::string_view version) noexcept
	Returns true when a peer protocol version is supported.

std::optional< std::string_view >	mcp::protocol::negotiate_protocol_version (std::string_view requested) noexcept
	Returns the peer-requested version when known.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (InitializeMethod, "initialize")
	`initialize` request method for lifecycle negotiation.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (InitializedMethod, "notifications/initialized")
	Notification sent after a successful initialize response.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (PingMethod, "ping")
	Lightweight liveness request.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (ServerDiscoverMethod, "server/discover")
	Stateless server discovery (SEP-2575).

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (PromptsListMethod, "prompts/list")
	Lists available prompts.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (PromptsGetMethod, "prompts/get")
	Retrieves a prompt by name and arguments.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (ResourcesListMethod, "resources/list")
	Lists concrete resources.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (ResourcesReadMethod, "resources/read")
	Reads resource contents by URI.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (ResourcesTemplatesListMethod, "resources/templates/list")
	Lists URI templates that can produce resources.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (ResourcesSubscribeMethod, "resources/subscribe")
	Subscribes to updates for a resource URI.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (ResourcesUnsubscribeMethod, "resources/unsubscribe")
	Removes a resource subscription.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (ToolsListMethod, "tools/list")
	Lists callable tools.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (ToolsGetMethod, "tools/get")
	Retrieves a tool definition.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (ToolsCallMethod, "tools/call")
	Calls a named tool with JSON arguments.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (CompletionCompleteMethod, "completion/complete")
	Completes a prompt or resource-template argument value.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (LoggingSetLevelMethod, "logging/setLevel")
	Updates the minimum logging level the peer should emit.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (SamplingCreateMessageMethod, "sampling/createMessage")
	Requests client-side model sampling.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (ElicitationCreateMethod, "elicitation/create")
	Requests user input through MCP elicitation.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (ElicitationCompleteNotificationMethod, "notifications/elicitation/complete")
	Notification that a URL-based elicitation interaction completed.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (TasksListMethod, "tasks/list")
	Lists asynchronous tasks known to the peer.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (TasksGetMethod, "tasks/get")
	Retrieves a task by id.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (TasksCancelMethod, "tasks/cancel")
	Requests cancellation of a task.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (TasksResultMethod, "tasks/result")
	Retrieves the result associated with a completed task.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (TasksCreateMethod, "tasks/create")
	Server-to-client request to create a new task.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (TasksStatusNotificationMethod, "notifications/tasks/status")
	Notification carrying task status updates.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (RootsListMethod, "roots/list")
	Lists client roots available to the server.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (CancelledNotificationMethod, "notifications/cancelled")
	JSON-RPC cancellation notification.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (ProgressNotificationMethod, "notifications/progress")
	JSON-RPC progress notification.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (RootsListChangedNotificationMethod, "notifications/roots/list_changed")
	Notification that the client root list changed.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (ResourcesListChangedNotificationMethod, "notifications/resources/list_changed")
	Notification that the server resource list changed.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (ResourcesUpdatedNotificationMethod, "notifications/resources/updated")
	Notification that one subscribed resource was updated.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (ToolsListChangedNotificationMethod, "notifications/tools/list_changed")
	Notification that the server tool list changed.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (PromptsListChangedNotificationMethod, "notifications/prompts/list_changed")
	Notification that the server prompt list changed.

	mcp::protocol::CXXMCP_PROTOCOL_STRING_CONSTANT (LoggingMessageNotificationMethod, "notifications/message")
	Notification carrying a logging message.

ErrorObject	mcp::protocol::make_error (int code, std::string message, std::optional< Json > data=std::nullopt)
	Builds a JSON-RPC error object.

ErrorObject	mcp::protocol::make_error (ErrorCode code, std::string message, std::optional< Json > data=std::nullopt)
	Builds a JSON-RPC error object from a typed error code.

JsonRpcResponse	mcp::protocol::make_response (RequestId id, Json result)
	Builds a successful JSON-RPC response.

JsonRpcResponse	mcp::protocol::make_error_response (std::optional< RequestId > id, ErrorObject error)
	Builds an error JSON-RPC response.

JsonRpcRequest	mcp::protocol::make_request (std::string method, RequestId id, Json params=Json::object())
	Builds a generic JSON-RPC request envelope.

JsonRpcNotification	mcp::protocol::make_notification (std::string method, Json params=Json::object())
	Builds a generic JSON-RPC notification envelope.

JsonRpcRequest	mcp::protocol::make_initialize_request (RequestId id, Json params=Json::object())
	Builds an `initialize` lifecycle request.

JsonRpcNotification	mcp::protocol::make_initialized_notification (Json params=Json::object())
	Builds an initialized lifecycle notification.

JsonRpcRequest	mcp::protocol::make_ping_request (RequestId id, Json params=Json::object())
	Builds a `ping` liveness request.

core::Result< JsonRpcMessage >	mcp::protocol::parse_message (std::string_view text)
	Parses any JSON-RPC message shape from text.

core::Result< std::string >	mcp::protocol::serialize_message (const JsonRpcMessage &message)
	Serializes any JSON-RPC message shape to JSON text.

core::Result< JsonRpcRequest >	mcp::protocol::parse_request (std::string_view text)
	Parses a JSON-RPC request envelope from text.

core::Result< JsonRpcResponse >	mcp::protocol::parse_response (std::string_view text)
	Parses a JSON-RPC response envelope from text.

core::Result< JsonRpcNotification >	mcp::protocol::parse_notification (std::string_view text)
	Parses a JSON-RPC notification envelope from text.

core::Result< std::string >	mcp::protocol::serialize_request (const JsonRpcRequest &request)
	Serializes a JSON-RPC request envelope to text.

core::Result< std::string >	mcp::protocol::serialize_response (const JsonRpcResponse &response)
	Serializes a JSON-RPC response envelope to text.

core::Result< std::string >	mcp::protocol::serialize_notification (const JsonRpcNotification &notification)
	Serializes a JSON-RPC notification envelope to text.

core::Result< std::string >	mcp::protocol::serialize_error (const ErrorObject &error, std::optional< RequestId > id=std::nullopt)
	Serializes a JSON-RPC error response to text.

Variables
constexpr core::StringConstant	mcp::protocol::McpProtocolVersion {"2025-11-25"}
	Latest MCP protocol version advertised during initialization.

constexpr std::array< const char *, 5 >	mcp::protocol::McpSupportedProtocolVersions
	Protocol versions accepted by this SDK during initialization.

Detailed Description

JSON-RPC method names and message construction/parsing helpers.

This header ties the protocol DTOs to the JSON-RPC wire format. Method name constants are the canonical strings used in request and notification envelopes; helper functions build, parse, and serialize those envelopes without changing feature-specific payload semantics.

Function Documentation

◆ make_error() [1/2]

ErrorObject mcp::protocol::make_error	(	ErrorCode	code,
		std::string	message,
		std::optional< Json >	data = `std::nullopt`
	)

Builds a JSON-RPC error object from a typed error code.

Parameters

code	Error code enum value.
message	Human-readable diagnostic text.
data	Optional structured error details.

Returns: Error object ready to place in a response.

◆ make_error() [2/2]

ErrorObject mcp::protocol::make_error	(	int	code,
		std::string	message,
		std::optional< Json >	data = `std::nullopt`
	)

Builds a JSON-RPC error object.

Parameters

code	Numeric JSON-RPC or MCP error code.
message	Human-readable diagnostic text.
data	Optional structured error details.

Returns: Error object ready to place in a response.

◆ make_error_response()

JsonRpcResponse mcp::protocol::make_error_response	(	std::optional< RequestId >	id,
		ErrorObject	error
	)

Builds an error JSON-RPC response.

Parameters

id	Request id to echo, or nullopt for parse-level errors.
error	Error object to serialize.

Returns: Response envelope with error set.

◆ make_initialize_request()

JsonRpcRequest mcp::protocol::make_initialize_request	(	RequestId	id,
		Json	params = `Json::object()`
	)

Builds an initialize lifecycle request.

Parameters

id	Request id assigned by the caller.
params	Initialize params object.

Returns: Request envelope using InitializeMethod.

◆ make_initialized_notification()

JsonRpcNotification mcp::protocol::make_initialized_notification ( Json params = Json::object() )

Builds an initialized lifecycle notification.

Parameters

params Optional initialized notification params.

Returns: Notification envelope using InitializedMethod.

◆ make_notification()

JsonRpcNotification mcp::protocol::make_notification	(	std::string	method,
		Json	params = `Json::object()`
	)

Builds a generic JSON-RPC notification envelope.

Parameters

method	MCP notification method name.
params	Notification params object.

Returns: Notification envelope ready for serialization.

◆ make_ping_request()

JsonRpcRequest mcp::protocol::make_ping_request	(	RequestId	id,
		Json	params = `Json::object()`
	)

Builds a ping liveness request.

Parameters

id	Request id assigned by the caller.
params	Optional ping params.

Returns: Request envelope using PingMethod.

◆ make_request()

JsonRpcRequest mcp::protocol::make_request	(	std::string	method,
		RequestId	id,
		Json	params = `Json::object()`
	)

Builds a generic JSON-RPC request envelope.

Parameters

method	MCP method name.
id	Request id assigned by the caller.
params	Method-specific params object.

Returns: Request envelope ready for serialization.

◆ make_response()

JsonRpcResponse mcp::protocol::make_response	(	RequestId	id,
		Json	result
	)

Builds a successful JSON-RPC response.

Parameters

id	Request id to echo.
result	Method-specific result object.

Returns: Response envelope with result set.

◆ parse_message()

core::Result< JsonRpcMessage > mcp::protocol::parse_message ( std::string_view text )

Parses any JSON-RPC message shape from text.

Parameters

text	UTF-8 JSON text.

Returns: Parsed request, response, or notification, or an error on invalid JSON-RPC.

◆ serialize_error()

core::Result< std::string > mcp::protocol::serialize_error	(	const ErrorObject &	error,
		std::optional< RequestId >	id = `std::nullopt`
	)

Serializes a JSON-RPC error response to text.

Parameters

error	Error object to encode.
id	Optional request id, omitted for parse-level errors.

Returns: JSON-RPC response text containing the error.

◆ serialize_message()

core::Result< std::string > mcp::protocol::serialize_message ( const JsonRpcMessage & message )

Serializes any JSON-RPC message shape to JSON text.

Parameters

message Message envelope to encode.

Returns: JSON text, or an error if the envelope is inconsistent.

Variable Documentation

◆ McpSupportedProtocolVersions

constexpr std::array<const char*, 5> mcp::protocol::McpSupportedProtocolVersions

inlineconstexpr

Initial value:

{

"2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25", "DRAFT-2026-v1"}

Protocol versions accepted by this SDK during initialization.

Macros

Functions

Variables

Detailed Description

Function Documentation

◆ make_error() [1/2]

◆ make_error() [2/2]

◆ make_error_response()

◆ make_initialize_request()

◆ make_initialized_notification()

◆ make_notification()

◆ make_ping_request()

◆ make_request()

◆ make_response()

◆ parse_message()

◆ serialize_error()

◆ serialize_message()

Variable Documentation

◆ McpSupportedProtocolVersions