Local, stdio-first MCP server with typed tools and bounded execution. More...

#include <server.h>

Public Types
using	MethodHandler = std::function< json(const json &, const json &)>
	Synchronous extension-method handler; the server wraps the JSON result.

using	NoResponseSink = std::function< void(const json &id)>
	Receives the id of a request that ended without a response: the client cancelled it, so no response is sent.

using	RawToolHandler = std::function< json(const json &, const std::shared_ptr< graph::CancelToken > &, const json &)>
	Extension hook for polymorphic tool results such as CreateTaskResult.

using	Reply = std::function< void(std::optional< json >)>
	The outcome of one message given to handle_message(message, reply): its response (an object, or an array for a batch), or nullopt when it has none (a notification, a response, a call the client cancelled, a batch with nothing to answer).

using	ResponseSink = std::function< void(const json &)>
	Receives complete JSON-RPC response envelopes produced asynchronously.

Public Member Functions
json	handle_message (const json &envelope)
	Process one parsed JSON-RPC message.

void	handle_message (const json &message, Reply reply)
	Process one parsed message and pass its outcome to `reply` exactly once: before this returns, or later from a worker thread for a tool call.

std::string	protocol_version () const
	The revision initialize negotiated: the client's when it is one of MCP_SUPPORTED_PROTOCOL_VERSIONS, MCP_PROTOCOL_VERSION otherwise.

void	register_extension (std::string identifier, json settings=json::object())
	Advertise an explicitly enabled MCP extension capability.

void	register_method (std::string method, MethodHandler handler)
	Register an extension JSON-RPC method before initialization.

void	register_raw_tool (ToolDefinition definition, RawToolHandler handler)
	Add a tool whose result shape is selected using request metadata.

void	register_tool (ToolDefinition definition, ToolHandler handler)
	Add a tool. Names must be unique and registration closes at initialize.

void	run (std::istream &in, std::ostream &out)
	Drive newline-delimited MCP stdio until EOF or a message-boundary stop.

void	set_response_sink (ResponseSink sink)
	Set the destination for asynchronously completed tool-call responses.

void	set_response_sink (ResponseSink sink, NoResponseSink no_response)
	As above; `no_response` receives the id of each call that ends without a response.

void	stop ()
	Cooperatively cancel outstanding calls and drain the worker pool.

Detailed Description

Local, stdio-first MCP server with typed tools and bounded execution.

Register tools before initialization, then call run(). Tool calls execute on a fixed-size worker pool. The request-scoped CancelToken passed to a handler is cancelled by notifications/cancelled; handlers cooperate by polling or propagating that token into their own async work.

A handler's failure keeps its class on the wire (reference, "Protocol failure mapping"): a HookBoundaryBlocked is JSON-RPC error -32010, a NodeInterrupt -32011, a call stop() cancelled -32000, and every other failure an isError result whose _meta["io.neograph/failure"] holds its stable code (graph::classify_failure). A call the client cancelled with notifications/cancelled gets no response at all, on every transport (MCP: the receiver SHOULD NOT respond); a transport that holds the request open learns that it ended through the NoResponseSink.

Definition at line 53 of file server.h.

Member Typedef Documentation

◆ NoResponseSink

using neograph::mcp::MCPServer::NoResponseSink = std::function<void(const json& id)>

Receives the id of a request that ended without a response: the client cancelled it, so no response is sent.

A transport that keeps the request open (an HTTP POST) closes it here; nothing must reach the client as a response to that id.

Definition at line 72 of file server.h.

Member Function Documentation

◆ handle_message() [1/2]

json neograph::mcp::MCPServer::handle_message ( const json & envelope )

Process one parsed JSON-RPC message.

Tool calls may complete via sink. A batch (an array) is answered with one array, at once when it holds no tool call and through the response sink otherwise; a batch whose calls were all cancelled produces nothing.

◆ handle_message() [2/2]

void neograph::mcp::MCPServer::handle_message	(	const json &	message,
		Reply	reply
	)

Process one parsed message and pass its outcome to reply exactly once: before this returns, or later from a worker thread for a tool call.

The response sinks are not used for it. A message may be a JSON-RPC batch when the negotiated revision has batches (2025-03-26, and 2024-11-05 peers alike); later revisions, and a batch before initialize, get one -32600 error object.

◆ protocol_version()

std::string neograph::mcp::MCPServer::protocol_version ( ) const

The revision initialize negotiated: the client's when it is one of MCP_SUPPORTED_PROTOCOL_VERSIONS, MCP_PROTOCOL_VERSION otherwise.

Empty before initialize.

◆ set_response_sink() [1/2]

void neograph::mcp::MCPServer::set_response_sink ( ResponseSink sink )

Set the destination for asynchronously completed tool-call responses.

A call the client cancelled produces no response.

◆ set_response_sink() [2/2]

void neograph::mcp::MCPServer::set_response_sink	(	ResponseSink	sink,
		NoResponseSink	no_response
	)

As above; no_response receives the id of each call that ends without a response.

Both sinks are replaced together.

The documentation for this class was generated from the following file:

include/neograph/mcp/server.h

Public Types

Public Member Functions