···
+
(** 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, and shutdown
+
- Provides capability negotiation during initialization to determine available features
+
- 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 resources
+
- Includes standardized error handling with defined error codes
+
This implementation follows Protocol Revision 2025-03-26.
···
(** Roles for conversation participants *)
+
(** Role represents conversation participants in MCP messages.
+
Roles can be either 'user' or 'assistant', determining the
+
source of each message in a conversation. *)
type t = [ `User | `Assistant ]
include Json.Jsonable.S with type t := t
(** Progress tokens for long-running operations *)
module ProgressToken : sig
+
(** 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. *)
type t = [ `String of string | `Int of int ]
include Json.Jsonable.S with type t := t
+
(** Request IDs uniquely identify JSON-RPC requests, allowing responses
+
to be correlated with their originating requests. They can be either
+
string or integer values. *)
type t = [ `String of string | `Int of int ]
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 pages. *)
include Json.Jsonable.S with type t := t
(** Annotations for objects *)
+
(** Annotations provide metadata for content objects, allowing
+
role-specific targeting and priority settings. *)
annotations: annotation option;
audience: Role.t list option;
+
(** Optional list of roles that should receive this content *)
+
(** Optional priority value for this content *)
include Json.Jsonable.S with type t := t
+
(** Text content - Core textual message representation in MCP *)
+
(** 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,
+
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. *)
+
(** 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 content elements. *)
include Json.Jsonable.S with type t := t
+
(** Image content - Visual data representation in MCP *)
module ImageContent : sig
+
(** 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:
+
"data": "base64-encoded-image-data",
+
"mimeType": "image/png"
+
The data MUST be base64-encoded to ensure safe transmission in JSON.
+
Common mime types include image/png, image/jpeg, image/gif, and image/svg+xml. *)
+
(** Base64-encoded image data. All binary image data must be encoded using
+
standard base64 encoding (RFC 4648) to safely transmit within JSON. *)
+
(** 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 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 content elements. *)
include Json.Jsonable.S with type t := t
+
(** Audio content - Sound data representation in MCP *)
module AudioContent : sig
+
(** 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:
+
"data": "base64-encoded-audio-data",
+
"mimeType": "audio/wav"
+
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. *)
+
(** Base64-encoded audio data. All binary audio data must be encoded using
+
standard base64 encoding (RFC 4648) to safely transmit within JSON. *)
+
(** 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 content elements. *)
include Json.Jsonable.S with type t := t
+
(** Base resource contents - Core resource metadata in MCP *)
module ResourceContents : sig
+
(** 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 needs.
+
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 initialization. *)
+
(** 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 changes. *)
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 may be used. *)
include Json.Jsonable.S with type t := t
+
(** Text resource contents - Textual resource data *)
module TextResourceContents : sig
+
(** 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:
+
"uri": "file:///example.txt",
+
"mimeType": "text/plain",
+
"text": "Resource content"
+
(** 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. *)
include Json.Jsonable.S with type t := t
+
(** Binary resource contents - Binary resource data *)
module BlobResourceContents : sig
+
(** 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
+
In JSON-RPC, this is represented as:
+
"uri": "file:///example.png",
+
"mimeType": "image/png",
+
"blob": "base64-encoded-data"
+
Binary data MUST be properly base64-encoded to ensure safe transmission
+
(** 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, etc. *)
include Json.Jsonable.S with type t := t
+
(** Embedded resource - Resource included directly in messages *)
module EmbeddedResource : sig
+
(** 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 resources API.
+
For example, a tool might return an embedded resource containing a chart or
+
a large dataset that the client can later reference or update. *)
resource: [ `Text of TextResourceContents.t | `Blob of BlobResourceContents.t ];
+
(** The resource content, either as text or binary blob.
+
This polymorphic variant allows handling both text and binary resources
+
with a unified interface, while maintaining type safety. *)
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 content elements. *)
include Json.Jsonable.S with type t := t
+
(** Content type used in messages - Unified multimodal content representation in MCP *)
+
| 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. *)
+
(** Convert content to Yojson representation
+
@param content The content to convert
+
@return JSON representation of the content
val yojson_of_content : content -> Json.t
+
(** Convert Yojson representation to content
+
@param json JSON representation of content
+
@return Parsed content object
val content_of_yojson : Json.t -> content
+
(** Message for prompts - Template messages in the MCP prompts feature *)
module PromptMessage : sig
+
(** 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 explicitly select.
+
In JSON-RPC, prompt messages are represented as:
+
"text": "Please review this code: ${code}"
+
Where $code would be replaced with a user-provided argument. *)
+
(** 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. *)
include Json.Jsonable.S with type t := t
+
(** Message for sampling - Messages used in LLM completion requests *)
module SamplingMessage : sig
+
(** 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. *)
+
(** The role of the message sender (user or assistant).
+
Typically, a sampling request will contain multiple messages
+
representing a conversation history, with alternating roles. *)
content: [ `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 definitions. *)
include Json.Jsonable.S with type t := t
(** Implementation information *)
module Implementation : sig
+
(** Implementation provides metadata about client and server implementations,
+
used during the initialization phase to identify each party. *)
+
(** Name of the implementation *)
+
(** Version of the implementation *)
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
+
(** Notification represents a JSON-RPC notification (one-way message without a response).
+
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:
+
"method": "notifications/resources/updated",
+
"uri": "file:///project/src/main.rs"
+
(** Method name for the notification, following the MCP naming conventions.
+
Common method patterns include:
+
- "notifications/X" for standard notifications
+
- "notifications/X/Y" for more specific notifications
+
Examples: "notifications/initialized", "notifications/resources/updated" *)
+
(** Optional parameters for the notification as arbitrary JSON.
+
The structure depends on the specific notification method. *)
+
(** 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 response:
+
"method": "resources/read",
+
"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 within the session. *)
+
(** Method name for the request, following the MCP naming conventions.
+
Common method patterns include:
+
- "X/Y" for standard operations
+
- "X/Y/Z" for more specific operations
+
Examples: "initialize", "resources/read", "tools/call", "prompts/get" *)
+
(** 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. *)
+
(** 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:
+
"uri": "file:///project/src/main.rs",
+
"mimeType": "text/x-rust",
+
"text": "fn main() {\n println!(\"Hello world!\");\n}"
+
(** 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. *)
+
(** 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:
+
"message": "Resource not found",
+
"uri": "file:///nonexistent.txt"
+
(** 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.
+
- -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. *)
+
(** Union type for all JSON-RPC message kinds, providing a single type
+
that can represent any MCP message. *)
| Notification of notification
+
(** Convert notification to Yojson representation
+
@param notification The notification to convert
+
@return JSON representation of the notification
val yojson_of_notification : notification -> Json.t
+
(** Convert request to Yojson representation
+
@param request The request to convert
+
@return JSON representation of the request
val yojson_of_request : request -> Json.t
+
(** Convert response to Yojson representation
+
@param response The response to convert
+
@return JSON representation of the response
val yojson_of_response : response -> Json.t
+
(** Convert error to Yojson representation
+
@param error The error to convert
+
@return JSON representation of the error
val yojson_of_error : error -> Json.t
+
(** Convert any message to Yojson representation
+
@param message The message to convert
+
@return JSON representation of the message
val yojson_of_t : t -> Json.t
+
(** 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 notification_of_yojson : Json.t -> notification
+
(** 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 request_of_yojson : Json.t -> request
+
(** 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 response_of_yojson : Json.t -> response
+
(** 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 error_of_yojson : Json.t -> error
+
(** 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 t_of_yojson : Json.t -> t
+
(** Create a new notification message
+
@param params Optional parameters for the notification
+
@param method_ Method name for the notification
+
@return A new JSON-RPC notification message
val create_notification : ?params:Json.t option -> method_:string -> unit -> t
+
(** 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 method_ Method name for the request
+
@return A new JSON-RPC request message
val create_request : ?params:Json.t option -> ?progress_token:ProgressToken.t option -> id:RequestId.t -> method_:string -> unit -> 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
val create_response : id:RequestId.t -> result:Json.t -> t
+
(** 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
val create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> t
+
(** 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 *)
+
(** 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. *)
+
capabilities: Json.t; (** 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: "2025-03-26" *)
include Json.Jsonable.S with type t := t
+
(** Create a new initialization request
+
@param capabilities 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 create : capabilities:Json.t -> client_info:Implementation.t -> protocol_version:string -> t
+
(** Convert to JSON-RPC message
+
@param id Unique request identifier
+
@param t Initialization request
+
@return JSON-RPC message containing the initialization request
val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t
+
(** 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. *)
+
capabilities: Json.t; (** 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. *)
include Json.Jsonable.S with type t := t
+
(** Create a new initialization result
+
@param capabilities 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 create : capabilities:Json.t -> server_info:Implementation.t -> protocol_version:string -> ?instructions:string -> ?meta:Json.t -> unit -> 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
val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t
+
(** Initialized notification - Completes the initialization phase of the MCP lifecycle *)
module Notification : sig
+
(** 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 prompts. *)
+
(** Optional additional metadata as arbitrary JSON. Can contain client-specific
+
information not covered by the standard fields. *)
include Json.Jsonable.S with type t := t
+
(** Create a new initialized notification
+
@param meta Optional additional metadata
+
@return A new initialized notification
val create : ?meta:Json.t -> unit -> t
+
(** Convert to JSON-RPC message
+
@param t Initialized notification
+
@return JSON-RPC message containing the initialized notification
val to_jsonrpc : 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
+
@param json 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 parse_message : Json.t -> 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 method_ Method name for the notification, typically following MCP naming conventions
+
@return A new JSON-RPC notification message
val create_notification : ?params:Json.t option -> method_:string -> unit -> JSONRPCMessage.t
+
(** 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
+
- "resources/read" - Retrieve resource contents
+
- "tools/list" - Discover available tools
+
- "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
+
@param progress_token Optional progress token for long-running operations
+
that can report progress updates
+
@param id Unique identifier for the request, used to correlate with the response
+
@param method_ Method name for the request, following MCP naming conventions
+
@return A new JSON-RPC request message
val create_request : ?params:Json.t option -> ?progress_token:ProgressToken.t option -> id:RequestId.t -> method_:string -> unit -> 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 flight simultaneously.
+
@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
val create_response : id:RequestId.t -> result:Json.t -> JSONRPCMessage.t
+
(** 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 codes:
+
- -32700: Parse error (invalid JSON)
+
- -32600: Invalid request (malformed JSON-RPC)
+
- -32601: Method not found
+
- -32602: Invalid parameters
+
- -32603: Internal error
+
- -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 create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> JSONRPCMessage.t
anil.recoil.org