···
+
(** MCP - Model Context Protocol implementation
+
The Model Context Protocol (MCP) is a standardized protocol for AI agents to
+
exchange context with servers. This module provides the core OCaml
+
implementation of MCP including all message types, content representations,
+
and serialization functionality.
- Uses JSON-RPC 2.0 as its underlying message format with UTF-8 encoding
+
- Follows a client-server model where clients (often LLM-integrated
+
applications) communicate with MCP servers
- Supports multiple transport methods including stdio and streamable HTTP
+
- Implements a three-phase connection lifecycle: initialization, operation,
+
- Provides capability negotiation during initialization to determine
+
- Offers four primary context exchange mechanisms: 1. Resources:
+
Server-exposed data that provides context to language models 2. Tools:
+
Server-exposed functionality that can be invoked by language models 3.
+
Prompts: Server-defined templates for structuring interactions with models
4. Sampling: Client-exposed ability to generate completions from LLMs
+
- Supports multimodal content types: text, images, audio, and embedded
- Includes standardized error handling with defined error codes
+
This implementation follows Protocol Revision 2025-03-26. *)
+
(** Utility functions for JSON parsing *)
+
val json_error : ('a, unit, string, 'b) format4 -> Json.t -> 'a
+
(** Helper to raise a Json.Of_json exception with formatted message
+
@param fmt Format string for the error message
+
@param json JSON value to include in the exception
+
@return Never returns, always raises an exception
+
@raise Json.Of_json with the formatted message and JSON value *)
+
val get_string_field : (string * Json.t) list -> string -> Json.t -> string
+
(** Extract a string field from JSON object or raise an error
+
@param fields Assoc list of fields from JSON object
+
@param name Field name to extract
+
@param json Original JSON for error context
+
@return The string value of the field
+
@raise Json.Of_json if the field is missing or not a string *)
+
val get_optional_string_field :
+
(string * Json.t) list -> string -> string option
+
(** Extract an optional string field from JSON object
+
@param fields Assoc list of fields from JSON object
+
@param name Field name to extract
+
@return Some string if present and a string, None if missing
+
@raise Json.Of_json if the field exists but is not a string *)
+
val get_int_field : (string * Json.t) list -> string -> Json.t -> int
+
(** Extract an int field from JSON object or raise an error
+
@param fields Assoc list of fields from JSON object
+
@param name Field name to extract
+
@param json Original JSON for error context
+
@return The int value of the field
+
@raise Json.Of_json if the field is missing or not an int *)
+
val get_float_field : (string * Json.t) list -> string -> Json.t -> float
+
(** Extract a float field from JSON object or raise an error
+
@param fields Assoc list of fields from JSON object
+
@param name Field name to extract
+
@param json Original JSON for error context
+
@return The float value of the field
+
@raise Json.Of_json if the field is missing or not a float *)
+
val get_bool_field : (string * Json.t) list -> string -> Json.t -> bool
+
(** Extract a boolean field from JSON object or raise an error
+
@param fields Assoc list of fields from JSON object
+
@param name Field name to extract
+
@param json Original JSON for error context
+
@return The boolean value of the field
+
@raise Json.Of_json if the field is missing or not a boolean *)
+
(string * Json.t) list -> string -> Json.t -> (string * Json.t) list
+
(** Extract an object field from JSON object or raise an error
+
@param fields Assoc list of fields from JSON object
+
@param name Field name to extract
+
@param json Original JSON for error context
+
@return The object as an assoc list
+
@raise Json.Of_json if the field is missing or not an object *)
+
val get_list_field : (string * Json.t) list -> string -> Json.t -> Json.t list
+
(** Extract a list field from JSON object or raise an error
+
@param fields Assoc list of fields from JSON object
+
@param name Field name to extract
+
@param json Original JSON for error context
+
@raise Json.Of_json if the field is missing or not a list *)
+
val verify_string_field :
+
(string * Json.t) list -> string -> string -> Json.t -> unit
+
(** Verify a specific string value in a field
+
@param fields Assoc list of fields from JSON object
+
@param name Field name to check
+
@param expected_value The expected string value
+
@param json Original JSON for error context
+
@raise Json.Of_json if the field is missing or not equal to expected_value
(** Error codes for JSON-RPC *)
(** Standard JSON-RPC error codes with MCP-specific additions *)
+
| ParseError (** -32700 - Invalid JSON *)
+
| InvalidRequest (** -32600 - Invalid JSON-RPC request *)
+
| MethodNotFound (** -32601 - Method not available *)
+
| InvalidParams (** -32602 - Invalid method parameters *)
+
| InternalError (** -32603 - Internal JSON-RPC error *)
+
(** -32002 - Custom MCP error: requested resource not found *)
+
| AuthRequired (** -32001 - Custom MCP error: authentication required *)
+
| CustomError of int (** For any other error codes *)
(** Convert the error code to its integer representation
@param code The error code to convert
+
@return The integer error code as defined in the JSON-RPC spec *)
+
val to_message : t -> string
(** Get error message for standard error codes
@param code The error code to get message for
+
@return A standard message for the error code *)
+
(** MCP Protocol Methods - Algebraic data type representing all MCP methods *)
+
(** Method type representing all MCP protocol methods *)
+
(* Initialization and lifecycle methods *)
+
| Initialize (** Start the MCP lifecycle *)
+
| Initialized (** Signal readiness after initialization *)
+
| ResourcesList (** Discover available resources *)
+
| ResourcesRead (** Retrieve resource contents *)
+
| ResourceTemplatesList (** List available resource templates *)
+
| ResourcesSubscribe (** Subscribe to resource changes *)
+
| ResourcesListChanged (** Resource list has changed *)
+
| ResourcesUpdated (** Resource has been updated *)
+
| ToolsList (** Discover available tools *)
+
| ToolsCall (** Invoke a tool *)
+
| ToolsListChanged (** Tool list has changed *)
+
| PromptsList (** Discover available prompts *)
+
| PromptsGet (** Retrieve a prompt template with arguments *)
+
| PromptsListChanged (** Prompt list has changed *)
+
(* Progress notifications *)
+
| Progress (** Progress update for long-running operations *)
+
val to_string : t -> string
+
(** Convert method type to string representation
+
@param meth The method to convert
+
The string representation of the method (e.g., "initialize",
+
val of_string : string -> t
+
(** Convert string to method type
+
@param s The string representation of the method
+
@return The corresponding method type
+
@raise Failure if the string is not a valid MCP method *)
(** Roles for conversation participants *)
type t = [ `User | `Assistant ]
+
(** Role represents conversation participants in MCP messages. Roles can be
+
either 'user' or 'assistant', determining the source of each message in a
include Json.Jsonable.S with type t := t
(** Progress tokens for long-running operations *)
module ProgressToken : sig
type t = [ `String of string | `Int of int ]
+
(** Progress tokens identify long-running operations and enable servers to
+
provide progress updates to clients. This is used to track operations that
+
may take significant time to complete. *)
include Json.Jsonable.S with type t := t
type t = [ `String of string | `Int of int ]
+
(** Request IDs uniquely identify JSON-RPC requests, allowing responses to be
+
correlated with their originating requests. They can be either string or
include Json.Jsonable.S with type t := t
(** Cursors for pagination *)
+
(** Cursors enable pagination in list operations for resources, tools, and
+
prompts. When a server has more items than can be returned in a single
+
response, it provides a cursor for the client to retrieve subsequent
include Json.Jsonable.S with type t := t
(** Annotations for objects *)
+
type t = { annotations : annotation option }
+
(** Annotations provide metadata for content objects, allowing role-specific
+
targeting and priority settings. *)
+
audience : Role.t list option;
+
(** Optional list of roles that should receive this content *)
+
priority : float option; (** Optional priority value for this content *)
include Json.Jsonable.S with type t := t
(** Text content - Core textual message representation in MCP *)
+
text : string; (** The actual text content as a UTF-8 encoded string *)
+
annotations : Annotated.annotation option;
+
(** Optional annotations for audience targeting and priority.
+
Annotations can restrict content visibility to specific roles
+
(user/assistant) and indicate relative importance of different
+
(** TextContent represents plain text messages in MCP conversations. This is
+
the most common content type used for natural language interactions
+
between users and assistants. Text content is used in prompts, tool
+
results, and model responses.
In JSON-RPC, this is represented as:
···
"text": "The text content of the message"
For security, implementations must sanitize text content to prevent
injection attacks or unauthorized access to resources. *)
include Json.Jsonable.S with type t := t
(** Image content - Visual data representation in MCP *)
module ImageContent : sig
+
(** Base64-encoded image data. All binary image data must be encoded
+
using standard base64 encoding (RFC 4648) to safely transmit within
+
(** MIME type of the image (e.g., "image/png", "image/jpeg",
+
"image/gif", "image/svg+xml"). This field is required and must
+
accurately represent the image format to ensure proper handling by
+
annotations : Annotated.annotation option;
+
(** Optional annotations for audience targeting and priority.
+
Annotations can restrict content visibility to specific roles
+
(user/assistant) and indicate relative importance of different
(** ImageContent enables including visual information in MCP messages,
supporting multimodal interactions where visual context is important.
Images can be used in several scenarios:
- As user inputs for visual understanding tasks
- As context for generating descriptions or analysis
- As outputs from tools that generate visualizations
- As part of prompt templates with visual components
In JSON-RPC, this is represented as:
···
The data MUST be base64-encoded to ensure safe transmission in JSON.
+
Common mime types include image/png, image/jpeg, image/gif, and
include Json.Jsonable.S with type t := t
(** Audio content - Sound data representation in MCP *)
module AudioContent : sig
+
(** Base64-encoded audio data. All binary audio data must be encoded
+
using standard base64 encoding (RFC 4648) to safely transmit within
+
(** MIME type of the audio (e.g., "audio/wav", "audio/mp3", "audio/ogg",
+
"audio/mpeg"). This field is required and must accurately represent
+
the audio format to ensure proper handling by clients. *)
+
annotations : Annotated.annotation option;
+
(** Optional annotations for audience targeting and priority.
+
Annotations can restrict content visibility to specific roles
+
(user/assistant) and indicate relative importance of different
(** AudioContent enables including audio information in MCP messages,
supporting multimodal interactions where audio context is important.
Audio can be used in several scenarios:
- As user inputs for speech recognition or audio analysis
- As context for transcription or sound classification tasks
- As outputs from tools that generate audio samples
- As part of prompt templates with audio components
In JSON-RPC, this is represented as:
···
The data MUST be base64-encoded to ensure safe transmission in JSON.
+
Common mime types include audio/wav, audio/mp3, audio/ogg, and audio/mpeg.
include Json.Jsonable.S with type t := t
(** Base resource contents - Core resource metadata in MCP *)
module ResourceContents : sig
+
(** URI that uniquely identifies the resource.
+
Resources use standard URI schemes including:
+
- file:// - For filesystem-like resources
+
- https:// - For web-accessible resources
+
- git:// - For version control integration
+
The URI serves as a stable identifier even if the underlying content
+
mime_type : string option;
+
(** Optional MIME type of the resource content to aid in client
+
rendering. Common MIME types include text/plain, application/json,
+
image/png, etc. For directories, the XDG MIME type inode/directory
(** ResourceContents provides basic metadata for resources in MCP.
+
Resources are server-exposed data that provides context to language
+
models, such as files, database schemas, or application-specific
+
information. Each resource is uniquely identified by a URI.
The MCP resources architecture is designed to be application-driven, with
+
host applications determining how to incorporate context based on their
+
In the protocol, resources are discovered via the 'resources/list'
+
endpoint and retrieved via the 'resources/read' endpoint. Servers that
+
support resources must declare the 'resources' capability during
include Json.Jsonable.S with type t := t
(** Text resource contents - Textual resource data *)
module TextResourceContents : sig
+
(** URI that uniquely identifies the resource. This URI can be
+
referenced in subsequent requests to fetch updates. *)
+
(** The actual text content of the resource as a UTF-8 encoded string.
+
This may be sanitized by the server to remove sensitive information.
+
mime_type : string option;
+
(** Optional MIME type of the text content to aid in client rendering.
+
Common text MIME types include: text/plain, text/markdown,
+
text/x-python, application/json, text/html, text/csv, etc. *)
(** TextResourceContents represents a text-based resource in MCP.
Text resources are used for sharing code snippets, documentation, logs,
configuration files, and other textual information with language models.
The server handles access control and security, ensuring that only
authorized resources are shared with clients.
In JSON-RPC, this is represented as:
···
"mimeType": "text/plain",
"text": "Resource content"
include Json.Jsonable.S with type t := t
(** Binary resource contents - Binary resource data *)
module BlobResourceContents : sig
+
(** URI that uniquely identifies the resource. This URI can be
+
referenced in subsequent requests to fetch updates. *)
+
(** Base64-encoded binary data using standard base64 encoding (RFC
+
4648). This encoding ensures that binary data can be safely
+
transmitted in JSON. *)
+
mime_type : string option;
+
(** Optional MIME type of the binary content to aid in client rendering.
+
Common binary MIME types include: image/png, image/jpeg,
+
application/pdf, audio/wav, video/mp4, application/octet-stream,
(** BlobResourceContents represents a binary resource in MCP.
Binary resources allow sharing non-textual data like images, audio files,
+
PDFs, and other binary formats with language models that support
+
processing such content.
In JSON-RPC, this is represented as:
···
"blob": "base64-encoded-data"
+
Binary data MUST be properly base64-encoded to ensure safe transmission in
include Json.Jsonable.S with type t := t
(** Embedded resource - Resource included directly in messages *)
module EmbeddedResource : sig
+
[ `Text of TextResourceContents.t | `Blob of BlobResourceContents.t ];
+
(** The resource content, either as text or binary blob. *)
+
annotations : Annotated.annotation option;
+
(** Optional annotations for audience targeting and priority.
+
Annotations can restrict resource visibility to specific roles
+
(user/assistant) and indicate relative importance of different
+
(** EmbeddedResource allows referencing server-side resources directly in MCP
+
messages, enabling seamless incorporation of managed content.
Embedded resources can be included in:
- Tool results to provide rich context
- Prompt templates to include reference materials
- Messages to provide additional context to language models
In contrast to direct content (TextContent, ImageContent, AudioContent),
+
embedded resources have the advantage of being persistently stored on the
+
server with a stable URI, allowing later retrieval and updates through the
+
For example, a tool might return an embedded resource containing a chart
+
or a large dataset that the client can later reference or update. *)
include Json.Jsonable.S with type t := t
+
(** Content type used in messages - Unified multimodal content representation in
+
| Text of TextContent.t
+
(** Text content for natural language messages. This is the most common
+
content type for user-assistant interactions. *)
+
| Image of ImageContent.t
+
(** Image content for visual data. Used for sharing visual context in
+
multimodal conversations. *)
+
| Audio of AudioContent.t
+
(** Audio content for audio data. Used for sharing audio context in
+
multimodal conversations. *)
+
| Resource of EmbeddedResource.t
+
(** Resource content for referencing server-side resources. Used for
+
incorporating managed server content with stable URIs. *)
+
val yojson_of_content : content -> Json.t
+
(** Convert content to Yojson representation
@param content The content to convert
+
@return JSON representation of the content *)
val content_of_yojson : Json.t -> content
+
(** Convert Yojson representation to content
+
@param json JSON representation of content
+
@return Parsed content object *)
(** Message for prompts - Template messages in the MCP prompts feature *)
module PromptMessage : sig
+
(** The role of the message sender (user or assistant). Prompt templates
+
typically alternate between user and assistant messages to create a
+
conversation structure. *)
+
(** The message content, which can be text, image, audio, or resource.
+
This unified content type supports rich multimodal prompts. *)
+
(** PromptMessage represents a message in an MCP prompt template, containing a
+
role and content which can be customized with arguments.
Prompt messages are part of prompt templates exposed by servers through
the prompts/get endpoint. They define structured conversation templates
that can be instantiated with user-provided arguments.
+
The prompt feature is designed to be user-controlled, with prompts
+
typically exposed through UI elements like slash commands that users can
In JSON-RPC, prompt messages are represented as:
···
Where $code would be replaced with a user-provided argument. *)
include Json.Jsonable.S with type t := t
(** Message for sampling - Messages used in LLM completion requests *)
module SamplingMessage : sig
+
(** The role of the message sender (user or assistant). Typically, a
+
sampling request will contain multiple messages representing a
+
conversation history, with alternating roles. *)
+
[ `Text of TextContent.t
+
| `Image of ImageContent.t
+
| `Audio of AudioContent.t ];
+
(** The message content, restricted to text, image, or audio (no
+
resources). Resources are not included since sampling messages
+
represent the actual context window for the LLM, not template
+
(** SamplingMessage represents a message in an MCP sampling request, used for
+
AI model generation based on a prompt.
The sampling feature allows clients to expose language model capabilities
to servers, enabling servers to request completions from the client's LLM.
This is effectively the reverse of the normal MCP flow, with the server
requesting generative capabilities from the client.
Sampling messages differ from prompt messages in that they don't support
+
embedded resources, as they represent the actual context window being sent
+
to the LLM rather than template definitions.
Clients that support sampling must declare the 'sampling' capability
during initialization. *)
include Json.Jsonable.S with type t := t
(** Implementation information *)
module Implementation : sig
+
name : string; (** Name of the implementation *)
+
version : string; (** Version of the implementation *)
+
(** Implementation provides metadata about client and server implementations,
+
used during the initialization phase to identify each party. *)
include Json.Jsonable.S with type t := t
(** JSONRPC message types - Core message protocol for MCP
+
MCP uses JSON-RPC 2.0 as its underlying messaging protocol. All MCP messages
+
are encoded as JSON-RPC 2.0 messages with UTF-8 encoding, following the
+
standard JSON-RPC message formats with some MCP-specific extensions.
+
MCP defines four message types: 1. Notifications: One-way messages that
+
don't expect a response 2. Requests: Messages that expect a corresponding
+
response 3. Responses: Replies to requests with successful results 4.
+
Errors: Replies to requests with error information
These can be transported over multiple transport mechanisms:
- stdio: Communication over standard input/output
- Streamable HTTP: HTTP POST/GET with SSE for server streaming
- Custom transports: Implementation-specific transports
+
Messages may be sent individually or as part of a JSON-RPC batch. *)
module JSONRPCMessage : sig
+
(** Method for the notification, using the Method.t type to ensure type
+
safety. Examples: Method.Initialized, Method.ResourcesUpdated *)
+
params : Json.t option;
+
(** Optional parameters for the notification as arbitrary JSON. The
+
structure depends on the specific notification method. *)
+
(** Notification represents a JSON-RPC notification (one-way message without a
Notifications are used for events that don't require a response, such as:
- The 'initialized' notification completing initialization
- Resource change notifications
- Progress updates for long-running operations
- List changed notifications for tools, resources, and prompts
In JSON-RPC, notifications are identified by the absence of an 'id' field:
···
"uri": "file:///project/src/main.rs"
+
(** Unique identifier for the request, which will be echoed in the
+
response. This can be a string or integer and should be unique
+
(** Method for the request, using the Method.t type to ensure type
+
safety. Examples: Method.Initialize, Method.ResourcesRead,
+
params : Json.t option;
+
(** Optional parameters for the request as arbitrary JSON. The structure
+
depends on the specific request method. *)
+
progress_token : ProgressToken.t option;
+
(** Optional progress token for long-running operations. If provided,
+
the server can send progress notifications using this token to
+
inform the client about the operation's status. *)
(** Request represents a JSON-RPC request that expects a response.
Requests are used for operations that require a response, such as:
- Listing resources, tools, or prompts
+
In JSON-RPC, requests include an 'id' field that correlates with the
···
"uri": "file:///project/src/main.rs"
+
(** ID matching the original request, allowing clients to correlate
+
responses with their originating requests, especially important when
+
multiple requests are in flight. *)
+
(** Result of the successful request as arbitrary JSON. The structure
+
depends on the specific request method that was called. *)
(** Response represents a successful JSON-RPC response to a request.
Responses are sent in reply to requests and contain the successful result.
Each response must include the same ID as its corresponding request.
In JSON-RPC, responses include the 'id' field matching the request:
···
+
(** ID matching the original request, allowing clients to correlate
+
errors with their originating requests. *)
+
(** Error code indicating the type of error, following the JSON-RPC
+
standard. Common codes include:
+
- -32600: Invalid request
+
- -32601: Method not found
+
- -32602: Invalid params
+
- -32603: Internal error
+
- -32002: Resource not found (MCP-specific)
+
- -32001: Authentication required (MCP-specific) *)
+
(** Human-readable error message describing the issue. This should be
+
concise but informative enough for debugging. *)
+
(** Optional additional error data as arbitrary JSON. This can provide
+
more context about the error, such as which resource wasn't found or
+
which parameter was invalid. *)
(** Error represents an error response to a JSON-RPC request.
+
Errors are sent in reply to requests when processing fails. Each error
+
must include the same ID as its corresponding request.
MCP defines several standard error codes:
- Standard JSON-RPC errors (-32700 to -32603)
- MCP-specific errors (-32002 for resource not found, etc.)
In JSON-RPC, errors follow this structure:
···
+
(** Union type for all JSON-RPC message kinds, providing a single type that
+
can represent any MCP message. *)
| Notification of notification
val yojson_of_notification : notification -> Json.t
+
(** Convert notification to Yojson representation
+
@param notification The notification to convert
+
@return JSON representation of the notification *)
val yojson_of_request : request -> Json.t
+
(** Convert request to Yojson representation
+
@param request The request to convert
+
@return JSON representation of the request *)
+
val yojson_of_response : response -> Json.t
+
(** Convert response to Yojson representation
@param response The response to convert
+
@return JSON representation of the response *)
+
val yojson_of_error : error -> Json.t
+
(** Convert error to Yojson representation
@param error The error to convert
+
@return JSON representation of the error *)
+
val yojson_of_t : t -> Json.t
+
(** Convert any message to Yojson representation
@param message The message to convert
+
@return JSON representation of the message *)
+
val notification_of_yojson : Json.t -> notification
+
(** Convert Yojson representation to notification
@param json JSON representation of a notification
@return Parsed notification object
+
@raise Parse error if the JSON is not a valid notification *)
+
val request_of_yojson : Json.t -> request
+
(** Convert Yojson representation to request
@param json JSON representation of a request
@return Parsed request object
+
@raise Parse error if the JSON is not a valid request *)
+
val response_of_yojson : Json.t -> response
+
(** Convert Yojson representation to response
@param json JSON representation of a response
@return Parsed response object
+
@raise Parse error if the JSON is not a valid response *)
+
val error_of_yojson : Json.t -> error
+
(** Convert Yojson representation to error
@param json JSON representation of an error
@return Parsed error object
+
@raise Parse error if the JSON is not a valid error *)
+
val t_of_yojson : Json.t -> t
+
(** Convert Yojson representation to any message
@param json JSON representation of any message type
@return Parsed message object
+
@raise Parse error if the JSON is not a valid message *)
+
val create_notification : ?params:Json.t option -> meth:Method.t -> unit -> t
(** Create a new notification message
@param params Optional parameters for the notification
+
@param meth Method name for the notification
+
@return A new JSON-RPC notification message *)
+
?params:Json.t option ->
+
?progress_token:ProgressToken.t option ->
(** Create a new request message
@param params Optional parameters for the request
@param progress_token Optional progress token for long-running operations
@param id Unique identifier for the request
+
@param meth Method name for the request
+
@return A new JSON-RPC request message *)
+
val create_response : id:RequestId.t -> result:Json.t -> t
(** Create a new response message
@param id ID matching the original request
@param result Result of the successful request
+
@return A new JSON-RPC response message *)
(** Create a new error message
@param id ID matching the original request
@param code Error code indicating the type of error
@param message Human-readable error message
@param data Optional additional error data
+
@return A new JSON-RPC error message *)
+
(** Initialize request/response - The first phase of the MCP lifecycle
+
The initialization phase is the mandatory first interaction between client
+
and server. During this phase, the protocol version is negotiated and
+
capabilities are exchanged to determine which optional features will be
+
available during the session.
+
This follows a strict sequence: 1. Client sends an InitializeRequest
+
containing its capabilities and protocol version 2. Server responds with an
+
InitializeResult containing its capabilities and protocol version 3. Client
+
sends an InitializedNotification to signal it's ready for normal operations
+
The Initialize module handles steps 1 and 2 of this process. *)
(** Initialize request *)
+
(** ClientCapabilities that define supported optional features. This
+
includes which optional protocol features the client supports,
+
such as 'roots' (filesystem access), 'sampling' (LLM generation),
+
and any experimental features. *)
+
client_info : Implementation.t;
+
(** Client implementation details (name and version) used for
+
identification and debugging. Helps servers understand which
+
client they're working with. *)
+
protocol_version : string;
+
(** MCP protocol version supported by the client, formatted as
+
YYYY-MM-DD according to the MCP versioning scheme. Example:
+
(** InitializeRequest starts the MCP lifecycle, negotiating capabilities and
+
protocol versions between client and server. This is always the first
+
message sent by the client and MUST NOT be part of a JSON-RPC batch.
+
The client SHOULD send the latest protocol version it supports. If the
+
server does not support this version, it will respond with a version it
+
does support, and the client must either use that version or disconnect.
include Json.Jsonable.S with type t := t
+
client_info:Implementation.t ->
+
protocol_version:string ->
(** Create a new initialization request
+
Client capabilities that define supported optional features
@param client_info Client implementation details
@param protocol_version MCP protocol version supported by the client
+
@return A new initialization request *)
+
val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t
(** Convert to JSON-RPC message
@param id Unique request identifier
@param t Initialization request
+
@return JSON-RPC message containing the initialization request *)
+
(** ServerCapabilities that define supported optional features. This
+
declares which server features are available, including:
+
- prompts: Server provides prompt templates
+
- resources: Server provides readable resources
+
- tools: Server exposes callable tools
+
- logging: Server emits structured log messages
+
Each capability may have sub-capabilities like:
+
- listChanged: Server will notify when available items change
+
- subscribe: Clients can subscribe to individual resources *)
+
server_info : Implementation.t;
+
(** Server implementation details (name and version) used for
+
identification and debugging. Helps clients understand which
+
server they're working with. *)
+
protocol_version : string;
+
(** MCP protocol version supported by the server, formatted as
+
YYYY-MM-DD. If the server supports the client's requested version,
+
it responds with the same version. Otherwise, it responds with a
+
version it does support. *)
+
instructions : string option;
+
(** Optional instructions for using the server. These can provide
+
human-readable guidance on how to interact with this specific
+
server implementation. *)
+
(** Optional additional metadata as arbitrary JSON. Can contain
+
server-specific information not covered by the standard fields. *)
(** InitializeResult is the server's response to an initialization request,
completing capability negotiation and establishing the protocol version.
+
After receiving this message, the client must send an
+
InitializedNotification. The server should not send any requests other
+
than pings and logging before receiving the initialized notification. *)
include Json.Jsonable.S with type t := t
+
server_info:Implementation.t ->
+
protocol_version:string ->
+
?instructions:string ->
(** Create a new initialization result
+
Server capabilities that define supported optional features
@param server_info Server implementation details
@param protocol_version MCP protocol version supported by the server
@param instructions Optional instructions for using the server
@param meta Optional additional metadata
+
@return A new initialization result *)
+
val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t
(** Convert to JSON-RPC message
@param id ID matching the original request
@param t Initialization result
+
@return JSON-RPC message containing the initialization result *)
+
(** Initialized notification - Completes the initialization phase of the MCP
module Notification : sig
+
(** Optional additional metadata as arbitrary JSON. Can contain
+
client-specific information not covered by the standard fields. *)
+
(** InitializedNotification is sent by the client after receiving the
+
initialization response, indicating it's ready to begin normal
+
operations. This completes the three-step initialization process, after
+
which both client and server can freely exchange messages according to
+
the negotiated capabilities.
+
Only after this notification has been sent should the client begin
+
normal operations like listing resources, calling tools, or requesting
include Json.Jsonable.S with type t := t
+
val create : ?meta:Json.t -> unit -> t
(** Create a new initialized notification
@param meta Optional additional metadata
+
@return A new initialized notification *)
+
val to_jsonrpc : t -> JSONRPCMessage.t
(** Convert to JSON-RPC message
@param t Initialized notification
+
@return JSON-RPC message containing the initialized notification *)
+
val parse_message : Json.t -> JSONRPCMessage.t
+
(** Parse a JSON message into an MCP message
+
This function takes a raw JSON value and parses it into a structured MCP
+
message. It's the primary entry point for processing incoming JSON-RPC
+
messages in the MCP protocol.
+
The function determines the message type (notification, request, response,
+
or error) based on the presence and values of specific fields:
- A message with "method" but no "id" is a notification
- A message with "method" and "id" is a request
- A message with "id" and "result" is a response
- A message with "id" and "error" is an error
+
The JSON message to parse, typically received from the transport layer
@return The parsed MCP message as a structured JSONRPCMessage.t value
+
@raise Parse error if the JSON cannot be parsed as a valid MCP message *)
+
val create_notification :
+
?params:Json.t option -> meth:Method.t -> unit -> JSONRPCMessage.t
(** Create a new notification message
+
Notifications are one-way messages that don't expect a response. This is a
+
convenience wrapper around JSONRPCMessage.create_notification.
Common notifications in MCP include:
- "notifications/initialized" - Sent after initialization
- "notifications/progress" - Updates on long-running operations
- "notifications/resources/updated" - Resource content changed
- "notifications/prompts/list_changed" - Available prompts changed
- "notifications/tools/list_changed" - Available tools changed
@param params Optional parameters for the notification as a JSON value
+
@param meth Method type for the notification
+
@return A new JSON-RPC notification message *)
+
?params:Json.t option ->
+
?progress_token:ProgressToken.t option ->
(** Create a new request message
+
Requests are messages that expect a corresponding response. This is a
+
convenience wrapper around JSONRPCMessage.create_request.
Common requests in MCP include:
- "initialize" - Start the MCP lifecycle
- "resources/list" - Discover available resources
···
- "tools/call" - Invoke a tool
- "prompts/list" - Discover available prompts
- "prompts/get" - Retrieve a prompt template
@param params Optional parameters for the request as a JSON value
+
Optional progress token for long-running operations that can report
+
Unique identifier for the request, used to correlate with the response
+
@param meth Method type for the request
+
@return A new JSON-RPC request message *)
+
val create_response : id:RequestId.t -> result:Json.t -> JSONRPCMessage.t
(** Create a new response message
+
Responses are sent in reply to requests and contain successful results. This
+
is a convenience wrapper around JSONRPCMessage.create_response.
+
Each response must include the same ID as its corresponding request to allow
+
the client to correlate them, especially when multiple requests are in
@param id ID matching the original request
@param result Result of the successful request as a JSON value
+
@return A new JSON-RPC response message *)
(** Create a new error message
+
Errors are sent in reply to requests when processing fails. This is a
+
convenience wrapper around JSONRPCMessage.create_error.
+
MCP uses standard JSON-RPC error codes as well as some protocol-specific
- -32700: Parse error (invalid JSON)
- -32600: Invalid request (malformed JSON-RPC)
- -32601: Method not found
···
- -32002: Resource not found (MCP-specific)
- -32001: Authentication required (MCP-specific)
@param id ID matching the original request
@param code Error code indicating the type of error
@param message Human-readable error message describing the issue
@param data Optional additional error data providing more context
+
@return A new JSON-RPC error message *)
+
val make_text_content : string -> content
(** Create a new text content object
@param text The text content
+
@return A content value with the text *)
+
val make_image_content : string -> string -> content
(** Create a new image content object
@param data Base64-encoded image data
+
@param mime_type MIME type of the image (e.g., "image/png", "image/jpeg")
+
@return A content value with the image *)
+
val make_audio_content : string -> string -> content
(** Create a new audio content object
@param data Base64-encoded audio data
@param mime_type MIME type of the audio (e.g., "audio/wav", "audio/mp3")
+
@return A content value with the audio *)
+
val make_resource_text_content : string -> string -> string option -> content
(** Create a new text resource content object
@param uri URI that uniquely identifies the resource
@param text The text content of the resource
@param mime_type Optional MIME type of the text content
+
@return A content value with the text resource *)
+
val make_resource_blob_content : string -> string -> string option -> content
(** Create a new binary resource content object
@param uri URI that uniquely identifies the resource
@param blob Base64-encoded binary data
@param mime_type Optional MIME type of the binary content
+
@return A content value with the binary resource *)
anil.recoil.org