···
1
-
(** MCP - Model Context Protocol implementation
3
-
The Model Context Protocol (MCP) is a standardized protocol for AI agents to exchange context
4
-
with servers. This module provides the core OCaml implementation of MCP including
5
-
all message types, content representations, and serialization functionality.
1
+
(** MCP - Model Context Protocol implementation
3
+
The Model Context Protocol (MCP) is a standardized protocol for AI agents to
4
+
exchange context with servers. This module provides the core OCaml
5
+
implementation of MCP including all message types, content representations,
6
+
and serialization functionality.
- Uses JSON-RPC 2.0 as its underlying message format with UTF-8 encoding
9
-
- Follows a client-server model where clients (often LLM-integrated applications) communicate with MCP servers
10
+
- Follows a client-server model where clients (often LLM-integrated
11
+
applications) communicate with MCP servers
- Supports multiple transport methods including stdio and streamable HTTP
11
-
- Implements a three-phase connection lifecycle: initialization, operation, and shutdown
12
-
- Provides capability negotiation during initialization to determine available features
13
-
- Offers four primary context exchange mechanisms:
14
-
1. Resources: Server-exposed data that provides context to language models
15
-
2. Tools: Server-exposed functionality that can be invoked by language models
16
-
3. Prompts: Server-defined templates for structuring interactions with models
13
+
- Implements a three-phase connection lifecycle: initialization, operation,
15
+
- Provides capability negotiation during initialization to determine
17
+
- Offers four primary context exchange mechanisms: 1. Resources:
18
+
Server-exposed data that provides context to language models 2. Tools:
19
+
Server-exposed functionality that can be invoked by language models 3.
20
+
Prompts: Server-defined templates for structuring interactions with models
4. Sampling: Client-exposed ability to generate completions from LLMs
18
-
- Supports multimodal content types: text, images, audio, and embedded resources
22
+
- Supports multimodal content types: text, images, audio, and embedded
- Includes standardized error handling with defined error codes
21
-
This implementation follows Protocol Revision 2025-03-26.
26
+
This implementation follows Protocol Revision 2025-03-26. *)
30
+
(** Utility functions for JSON parsing *)
32
+
val json_error : ('a, unit, string, 'b) format4 -> Json.t -> 'a
33
+
(** Helper to raise a Json.Of_json exception with formatted message
34
+
@param fmt Format string for the error message
35
+
@param json JSON value to include in the exception
36
+
@return Never returns, always raises an exception
37
+
@raise Json.Of_json with the formatted message and JSON value *)
39
+
val get_string_field : (string * Json.t) list -> string -> Json.t -> string
40
+
(** Extract a string field from JSON object or raise an error
41
+
@param fields Assoc list of fields from JSON object
42
+
@param name Field name to extract
43
+
@param json Original JSON for error context
44
+
@return The string value of the field
45
+
@raise Json.Of_json if the field is missing or not a string *)
47
+
val get_optional_string_field :
48
+
(string * Json.t) list -> string -> string option
49
+
(** Extract an optional string field from JSON object
50
+
@param fields Assoc list of fields from JSON object
51
+
@param name Field name to extract
52
+
@return Some string if present and a string, None if missing
53
+
@raise Json.Of_json if the field exists but is not a string *)
55
+
val get_int_field : (string * Json.t) list -> string -> Json.t -> int
56
+
(** Extract an int field from JSON object or raise an error
57
+
@param fields Assoc list of fields from JSON object
58
+
@param name Field name to extract
59
+
@param json Original JSON for error context
60
+
@return The int value of the field
61
+
@raise Json.Of_json if the field is missing or not an int *)
63
+
val get_float_field : (string * Json.t) list -> string -> Json.t -> float
64
+
(** Extract a float field from JSON object or raise an error
65
+
@param fields Assoc list of fields from JSON object
66
+
@param name Field name to extract
67
+
@param json Original JSON for error context
68
+
@return The float value of the field
69
+
@raise Json.Of_json if the field is missing or not a float *)
71
+
val get_bool_field : (string * Json.t) list -> string -> Json.t -> bool
72
+
(** Extract a boolean field from JSON object or raise an error
73
+
@param fields Assoc list of fields from JSON object
74
+
@param name Field name to extract
75
+
@param json Original JSON for error context
76
+
@return The boolean value of the field
77
+
@raise Json.Of_json if the field is missing or not a boolean *)
79
+
val get_object_field :
80
+
(string * Json.t) list -> string -> Json.t -> (string * Json.t) list
81
+
(** Extract an object field from JSON object or raise an error
82
+
@param fields Assoc list of fields from JSON object
83
+
@param name Field name to extract
84
+
@param json Original JSON for error context
85
+
@return The object as an assoc list
86
+
@raise Json.Of_json if the field is missing or not an object *)
88
+
val get_list_field : (string * Json.t) list -> string -> Json.t -> Json.t list
89
+
(** Extract a list field from JSON object or raise an error
90
+
@param fields Assoc list of fields from JSON object
91
+
@param name Field name to extract
92
+
@param json Original JSON for error context
93
+
@return The list items
94
+
@raise Json.Of_json if the field is missing or not a list *)
96
+
val verify_string_field :
97
+
(string * Json.t) list -> string -> string -> Json.t -> unit
98
+
(** Verify a specific string value in a field
99
+
@param fields Assoc list of fields from JSON object
100
+
@param name Field name to check
101
+
@param expected_value The expected string value
102
+
@param json Original JSON for error context
103
+
@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 *)
30
-
| ParseError (** -32700 - Invalid JSON *)
31
-
| InvalidRequest (** -32600 - Invalid JSON-RPC request *)
32
-
| MethodNotFound (** -32601 - Method not available *)
33
-
| InvalidParams (** -32602 - Invalid method parameters *)
34
-
| InternalError (** -32603 - Internal JSON-RPC error *)
35
-
| ResourceNotFound (** -32002 - Custom MCP error: requested resource not found *)
36
-
| AuthRequired (** -32001 - Custom MCP error: authentication required *)
37
-
| CustomError of int (** For any other error codes *)
111
+
| ParseError (** -32700 - Invalid JSON *)
112
+
| InvalidRequest (** -32600 - Invalid JSON-RPC request *)
113
+
| MethodNotFound (** -32601 - Method not available *)
114
+
| InvalidParams (** -32602 - Invalid method parameters *)
115
+
| InternalError (** -32603 - Internal JSON-RPC error *)
117
+
(** -32002 - Custom MCP error: requested resource not found *)
118
+
| AuthRequired (** -32001 - Custom MCP error: authentication required *)
119
+
| CustomError of int (** For any other error codes *)
121
+
val to_int : t -> int
(** Convert the error code to its integer representation
@param code The error code to convert
41
-
@return The integer error code as defined in the JSON-RPC spec
43
-
val to_int : t -> int
124
+
@return The integer error code as defined in the JSON-RPC spec *)
126
+
val to_message : t -> string
(** Get error message for standard error codes
@param code The error code to get message for
47
-
@return A standard message for the error code
49
-
val to_message : t -> string
129
+
@return A standard message for the error code *)
52
-
(** MCP Protocol Methods - Standard method names used in JSON-RPC messages *)
132
+
(** MCP Protocol Methods - Algebraic data type representing all MCP methods *)
54
-
(** Standard protocol methods used in MCP JSON-RPC messages *)
56
-
val initialize : string (** "initialize" - Start the MCP lifecycle *)
58
-
val initialized : string (** "notifications/initialized" - Signal readiness after initialization *)
60
-
val resources_list : string (** "resources/list" - Discover available resources *)
62
-
val resources_read : string (** "resources/read" - Retrieve resource contents *)
64
-
val resources_templates_list : string (** "resources/templates/list" - List available resource templates *)
66
-
val resources_subscribe : string (** "resources/subscribe" - Subscribe to resource changes *)
68
-
val resources_list_changed : string (** "notifications/resources/list_changed" - Resource list has changed *)
70
-
val resources_updated : string (** "notifications/resources/updated" - Resource has been updated *)
72
-
val tools_list : string (** "tools/list" - Discover available tools *)
74
-
val tools_call : string (** "tools/call" - Invoke a tool *)
134
+
(** Method type representing all MCP protocol methods *)
136
+
(* Initialization and lifecycle methods *)
137
+
| Initialize (** Start the MCP lifecycle *)
138
+
| Initialized (** Signal readiness after initialization *)
139
+
(* Resource methods *)
140
+
| ResourcesList (** Discover available resources *)
141
+
| ResourcesRead (** Retrieve resource contents *)
142
+
| ResourceTemplatesList (** List available resource templates *)
143
+
| ResourcesSubscribe (** Subscribe to resource changes *)
144
+
| ResourcesListChanged (** Resource list has changed *)
145
+
| ResourcesUpdated (** Resource has been updated *)
147
+
| ToolsList (** Discover available tools *)
148
+
| ToolsCall (** Invoke a tool *)
149
+
| ToolsListChanged (** Tool list has changed *)
150
+
(* Prompt methods *)
151
+
| PromptsList (** Discover available prompts *)
152
+
| PromptsGet (** Retrieve a prompt template with arguments *)
153
+
| PromptsListChanged (** Prompt list has changed *)
154
+
(* Progress notifications *)
155
+
| Progress (** Progress update for long-running operations *)
76
-
val tools_list_changed : string (** "notifications/tools/list_changed" - Tool list has changed *)
157
+
val to_string : t -> string
158
+
(** Convert method type to string representation
159
+
@param meth The method to convert
161
+
The string representation of the method (e.g., "initialize",
162
+
"resources/list") *)
78
-
val prompts_list : string (** "prompts/list" - Discover available prompts *)
80
-
val prompts_get : string (** "prompts/get" - Retrieve a prompt template with arguments *)
82
-
val prompts_list_changed : string (** "notifications/prompts/list_changed" - Prompt list has changed *)
84
-
val progress : string (** "notifications/progress" - Progress update for long-running operations *)
164
+
val of_string : string -> t
165
+
(** Convert string to method type
166
+
@param s The string representation of the method
167
+
@return The corresponding method type
168
+
@raise Failure if the string is not a valid MCP method *)
(** Roles for conversation participants *)
92
-
(** Role represents conversation participants in MCP messages.
93
-
Roles can be either 'user' or 'assistant', determining the
94
-
source of each message in a conversation. *)
type t = [ `User | `Assistant ]
176
+
(** Role represents conversation participants in MCP messages. Roles can be
177
+
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
101
-
(** Progress tokens identify long-running operations and enable
102
-
servers to provide progress updates to clients. This is used
103
-
to track operations that may take significant time to complete. *)
type t = [ `String of string | `Int of int ]
186
+
(** Progress tokens identify long-running operations and enable servers to
187
+
provide progress updates to clients. This is used to track operations that
188
+
may take significant time to complete. *)
include Json.Jsonable.S with type t := t
110
-
(** Request IDs uniquely identify JSON-RPC requests, allowing responses
111
-
to be correlated with their originating requests. They can be either
112
-
string or integer values. *)
type t = [ `String of string | `Int of int ]
196
+
(** Request IDs uniquely identify JSON-RPC requests, allowing responses to be
197
+
correlated with their originating requests. They can be either string or
include Json.Jsonable.S with type t := t
(** Cursors for pagination *)
119
-
(** Cursors enable pagination in list operations for resources, tools, and prompts.
120
-
When a server has more items than can be returned in a single response,
121
-
it provides a cursor for the client to retrieve subsequent pages. *)
206
+
(** Cursors enable pagination in list operations for resources, tools, and
207
+
prompts. When a server has more items than can be returned in a single
208
+
response, it provides a cursor for the client to retrieve subsequent
include Json.Jsonable.S with type t := t
(** Annotations for objects *)
128
-
(** Annotations provide metadata for content objects, allowing
129
-
role-specific targeting and priority settings. *)
131
-
annotations: annotation option;
216
+
type t = { annotations : annotation option }
217
+
(** Annotations provide metadata for content objects, allowing role-specific
218
+
targeting and priority settings. *)
134
-
audience: Role.t list option;
135
-
(** Optional list of roles that should receive this content *)
136
-
priority: float option;
137
-
(** Optional priority value for this content *)
221
+
audience : Role.t list option;
222
+
(** Optional list of roles that should receive this content *)
223
+
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 *)
144
-
(** TextContent represents plain text messages in MCP conversations.
145
-
This is the most common content type used for natural language interactions
146
-
between users and assistants. Text content is used in prompts, tool results,
147
-
and model responses.
232
+
text : string; (** The actual text content as a UTF-8 encoded string *)
233
+
annotations : Annotated.annotation option;
234
+
(** Optional annotations for audience targeting and priority.
235
+
Annotations can restrict content visibility to specific roles
236
+
(user/assistant) and indicate relative importance of different
237
+
content elements. *)
239
+
(** TextContent represents plain text messages in MCP conversations. This is
240
+
the most common content type used for natural language interactions
241
+
between users and assistants. Text content is used in prompts, tool
242
+
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. *)
161
-
(** The actual text content as a UTF-8 encoded string *)
162
-
annotations: Annotated.annotation option;
163
-
(** Optional annotations for audience targeting and priority.
164
-
Annotations can restrict content visibility to specific roles (user/assistant)
165
-
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
262
+
(** Base64-encoded image data. All binary image data must be encoded
263
+
using standard base64 encoding (RFC 4648) to safely transmit within
265
+
mime_type : string;
266
+
(** MIME type of the image (e.g., "image/png", "image/jpeg",
267
+
"image/gif", "image/svg+xml"). This field is required and must
268
+
accurately represent the image format to ensure proper handling by
270
+
annotations : Annotated.annotation option;
271
+
(** Optional annotations for audience targeting and priority.
272
+
Annotations can restrict content visibility to specific roles
273
+
(user/assistant) and indicate relative importance of different
274
+
content elements. *)
(** 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.
191
-
Common mime types include image/png, image/jpeg, image/gif, and image/svg+xml. *)
194
-
(** Base64-encoded image data. All binary image data must be encoded using
195
-
standard base64 encoding (RFC 4648) to safely transmit within JSON. *)
197
-
(** MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/svg+xml").
198
-
This field is required and must accurately represent the image format to ensure
199
-
proper handling by clients. *)
200
-
annotations: Annotated.annotation option;
201
-
(** Optional annotations for audience targeting and priority.
202
-
Annotations can restrict content visibility to specific roles (user/assistant)
203
-
and indicate relative importance of different content elements. *)
295
+
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
305
+
(** Base64-encoded audio data. All binary audio data must be encoded
306
+
using standard base64 encoding (RFC 4648) to safely transmit within
308
+
mime_type : string;
309
+
(** MIME type of the audio (e.g., "audio/wav", "audio/mp3", "audio/ogg",
310
+
"audio/mpeg"). This field is required and must accurately represent
311
+
the audio format to ensure proper handling by clients. *)
312
+
annotations : Annotated.annotation option;
313
+
(** Optional annotations for audience targeting and priority.
314
+
Annotations can restrict content visibility to specific roles
315
+
(user/assistant) and indicate relative importance of different
316
+
content elements. *)
(** 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.
229
-
Common mime types include audio/wav, audio/mp3, audio/ogg, and audio/mpeg. *)
232
-
(** Base64-encoded audio data. All binary audio data must be encoded using
233
-
standard base64 encoding (RFC 4648) to safely transmit within JSON. *)
235
-
(** MIME type of the audio (e.g., "audio/wav", "audio/mp3", "audio/ogg", "audio/mpeg").
236
-
This field is required and must accurately represent the audio format to ensure
237
-
proper handling by clients. *)
238
-
annotations: Annotated.annotation option;
239
-
(** Optional annotations for audience targeting and priority.
240
-
Annotations can restrict content visibility to specific roles (user/assistant)
241
-
and indicate relative importance of different content elements. *)
337
+
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
347
+
(** URI that uniquely identifies the resource.
349
+
Resources use standard URI schemes including:
350
+
- file:// - For filesystem-like resources
351
+
- https:// - For web-accessible resources
352
+
- git:// - For version control integration
354
+
The URI serves as a stable identifier even if the underlying content
356
+
mime_type : string option;
357
+
(** Optional MIME type of the resource content to aid in client
358
+
rendering. Common MIME types include text/plain, application/json,
359
+
image/png, etc. For directories, the XDG MIME type inode/directory
(** ResourceContents provides basic metadata for resources in MCP.
250
-
Resources are server-exposed data that provides context to language models,
251
-
such as files, database schemas, or application-specific information.
252
-
Each resource is uniquely identified by a URI.
364
+
Resources are server-exposed data that provides context to language
365
+
models, such as files, database schemas, or application-specific
366
+
information. Each resource is uniquely identified by a URI.
The MCP resources architecture is designed to be application-driven, with
255
-
host applications determining how to incorporate context based on their needs.
257
-
In the protocol, resources are discovered via the 'resources/list' endpoint
258
-
and retrieved via the 'resources/read' endpoint. Servers that support resources
259
-
must declare the 'resources' capability during initialization. *)
262
-
(** URI that uniquely identifies the resource.
264
-
Resources use standard URI schemes including:
265
-
- file:// - For filesystem-like resources
266
-
- https:// - For web-accessible resources
267
-
- git:// - For version control integration
269
-
The URI serves as a stable identifier even if the underlying content changes. *)
270
-
mime_type: string option;
271
-
(** Optional MIME type of the resource content to aid in client rendering.
272
-
Common MIME types include text/plain, application/json, image/png, etc.
273
-
For directories, the XDG MIME type inode/directory may be used. *)
369
+
host applications determining how to incorporate context based on their
372
+
In the protocol, resources are discovered via the 'resources/list'
373
+
endpoint and retrieved via the 'resources/read' endpoint. Servers that
374
+
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
384
+
(** URI that uniquely identifies the resource. This URI can be
385
+
referenced in subsequent requests to fetch updates. *)
387
+
(** The actual text content of the resource as a UTF-8 encoded string.
388
+
This may be sanitized by the server to remove sensitive information.
390
+
mime_type : string option;
391
+
(** Optional MIME type of the text content to aid in client rendering.
392
+
Common text MIME types include: text/plain, text/markdown,
393
+
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"
299
-
(** URI that uniquely identifies the resource.
300
-
This URI can be referenced in subsequent requests to fetch updates. *)
302
-
(** The actual text content of the resource as a UTF-8 encoded string.
303
-
This may be sanitized by the server to remove sensitive information. *)
304
-
mime_type: string option;
305
-
(** Optional MIME type of the text content to aid in client rendering.
306
-
Common text MIME types include: text/plain, text/markdown, text/x-python,
307
-
application/json, text/html, text/csv, etc. *)
include Json.Jsonable.S with type t := t
(** Binary resource contents - Binary resource data *)
module BlobResourceContents : sig
419
+
(** URI that uniquely identifies the resource. This URI can be
420
+
referenced in subsequent requests to fetch updates. *)
422
+
(** Base64-encoded binary data using standard base64 encoding (RFC
423
+
4648). This encoding ensures that binary data can be safely
424
+
transmitted in JSON. *)
425
+
mime_type : string option;
426
+
(** Optional MIME type of the binary content to aid in client rendering.
427
+
Common binary MIME types include: image/png, image/jpeg,
428
+
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,
317
-
PDFs, and other binary formats with language models that support processing
434
+
PDFs, and other binary formats with language models that support
435
+
processing such content.
In JSON-RPC, this is represented as:
···
"blob": "base64-encoded-data"
329
-
Binary data MUST be properly base64-encoded to ensure safe transmission
330
-
in JSON payloads. *)
333
-
(** URI that uniquely identifies the resource.
334
-
This URI can be referenced in subsequent requests to fetch updates. *)
336
-
(** Base64-encoded binary data using standard base64 encoding (RFC 4648).
337
-
This encoding ensures that binary data can be safely transmitted in JSON. *)
338
-
mime_type: string option;
339
-
(** Optional MIME type of the binary content to aid in client rendering.
340
-
Common binary MIME types include: image/png, image/jpeg, application/pdf,
341
-
audio/wav, video/mp4, application/octet-stream, etc. *)
446
+
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
348
-
(** EmbeddedResource allows referencing server-side resources directly
349
-
in MCP messages, enabling seamless incorporation of managed content.
456
+
[ `Text of TextResourceContents.t | `Blob of BlobResourceContents.t ];
457
+
(** The resource content, either as text or binary blob. *)
458
+
annotations : Annotated.annotation option;
459
+
(** Optional annotations for audience targeting and priority.
460
+
Annotations can restrict resource visibility to specific roles
461
+
(user/assistant) and indicate relative importance of different
462
+
content elements. *)
464
+
(** EmbeddedResource allows referencing server-side resources directly in MCP
465
+
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),
357
-
embedded resources have the advantage of being persistently stored on the server
358
-
with a stable URI, allowing later retrieval and updates through the resources API.
360
-
For example, a tool might return an embedded resource containing a chart or
361
-
a large dataset that the client can later reference or update. *)
363
-
resource: [ `Text of TextResourceContents.t | `Blob of BlobResourceContents.t ];
364
-
(** The resource content, either as text or binary blob. *)
365
-
annotations: Annotated.annotation option;
366
-
(** Optional annotations for audience targeting and priority.
367
-
Annotations can restrict resource visibility to specific roles (user/assistant)
368
-
and indicate relative importance of different content elements. *)
473
+
embedded resources have the advantage of being persistently stored on the
474
+
server with a stable URI, allowing later retrieval and updates through the
477
+
For example, a tool might return an embedded resource containing a chart
478
+
or a large dataset that the client can later reference or update. *)
include Json.Jsonable.S with type t := t
373
-
(** Content type used in messages - Unified multimodal content representation in MCP *)
375
-
| Text of TextContent.t (** Text content for natural language messages. This is the most common content type for user-assistant interactions. *)
376
-
| Image of ImageContent.t (** Image content for visual data. Used for sharing visual context in multimodal conversations. *)
377
-
| Audio of AudioContent.t (** Audio content for audio data. Used for sharing audio context in multimodal conversations. *)
378
-
| Resource of EmbeddedResource.t (** Resource content for referencing server-side resources. Used for incorporating managed server content with stable URIs. *)
483
+
(** Content type used in messages - Unified multimodal content representation in
486
+
| Text of TextContent.t
487
+
(** Text content for natural language messages. This is the most common
488
+
content type for user-assistant interactions. *)
489
+
| Image of ImageContent.t
490
+
(** Image content for visual data. Used for sharing visual context in
491
+
multimodal conversations. *)
492
+
| Audio of AudioContent.t
493
+
(** Audio content for audio data. Used for sharing audio context in
494
+
multimodal conversations. *)
495
+
| Resource of EmbeddedResource.t
496
+
(** Resource content for referencing server-side resources. Used for
497
+
incorporating managed server content with stable URIs. *)
380
-
(** Convert content to Yojson representation
499
+
val yojson_of_content : content -> Json.t
500
+
(** Convert content to Yojson representation
@param content The content to convert
382
-
@return JSON representation of the content
384
-
val yojson_of_content : content -> Json.t
502
+
@return JSON representation of the content *)
386
-
(** Convert Yojson representation to content
387
-
@param json JSON representation of content
388
-
@return Parsed content object
val content_of_yojson : Json.t -> content
505
+
(** Convert Yojson representation to content
506
+
@param json JSON representation of content
507
+
@return Parsed content object *)
(** Message for prompts - Template messages in the MCP prompts feature *)
module PromptMessage : sig
394
-
(** PromptMessage represents a message in an MCP prompt template,
395
-
containing a role and content which can be customized with arguments.
513
+
(** The role of the message sender (user or assistant). Prompt templates
514
+
typically alternate between user and assistant messages to create a
515
+
conversation structure. *)
517
+
(** The message content, which can be text, image, audio, or resource.
518
+
This unified content type supports rich multimodal prompts. *)
520
+
(** PromptMessage represents a message in an MCP prompt template, containing a
521
+
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.
401
-
The prompt feature is designed to be user-controlled, with prompts typically
402
-
exposed through UI elements like slash commands that users can explicitly select.
527
+
The prompt feature is designed to be user-controlled, with prompts
528
+
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. *)
418
-
(** The role of the message sender (user or assistant).
419
-
Prompt templates typically alternate between user and assistant messages
420
-
to create a conversation structure. *)
422
-
(** The message content, which can be text, image, audio, or resource.
423
-
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
430
-
(** SamplingMessage represents a message in an MCP sampling request,
431
-
used for AI model generation based on a prompt.
551
+
(** The role of the message sender (user or assistant). Typically, a
552
+
sampling request will contain multiple messages representing a
553
+
conversation history, with alternating roles. *)
555
+
[ `Text of TextContent.t
556
+
| `Image of ImageContent.t
557
+
| `Audio of AudioContent.t ];
558
+
(** The message content, restricted to text, image, or audio (no
559
+
resources). Resources are not included since sampling messages
560
+
represent the actual context window for the LLM, not template
563
+
(** SamplingMessage represents a message in an MCP sampling request, used for
564
+
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
439
-
embedded resources, as they represent the actual context window being
440
-
sent to the LLM rather than template definitions.
572
+
embedded resources, as they represent the actual context window being sent
573
+
to the LLM rather than template definitions.
Clients that support sampling must declare the 'sampling' capability
during initialization. *)
446
-
(** The role of the message sender (user or assistant).
447
-
Typically, a sampling request will contain multiple messages
448
-
representing a conversation history, with alternating roles. *)
449
-
content: [ `Text of TextContent.t | `Image of ImageContent.t | `Audio of AudioContent.t ];
450
-
(** The message content, restricted to text, image, or audio (no resources).
451
-
Resources are not included since sampling messages represent the
452
-
actual context window for the LLM, not template definitions. *)
include Json.Jsonable.S with type t := t
(** Implementation information *)
module Implementation : sig
459
-
(** Implementation provides metadata about client and server implementations,
460
-
used during the initialization phase to identify each party. *)
463
-
(** Name of the implementation *)
465
-
(** Version of the implementation *)
584
+
name : string; (** Name of the implementation *)
585
+
version : string; (** Version of the implementation *)
587
+
(** Implementation provides metadata about client and server implementations,
588
+
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
472
-
MCP uses JSON-RPC 2.0 as its underlying messaging protocol.
473
-
All MCP messages are encoded as JSON-RPC 2.0 messages with UTF-8 encoding,
474
-
following the standard JSON-RPC message formats with some MCP-specific extensions.
476
-
MCP defines four message types:
477
-
1. Notifications: One-way messages that don't expect a response
478
-
2. Requests: Messages that expect a corresponding response
479
-
3. Responses: Replies to requests with successful results
480
-
4. Errors: Replies to requests with error information
595
+
MCP uses JSON-RPC 2.0 as its underlying messaging protocol. All MCP messages
596
+
are encoded as JSON-RPC 2.0 messages with UTF-8 encoding, following the
597
+
standard JSON-RPC message formats with some MCP-specific extensions.
599
+
MCP defines four message types: 1. Notifications: One-way messages that
600
+
don't expect a response 2. Requests: Messages that expect a corresponding
601
+
response 3. Responses: Replies to requests with successful results 4.
602
+
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
487
-
Messages may be sent individually or as part of a JSON-RPC batch.
609
+
Messages may be sent individually or as part of a JSON-RPC batch. *)
module JSONRPCMessage : sig
490
-
(** Notification represents a JSON-RPC notification (one-way message without a response).
611
+
type notification = {
613
+
(** Method for the notification, using the Method.t type to ensure type
614
+
safety. Examples: Method.Initialized, Method.ResourcesUpdated *)
615
+
params : Json.t option;
616
+
(** Optional parameters for the notification as arbitrary JSON. The
617
+
structure depends on the specific notification method. *)
619
+
(** 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"
509
-
type notification = {
511
-
(** Method name for the notification, following the MCP naming conventions.
512
-
Common method patterns include:
513
-
- "notifications/X" for standard notifications
514
-
- "notifications/X/Y" for more specific notifications
516
-
Examples: "notifications/initialized", "notifications/resources/updated" *)
517
-
params: Json.t option;
518
-
(** Optional parameters for the notification as arbitrary JSON.
519
-
The structure depends on the specific notification method. *)
641
+
(** Unique identifier for the request, which will be echoed in the
642
+
response. This can be a string or integer and should be unique
643
+
within the session. *)
645
+
(** Method for the request, using the Method.t type to ensure type
646
+
safety. Examples: Method.Initialize, Method.ResourcesRead,
647
+
Method.ToolsCall *)
648
+
params : Json.t option;
649
+
(** Optional parameters for the request as arbitrary JSON. The structure
650
+
depends on the specific request method. *)
651
+
progress_token : ProgressToken.t option;
652
+
(** Optional progress token for long-running operations. If provided,
653
+
the server can send progress notifications using this token to
654
+
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
531
-
In JSON-RPC, requests include an 'id' field that correlates with the response:
665
+
In JSON-RPC, requests include an 'id' field that correlates with the
···
"uri": "file:///project/src/main.rs"
545
-
(** Unique identifier for the request, which will be echoed in the response.
546
-
This can be a string or integer and should be unique within the session. *)
548
-
(** Method name for the request, following the MCP naming conventions.
549
-
Common method patterns include:
550
-
- "X/Y" for standard operations
551
-
- "X/Y/Z" for more specific operations
553
-
Examples: "initialize", "resources/read", "tools/call", "prompts/get" *)
554
-
params: Json.t option;
555
-
(** Optional parameters for the request as arbitrary JSON.
556
-
The structure depends on the specific request method. *)
557
-
progress_token: ProgressToken.t option;
558
-
(** Optional progress token for long-running operations.
559
-
If provided, the server can send progress notifications using this token
560
-
to inform the client about the operation's status. *)
680
+
(** ID matching the original request, allowing clients to correlate
681
+
responses with their originating requests, especially important when
682
+
multiple requests are in flight. *)
684
+
(** Result of the successful request as arbitrary JSON. The structure
685
+
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:
···
587
-
(** ID matching the original request, allowing clients to correlate
588
-
responses with their originating requests, especially important
589
-
when multiple requests are in flight. *)
591
-
(** Result of the successful request as arbitrary JSON.
592
-
The structure depends on the specific request method that was called. *)
711
+
(** ID matching the original request, allowing clients to correlate
712
+
errors with their originating requests. *)
714
+
(** Error code indicating the type of error, following the JSON-RPC
715
+
standard. Common codes include:
716
+
- -32700: Parse error
717
+
- -32600: Invalid request
718
+
- -32601: Method not found
719
+
- -32602: Invalid params
720
+
- -32603: Internal error
721
+
- -32002: Resource not found (MCP-specific)
722
+
- -32001: Authentication required (MCP-specific) *)
724
+
(** Human-readable error message describing the issue. This should be
725
+
concise but informative enough for debugging. *)
726
+
data : Json.t option;
727
+
(** Optional additional error data as arbitrary JSON. This can provide
728
+
more context about the error, such as which resource wasn't found or
729
+
which parameter was invalid. *)
(** Error represents an error response to a JSON-RPC request.
597
-
Errors are sent in reply to requests when processing fails.
598
-
Each error must include the same ID as its corresponding request.
733
+
Errors are sent in reply to requests when processing fails. Each error
734
+
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:
···
621
-
(** ID matching the original request, allowing clients to correlate
622
-
errors with their originating requests. *)
624
-
(** Error code indicating the type of error, following the JSON-RPC standard.
625
-
Common codes include:
626
-
- -32700: Parse error
627
-
- -32600: Invalid request
628
-
- -32601: Method not found
629
-
- -32602: Invalid params
630
-
- -32603: Internal error
631
-
- -32002: Resource not found (MCP-specific)
632
-
- -32001: Authentication required (MCP-specific) *)
634
-
(** Human-readable error message describing the issue.
635
-
This should be concise but informative enough for debugging. *)
636
-
data: Json.t option;
637
-
(** Optional additional error data as arbitrary JSON.
638
-
This can provide more context about the error, such as which
639
-
resource wasn't found or which parameter was invalid. *)
642
-
(** Union type for all JSON-RPC message kinds, providing a single type
643
-
that can represent any MCP message. *)
755
+
(** Union type for all JSON-RPC message kinds, providing a single type that
756
+
can represent any MCP message. *)
| Notification of notification
650
-
(** Convert notification to Yojson representation
651
-
@param notification The notification to convert
652
-
@return JSON representation of the notification
val yojson_of_notification : notification -> Json.t
656
-
(** Convert request to Yojson representation
657
-
@param request The request to convert
658
-
@return JSON representation of the request
764
+
(** Convert notification to Yojson representation
765
+
@param notification The notification to convert
766
+
@return JSON representation of the notification *)
val yojson_of_request : request -> Json.t
662
-
(** Convert response to Yojson representation
769
+
(** Convert request to Yojson representation
770
+
@param request The request to convert
771
+
@return JSON representation of the request *)
773
+
val yojson_of_response : response -> Json.t
774
+
(** Convert response to Yojson representation
@param response The response to convert
664
-
@return JSON representation of the response
666
-
val yojson_of_response : response -> Json.t
668
-
(** Convert error to Yojson representation
776
+
@return JSON representation of the response *)
778
+
val yojson_of_error : error -> Json.t
779
+
(** Convert error to Yojson representation
@param error The error to convert
670
-
@return JSON representation of the error
672
-
val yojson_of_error : error -> Json.t
674
-
(** Convert any message to Yojson representation
781
+
@return JSON representation of the error *)
783
+
val yojson_of_t : t -> Json.t
784
+
(** Convert any message to Yojson representation
@param message The message to convert
676
-
@return JSON representation of the message
678
-
val yojson_of_t : t -> Json.t
786
+
@return JSON representation of the message *)
680
-
(** Convert Yojson representation to notification
788
+
val notification_of_yojson : Json.t -> notification
789
+
(** Convert Yojson representation to notification
@param json JSON representation of a notification
@return Parsed notification object
683
-
@raise Parse error if the JSON is not a valid notification
685
-
val notification_of_yojson : Json.t -> notification
687
-
(** Convert Yojson representation to request
792
+
@raise Parse error if the JSON is not a valid notification *)
794
+
val request_of_yojson : Json.t -> request
795
+
(** Convert Yojson representation to request
@param json JSON representation of a request
@return Parsed request object
690
-
@raise Parse error if the JSON is not a valid request
692
-
val request_of_yojson : Json.t -> request
694
-
(** Convert Yojson representation to response
798
+
@raise Parse error if the JSON is not a valid request *)
800
+
val response_of_yojson : Json.t -> response
801
+
(** Convert Yojson representation to response
@param json JSON representation of a response
@return Parsed response object
697
-
@raise Parse error if the JSON is not a valid response
699
-
val response_of_yojson : Json.t -> response
701
-
(** Convert Yojson representation to error
804
+
@raise Parse error if the JSON is not a valid response *)
806
+
val error_of_yojson : Json.t -> error
807
+
(** Convert Yojson representation to error
@param json JSON representation of an error
@return Parsed error object
704
-
@raise Parse error if the JSON is not a valid error
706
-
val error_of_yojson : Json.t -> error
708
-
(** Convert Yojson representation to any message
810
+
@raise Parse error if the JSON is not a valid error *)
812
+
val t_of_yojson : Json.t -> t
813
+
(** Convert Yojson representation to any message
@param json JSON representation of any message type
@return Parsed message object
711
-
@raise Parse error if the JSON is not a valid message
713
-
val t_of_yojson : Json.t -> t
816
+
@raise Parse error if the JSON is not a valid message *)
818
+
val create_notification : ?params:Json.t option -> meth:Method.t -> unit -> t
(** Create a new notification message
@param params Optional parameters for the notification
717
-
@param method_ Method name for the notification
718
-
@return A new JSON-RPC notification message
720
-
val create_notification : ?params:Json.t option -> method_:string -> unit -> t
821
+
@param meth Method name for the notification
822
+
@return A new JSON-RPC notification message *)
824
+
val create_request :
825
+
?params:Json.t option ->
826
+
?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
726
-
@param method_ Method name for the request
727
-
@return A new JSON-RPC request message
729
-
val create_request : ?params:Json.t option -> ?progress_token:ProgressToken.t option -> id:RequestId.t -> method_:string -> unit -> t
835
+
@param meth Method name for the request
836
+
@return A new JSON-RPC request message *)
838
+
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
734
-
@return A new JSON-RPC response message
736
-
val create_response : id:RequestId.t -> result:Json.t -> t
842
+
@return A new JSON-RPC response message *)
848
+
?data:Json.t option ->
(** 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
743
-
@return A new JSON-RPC error message
745
-
val create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> t
856
+
@return A new JSON-RPC error message *)
748
-
(** Initialize request/response - The first phase of the MCP lifecycle
750
-
The initialization phase is the mandatory first interaction between client and server.
751
-
During this phase, the protocol version is negotiated and capabilities are exchanged
752
-
to determine which optional features will be available during the session.
754
-
This follows a strict sequence:
755
-
1. Client sends an InitializeRequest containing its capabilities and protocol version
756
-
2. Server responds with an InitializeResult containing its capabilities and protocol version
757
-
3. Client sends an InitializedNotification to signal it's ready for normal operations
759
-
The Initialize module handles steps 1 and 2 of this process.
859
+
(** Initialize request/response - The first phase of the MCP lifecycle
861
+
The initialization phase is the mandatory first interaction between client
862
+
and server. During this phase, the protocol version is negotiated and
863
+
capabilities are exchanged to determine which optional features will be
864
+
available during the session.
866
+
This follows a strict sequence: 1. Client sends an InitializeRequest
867
+
containing its capabilities and protocol version 2. Server responds with an
868
+
InitializeResult containing its capabilities and protocol version 3. Client
869
+
sends an InitializedNotification to signal it's ready for normal operations
871
+
The Initialize module handles steps 1 and 2 of this process. *)
(** Initialize request *)
764
-
(** InitializeRequest starts the MCP lifecycle, negotiating capabilities
765
-
and protocol versions between client and server. This is always the first
766
-
message sent by the client and MUST NOT be part of a JSON-RPC batch.
768
-
The client SHOULD send the latest protocol version it supports. If the server
769
-
does not support this version, it will respond with a version it does support,
770
-
and the client must either use that version or disconnect. *)
772
-
capabilities: Json.t; (** ClientCapabilities that define supported optional features.
773
-
This includes which optional protocol features the client supports,
774
-
such as 'roots' (filesystem access), 'sampling' (LLM generation),
775
-
and any experimental features. *)
776
-
client_info: Implementation.t;
777
-
(** Client implementation details (name and version) used for identification
778
-
and debugging. Helps servers understand which client they're working with. *)
779
-
protocol_version: string;
780
-
(** MCP protocol version supported by the client, formatted as YYYY-MM-DD
781
-
according to the MCP versioning scheme. Example: "2025-03-26" *)
876
+
capabilities : Json.t;
877
+
(** ClientCapabilities that define supported optional features. This
878
+
includes which optional protocol features the client supports,
879
+
such as 'roots' (filesystem access), 'sampling' (LLM generation),
880
+
and any experimental features. *)
881
+
client_info : Implementation.t;
882
+
(** Client implementation details (name and version) used for
883
+
identification and debugging. Helps servers understand which
884
+
client they're working with. *)
885
+
protocol_version : string;
886
+
(** MCP protocol version supported by the client, formatted as
887
+
YYYY-MM-DD according to the MCP versioning scheme. Example:
890
+
(** InitializeRequest starts the MCP lifecycle, negotiating capabilities and
891
+
protocol versions between client and server. This is always the first
892
+
message sent by the client and MUST NOT be part of a JSON-RPC batch.
894
+
The client SHOULD send the latest protocol version it supports. If the
895
+
server does not support this version, it will respond with a version it
896
+
does support, and the client must either use that version or disconnect.
include Json.Jsonable.S with type t := t
902
+
capabilities:Json.t ->
903
+
client_info:Implementation.t ->
904
+
protocol_version:string ->
(** Create a new initialization request
786
-
@param capabilities Client capabilities that define supported optional features
907
+
@param capabilities
908
+
Client capabilities that define supported optional features
@param client_info Client implementation details
@param protocol_version MCP protocol version supported by the client
789
-
@return A new initialization request
791
-
val create : capabilities:Json.t -> client_info:Implementation.t -> protocol_version:string -> t
911
+
@return A new initialization request *)
913
+
val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t
(** Convert to JSON-RPC message
@param id Unique request identifier
@param t Initialization request
796
-
@return JSON-RPC message containing the initialization request
798
-
val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t
917
+
@return JSON-RPC message containing the initialization request *)
923
+
capabilities : Json.t;
924
+
(** ServerCapabilities that define supported optional features. This
925
+
declares which server features are available, including:
926
+
- prompts: Server provides prompt templates
927
+
- resources: Server provides readable resources
928
+
- tools: Server exposes callable tools
929
+
- logging: Server emits structured log messages
931
+
Each capability may have sub-capabilities like:
932
+
- listChanged: Server will notify when available items change
933
+
- subscribe: Clients can subscribe to individual resources *)
934
+
server_info : Implementation.t;
935
+
(** Server implementation details (name and version) used for
936
+
identification and debugging. Helps clients understand which
937
+
server they're working with. *)
938
+
protocol_version : string;
939
+
(** MCP protocol version supported by the server, formatted as
940
+
YYYY-MM-DD. If the server supports the client's requested version,
941
+
it responds with the same version. Otherwise, it responds with a
942
+
version it does support. *)
943
+
instructions : string option;
944
+
(** Optional instructions for using the server. These can provide
945
+
human-readable guidance on how to interact with this specific
946
+
server implementation. *)
947
+
meta : Json.t option;
948
+
(** Optional additional metadata as arbitrary JSON. Can contain
949
+
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.
806
-
After receiving this message, the client must send an InitializedNotification.
807
-
The server should not send any requests other than pings and logging before
808
-
receiving the initialized notification. *)
810
-
capabilities: Json.t; (** ServerCapabilities that define supported optional features.
811
-
This declares which server features are available, including:
812
-
- prompts: Server provides prompt templates
813
-
- resources: Server provides readable resources
814
-
- tools: Server exposes callable tools
815
-
- logging: Server emits structured log messages
817
-
Each capability may have sub-capabilities like:
818
-
- listChanged: Server will notify when available items change
819
-
- subscribe: Clients can subscribe to individual resources *)
820
-
server_info: Implementation.t;
821
-
(** Server implementation details (name and version) used for identification
822
-
and debugging. Helps clients understand which server they're working with. *)
823
-
protocol_version: string;
824
-
(** MCP protocol version supported by the server, formatted as YYYY-MM-DD.
825
-
If the server supports the client's requested version, it responds with
826
-
the same version. Otherwise, it responds with a version it does support. *)
827
-
instructions: string option;
828
-
(** Optional instructions for using the server. These can provide human-readable
829
-
guidance on how to interact with this specific server implementation. *)
830
-
meta: Json.t option;
831
-
(** Optional additional metadata as arbitrary JSON. Can contain server-specific
832
-
information not covered by the standard fields. *)
954
+
After receiving this message, the client must send an
955
+
InitializedNotification. The server should not send any requests other
956
+
than pings and logging before receiving the initialized notification. *)
include Json.Jsonable.S with type t := t
961
+
capabilities:Json.t ->
962
+
server_info:Implementation.t ->
963
+
protocol_version:string ->
964
+
?instructions:string ->
(** Create a new initialization result
837
-
@param capabilities Server capabilities that define supported optional features
969
+
@param capabilities
970
+
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
842
-
@return A new initialization result
844
-
val create : capabilities:Json.t -> server_info:Implementation.t -> protocol_version:string -> ?instructions:string -> ?meta:Json.t -> unit -> t
975
+
@return A new initialization result *)
977
+
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
849
-
@return JSON-RPC message containing the initialization result
851
-
val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t
981
+
@return JSON-RPC message containing the initialization result *)
855
-
(** Initialized notification - Completes the initialization phase of the MCP lifecycle *)
985
+
(** Initialized notification - Completes the initialization phase of the MCP
module Notification : sig
858
-
(** InitializedNotification is sent by the client after receiving the initialization
859
-
response, indicating it's ready to begin normal operations. This completes the
860
-
three-step initialization process, after which both client and server can
861
-
freely exchange messages according to the negotiated capabilities.
863
-
Only after this notification has been sent should the client begin normal operations
864
-
like listing resources, calling tools, or requesting prompts. *)
866
-
meta: Json.t option;
867
-
(** Optional additional metadata as arbitrary JSON. Can contain client-specific
868
-
information not covered by the standard fields. *)
990
+
meta : Json.t option;
991
+
(** Optional additional metadata as arbitrary JSON. Can contain
992
+
client-specific information not covered by the standard fields. *)
994
+
(** InitializedNotification is sent by the client after receiving the
995
+
initialization response, indicating it's ready to begin normal
996
+
operations. This completes the three-step initialization process, after
997
+
which both client and server can freely exchange messages according to
998
+
the negotiated capabilities.
1000
+
Only after this notification has been sent should the client begin
1001
+
normal operations like listing resources, calling tools, or requesting
include Json.Jsonable.S with type t := t
1006
+
val create : ?meta:Json.t -> unit -> t
(** Create a new initialized notification
@param meta Optional additional metadata
874
-
@return A new initialized notification
876
-
val create : ?meta:Json.t -> unit -> t
1009
+
@return A new initialized notification *)
1011
+
val to_jsonrpc : t -> JSONRPCMessage.t
(** Convert to JSON-RPC message
@param t Initialized notification
880
-
@return JSON-RPC message containing the initialized notification
882
-
val to_jsonrpc : t -> JSONRPCMessage.t
1014
+
@return JSON-RPC message containing the initialized notification *)
886
-
(** Parse a JSON message into an MCP message
888
-
This function takes a raw JSON value and parses it into a structured MCP message.
889
-
It's the primary entry point for processing incoming JSON-RPC messages in the MCP protocol.
891
-
The function determines the message type (notification, request, response, or error)
892
-
based on the presence and values of specific fields:
1018
+
val parse_message : Json.t -> JSONRPCMessage.t
1019
+
(** Parse a JSON message into an MCP message
1021
+
This function takes a raw JSON value and parses it into a structured MCP
1022
+
message. It's the primary entry point for processing incoming JSON-RPC
1023
+
messages in the MCP protocol.
1025
+
The function determines the message type (notification, request, response,
1026
+
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
898
-
@param json The JSON message to parse, typically received from the transport layer
1033
+
The JSON message to parse, typically received from the transport layer
@return The parsed MCP message as a structured JSONRPCMessage.t value
900
-
@raise Parse error if the JSON cannot be parsed as a valid MCP message
902
-
val parse_message : Json.t -> JSONRPCMessage.t
1035
+
@raise Parse error if the JSON cannot be parsed as a valid MCP message *)
1037
+
val create_notification :
1038
+
?params:Json.t option -> meth:Method.t -> unit -> JSONRPCMessage.t
(** Create a new notification message
906
-
Notifications are one-way messages that don't expect a response.
907
-
This is a convenience wrapper around JSONRPCMessage.create_notification.
1041
+
Notifications are one-way messages that don't expect a response. This is a
1042
+
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
917
-
@param method_ Method name for the notification, typically following MCP naming conventions
918
-
@return A new JSON-RPC notification message
920
-
val create_notification : ?params:Json.t option -> method_:string -> unit -> JSONRPCMessage.t
1052
+
@param meth Method type for the notification
1053
+
@return A new JSON-RPC notification message *)
1055
+
val create_request :
1056
+
?params:Json.t option ->
1057
+
?progress_token:ProgressToken.t option ->
(** Create a new request message
924
-
Requests are messages that expect a corresponding response.
925
-
This is a convenience wrapper around JSONRPCMessage.create_request.
1064
+
Requests are messages that expect a corresponding response. This is a
1065
+
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
937
-
@param progress_token Optional progress token for long-running operations
938
-
that can report progress updates
939
-
@param id Unique identifier for the request, used to correlate with the response
940
-
@param method_ Method name for the request, following MCP naming conventions
941
-
@return A new JSON-RPC request message
943
-
val create_request : ?params:Json.t option -> ?progress_token:ProgressToken.t option -> id:RequestId.t -> method_:string -> unit -> JSONRPCMessage.t
1077
+
@param progress_token
1078
+
Optional progress token for long-running operations that can report
1081
+
Unique identifier for the request, used to correlate with the response
1082
+
@param meth Method type for the request
1083
+
@return A new JSON-RPC request message *)
1085
+
val create_response : id:RequestId.t -> result:Json.t -> JSONRPCMessage.t
(** Create a new response message
947
-
Responses are sent in reply to requests and contain successful results.
948
-
This is a convenience wrapper around JSONRPCMessage.create_response.
950
-
Each response must include the same ID as its corresponding request
951
-
to allow the client to correlate them, especially when multiple
952
-
requests are in flight simultaneously.
1088
+
Responses are sent in reply to requests and contain successful results. This
1089
+
is a convenience wrapper around JSONRPCMessage.create_response.
1091
+
Each response must include the same ID as its corresponding request to allow
1092
+
the client to correlate them, especially when multiple requests are in
1093
+
flight simultaneously.
@param id ID matching the original request
@param result Result of the successful request as a JSON value
956
-
@return A new JSON-RPC response message
958
-
val create_response : id:RequestId.t -> result:Json.t -> JSONRPCMessage.t
1097
+
@return A new JSON-RPC response message *)
1099
+
val create_error :
1103
+
?data:Json.t option ->
(** Create a new error message
962
-
Errors are sent in reply to requests when processing fails.
963
-
This is a convenience wrapper around JSONRPCMessage.create_error.
965
-
MCP uses standard JSON-RPC error codes as well as some protocol-specific codes:
1108
+
Errors are sent in reply to requests when processing fails. This is a
1109
+
convenience wrapper around JSONRPCMessage.create_error.
1111
+
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
978
-
@return A new JSON-RPC error message
980
-
val create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> JSONRPCMessage.t
1125
+
@return A new JSON-RPC error message *)
1127
+
val make_text_content : string -> content
(** Create a new text content object
@param text The text content
984
-
@return A content value with the text
986
-
val make_text_content : string -> content
1130
+
@return A content value with the text *)
1132
+
val make_image_content : string -> string -> content
(** Create a new image content object
@param data Base64-encoded image data
990
-
@param mime_type MIME type of the image (e.g., "image/png", "image/jpeg")
991
-
@return A content value with the image
993
-
val make_image_content : string -> string -> content
1135
+
@param mime_type MIME type of the image (e.g., "image/png", "image/jpeg")
1136
+
@return A content value with the image *)
1138
+
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")
998
-
@return A content value with the audio
1000
-
val make_audio_content : string -> string -> content
1142
+
@return A content value with the audio *)
1144
+
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
1006
-
@return A content value with the text resource
1008
-
val make_resource_text_content : string -> string -> string option -> content
1149
+
@return A content value with the text resource *)
1151
+
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
1014
-
@return A content value with the binary resource
1016
-
val make_resource_blob_content : string -> string -> string option -> content
1156
+
@return A content value with the binary resource *)
anil.recoil.org