Helpers for building Model Context Protocol (MCP) envelopes. More...
Helpers for building Model Context Protocol (MCP) envelopes.
This functionality is included as follows:
Authenticate the caller and authorize each resource before opening a file or making a network request. URI validation and sourcemeta::core::mcp_make_resource do not grant resource-access permission.
sourcemeta::core::mcp_validate_continuation checks protocol fields and, optionally, an exact state-token echo. The application must protect state integrity, bind it to the caller and operation, and enforce expiry and replay policy. These are application controls, not additional requirements imposed by Core's MCP validators. Multiple workers need shared atomic state consumption.
| struct sourcemeta::core::MCPImplementation |
Information about an MCP implementation (client or server). Every string is a borrowed view and the icons array is a borrowed pointer, so the referents must outlive any builder this is passed to. For example:
Public Attributes | |
|---|---|
| JSON::StringView | name |
| Implementation identifier name. | |
| JSON::StringView | version |
| Implementation version (not required to be SemVer). | |
| JSON::StringView | title = {} |
| Optional human-readable title. | |
| JSON::StringView | description = {} |
| Optional human-readable description. | |
| JSON::StringView | website_url = {} |
| Optional public website URL. | |
| const JSON * | icons = nullptr |
| Optional borrowed array of icons (2025-11-25 and later). | |
| struct sourcemeta::core::MCPClientCapabilities |
Capabilities advertised by an MCP client. The typed flags describe the capabilities this library understands, while the snapshot retains whatever else the peer sent so that a parse followed by a serialize does not discard it.
Roots and sampling are deprecated as of protocol version 2026-07-28, which states that new implementations should not adopt them. They remain representable here because the library still speaks the revisions that define them.
Public Attributes | |
|---|---|
| bool | roots = false |
| Whether the client advertises roots. | |
| bool | roots_list_changed = false |
| Whether roots advertise listChanged (legacy revisions only). | |
| bool | sampling = false |
| Whether the client advertises sampling. | |
| bool | sampling_context = false |
| bool | sampling_tools = false |
| Whether sampling advertises tools support. | |
| bool | elicitation = false |
| Whether the client advertises elicitation. | |
| bool | elicitation_form = false |
| Whether elicitation advertises form support. | |
| bool | elicitation_url = false |
| Whether elicitation advertises url support. | |
| std::optional< sourcemeta::core::JSON > | extensions = std::nullopt |
| Optional extensions map for client capabilities. | |
| std::optional< sourcemeta::core::JSON > | experimental = std::nullopt |
| Optional experimental map for client capabilities. | |
| std::optional< JSON > | source = std::nullopt |
| bool sourcemeta::core::MCPClientCapabilities::sampling_context = false |
Whether sampling advertises context support. Declaring it is what permits a server to ask for context from the requesting server or from all of them. Those two request values were deprecated in 2025-11-25, which asks a server to avoid them and not to use them at all unless a client declares this capability. The capability itself is not deprecated.
| std::optional<JSON> sourcemeta::core::MCPClientCapabilities::source = std::nullopt |
Optional owned source preserving the parsed capability settings. Keeps extension settings, unknown capabilities and 2025-11-25 task data. Typed flags and optional maps override this snapshot when serializing. The per-request metadata view does not allocate or populate this snapshot.
| struct sourcemeta::core::MCPServerCapabilities |
Capabilities advertised by an MCP server.
Public Attributes | |
|---|---|
| bool | prompts = false |
| Whether the server advertises prompts. | |
| bool | resources = false |
| Whether the server advertises resources. | |
| bool | tools = false |
| Whether the server advertises tools. | |
| bool | logging = false |
| Whether the server advertises logging. | |
| bool | completions = false |
| Whether the server advertises completions. | |
| bool | tools_list_changed = false |
| Whether tools advertise listChanged. | |
| bool | resources_subscribe = false |
| Whether resources advertise subscribe. | |
| bool | resources_list_changed = false |
| Whether resources advertise listChanged. | |
| bool | prompts_list_changed = false |
| Whether prompts advertise listChanged. | |
| std::optional< sourcemeta::core::JSON > | extensions = std::nullopt |
| Optional extensions map for capabilities. | |
| std::optional< sourcemeta::core::JSON > | experimental = std::nullopt |
| Optional experimental map for capabilities. | |
| std::optional< JSON > | source = std::nullopt |
| std::optional<JSON> sourcemeta::core::MCPServerCapabilities::source = std::nullopt |
Owned source preserving unknown capabilities, settings and legacy tasks. Typed flags and optional maps override their corresponding source fields.
| class sourcemeta::core::MCPError |
An error that represents a violation of an MCP contract, such as building a result for a revision that does not define it, or supplying a descriptor the specification rejects. For example:
Public Member Functions | |
|---|---|
| MCPError (const StaticString message) noexcept | |
| Construct an error with a descriptive message. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
| struct sourcemeta::core::MCPRequestMeta |
Parsed representation of 2026-07-28 request metadata. The protocol revision is a value, while the capabilities, implementation, log level, metadata object and progress token all reference the validated request, so the request must outlive this view.
Public Attributes | |
|---|---|
| MCPProtocolVersion | protocol_version |
| The declared protocol revision. | |
| const JSON & | client_capabilities |
| Borrowed capabilities. The source request must outlive this view. | |
| std::optional< MCPImplementation > | client_info |
| Optional borrowed implementation description. | |
| std::optional< JSON::StringView > | log_level |
| Optional requested log level. | |
| const JSON & | meta_object |
| Borrowed metadata. Never null after successful validation. | |
| const JSON * | progress_token = nullptr |
| Optional borrowed progress token. | |
| struct sourcemeta::core::MCPHeaderParameter |
A caller-provided parameter header descriptor. String views borrow the name and property path supplied by the caller. The path names the chain of properties reaching the mirrored value from the arguments root, and the type is restricted to the three primitives the specification permits.
A server declares these mirrors as annotations inside a tool's input schema, and deriving descriptors from that schema is the caller's job rather than this module's, because it means interpreting a schema. In particular the caller owns the rule that an annotation counts only where the property is reachable from the schema root through a chain of property keys alone, never through an array, composition, conditional or reference keyword, and that a tool whose annotation sits anywhere else is rejected and excluded from the tool listing.
Given descriptors, this module enforces the remaining constraints on them: each name is a non-empty HTTP token, which also rules out control characters, the names are case-insensitively unique, only the three primitive types are mirrored, and an integer value stays within the range a double can represent exactly.
Public Attributes | |
|---|---|
| JSON::StringView | name |
| The suffix of Mcp-Param-{name}. | |
| std::vector< JSON::StringView > | path |
| Instance property path, with no array or reference traversal. | |
| JSON::Type | type |
| One of String, Integer or Boolean. | |
| struct sourcemeta::core::MCPCachePolicy |
Cache policy specifying TTL in milliseconds and scope for cacheable MCP results. Both fields are required for cacheable operations in MCP 2026-07-28.
Public Attributes | |
|---|---|
| std::int64_t | ttl_ms = 0 |
| MCPCacheScope | scope = MCPCacheScope::Private |
| Cache scope (public or private). | |
| std::int64_t sourcemeta::core::MCPCachePolicy::ttl_ms = 0 |
Time-to-live in milliseconds. The schema bounds this below by zero, so a negative value is refused rather than folded to zero.
| struct sourcemeta::core::MCPToolAnnotations |
Optional hints attached to an MCP tool descriptor. The defaults are the conservative reading the specification assigns to a hint a server does not state, so a descriptor built without them claims nothing favourable about the tool.
Public Attributes | |
|---|---|
| JSON::StringView | title = {} |
| Optional human-readable title for the tool. | |
| bool | read_only = false |
| true as an advisory hint that the tool does not modify its environment. | |
| bool | destructive = true |
| true when the tool may mutate or delete state. | |
| bool | idempotent = false |
| bool | open_world = true |
| true when the tool interacts with state outside the server's control. | |
| bool sourcemeta::core::MCPToolAnnotations::idempotent = false |
true when repeated invocations with the same arguments have no additional effect on the environment.
| struct sourcemeta::core::MCPResourceAnnotations |
Advisory resource/content annotations. String and audience views are borrowed, so their referents must outlive any builder this is passed to.
Public Attributes | |
|---|---|
| std::optional< std::span< const JSON::StringView > > | audience = std::nullopt |
| Optional audience roles ("user" and/or "assistant"). Empty stays explicit. | |
| std::optional< double > | priority = std::nullopt |
| JSON::StringView | last_modified = {} |
| Optional timestamp string. The caller supplies a valid ISO 8601 timestamp. | |
| std::optional<double> sourcemeta::core::MCPResourceAnnotations::priority = std::nullopt |
Optional priority. The schema bounds this between zero and one, so a value outside them is refused rather than folded in.
| struct sourcemeta::core::MCPDescriptorPresentation |
Optional presentation fields shared by descriptors. All views borrow data. A field the target revision does not define is dropped rather than reported.
Public Attributes | |
|---|---|
| JSON::StringView | title = {} |
| Human-readable title (2025-06-18 and later). | |
| const JSON * | icons = nullptr |
| Optional icon array (2025-11-25 and later). | |
| struct sourcemeta::core::MCPSubscriptionFilter |
Opt-in filters for a 2026-07-28 subscription. Explicit false values are preserved. An absent value is not requested. Resource URI views are borrowed, so the parsed parameters must outlive the filter.
Public Attributes | |
|---|---|
| std::optional< bool > | tools_list_changed = std::nullopt |
| Opt in to notifications that the tool list changed. | |
| std::optional< bool > | prompts_list_changed = std::nullopt |
| Opt in to notifications that the prompt list changed. | |
| std::optional< bool > | resources_list_changed = std::nullopt |
| Opt in to notifications that the resource list changed. | |
| std::optional< std::vector< JSON::StringView > > | resource_subscriptions |
| std::optional<std::vector<JSON::StringView> > sourcemeta::core::MCPSubscriptionFilter::resource_subscriptions |
Borrowed resource URIs whose updates are requested. An absent list requests no subscriptions, while an explicit empty list stays explicit.
|
strong |
Cache scope for 2026-07-28 cacheable MCP results.
| Enumerator | |
|---|---|
| Public | Public caching is permissible across multiple clients/users. |
| Private | Result is private and must only be reused within the same authorization context. |
|
strong |
Context for errors with no readable MCP request identifier. The two legacy revisions require an error response to echo a readable identifier, which a transport-level rejection cannot always produce, so the context selects whether that requirement is enforced.
|
strong |
Syslog severity levels, ordered from least to most severe. A request's logging threshold admits its own level and all more severe levels. The enumerator order is the severity order, so the levels compare directly.
This feature is deprecated as of protocol version 2026-07-28, which states that new implementations should not adopt it and that existing implementations should migrate to standard error output for the stdio transport, or to a general-purpose observability framework.
| Enumerator | |
|---|---|
| Debug | Detailed information useful for debugging. |
| Info | General informational messages. |
| Notice | Normal but significant conditions. |
| Warning | Conditions that may require attention. |
| Error | Error conditions. |
| Critical | Critical conditions. |
| Alert | Conditions requiring immediate action. |
| Emergency | Conditions indicating that the system is unusable. |
|
strong |
The supported MCP protocol revisions.
MCP 2026-07-28 is a major architectural redesign replacing stateful initialization with stateless, per-request capability negotiation, removing initialize, ping, and logging/setLevel, and introducing server/discover, subscriptions/listen, explicit result types, and caching policies.
Supported legacy revisions (2025-03-26 through 2025-11-25) use connection-scoped initialization handshakes and stateful protocol sessions.
|
strong |
Validation status returned by mcp_validate_request_meta.
| Enumerator | |
|---|---|
| Valid | The request metadata is fully valid. |
| InvalidEnvelope | The input is not a valid MCP request envelope. |
| InvalidMetaKey | Metadata contains an invalid key name or malformed tracing value. |
| InvalidClientCapabilities | Known client capability fields have invalid shapes. |
| ClientInfoWebsiteUrlNotString | Client websiteUrl must be a string. |
| InvalidClientInfo | Implementation icons have invalid shapes. |
| InvalidLogLevel | logLevel must be one of the eight specified logging levels. |
| InvalidProgressToken | progressToken must be a string or integer. |
| MissingParams | Request envelope lacks a params property. |
| ParamsNotObject | The params property is not a JSON object. |
| MissingMeta | The params object lacks a _meta property. |
| MetaNotObject | The _meta property is not a JSON object. |
| MissingProtocolVersion | _meta lacks io.modelcontextprotocol/protocolVersion. |
| ProtocolVersionNotString | io.modelcontextprotocol/protocolVersion is not a string. |
| UnsupportedProtocolVersion | io.modelcontextprotocol/protocolVersion is not a recognized version. |
| MissingClientCapabilities | _meta lacks io.modelcontextprotocol/clientCapabilities. |
| ClientCapabilitiesNotObject | io.modelcontextprotocol/clientCapabilities is not a JSON object. |
| ClientInfoNotObject | io.modelcontextprotocol/clientInfo is not a JSON object. |
| MissingClientInfoName | io.modelcontextprotocol/clientInfo lacks required name property. |
| ClientInfoNameNotString | name property in io.modelcontextprotocol/clientInfo is not a string. |
| MissingClientInfoVersion | io.modelcontextprotocol/clientInfo lacks required version property. |
| ClientInfoVersionNotString | version property in io.modelcontextprotocol/clientInfo is not a string. |
| ClientInfoTitleNotString | title property in io.modelcontextprotocol/clientInfo is not a string. |
| ClientInfoDescriptionNotString | description property in io.modelcontextprotocol/clientInfo is not a string. |
|
nodiscardconstexprnoexcept |
Canonical string conversion for cache scope. For example:
|
nodiscard |
Decorate an MCP result object with cache metadata (ttlMs and cacheScope) for 2026-07-28. Takes and returns a bare result object. For example:
|
nodiscard |
Decorate a successful MCP result object with version-appropriate envelope fields (resultType: "complete" and optional _meta.io.modelcontextprotocol/serverInfo for 2026-07-28). Takes and returns a bare result object, so an earlier revision leaves it unchanged. For example:
|
nodiscard |
Encode a Mcp-Name or Mcp-Param value using the MCP 2026-07-28 sentinel encoding when the value cannot be represented literally. A value passes through only when every byte is printable ASCII, it neither begins nor ends with a space, and it would not be mistaken for the sentinel form. Everything else is encoded. Throws MCPError for input that is not UTF-8. For example:
|
nodiscardconstexprnoexcept |
Map an MCP or JSON-RPC error code to the HTTP status the specification mandates for it on the Streamable HTTP transport, or nothing where it mandates none.
Only 2026-07-28 ties a status to an error code on its own, and only for four of them: an unimplemented method answers 404, while a header mismatch, a missing required client capability and an unsupported protocol version each answer 400.
Invalid parameters is deliberately absent despite carrying a mandate of its own, because the mandate is written for one cause of that code, a request that omits a required metadata field, while the same code also answers a resource that cannot be found and an argument that disagrees with its mirrored header. Those have no mandated status, and a missing resource would be poorly served by the one the metadata rule gives. A caller rejecting a request for missing metadata therefore answers 400 on its own authority, which it can do because it chose that rejection and this helper cannot see which cause produced the code.
Every other code in that revision, and every code in the three earlier revisions, has no mandated status: those revisions tie a status to a transport condition such as a terminated session rather than to a JSON-RPC error, which in that era travels on a 200.
So an absent result is not a gap to paper over. It says the choice belongs to the adapter, which is why this returns nothing instead of inventing a status, and in particular why a resource that cannot be found no longer reports the server as being at fault. For example:
|
nodiscard |
Restrict requested events and URIs to those the server supports. The result is the subset the server agreed to honor, so an event only carries a value when both sides opted into it and an unsupported event stays absent. For example:
|
nodiscardconstexprnoexcept |
Whether a complete operation result requires caching metadata in 2026-07-28. For example:
|
nodiscardconstexprnoexcept |
Check the base client notification direction for an exact revision. For example:
|
nodiscardconstexprnoexcept |
Whether a nested MRTR request method is defined in this revision. For example:
|
nodiscardconstexprnoexcept |
Whether an operation may return an input_required result. For example:
|
nodiscardconstexprnoexcept |
Whether a notification method is defined in this revision. For example:
|
nodiscardconstexprnoexcept |
Whether a base client-to-server request is defined in this revision. For example:
|
nodiscardconstexprnoexcept |
Check the base server notification direction for an exact revision. For example:
|
nodiscardconstexprnoexcept |
Whether a standalone server-to-client request is defined in this revision. In 2026-07-28 these are nested MRTR requests, not JSON-RPC requests. For example:
|
nodiscardconstexprnoexcept |
Whether a notification meets an explicitly selected logging threshold. A threshold admits its own severity and every more severe one. The specification scopes a threshold to the request that carried it and only permits a notification once a request has asked for one, so a caller reaches this predicate having already found a threshold to apply. For example:
|
nodiscardconstexprnoexcept |
Convert a logging severity to its canonical wire string. For example:
|
nodiscard |
Build a base64 audio block, with the same contracts as the image builder. For example:
|
nodiscard |
Build a completion result. Values must be strings and contain at most 100 entries. A supplied total cannot be smaller than the returned entry count. Returns a bare result object. For example:
|
nodiscard |
Embed a checked text/blob resource-content entry in a content block. For example:
|
nodiscard |
Build an empty MCP response with resultType: "complete".
The builders in this header come in two shapes, and the name says which. A function named for a result returns the bare payload that belongs under the result key, while one named for a response returns the whole JSON-RPC envelope around it and therefore takes the identifier to echo. That is the specification's own distinction, which pairs a result such as DiscoverResult with the envelope DiscoverResultResponse, and reserves JSONRPCResultResponse for the generic shape. For example:
|
nodiscard |
Construct a checked MCP error. Null, fractional and container identifiers are treated as unreadable. For 2026-07-28, rejects retired and undefined reserved codes and checks the required data for version/capability errors. Every revision the version error advertises must be one this library models. The caller remains responsible for choosing an error that describes the actual failure. Header mismatch data is optional. Returns a complete JSON-RPC error envelope rather than a bare error object. For example:
|
nodiscard |
Build a JSON-RPC error response for header mismatch (-32020) reporting an unexpected header supplied without a corresponding body value. Defined for 2026-07-28 only. For example:
|
nodiscard |
Build a JSON-RPC error response for header mismatch (-32020) with detailed header mismatch payload, naming the header along with the conflicting transport and body values. Defined for 2026-07-28 only. For example:
|
nodiscard |
Build a JSON-RPC error response for header mismatch (-32020). This overload carries a caller-supplied message and no data, for a mismatch that names no single header. Defined for 2026-07-28 only. For example:
|
nodiscard |
Build a JSON-RPC error response for missing required client capability (-32021). This error is defined for 2026-07-28 only, and the required capabilities must themselves be a valid client capability object. For example:
|
nodiscard |
Construct an appropriate JSON-RPC error response from an invalid MCPRequestMetaStatus. An unrecognized revision becomes the dedicated unsupported-version error carrying the supported list, an envelope that is not a readable request becomes an invalid-request error, and every remaining failure becomes an invalid-params error naming the offending field. Passing the status for valid metadata throws MCPError, and so does a supported list naming a revision this library does not model, since that is a condition on the caller rather than on the peer. For example:
|
nodiscard |
Build a version-aware JSON-RPC error response reporting that a resource was not found. Emits -32002 for legacy revisions, and -32602 (Invalid Params) for 2026-07-28, which retired the dedicated code. For example:
|
nodiscard |
Build a JSON-RPC error response for unsupported protocol version (-32022). This error is defined for 2026-07-28 only, and the list of supported revisions must not be empty. Every revision in it must be one this library models, which is a condition on the caller rather than on the peer, so a violation throws instead of becoming an error envelope. An absent identifier omits the member rather than sending a null one. For example:
|
nodiscard |
Build a base64 image or audio content block for an explicit revision. Core checks the block shape, not the media bytes or MIME semantics. Returns a bare content block for the caller to place in a result.
The encoding of the data is a schema format annotation rather than a stated requirement, so it is not checked here, and a caller that cares about it decodes the data itself. Contrast the address of a URL mode elicitation, which the specification states as a requirement in prose and which is therefore checked. For example:
|
nodiscard |
Build the JSON-RPC envelope returned in response to an MCP initialize request. The revision is the one the client asked for when the server supports it and it uses the handshake, and otherwise the highest supported handshake revision, so an unrecognized request negotiates down rather than failing. The advertised list must be non-empty, every revision in it must be one this library models, and at least one must use the handshake. A request that is not readable, or whose parameters are missing or malformed, does yield an error envelope. For example:
|
nodiscard |
Build an MCP Multi Round-Trip Result (input_required). At least one of input_requests or request_state must be provided. Only tools/call, resources/read, and prompts/get may carry this result. The client capabilities are checked so a server does not ask for input the client never advertised.
A nested request that sends the user to an address has that address checked for being a URI with a scheme, which is the format the specification annotates the field with and the reading its prose requirement supports. What makes an address usable within a particular scheme is left alone: the specification restricts the scheme not at all, and each scheme states its own rules in its own document, so enforcing one scheme's rules and not the others would be a policy this builder has no grounds to choose. A caller that needs an address it can actually open checks that where it opens it. For example:
|
nodiscard |
Construct a checked notification. The direction and parameters are explicit. 2026-07-28 logging/progress require the current validated request context. Logging must meet the requested severity and cannot use a subscription ID. The caller must route it on the response stream of that same request. For 2026-07-28 server list/resource updates, subscription_id and the already acknowledged filter are mandatory. A server cancellation must name that subscription. Runtime code owns acknowledgment ordering, token activity, increasing progress, authorization and stream lifetime. For example:
|
nodiscard |
Produce mirrored parameter headers. Missing/null values are omitted. Throws MCPError on a type mismatch or an unsafe integer. A value that cannot be represented literally is sentinel encoded. For example:
|
nodiscard |
Build a prompt result from checked role/content messages. Returns a bare result object. For example:
|
nodiscard |
Build an MCP prompts/list result object for 2026-07-28 with required cache metadata. Returns a bare result object. For example:
|
nodiscard |
Build an MCP resource descriptor as used in resources/list responses. Returns a bare descriptor for the caller to collect into a list result. For example:
|
nodiscard |
Build a blob resource-content entry. The caller supplies base64-encoded data. For example:
|
nodiscard |
Build an MCP content block referencing a resource by URI. This block type was introduced in 2025-06-18, so an earlier revision is rejected. For example:
|
nodiscard |
Build a single entry for an MCP resources/templates/list response. For example:
|
nodiscard |
Build an MCP resources/templates/list result object for 2026-07-28 with required cache metadata. Returns a bare result object. For example:
|
nodiscard |
Build an MCP resources/read content entry of Text flavour. For example:
|
nodiscard |
Build an MCP resources/list result object for 2026-07-28 with required cache metadata. Returns a bare result object. For example:
|
nodiscard |
Wrap a pre-built array of content entries into the MCP resources/read result envelope with a required cache policy for 2026-07-28. Returns a bare result object, so the caller still wraps it in a JSON-RPC envelope. For example:
|
nodiscard |
Build the JSON-RPC response envelope for an MCP 2026-07-28 server/discover request. This is the stateless replacement for the initialization handshake, so it carries the supported revisions, the capabilities and the cache metadata in one response. The advertised list must be non-empty, must include the revision being served, and every revision in it must be one this library models. For example:
|
nodiscard |
Build an acknowledgement notification for subscriptions/listen with a string subscription ID. For example:
|
nodiscard |
Build an acknowledgement notification for subscriptions/listen with a string or integer subscription ID. The filter is restricted to the intersection of requested and server-supported events and URIs. For example:
|
nodiscard |
Build a graceful close response for subscriptions/listen. Returns a complete JSON-RPC envelope. For example:
|
nodiscard |
Build an MCP Text content block carrying the given text payload. For example:
|
nodiscard |
Build a single entry for an MCP tools/list response. Schemas must declare type: object at the root. The caller validates the remaining schema content. The behavioural hints are always emitted, with the conservative defaults the specification assigns to an absent hint. For example:
|
nodiscard |
Build a version-aware JSON-RPC envelope wrapping a failed MCP tool call response with the given error message. For 2026-07-28, adds resultType: "complete". A tool failure is reported inside a successful response rather than as a JSON-RPC error. For example:
|
nodiscard |
Build a JSON-RPC envelope wrapping a successful MCP tool call response from the given result payload. The payload is rendered as a text content block and, from 2025-06-18 onward, also carried as structured content. This checks the MCP result shape, not the payload against a tool's outputSchema. Evaluate declared output schemas before publishing a successful result; rejecting a result cannot undo side effects of a tool that already ran. For example:
|
nodiscard |
Build a JSON-RPC envelope wrapping a successful MCP tool call response from caller-provided content blocks and a structured payload. For example:
|
nodiscard |
Build an MCP tools/list result object for 2026-07-28 with required cache metadata. Returns a bare result object. An absent cursor omits the member, while an explicit empty one is preserved. For example:
|
nodiscard |
Parse client capabilities from a JSON object. A capability the given revision does not define is ignored rather than reported, while a known capability of the wrong type is rejected with MCPError. For example:
|
nodiscard |
Parse validated server capabilities, owning the snapshot and opaque settings. For example:
|
nodiscard |
Parse the filter in checked 2026-07-28 listen parameters. String views borrow the parameters, while the optional URI vector owns only those views, so the parameters must outlive the filter. For example:
|
nodiscardconstexprnoexcept |
Check whether an MCP protocol revision is at least the given minimum version. For example:
|
nodiscardconstexprnoexcept |
Check whether the given wire string is a valid, recognized MCP protocol version. For example:
|
nodiscardconstexprnoexcept |
Convert an MCPProtocolVersion enum value to its canonical string representation. For example:
|
nodiscard |
Access inputResponses from an MRTR continuation request envelope. Returns a borrowed pointer into the envelope, or null when the member is absent or malformed. For example:
|
nodiscard |
Borrow the target tool name or resource URI from a JSON-RPC request body. The returned view is valid only while the source string remains alive and unchanged. A resource read is named by its URI rather than by a name, and a request that names no target yields nothing. For example:
|
nodiscard |
Access requestState token from an MRTR continuation request envelope. The returned view borrows the envelope. For example:
|
nodiscard |
Access io.modelcontextprotocol/subscriptionId from request or result metadata. Returns a borrowed pointer into the envelope, or null when absent. For example:
|
nodiscardconstexprnoexcept |
Whether cacheable responses in the specified protocol version must include ttlMs and cacheScope. For example:
|
nodiscardconstexprnoexcept |
Whether requests in the specified protocol version must carry metadata inside params._meta. For example:
|
nodiscardconstexprnoexcept |
Whether result responses in the specified protocol version must carry an explicit resultType field. For example:
|
nodiscardconstexprnoexcept |
Parse a canonical cache scope string. For example:
|
nodiscardconstexprnoexcept |
Parse an exact, case-sensitive logging severity without allocating. An unrecognized value yields no level, which the specification asks a server to report as an invalid parameter. For example:
|
nodiscardconstexprnoexcept |
Resolve an MCP protocol version wire string to its corresponding enum value, or std::nullopt when the string does not match any recognized version. For example:
|
nodiscard |
Recognize base and explicitly negotiated extension result types. The extension span is the caller's negotiated allowlist, not arbitrary input. Missing discriminators mean complete. Input_required and extensions require 2026-07-28. The returned view borrows the result (or a static base name). For example:
|
nodiscard |
Extract a raw result discriminator without validating support. Absent resultType means complete on incoming legacy results. Unknown string discriminators remain available to extensions. For example:
|
nodiscard |
Serialize client capabilities into a JSON object for the specified protocol version. A capability the target revision does not define is dropped, so serializing for an older revision than the one parsed is how a caller downgrades an advertisement. For example:
|
nodiscard |
Serialize advisory annotations, checking audience roles and gating lastModified to 2025-06-18 and later. Empty annotations remain an object. For example:
|
nodiscard |
Serialize server capabilities for an explicit revision. Typed flags override the source snapshot. Opaque settings survive only in retained capabilities. Throws MCPError for malformed known fields. For example:
|
nodiscardconstexprnoexcept |
Whether the specified MCP protocol version supports implementation description. For example:
|
nodiscardconstexprnoexcept |
Whether the specified MCP protocol version supports implementation title. For example:
|
nodiscardconstexprnoexcept |
Whether the specified MCP protocol version supports implementation website URL. For example:
|
nodiscardconstexprnoexcept |
Whether the specified MCP protocol version supports JSON-RPC batching. For example:
|
nodiscardconstexprnoexcept |
Whether a method is defined by the base protocol, including nested requests. This does not establish server implementation or negotiated extension support. For example:
|
nodiscardconstexprnoexcept |
Whether the specified MCP protocol version supports Multi Round-Trip Results (input_required). For example:
|
nodiscardconstexprnoexcept |
Whether the specified MCP protocol version supports output schema on tool definitions. For example:
|
nodiscardconstexprnoexcept |
Whether the specified MCP protocol version supports the ping method. For example:
|
nodiscardconstexprnoexcept |
Whether the specified MCP protocol version supports stateful protocol sessions. For example:
|
nodiscardconstexprnoexcept |
Whether the specified MCP protocol version supports resource link content. For example:
|
nodiscardconstexprnoexcept |
Whether the specified MCP protocol version supports the 2026-07-28 server/discover method. For example:
|
nodiscardconstexprnoexcept |
Whether the specified MCP protocol version supports structured content. For example:
|
nodiscardconstexprnoexcept |
Whether the specified MCP protocol version supports 2026-07-28 server-side subscriptions via subscriptions/listen. For example:
|
nodiscard |
Borrow the arguments object from a JSON-RPC tools/call envelope. Returns null when the member is absent or is not an object, so a tool that takes no arguments is indistinguishable from a malformed one here. For example:
|
nodiscardconstexprnoexcept |
Whether the specified MCP protocol version uses an initialization handshake (initialize / notifications/initialized). For example:
|
nodiscard |
Check continuation field shapes, exact state echo when expected, and known response kinds against the prior input requests. Unknown response keys are ignored. Core does not validate the user's form values against arbitrary JSON Schema, protect state integrity, or enforce new request IDs/history. This overload checks field shapes without matching a state token. For example:
|
nodiscard |
Check continuation fields and the state token, where the expected state selects one of three outcomes. Passing std::nullopt requires the token to be absent, which is how a server that issued no state enforces that the retry carries none. Passing an empty string requires a token that is present and empty. Passing any other string requires the token to equal it exactly. For example:
|
nodiscard |
Compare annotated parameters with raw HTTP headers case-insensitively. Validates required mirrors, encoding, duplicates and numeric equivalence. Protocol version must be 2026-07-28. The caller supplies the descriptors. Returns nothing when every mirror agrees, and a JSON-RPC error envelope otherwise. For example:
|
nodiscard |
Validate Streamable HTTP transport header values against the parsed JSON-RPC request body for the specified protocol version. Returns nothing when the headers agree with the body, and a ready-to-send JSON-RPC error envelope otherwise. Every revision in the supported list must be one this library models, which is a condition on the caller rather than on the peer, so a violation throws rather than producing an envelope. For example:
|
nodiscard |
Validate a borrowed HTTP header collection. Names are case insensitive. Duplicate recognized singleton fields are rejected. Unknown fields stay opaque. HTTP framing, Origin and session validation belong to the adapter. Returns nothing on success and a JSON-RPC error envelope otherwise. Every revision in the supported list must be one this library models, which is a condition on the caller rather than on the peer, so a violation throws rather than producing an envelope. For example:
|
nodiscard |
Validate and extract MCP 2026-07-28 request metadata from a request envelope. Use mcp_validate_request_parameters for parameters. The metadata is only present when the status is MCPRequestMetaStatus::Valid, and it borrows from the envelope. For example:
|
nodiscard |
Validate metadata in a parameters object, without guessing envelope shape. This is the entry point for a caller that has already located the parameters, such as one dispatching a batch member. For example:
| SOURCEMETA_CORE_MCP_EXPORT auto sourcemeta::core::mcp_write_result | ( | std::ostream & | stream, |
| MCPProtocolVersion | version, | ||
| JSON::StringView | method, | ||
| const JSON & | identifier, | ||
| const JSON & | result, | ||
| std::optional< MCPCachePolicy > | cache_policy, | ||
| std::optional< MCPImplementation > | server_info = std::nullopt ) -> void |
Serialize a complete MCP response for one of the six cacheable operations. The result is copied before decoration. The source remains unchanged. A cache policy is mandatory for 2026-07-28. Pass std::nullopt for legacy responses. A precomputed discovery result is held to the same rules as the builder that produces one, so its advertised revisions must be non-empty, must include the revision being served, and must each be one this library models. This writes JSON only. Stdio callers must append a newline themselves. For example:
| SOURCEMETA_CORE_MCP_EXPORT auto sourcemeta::core::mcp_write_result | ( | std::ostream & | stream, |
| MCPProtocolVersion | version, | ||
| JSON::StringView | method, | ||
| const JSON & | identifier, | ||
| JSON && | result, | ||
| std::optional< MCPCachePolicy > | cache_policy, | ||
| std::optional< MCPImplementation > | server_info = std::nullopt ) -> void |
Serialize a complete MCP response for one of the six cacheable operations using move semantics, decorating the provided result in-place. A cache policy is mandatory for 2026-07-28. Pass std::nullopt for legacy responses. A precomputed discovery result is held to the same rules as the builder that produces one, so its advertised revisions must be non-empty, must include the revision being served, and must each be one this library models. This writes JSON only. Stdio callers must append a newline themselves.
|
constexpr |
The MCP error code indicating that a transport header disagreed with the request body.
|
constexpr |
The MCP error code indicating that a required capability was not declared in request metadata.
|
constexpr |
The legacy MCP error code returned when a requested resource cannot be found.
|
constexpr |
The MCP error code indicating that the requested protocol version is not supported by the receiver.
|
constexpr |
The MCP error code indicating that the client must complete a URL elicitation flow before retrying. Defined in 2025-11-25 and retired in 2026-07-28.
|
constexpr |
Header name for the MCP method in Streamable HTTP transport.
|
constexpr |
Header name for the target name/URI in Streamable HTTP transport.
|
constexpr |
Header name for the protocol version in Streamable HTTP transport.
|
constexpr |
Wire string for the completion request method.
|
constexpr |
Wire string for the elicitation create request method.
|
constexpr |
Wire string for the initialization handshake request method.
|
constexpr |
Wire string for the legacy logging set-level request method.
|
constexpr |
Wire string for the cancelled notification method.
|
constexpr |
Wire method name for notifications/elicitation/complete.
|
constexpr |
Wire string for the initialization confirmation notification.
|
constexpr |
Wire string for the message notification method.
|
constexpr |
Wire string for the progress notification method.
|
constexpr |
Wire string for the prompts list changed notification method.
|
constexpr |
Wire string for the resources list changed notification method.
|
constexpr |
Wire string for the resources updated notification method.
|
constexpr |
Wire method name for notifications/roots/list_changed.
This feature is deprecated as of protocol version 2026-07-28, which states that new implementations should not adopt it. The method remains here because the library still speaks the revisions that define it.
|
constexpr |
Wire string for the 2026-07-28 subscriptions acknowledged notification.
|
constexpr |
Wire method name for notifications/tasks/status.
|
constexpr |
Wire string for the tools list changed notification method.
|
constexpr |
Wire string for the connection liveness check method.
|
constexpr |
|
constexpr |
Wire string for the prompts list request method.
|
constexpr |
Wire string for the resources list request method.
|
constexpr |
Wire string for the resource read request method.
|
constexpr |
Wire string for the resource subscribe request method.
|
constexpr |
Wire string for the resource templates list request method.
|
constexpr |
Wire string for the resource unsubscribe request method.
|
constexpr |
Wire string for the roots list request method.
This feature is deprecated as of protocol version 2026-07-28, which states that new implementations should not adopt it. The method remains here because the library still speaks the revisions that define it.
|
constexpr |
Wire string for the sampling create-message request method.
This feature is deprecated as of protocol version 2026-07-28, which states that new implementations should not adopt it. The method remains here because the library still speaks the revisions that define it.
|
constexpr |
Wire string for the 2026-07-28 server discovery request method.
|
constexpr |
Wire string for the 2026-07-28 subscriptions listen request method.
|
constexpr |
Wire method name for tasks/cancel.
|
constexpr |
Wire method name for tasks/get.
|
constexpr |
Wire method name for tasks/list.
|
constexpr |
Wire method name for tasks/result.
|
constexpr |
|
constexpr |
|
constexpr |
Wire string constant for MCP protocol version 2025-03-26.
|
constexpr |
Wire string constant for MCP protocol version 2025-06-18.
|
constexpr |
Wire string constant for MCP protocol version 2025-11-25.
|
constexpr |
Wire string constant for MCP protocol version 2026-07-28.