14namespace mcp::server {
17inline core::Error handler_method_not_found(std::string_view message) {
19 static_cast<int>(protocol::ErrorCode::MethodNotFound),
28 using JsonContextHandler = Server::JsonContextHandler;
29 using JsonRequestContextHandler = Server::JsonRequestContextHandler;
48 virtual std::optional<core::Result<protocol::ToolsListResult>> on_list_tools(
52 virtual std::optional<core::Result<protocol::ToolsListResult>> on_list_tools(
56 return on_list_tools(context);
58 virtual std::optional<core::Result<protocol::ToolDefinition>> on_get_tool(
62 virtual std::optional<core::Result<protocol::PromptsListResult>>
66 virtual std::optional<core::Result<protocol::PromptsListResult>>
70 return on_list_prompts(context);
72 virtual std::optional<core::Result<protocol::ResourcesListResult>>
76 virtual std::optional<core::Result<protocol::ResourcesListResult>>
80 return on_list_resources(context);
82 virtual std::optional<core::Result<protocol::ResourceTemplatesListResult>>
86 virtual std::optional<core::Result<protocol::ResourceTemplatesListResult>>
90 return on_list_resource_templates(context);
92 virtual std::optional<core::Result<protocol::ToolResult>> on_call_tool(
96 virtual std::optional<core::Result<protocol::ToolResult>> on_call_tool(
99 return on_call_tool(call);
101 virtual std::optional<core::Result<protocol::ToolResult>> on_call_tool(
105 return on_call_tool(call, context);
107 virtual std::optional<core::Result<protocol::PromptsGetResult>> on_get_prompt(
111 virtual std::optional<core::Result<protocol::PromptsGetResult>> on_get_prompt(
115 return on_get_prompt(params);
117 virtual std::optional<core::Result<protocol::PromptsGetResult>> on_get_prompt(
121 return on_get_prompt(params, context);
123 virtual std::optional<core::Result<protocol::ResourcesReadResult>>
127 virtual std::optional<core::Result<protocol::ResourcesReadResult>>
131 return on_read_resource(params);
133 virtual std::optional<core::Result<protocol::ResourcesReadResult>>
138 return on_read_resource(params, context);
141 virtual std::optional<core::Result<protocol::Json>> on_completion(
145 virtual std::optional<core::Result<protocol::Json>> on_completion(
148 return on_completion(params);
150 virtual std::optional<core::Result<protocol::Json>> on_completion(
154 return on_completion(params, context);
156 virtual std::optional<core::Result<protocol::Json>> on_sampling(
160 virtual std::optional<core::Result<protocol::Json>> on_sampling(
163 return on_sampling(params);
165 virtual std::optional<core::Result<protocol::Json>> on_sampling(
169 return on_sampling(params, context);
171 virtual std::optional<core::Result<protocol::Json>> on_set_level(
175 virtual std::optional<core::Result<protocol::Json>> on_set_level(
178 return on_set_level(params);
180 virtual std::optional<core::Result<protocol::Json>> on_set_level(
184 return on_set_level(params, context);
186 virtual std::optional<core::Result<protocol::Json>> on_subscribe(
190 virtual std::optional<core::Result<protocol::Json>> on_subscribe(
193 return on_subscribe(params);
195 virtual std::optional<core::Result<protocol::Json>> on_subscribe(
199 return on_subscribe(params, context);
201 virtual std::optional<core::Result<protocol::Json>> on_unsubscribe(
205 virtual std::optional<core::Result<protocol::Json>> on_unsubscribe(
208 return on_unsubscribe(params);
210 virtual std::optional<core::Result<protocol::Json>> on_unsubscribe(
214 return on_unsubscribe(params, context);
216 virtual void on_logging(std::string_view, std::string_view)
const {}
217 virtual std::optional<protocol::JsonRpcResponse> on_raw_request(
221 virtual std::optional<core::Result<core::Unit>> on_raw_notification(
225 virtual std::optional<protocol::JsonRpcResponse> on_custom_request(
228 return on_raw_request(request, context);
230 virtual std::optional<core::Result<core::Unit>> on_custom_notification(
233 return on_raw_notification(notification, context);
235 virtual std::optional<core::Result<protocol::TaskListResult>> on_task_list(
239 virtual std::optional<core::Result<protocol::TaskListResult>> on_task_list(
243 return on_task_list(params);
245 virtual std::optional<core::Result<protocol::Task>> on_task_get(
249 virtual std::optional<core::Result<protocol::Task>> on_task_get(
253 return on_task_get(params);
255 virtual std::optional<core::Result<protocol::Task>> on_task_cancel(
259 virtual std::optional<core::Result<protocol::Task>> on_task_cancel(
263 return on_task_cancel(params);
265 virtual std::optional<core::Result<protocol::Json>> on_task_result(
269 virtual std::optional<core::Result<protocol::Json>> on_task_result(
273 return on_task_result(params);
275 virtual std::optional<core::Result<core::Unit>> on_progress(
279 virtual std::optional<core::Result<core::Unit>> on_progress(
283 return on_progress(params);
285 virtual std::optional<core::Result<core::Unit>> on_roots_list_changed()
289 virtual std::optional<core::Result<core::Unit>> on_roots_list_changed(
292 return on_roots_list_changed();
294 virtual std::optional<core::Result<core::Unit>> on_tool_list_changed()
const {
297 virtual std::optional<core::Result<core::Unit>> on_tool_list_changed(
300 return on_tool_list_changed();
302 virtual std::optional<core::Result<core::Unit>> on_prompt_list_changed()
306 virtual std::optional<core::Result<core::Unit>> on_prompt_list_changed(
309 return on_prompt_list_changed();
311 virtual std::optional<core::Result<core::Unit>> on_resource_list_changed()
315 virtual std::optional<core::Result<core::Unit>> on_resource_list_changed(
318 return on_resource_list_changed();
320 virtual std::optional<core::Result<core::Unit>> on_resource_updated(
321 const std::string&)
const {
324 virtual std::optional<core::Result<core::Unit>> on_resource_updated(
327 return on_resource_updated(uri);
333 return protocol::make_error_response(
334 std::optional<protocol::RequestId>{request.
id},
338 : std::optional<protocol::Json>{error.
detail}));
341template <
class T,
class Serializer>
342inline std::optional<protocol::JsonRpcResponse> server_handler_result_response(
343 const protocol::JsonRpcRequest& request,
const core::Result<T>& result,
344 Serializer serializer) {
346 return server_handler_error_response(request, result.error());
348 return protocol::make_response(request.id, serializer(*result));
351inline std::optional<protocol::JsonRpcResponse>
352dispatch_server_handler_discovery_request(
353 const ServerHandlerInterface& handler,
354 const protocol::JsonRpcRequest& request,
const SessionContext& context) {
355 if (request.method == protocol::ToolsListMethod) {
357 protocol::paginated_request_params_from_json(request.params);
359 return server_handler_error_response(
360 request, core::Error{
361 static_cast<int>(protocol::ErrorCode::InvalidParams),
362 "tools/list params must be an object with an optional "
367 const auto result = handler.on_list_tools(*params, context);
368 if (result.has_value()) {
369 return server_handler_result_response(
370 request, *result, [](
const protocol::ToolsListResult& value) {
371 return protocol::tools_list_result_to_json(value);
377 if (request.method == protocol::ToolsGetMethod) {
378 if (!request.params.is_object() || !request.params.contains(
"name") ||
379 !request.params.at(
"name").is_string()) {
380 return server_handler_error_response(
381 request, core::Error{
382 static_cast<int>(protocol::ErrorCode::InvalidParams),
383 "tools/get requires a string name",
387 const auto result = handler.on_get_tool(
388 request.params.at(
"name").get<std::string>(), context);
389 if (result.has_value()) {
390 return server_handler_result_response(
391 request, *result, [](
const protocol::ToolDefinition& value) {
392 return protocol::tool_definition_to_json(value);
398 if (request.method == protocol::PromptsListMethod) {
400 protocol::paginated_request_params_from_json(request.params);
402 return server_handler_error_response(
403 request, core::Error{
404 static_cast<int>(protocol::ErrorCode::InvalidParams),
405 "prompts/list params must be an object with an optional "
410 const auto result = handler.on_list_prompts(*params, context);
411 if (result.has_value()) {
412 return server_handler_result_response(
413 request, *result, [](
const protocol::PromptsListResult& value) {
414 return protocol::prompts_list_result_to_json(value);
420 if (request.method == protocol::ResourcesListMethod) {
422 protocol::paginated_request_params_from_json(request.params);
424 return server_handler_error_response(
425 request, core::Error{
426 static_cast<int>(protocol::ErrorCode::InvalidParams),
427 "resources/list params must be an object with an "
428 "optional string cursor",
432 const auto result = handler.on_list_resources(*params, context);
433 if (result.has_value()) {
434 return server_handler_result_response(
435 request, *result, [](
const protocol::ResourcesListResult& value) {
436 return protocol::resources_list_result_to_json(value);
442 if (request.method == protocol::ResourcesTemplatesListMethod) {
444 protocol::paginated_request_params_from_json(request.params);
446 return server_handler_error_response(
447 request, core::Error{
448 static_cast<int>(protocol::ErrorCode::InvalidParams),
449 "resources/templates/list params must be an object with "
450 "an optional string cursor",
454 const auto result = handler.on_list_resource_templates(*params, context);
455 if (result.has_value()) {
456 return server_handler_result_response(
458 [](
const protocol::ResourceTemplatesListResult& value) {
459 return protocol::resource_templates_list_result_to_json(value);
466inline std::optional<protocol::JsonRpcResponse> dispatch_server_handler_request(
467 const ServerHandlerInterface& handler,
468 const protocol::JsonRpcRequest& request,
const SessionContext& context,
469 CancellationToken cancellation) {
470 const auto discovery_response =
471 dispatch_server_handler_discovery_request(handler, request, context);
472 if (discovery_response.has_value()) {
473 return discovery_response;
476 if (request.method == protocol::ToolsCallMethod) {
477 const auto call = protocol::tool_call_from_json(request.params);
479 return server_handler_error_response(request, call.error());
481 if (call->task.has_value()) {
484 const auto result = handler.on_call_tool(*call, context, cancellation);
485 if (result.has_value()) {
486 return server_handler_result_response(
487 request, *result, [](
const protocol::ToolResult& value) {
488 return protocol::tool_result_to_json(value);
494 if (request.method == protocol::PromptsGetMethod) {
495 const auto params = protocol::prompts_get_params_from_json(request.params);
497 return server_handler_error_response(request, params.error());
499 const auto result = handler.on_get_prompt(*params, context, cancellation);
500 if (result.has_value()) {
501 return server_handler_result_response(
502 request, *result, [](
const protocol::PromptsGetResult& value) {
503 return protocol::prompts_get_result_to_json(value);
509 if (request.method == protocol::ResourcesReadMethod) {
511 protocol::resources_read_params_from_json(request.params);
513 return server_handler_error_response(request, params.error());
516 handler.on_read_resource(*params, context, cancellation);
517 if (result.has_value()) {
518 return server_handler_result_response(
519 request, *result, [](
const protocol::ResourcesReadResult& value) {
520 return protocol::resources_read_result_to_json(value);
526 if (request.method == protocol::LoggingSetLevelMethod) {
528 handler.on_set_level(request.params, context, cancellation);
529 if (result.has_value()) {
530 return server_handler_result_response(
531 request, *result, [](
const protocol::Json& value) {
return value; });
536 if (request.method == protocol::ResourcesSubscribeMethod) {
538 handler.on_subscribe(request.params, context, cancellation);
539 if (result.has_value()) {
540 return server_handler_result_response(
541 request, *result, [](
const protocol::Json& value) {
return value; });
546 if (request.method == protocol::ResourcesUnsubscribeMethod) {
548 handler.on_unsubscribe(request.params, context, cancellation);
549 if (result.has_value()) {
550 return server_handler_result_response(
551 request, *result, [](
const protocol::Json& value) {
return value; });
566 using JsonContextHandler = Server::JsonContextHandler;
567 using JsonRequestContextHandler = Server::JsonRequestContextHandler;
725 std::shared_ptr<const ServerHandlerInterface> handler) {
727 throw std::invalid_argument(
728 "ServerHandlerInterface shared handler must not be null");
735 const auto response =
736 handler->on_completion(request, context, cancellation);
737 if (response.has_value()) {
738 return std::move(*response);
740 return mcp::core::unexpected(handler_method_not_found(
741 "server handler does not handle completion"));
747 const auto response =
748 handler->on_sampling(request, context, cancellation);
749 if (response.has_value()) {
750 return std::move(*response);
752 return mcp::core::unexpected(handler_method_not_found(
753 "server handler does not handle sampling"));
756 [handler](std::string_view level, std::string_view message) {
757 handler->on_logging(level, message);
762 -> std::optional<protocol::JsonRpcResponse> {
763 const auto handler_response = dispatch_server_handler_request(
764 *handler, request, context, cancellation);
765 if (handler_response.has_value()) {
766 return handler_response;
768 return handler->on_custom_request(request, context);
773 const auto response =
774 handler->on_raw_notification(notification, context);
775 if (response.has_value()) {
776 return std::move(*response);
783 const auto response =
784 handler->on_custom_notification(notification, context);
785 if (response.has_value()) {
786 return std::move(*response);
793 const auto response = handler->on_task_list(params, context);
794 if (response.has_value()) {
795 return std::move(*response);
797 return mcp::core::unexpected(
798 handler_method_not_found(
"server handler does not handle task list"));
803 const auto response = handler->on_task_get(params, context);
804 if (response.has_value()) {
805 return std::move(*response);
807 return mcp::core::unexpected(handler_method_not_found(
808 "server handler does not handle task get"));
813 const auto response = handler->on_task_cancel(params, context);
814 if (response.has_value()) {
815 return std::move(*response);
817 return mcp::core::unexpected(handler_method_not_found(
818 "server handler does not handle task cancel"));
823 const auto response = handler->on_task_result(params, context);
824 if (response.has_value()) {
825 return std::move(*response);
827 return mcp::core::unexpected(handler_method_not_found(
828 "server handler does not handle task result"));
833 const auto response = handler->on_progress(params, context);
834 if (response.has_value()) {
835 return std::move(*response);
841 const auto response = handler->on_roots_list_changed(context);
842 if (response.has_value()) {
843 return std::move(*response);
849 const auto response = handler->on_tool_list_changed(context);
850 if (response.has_value()) {
851 return std::move(*response);
857 const auto response = handler->on_prompt_list_changed(context);
858 if (response.has_value()) {
859 return std::move(*response);
865 const auto response = handler->on_resource_list_changed(context);
866 if (response.has_value()) {
867 return std::move(*response);
872 [handler](
const std::string& uri,
874 const auto response = handler->on_resource_updated(uri, context);
875 if (response.has_value()) {
876 return std::move(*response);
885 return set_handler(std::shared_ptr<const ServerHandlerInterface>(
Copyable token observed by cancellation-aware SDK operations.
Definition cancellation.hpp:104
High-level MCP server compatibility API.
Definition server.hpp:83
void set_resource_templates_list_handler(ResourceTemplatesListHandler handler)
Registers a resources/templates/list request handler.
void set_custom_notification_handler(RawNotificationHandler handler)
Registers a custom notification handler.
void set_prompt_list_changed_handler(ListChangedHandler handler)
Registers a prompt-list-changed notification handler.
std::function< core::Result< core::Unit >(const std::string &uri, const SessionContext &)> ResourceUpdatedHandler
Handles client resource-updated notifications.
Definition server.hpp:397
void set_custom_request_handler(RawRequestHandler handler)
Registers a custom request handler.
std::function< core::Result< protocol::PromptsListResult >(const protocol::PaginatedRequestParams &, const SessionContext &)> PromptsListHandler
Handles prompts/list requests.
Definition server.hpp:359
std::function< core::Result< protocol::ResourceTemplatesListResult >(const protocol::PaginatedRequestParams &, const SessionContext &)> ResourceTemplatesListHandler
Handles resources/templates/list requests.
Definition server.hpp:369
void set_prompts_list_handler(PromptsListHandler handler)
Registers a prompts/list request handler.
void set_progress_handler(ProgressHandler handler)
Registers a progress notification handler.
void set_resource_updated_handler(ResourceUpdatedHandler handler)
Registers a resource-updated notification handler.
void set_logging_handler(LoggingHandler handler)
Registers the logging notification handler.
void set_tools_list_handler(ToolsListHandler handler)
Registers a tools/list request handler.
void set_resource_list_changed_handler(ListChangedHandler handler)
Registers a resource-list-changed notification handler.
std::function< core::Result< protocol::Task >(const protocol::TaskGetParams &, const SessionContext &)> TaskGetHandler
Handles task get requests.
Definition server.hpp:373
void set_resources_list_handler(ResourcesListHandler handler)
Registers a resources/list request handler.
void set_task_list_handler(TaskListHandler handler)
Registers a task list request handler.
std::function< core::Result< protocol::Json >(const protocol::TaskResultParams &, const SessionContext &)> TaskResultHandler
Handles task result requests.
Definition server.hpp:381
void set_raw_request_handler(RawRequestHandler handler)
Registers a raw request hook.
void set_task_cancel_handler(TaskCancelHandler handler)
Registers a task cancel request handler.
void set_raw_notification_handler(RawNotificationHandler handler)
Registers a raw notification hook.
std::function< core::Result< protocol::Task >(const protocol::TaskCancelParams &, const SessionContext &)> TaskCancelHandler
Handles task cancel requests.
Definition server.hpp:377
void set_task_get_handler(TaskGetHandler handler)
Registers a task get request handler.
std::function< std::optional< protocol::JsonRpcResponse >(const protocol::JsonRpcRequest &, const SessionContext &)> RawRequestHandler
Optionally handles raw or custom requests before built-in fallback.
Definition server.hpp:337
std::function< core::Result< protocol::Json >(const protocol::Json &)> JsonHandler
Handles JSON-shaped extension requests such as completion or sampling.
Definition server.hpp:322
std::function< core::Result< core::Unit >(const protocol::JsonRpcNotification &, const SessionContext &)> RawNotificationHandler
Handles raw or custom notifications.
Definition server.hpp:345
void set_completion_handler(JsonHandler handler)
Registers the completion request handler.
std::function< void(std::string_view, std::string_view)> LoggingHandler
Handles logging messages from clients.
Definition server.hpp:330
void set_tool_list_changed_handler(ListChangedHandler handler)
Registers a tool-list-changed notification handler.
void set_task_result_handler(TaskResultHandler handler)
Registers a task result request handler.
std::function< core::Result< core::Unit >(const SessionContext &)> RootsListChangedHandler
Handles client roots-list-changed notifications.
Definition server.hpp:385
void set_sampling_handler(JsonHandler handler)
Registers the sampling request handler.
std::function< core::Result< protocol::ResourcesListResult >(const protocol::PaginatedRequestParams &, const SessionContext &)> ResourcesListHandler
Handles resources/list requests.
Definition server.hpp:364
std::function< core::Result< core::Unit >(const SessionContext &)> ListChangedHandler
Handles client list-changed notifications.
Definition server.hpp:393
std::function< core::Result< core::Unit >(const protocol::ProgressNotificationParams &, const SessionContext &)> ProgressHandler
Handles client progress notifications.
Definition server.hpp:389
std::function< core::Result< protocol::TaskListResult >(const protocol::TaskListParams &, const SessionContext &)> TaskListHandler
Handles task list requests.
Definition server.hpp:349
std::function< core::Result< protocol::ToolsListResult >(const protocol::PaginatedRequestParams &, const SessionContext &)> ToolsListHandler
Handles tools/list requests.
Definition server.hpp:354
Server & set_handler(const ServerHandler &handler)
Installs every non-empty callback from a ServerHandler aggregate.
Definition handler.hpp:718
void set_roots_list_changed_handler(RootsListChangedHandler handler)
Registers a roots-list-changed notification handler.
nlohmann::json Json
JSON value type used by all protocol DTOs.
Definition types.hpp:28
std::monostate Unit
Success value for operations that only need to report failure.
Definition result.hpp:55
tl::expected< T, Error > Result
Alias for the SDK result type.
Definition result.hpp:64
High-level server compatibility API, builder, and convenience app API.
Structured error returned by fallible SDK operations.
Definition result.hpp:35
std::string detail
Optional extended diagnostic information.
Definition result.hpp:43
std::string message
Short human-readable explanation of the failure.
Definition result.hpp:40
int code
Numeric protocol, transport, or component-specific error code.
Definition result.hpp:37
JSON-RPC notification envelope for one-way MCP messages.
Definition types.hpp:137
JSON-RPC request envelope carrying an MCP method invocation.
Definition types.hpp:99
RequestId id
Request id that must be echoed by the response.
Definition types.hpp:105
JSON-RPC response envelope for either success or failure.
Definition types.hpp:115
Shared pagination params for MCP list requests that use cursor.
Definition types.hpp:43
Parameters for notifications/progress.
Definition types.hpp:226
Parameters for prompts/get.
Definition prompt.hpp:181
Parameters for resources/read.
Definition resource.hpp:227
Parameters for tasks/cancel.
Definition task.hpp:234
Parameters for tasks/get.
Definition task.hpp:209
Parameters for tasks/list.
Definition task.hpp:187
Contract-style server handler interface.
Definition handler.hpp:26
Optional callback bundle for configuring a Server in one call.
Definition handler.hpp:564
ResourceUpdatedHandler on_resource_updated
Handles resource-updated notifications from clients.
Definition handler.hpp:625
RawRequestHandler on_raw_request
Optionally handles raw requests before built-in dispatch.
Definition handler.hpp:591
RawNotificationHandler on_custom_notification
Handles custom notifications.
Definition handler.hpp:597
LoggingHandler on_logging
Handles logging notifications.
Definition handler.hpp:589
TaskCancelHandler on_task_cancel
Handles task cancel requests.
Definition handler.hpp:611
ResourcesListHandler on_resources_list
Handles resources/list requests.
Definition handler.hpp:603
JsonContextHandler on_sampling_with_context
Handles sampling requests with session context.
Definition handler.hpp:629
JsonRequestContextHandler on_completion_with_request_context
Handles completion requests with session context and cancellation.
Definition handler.hpp:631
JsonContextHandler on_completion_with_context
Handles completion requests with session context.
Definition handler.hpp:627
ListChangedHandler on_resource_list_changed
Handles resource-list-changed notifications from clients.
Definition handler.hpp:623
RootsListChangedHandler on_roots_list_changed
Handles roots-list-changed notifications from clients.
Definition handler.hpp:617
ProgressHandler on_progress
Handles progress notifications from clients.
Definition handler.hpp:615
PromptsListHandler on_prompts_list
Handles prompts/list requests.
Definition handler.hpp:601
ToolsListHandler on_tools_list
Handles tools/list requests.
Definition handler.hpp:599
RawRequestHandler on_custom_request
Optionally handles custom requests.
Definition handler.hpp:595
TaskListHandler on_task_list
Handles task list requests.
Definition handler.hpp:607
TaskGetHandler on_task_get
Handles task get requests.
Definition handler.hpp:609
JsonHandler on_completion
Handles completion requests.
Definition handler.hpp:585
JsonRequestContextHandler on_sampling_with_request_context
Handles sampling requests with session context and cancellation.
Definition handler.hpp:633
ListChangedHandler on_prompt_list_changed
Handles prompt-list-changed notifications from clients.
Definition handler.hpp:621
ResourceTemplatesListHandler on_resource_templates_list
Handles resources/templates/list requests.
Definition handler.hpp:605
ListChangedHandler on_tool_list_changed
Handles tool-list-changed notifications from clients.
Definition handler.hpp:619
TaskResultHandler on_task_result
Handles task result requests.
Definition handler.hpp:613
void apply_to(Server &server) const
Applies all non-empty callbacks to a server.
Definition handler.hpp:637
JsonHandler on_sampling
Handles sampling requests.
Definition handler.hpp:587
RawNotificationHandler on_raw_notification
Handles raw notifications.
Definition handler.hpp:593
Per-message connection metadata supplied to server handlers.
Definition transport.hpp:42