···
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.
8
-
- 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
-
- 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
17
-
4. Sampling: Client-exposed ability to generate completions from LLMs
18
-
- Supports multimodal content types: text, images, audio, and embedded resources
19
-
- Includes standardized error handling with defined error codes
21
-
This implementation follows Protocol Revision 2025-03-26.
1
+
(** MCP - Model Context Protocol implementation *)
26
-
(** Utility functions for JSON parsing *)
28
-
(** Helper to raise a Json.Of_json exception with formatted message
29
-
@param fmt Format string for the error message
30
-
@param json JSON value to include in the exception
31
-
@return Never returns, always raises an exception
32
-
@raise Json.Of_json with the formatted message and JSON value
34
-
val json_error : ('a, unit, string, 'b) format4 -> Json.t -> 'a
36
-
(** Extract a string field from JSON object or raise an error
37
-
@param fields Assoc list of fields from JSON object
38
-
@param name Field name to extract
39
-
@param json Original JSON for error context
40
-
@return The string value of the field
41
-
@raise Json.Of_json if the field is missing or not a string
43
-
val get_string_field : (string * Json.t) list -> string -> Json.t -> string
45
-
(** Extract an optional string field from JSON object
46
-
@param fields Assoc list of fields from JSON object
47
-
@param name Field name to extract
48
-
@return Some string if present and a string, None if missing
49
-
@raise Json.Of_json if the field exists but is not a string
51
-
val get_optional_string_field : (string * Json.t) list -> string -> string option
53
-
(** Extract an int field from JSON object or raise an error
54
-
@param fields Assoc list of fields from JSON object
55
-
@param name Field name to extract
56
-
@param json Original JSON for error context
57
-
@return The int value of the field
58
-
@raise Json.Of_json if the field is missing or not an int
60
-
val get_int_field : (string * Json.t) list -> string -> Json.t -> int
62
-
(** Extract a float field from JSON object or raise an error
63
-
@param fields Assoc list of fields from JSON object
64
-
@param name Field name to extract
65
-
@param json Original JSON for error context
66
-
@return The float value of the field
67
-
@raise Json.Of_json if the field is missing or not a float
69
-
val get_float_field : (string * Json.t) list -> string -> Json.t -> float
71
-
(** Extract a boolean field from JSON object or raise an error
72
-
@param fields Assoc list of fields from JSON object
73
-
@param name Field name to extract
74
-
@param json Original JSON for error context
75
-
@return The boolean value of the field
76
-
@raise Json.Of_json if the field is missing or not a boolean
78
-
val get_bool_field : (string * Json.t) list -> string -> Json.t -> bool
80
-
(** Extract an object field from JSON object or raise an error
81
-
@param fields Assoc list of fields from JSON object
82
-
@param name Field name to extract
83
-
@param json Original JSON for error context
84
-
@return The object as an assoc list
85
-
@raise Json.Of_json if the field is missing or not an object
87
-
val get_object_field : (string * Json.t) list -> string -> Json.t -> (string * 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 get_list_field : (string * Json.t) list -> string -> Json.t -> Json.t list
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
105
-
val verify_string_field : (string * Json.t) list -> string -> string -> Json.t -> unit
108
-
(** Error codes for JSON-RPC *)
5
+
(** Standard error codes *)
110
-
(** Standard JSON-RPC error codes with MCP-specific additions *)
112
-
| ParseError (** -32700 - Invalid JSON *)
113
-
| InvalidRequest (** -32600 - Invalid JSON-RPC request *)
114
-
| MethodNotFound (** -32601 - Method not available *)
115
-
| InvalidParams (** -32602 - Invalid method parameters *)
116
-
| InternalError (** -32603 - Internal JSON-RPC error *)
117
-
| ResourceNotFound (** -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
-
(** Convert the error code to its integer representation
122
-
@param code The error code to convert
123
-
@return The integer error code as defined in the JSON-RPC spec
125
-
val to_int : t -> int
127
-
(** Get error message for standard error codes
128
-
@param code The error code to get message for
129
-
@return A standard message for the error code
131
-
val to_message : t -> string
7
+
val parse_error : int
8
+
val invalid_request : int
9
+
val method_not_found : int
10
+
val invalid_params : int
11
+
val internal_error : int
12
+
val resource_not_found : int
13
+
val server_error_start : int
14
+
val server_error_end : int
134
-
(** MCP Protocol Methods - Algebraic data type representing all MCP methods *)
135
-
module Method : sig
136
-
(** Method type representing all MCP protocol methods *)
138
-
(* Initialization and lifecycle methods *)
139
-
| Initialize (** Start the MCP lifecycle *)
140
-
| Initialized (** Signal readiness after initialization *)
142
-
(* Resource methods *)
143
-
| ResourcesList (** Discover available resources *)
144
-
| ResourcesRead (** Retrieve resource contents *)
145
-
| ResourcesTemplatesList (** List available resource templates *)
146
-
| ResourcesSubscribe (** Subscribe to resource changes *)
147
-
| ResourcesListChanged (** Resource list has changed *)
148
-
| ResourcesUpdated (** Resource has been updated *)
151
-
| ToolsList (** Discover available tools *)
152
-
| ToolsCall (** Invoke a tool *)
153
-
| ToolsListChanged (** Tool list has changed *)
155
-
(* Prompt methods *)
156
-
| PromptsList (** Discover available prompts *)
157
-
| PromptsGet (** Retrieve a prompt template with arguments *)
158
-
| PromptsListChanged (** Prompt list has changed *)
160
-
(* Progress notifications *)
161
-
| Progress (** Progress update for long-running operations *)
163
-
(** Convert method type to string representation
164
-
@param meth The method to convert
165
-
@return The string representation of the method (e.g., "initialize", "resources/list")
167
-
val to_string : t -> string
169
-
(** Convert string to method type
170
-
@param s The string representation of the method
171
-
@return The corresponding method type
172
-
@raise Failure if the string is not a valid MCP method
174
-
val of_string : string -> t
(** Roles for conversation participants *)
182
-
(** Role represents conversation participants in MCP messages.
183
-
Roles can be either 'user' or 'assistant', determining the
184
-
source of each message in a conversation. *)
type t = [ `User | `Assistant ]
186
-
include Json.Jsonable.S with type t := t
23
+
val to_string : t -> string
24
+
val of_string : string -> t
26
+
val yojson_of_t : t -> Json.t
27
+
val t_of_yojson : Json.t -> t
(** Progress tokens for long-running operations *)
module ProgressToken : sig
191
-
(** Progress tokens identify long-running operations and enable
192
-
servers to provide progress updates to clients. This is used
193
-
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
200
-
(** Request IDs uniquely identify JSON-RPC requests, allowing responses
201
-
to be correlated with their originating requests. They can be either
202
-
string or integer values. *)
type t = [ `String of string | `Int of int ]
include Json.Jsonable.S with type t := t
(** Cursors for pagination *)
209
-
(** Cursors enable pagination in list operations for resources, tools, and prompts.
210
-
When a server has more items than can be returned in a single response,
211
-
it provides a cursor for the client to retrieve subsequent pages. *)
213
-
include Json.Jsonable.S with type t := t
48
+
val yojson_of_t : t -> Json.t
49
+
val t_of_yojson : Json.t -> t
(** Annotations for objects *)
218
-
(** Annotations provide metadata for content objects, allowing
219
-
role-specific targeting and priority settings. *)
annotations: annotation option;
audience: Role.t list option;
225
-
(** Optional list of roles that should receive this content *)
227
-
(** Optional priority value for this content *)
229
-
include Json.Jsonable.S with type t := t
62
+
val yojson_of_annotation : annotation -> Json.t
63
+
val annotation_of_yojson : Json.t -> annotation
65
+
val yojson_of_t : t -> Json.t
66
+
val t_of_yojson : Json.t -> t
232
-
(** Text content - Core textual message representation in MCP *)
234
-
(** TextContent represents plain text messages in MCP conversations.
235
-
This is the most common content type used for natural language interactions
236
-
between users and assistants. Text content is used in prompts, tool results,
237
-
and model responses.
239
-
In JSON-RPC, this is represented as:
243
-
"text": "The text content of the message"
247
-
For security, implementations must sanitize text content to prevent
248
-
injection attacks or unauthorized access to resources. *)
251
-
(** The actual text content as a UTF-8 encoded string *)
annotations: Annotated.annotation option;
253
-
(** Optional annotations for audience targeting and priority.
254
-
Annotations can restrict content visibility to specific roles (user/assistant)
255
-
and indicate relative importance of different content elements. *)
257
-
include Json.Jsonable.S with type t := t
76
+
val yojson_of_t : t -> Json.t
77
+
val t_of_yojson : Json.t -> t
260
-
(** Image content - Visual data representation in MCP *)
80
+
(** Image content *)
module ImageContent : sig
262
-
(** ImageContent enables including visual information in MCP messages,
263
-
supporting multimodal interactions where visual context is important.
265
-
Images can be used in several scenarios:
266
-
- As user inputs for visual understanding tasks
267
-
- As context for generating descriptions or analysis
268
-
- As outputs from tools that generate visualizations
269
-
- As part of prompt templates with visual components
271
-
In JSON-RPC, this is represented as:
275
-
"data": "base64-encoded-image-data",
276
-
"mimeType": "image/png"
280
-
The data MUST be base64-encoded to ensure safe transmission in JSON.
281
-
Common mime types include image/png, image/jpeg, image/gif, and image/svg+xml. *)
284
-
(** Base64-encoded image data. All binary image data must be encoded using
285
-
standard base64 encoding (RFC 4648) to safely transmit within JSON. *)
287
-
(** MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/svg+xml").
288
-
This field is required and must accurately represent the image format to ensure
289
-
proper handling by clients. *)
annotations: Annotated.annotation option;
291
-
(** Optional annotations for audience targeting and priority.
292
-
Annotations can restrict content visibility to specific roles (user/assistant)
293
-
and indicate relative importance of different content elements. *)
295
-
include Json.Jsonable.S with type t := t
88
+
val yojson_of_t : t -> Json.t
89
+
val t_of_yojson : Json.t -> t
298
-
(** Audio content - Sound data representation in MCP *)
92
+
(** Audio content *)
module AudioContent : sig
300
-
(** AudioContent enables including audio information in MCP messages,
301
-
supporting multimodal interactions where audio context is important.
303
-
Audio can be used in several scenarios:
304
-
- As user inputs for speech recognition or audio analysis
305
-
- As context for transcription or sound classification tasks
306
-
- As outputs from tools that generate audio samples
307
-
- As part of prompt templates with audio components
309
-
In JSON-RPC, this is represented as:
313
-
"data": "base64-encoded-audio-data",
314
-
"mimeType": "audio/wav"
318
-
The data MUST be base64-encoded to ensure safe transmission in JSON.
319
-
Common mime types include audio/wav, audio/mp3, audio/ogg, and audio/mpeg. *)
322
-
(** Base64-encoded audio data. All binary audio data must be encoded using
323
-
standard base64 encoding (RFC 4648) to safely transmit within JSON. *)
325
-
(** MIME type of the audio (e.g., "audio/wav", "audio/mp3", "audio/ogg", "audio/mpeg").
326
-
This field is required and must accurately represent the audio format to ensure
327
-
proper handling by clients. *)
annotations: Annotated.annotation option;
329
-
(** Optional annotations for audience targeting and priority.
330
-
Annotations can restrict content visibility to specific roles (user/assistant)
331
-
and indicate relative importance of different content elements. *)
333
-
include Json.Jsonable.S with type t := t
100
+
val yojson_of_t : t -> Json.t
101
+
val t_of_yojson : Json.t -> t
336
-
(** Base resource contents - Core resource metadata in MCP *)
104
+
(** Base resource contents *)
module ResourceContents : sig
338
-
(** ResourceContents provides basic metadata for resources in MCP.
340
-
Resources are server-exposed data that provides context to language models,
341
-
such as files, database schemas, or application-specific information.
342
-
Each resource is uniquely identified by a URI.
344
-
The MCP resources architecture is designed to be application-driven, with
345
-
host applications determining how to incorporate context based on their needs.
347
-
In the protocol, resources are discovered via the 'resources/list' endpoint
348
-
and retrieved via the 'resources/read' endpoint. Servers that support resources
349
-
must declare the 'resources' capability during initialization. *)
352
-
(** URI that uniquely identifies the resource.
354
-
Resources use standard URI schemes including:
355
-
- file:// - For filesystem-like resources
356
-
- https:// - For web-accessible resources
357
-
- git:// - For version control integration
359
-
The URI serves as a stable identifier even if the underlying content changes. *)
mime_type: string option;
361
-
(** Optional MIME type of the resource content to aid in client rendering.
362
-
Common MIME types include text/plain, application/json, image/png, etc.
363
-
For directories, the XDG MIME type inode/directory may be used. *)
365
-
include Json.Jsonable.S with type t := t
111
+
val yojson_of_t : t -> Json.t
112
+
val t_of_yojson : Json.t -> t
368
-
(** Text resource contents - Textual resource data *)
115
+
(** Text resource contents *)
module TextResourceContents : sig
370
-
(** TextResourceContents represents a text-based resource in MCP.
372
-
Text resources are used for sharing code snippets, documentation, logs,
373
-
configuration files, and other textual information with language models.
375
-
The server handles access control and security, ensuring that only
376
-
authorized resources are shared with clients.
378
-
In JSON-RPC, this is represented as:
381
-
"uri": "file:///example.txt",
382
-
"mimeType": "text/plain",
383
-
"text": "Resource content"
389
-
(** URI that uniquely identifies the resource.
390
-
This URI can be referenced in subsequent requests to fetch updates. *)
392
-
(** The actual text content of the resource as a UTF-8 encoded string.
393
-
This may be sanitized by the server to remove sensitive information. *)
mime_type: string option;
395
-
(** Optional MIME type of the text content to aid in client rendering.
396
-
Common text MIME types include: text/plain, text/markdown, text/x-python,
397
-
application/json, text/html, text/csv, etc. *)
399
-
include Json.Jsonable.S with type t := t
123
+
val yojson_of_t : t -> Json.t
124
+
val t_of_yojson : Json.t -> t
402
-
(** Binary resource contents - Binary resource data *)
127
+
(** Binary resource contents *)
module BlobResourceContents : sig
404
-
(** BlobResourceContents represents a binary resource in MCP.
406
-
Binary resources allow sharing non-textual data like images, audio files,
407
-
PDFs, and other binary formats with language models that support processing
410
-
In JSON-RPC, this is represented as:
413
-
"uri": "file:///example.png",
414
-
"mimeType": "image/png",
415
-
"blob": "base64-encoded-data"
419
-
Binary data MUST be properly base64-encoded to ensure safe transmission
420
-
in JSON payloads. *)
423
-
(** URI that uniquely identifies the resource.
424
-
This URI can be referenced in subsequent requests to fetch updates. *)
426
-
(** Base64-encoded binary data using standard base64 encoding (RFC 4648).
427
-
This encoding ensures that binary data can be safely transmitted in JSON. *)
mime_type: string option;
429
-
(** Optional MIME type of the binary content to aid in client rendering.
430
-
Common binary MIME types include: image/png, image/jpeg, application/pdf,
431
-
audio/wav, video/mp4, application/octet-stream, etc. *)
433
-
include Json.Jsonable.S with type t := t
135
+
val yojson_of_t : t -> Json.t
136
+
val t_of_yojson : Json.t -> t
436
-
(** Embedded resource - Resource included directly in messages *)
139
+
(** Embedded resource *)
module EmbeddedResource : sig
438
-
(** EmbeddedResource allows referencing server-side resources directly
439
-
in MCP messages, enabling seamless incorporation of managed content.
441
-
Embedded resources can be included in:
442
-
- Tool results to provide rich context
443
-
- Prompt templates to include reference materials
444
-
- Messages to provide additional context to language models
446
-
In contrast to direct content (TextContent, ImageContent, AudioContent),
447
-
embedded resources have the advantage of being persistently stored on the server
448
-
with a stable URI, allowing later retrieval and updates through the resources API.
450
-
For example, a tool might return an embedded resource containing a chart or
451
-
a large dataset that the client can later reference or update. *)
resource: [ `Text of TextResourceContents.t | `Blob of BlobResourceContents.t ];
454
-
(** The resource content, either as text or binary blob. *)
annotations: Annotated.annotation option;
456
-
(** Optional annotations for audience targeting and priority.
457
-
Annotations can restrict resource visibility to specific roles (user/assistant)
458
-
and indicate relative importance of different content elements. *)
460
-
include Json.Jsonable.S with type t := t
146
+
val yojson_of_t : t -> Json.t
147
+
val t_of_yojson : Json.t -> t
463
-
(** Content type used in messages - Unified multimodal content representation in MCP *)
150
+
(** Content type used in messages *)
465
-
| Text of TextContent.t (** Text content for natural language messages. This is the most common content type for user-assistant interactions. *)
466
-
| Image of ImageContent.t (** Image content for visual data. Used for sharing visual context in multimodal conversations. *)
467
-
| Audio of AudioContent.t (** Audio content for audio data. Used for sharing audio context in multimodal conversations. *)
468
-
| Resource of EmbeddedResource.t (** Resource content for referencing server-side resources. Used for incorporating managed server content with stable URIs. *)
152
+
| Text of TextContent.t
153
+
| Image of ImageContent.t
154
+
| Audio of AudioContent.t
155
+
| Resource of EmbeddedResource.t
470
-
(** Convert content to Yojson representation
471
-
@param content The content to convert
472
-
@return JSON representation of the content
val yojson_of_content : content -> Json.t
476
-
(** Convert Yojson representation to content
477
-
@param json JSON representation of content
478
-
@return Parsed content object
val content_of_yojson : Json.t -> content
482
-
(** Message for prompts - Template messages in the MCP prompts feature *)
160
+
(** Message for prompts *)
module PromptMessage : sig
484
-
(** PromptMessage represents a message in an MCP prompt template,
485
-
containing a role and content which can be customized with arguments.
487
-
Prompt messages are part of prompt templates exposed by servers through
488
-
the prompts/get endpoint. They define structured conversation templates
489
-
that can be instantiated with user-provided arguments.
491
-
The prompt feature is designed to be user-controlled, with prompts typically
492
-
exposed through UI elements like slash commands that users can explicitly select.
494
-
In JSON-RPC, prompt messages are represented as:
500
-
"text": "Please review this code: ${code}"
505
-
Where $code would be replaced with a user-provided argument. *)
508
-
(** The role of the message sender (user or assistant).
509
-
Prompt templates typically alternate between user and assistant messages
510
-
to create a conversation structure. *)
512
-
(** The message content, which can be text, image, audio, or resource.
513
-
This unified content type supports rich multimodal prompts. *)
515
-
include Json.Jsonable.S with type t := t
167
+
val yojson_of_t : t -> Json.t
168
+
val t_of_yojson : Json.t -> t
518
-
(** Message for sampling - Messages used in LLM completion requests *)
171
+
(** Message for sampling *)
module SamplingMessage : sig
520
-
(** SamplingMessage represents a message in an MCP sampling request,
521
-
used for AI model generation based on a prompt.
523
-
The sampling feature allows clients to expose language model capabilities
524
-
to servers, enabling servers to request completions from the client's LLM.
525
-
This is effectively the reverse of the normal MCP flow, with the server
526
-
requesting generative capabilities from the client.
528
-
Sampling messages differ from prompt messages in that they don't support
529
-
embedded resources, as they represent the actual context window being
530
-
sent to the LLM rather than template definitions.
532
-
Clients that support sampling must declare the 'sampling' capability
533
-
during initialization. *)
536
-
(** The role of the message sender (user or assistant).
537
-
Typically, a sampling request will contain multiple messages
538
-
representing a conversation history, with alternating roles. *)
539
-
content: [ `Text of TextContent.t | `Image of ImageContent.t | `Audio of AudioContent.t ];
540
-
(** The message content, restricted to text, image, or audio (no resources).
541
-
Resources are not included since sampling messages represent the
542
-
actual context window for the LLM, not template definitions. *)
175
+
content: [ `Text of TextContent.t | `Image of ImageContent.t ];
544
-
include Json.Jsonable.S with type t := t
178
+
val yojson_of_t : t -> Json.t
179
+
val t_of_yojson : Json.t -> t
(** Implementation information *)
module Implementation : sig
549
-
(** Implementation provides metadata about client and server implementations,
550
-
used during the initialization phase to identify each party. *)
553
-
(** Name of the implementation *)
555
-
(** Version of the implementation *)
557
-
include Json.Jsonable.S with type t := t
189
+
val yojson_of_t : t -> Json.t
190
+
val t_of_yojson : Json.t -> t
560
-
(** JSONRPC message types - Core message protocol for MCP
562
-
MCP uses JSON-RPC 2.0 as its underlying messaging protocol.
563
-
All MCP messages are encoded as JSON-RPC 2.0 messages with UTF-8 encoding,
564
-
following the standard JSON-RPC message formats with some MCP-specific extensions.
566
-
MCP defines four message types:
567
-
1. Notifications: One-way messages that don't expect a response
568
-
2. Requests: Messages that expect a corresponding response
569
-
3. Responses: Replies to requests with successful results
570
-
4. Errors: Replies to requests with error information
572
-
These can be transported over multiple transport mechanisms:
573
-
- stdio: Communication over standard input/output
574
-
- Streamable HTTP: HTTP POST/GET with SSE for server streaming
575
-
- Custom transports: Implementation-specific transports
577
-
Messages may be sent individually or as part of a JSON-RPC batch.
193
+
(** JSONRPC message types *)
module JSONRPCMessage : sig
580
-
(** Notification represents a JSON-RPC notification (one-way message without a response).
582
-
Notifications are used for events that don't require a response, such as:
583
-
- The 'initialized' notification completing initialization
584
-
- Resource change notifications
585
-
- Progress updates for long-running operations
586
-
- List changed notifications for tools, resources, and prompts
588
-
In JSON-RPC, notifications are identified by the absence of an 'id' field:
592
-
"method": "notifications/resources/updated",
594
-
"uri": "file:///project/src/main.rs"
601
-
(** Method for the notification, using the Method.t type to ensure type safety.
602
-
Examples: Method.Initialized, Method.ResourcesUpdated *)
604
-
(** Optional parameters for the notification as arbitrary JSON.
605
-
The structure depends on the specific notification method. *)
608
-
(** Request represents a JSON-RPC request that expects a response.
610
-
Requests are used for operations that require a response, such as:
612
-
- Listing resources, tools, or prompts
613
-
- Reading resources
617
-
In JSON-RPC, requests include an 'id' field that correlates with the response:
622
-
"method": "resources/read",
624
-
"uri": "file:///project/src/main.rs"
631
-
(** Unique identifier for the request, which will be echoed in the response.
632
-
This can be a string or integer and should be unique within the session. *)
634
-
(** Method for the request, using the Method.t type to ensure type safety.
635
-
Examples: Method.Initialize, Method.ResourcesRead, Method.ToolsCall *)
637
-
(** Optional parameters for the request as arbitrary JSON.
638
-
The structure depends on the specific request method. *)
progress_token: ProgressToken.t option;
640
-
(** Optional progress token for long-running operations.
641
-
If provided, the server can send progress notifications using this token
642
-
to inform the client about the operation's status. *)
645
-
(** Response represents a successful JSON-RPC response to a request.
647
-
Responses are sent in reply to requests and contain the successful result.
648
-
Each response must include the same ID as its corresponding request.
650
-
In JSON-RPC, responses include the 'id' field matching the request:
658
-
"uri": "file:///project/src/main.rs",
659
-
"mimeType": "text/x-rust",
660
-
"text": "fn main() {\n println!(\"Hello world!\");\n}"
669
-
(** ID matching the original request, allowing clients to correlate
670
-
responses with their originating requests, especially important
671
-
when multiple requests are in flight. *)
673
-
(** Result of the successful request as arbitrary JSON.
674
-
The structure depends on the specific request method that was called. *)
677
-
(** Error represents an error response to a JSON-RPC request.
679
-
Errors are sent in reply to requests when processing fails.
680
-
Each error must include the same ID as its corresponding request.
682
-
MCP defines several standard error codes:
683
-
- Standard JSON-RPC errors (-32700 to -32603)
684
-
- MCP-specific errors (-32002 for resource not found, etc.)
686
-
In JSON-RPC, errors follow this structure:
693
-
"message": "Resource not found",
695
-
"uri": "file:///nonexistent.txt"
703
-
(** ID matching the original request, allowing clients to correlate
704
-
errors with their originating requests. *)
706
-
(** Error code indicating the type of error, following the JSON-RPC standard.
707
-
Common codes include:
708
-
- -32700: Parse error
709
-
- -32600: Invalid request
710
-
- -32601: Method not found
711
-
- -32602: Invalid params
712
-
- -32603: Internal error
713
-
- -32002: Resource not found (MCP-specific)
714
-
- -32001: Authentication required (MCP-specific) *)
716
-
(** Human-readable error message describing the issue.
717
-
This should be concise but informative enough for debugging. *)
719
-
(** Optional additional error data as arbitrary JSON.
720
-
This can provide more context about the error, such as which
721
-
resource wasn't found or which parameter was invalid. *)
724
-
(** Union type for all JSON-RPC message kinds, providing a single type
725
-
that can represent any MCP message. *)
| Notification of notification
732
-
(** Convert notification to Yojson representation
733
-
@param notification The notification to convert
734
-
@return JSON representation of the notification
val yojson_of_notification : notification -> Json.t
738
-
(** Convert request to Yojson representation
739
-
@param request The request to convert
740
-
@return JSON representation of the request
val yojson_of_request : request -> Json.t
744
-
(** Convert response to Yojson representation
745
-
@param response The response to convert
746
-
@return JSON representation of the response
val yojson_of_response : response -> Json.t
750
-
(** Convert error to Yojson representation
751
-
@param error The error to convert
752
-
@return JSON representation of the error
val yojson_of_error : error -> Json.t
756
-
(** Convert any message to Yojson representation
757
-
@param message The message to convert
758
-
@return JSON representation of the message
val yojson_of_t : t -> Json.t
762
-
(** Convert Yojson representation to notification
763
-
@param json JSON representation of a notification
764
-
@return Parsed notification object
765
-
@raise Parse error if the JSON is not a valid notification
val notification_of_yojson : Json.t -> notification
769
-
(** Convert Yojson representation to request
770
-
@param json JSON representation of a request
771
-
@return Parsed request object
772
-
@raise Parse error if the JSON is not a valid request
val request_of_yojson : Json.t -> request
776
-
(** Convert Yojson representation to response
777
-
@param json JSON representation of a response
778
-
@return Parsed response object
779
-
@raise Parse error if the JSON is not a valid response
val response_of_yojson : Json.t -> response
783
-
(** Convert Yojson representation to error
784
-
@param json JSON representation of an error
785
-
@return Parsed error object
786
-
@raise Parse error if the JSON is not a valid error
val error_of_yojson : Json.t -> error
790
-
(** Convert Yojson representation to any message
791
-
@param json JSON representation of any message type
792
-
@return Parsed message object
793
-
@raise Parse error if the JSON is not a valid message
val t_of_yojson : Json.t -> t
797
-
(** Create a new notification message
798
-
@param params Optional parameters for the notification
799
-
@param meth Method name for the notification
800
-
@return A new JSON-RPC notification message
802
-
val create_notification : ?params:Json.t option -> meth:Method.t -> unit -> t
804
-
(** Create a new request message
805
-
@param params Optional parameters for the request
806
-
@param progress_token Optional progress token for long-running operations
807
-
@param id Unique identifier for the request
808
-
@param meth Method name for the request
809
-
@return A new JSON-RPC request message
811
-
val create_request : ?params:Json.t option -> ?progress_token:ProgressToken.t option -> id:RequestId.t -> meth:Method.t -> unit -> t
813
-
(** Create a new response message
814
-
@param id ID matching the original request
815
-
@param result Result of the successful request
816
-
@return A new JSON-RPC response message
237
+
val create_notification : ?params:Json.t option -> method_:string -> unit -> t
238
+
val create_request : ?params:Json.t option -> ?progress_token:ProgressToken.t option -> id:RequestId.t -> method_:string -> unit -> t
val create_response : id:RequestId.t -> result:Json.t -> t
820
-
(** Create a new error message
821
-
@param id ID matching the original request
822
-
@param code Error code indicating the type of error
823
-
@param message Human-readable error message
824
-
@param data Optional additional error data
825
-
@return A new JSON-RPC error message
val create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> t
830
-
(** Initialize request/response - The first phase of the MCP lifecycle
832
-
The initialization phase is the mandatory first interaction between client and server.
833
-
During this phase, the protocol version is negotiated and capabilities are exchanged
834
-
to determine which optional features will be available during the session.
836
-
This follows a strict sequence:
837
-
1. Client sends an InitializeRequest containing its capabilities and protocol version
838
-
2. Server responds with an InitializeResult containing its capabilities and protocol version
839
-
3. Client sends an InitializedNotification to signal it's ready for normal operations
841
-
The Initialize module handles steps 1 and 2 of this process.
243
+
(** Initialize request/response *)
(** Initialize request *)
846
-
(** InitializeRequest starts the MCP lifecycle, negotiating capabilities
847
-
and protocol versions between client and server. This is always the first
848
-
message sent by the client and MUST NOT be part of a JSON-RPC batch.
850
-
The client SHOULD send the latest protocol version it supports. If the server
851
-
does not support this version, it will respond with a version it does support,
852
-
and the client must either use that version or disconnect. *)
854
-
capabilities: Json.t; (** ClientCapabilities that define supported optional features.
855
-
This includes which optional protocol features the client supports,
856
-
such as 'roots' (filesystem access), 'sampling' (LLM generation),
857
-
and any experimental features. *)
248
+
capabilities: Json.t; (** ClientCapabilities *)
client_info: Implementation.t;
859
-
(** Client implementation details (name and version) used for identification
860
-
and debugging. Helps servers understand which client they're working with. *)
protocol_version: string;
862
-
(** MCP protocol version supported by the client, formatted as YYYY-MM-DD
863
-
according to the MCP versioning scheme. Example: "2025-03-26" *)
865
-
include Json.Jsonable.S with type t := t
253
+
val yojson_of_t : t -> Json.t
254
+
val t_of_yojson : Json.t -> t
867
-
(** Create a new initialization request
868
-
@param capabilities Client capabilities that define supported optional features
869
-
@param client_info Client implementation details
870
-
@param protocol_version MCP protocol version supported by the client
871
-
@return A new initialization request
val create : capabilities:Json.t -> client_info:Implementation.t -> protocol_version:string -> t
875
-
(** Convert to JSON-RPC message
876
-
@param id Unique request identifier
877
-
@param t Initialization request
878
-
@return JSON-RPC message containing the initialization request
val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t
885
-
(** InitializeResult is the server's response to an initialization request,
886
-
completing capability negotiation and establishing the protocol version.
888
-
After receiving this message, the client must send an InitializedNotification.
889
-
The server should not send any requests other than pings and logging before
890
-
receiving the initialized notification. *)
892
-
capabilities: Json.t; (** ServerCapabilities that define supported optional features.
893
-
This declares which server features are available, including:
894
-
- prompts: Server provides prompt templates
895
-
- resources: Server provides readable resources
896
-
- tools: Server exposes callable tools
897
-
- logging: Server emits structured log messages
899
-
Each capability may have sub-capabilities like:
900
-
- listChanged: Server will notify when available items change
901
-
- subscribe: Clients can subscribe to individual resources *)
263
+
capabilities: Json.t; (** ServerCapabilities *)
server_info: Implementation.t;
903
-
(** Server implementation details (name and version) used for identification
904
-
and debugging. Helps clients understand which server they're working with. *)
protocol_version: string;
906
-
(** MCP protocol version supported by the server, formatted as YYYY-MM-DD.
907
-
If the server supports the client's requested version, it responds with
908
-
the same version. Otherwise, it responds with a version it does support. *)
instructions: string option;
910
-
(** Optional instructions for using the server. These can provide human-readable
911
-
guidance on how to interact with this specific server implementation. *)
913
-
(** Optional additional metadata as arbitrary JSON. Can contain server-specific
914
-
information not covered by the standard fields. *)
916
-
include Json.Jsonable.S with type t := t
270
+
val yojson_of_t : t -> Json.t
271
+
val t_of_yojson : Json.t -> t
918
-
(** Create a new initialization result
919
-
@param capabilities Server capabilities that define supported optional features
920
-
@param server_info Server implementation details
921
-
@param protocol_version MCP protocol version supported by the server
922
-
@param instructions Optional instructions for using the server
923
-
@param meta Optional additional metadata
924
-
@return A new initialization result
val create : capabilities:Json.t -> server_info:Implementation.t -> protocol_version:string -> ?instructions:string -> ?meta:Json.t -> unit -> t
928
-
(** Convert to JSON-RPC message
929
-
@param id ID matching the original request
930
-
@param t Initialization result
931
-
@return JSON-RPC message containing the initialization result
val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t
937
-
(** Initialized notification - Completes the initialization phase of the MCP lifecycle *)
278
+
(** Initialized notification *)
module Notification : sig
940
-
(** InitializedNotification is sent by the client after receiving the initialization
941
-
response, indicating it's ready to begin normal operations. This completes the
942
-
three-step initialization process, after which both client and server can
943
-
freely exchange messages according to the negotiated capabilities.
945
-
Only after this notification has been sent should the client begin normal operations
946
-
like listing resources, calling tools, or requesting prompts. *)
949
-
(** Optional additional metadata as arbitrary JSON. Can contain client-specific
950
-
information not covered by the standard fields. *)
952
-
include Json.Jsonable.S with type t := t
285
+
val yojson_of_t : t -> Json.t
286
+
val t_of_yojson : Json.t -> t
954
-
(** Create a new initialized notification
955
-
@param meta Optional additional metadata
956
-
@return A new initialized notification
val create : ?meta:Json.t -> unit -> t
960
-
(** Convert to JSON-RPC message
961
-
@param t Initialized notification
962
-
@return JSON-RPC message containing the initialized notification
val to_jsonrpc : t -> JSONRPCMessage.t
968
-
(** Parse a JSON message into an MCP message
970
-
This function takes a raw JSON value and parses it into a structured MCP message.
971
-
It's the primary entry point for processing incoming JSON-RPC messages in the MCP protocol.
973
-
The function determines the message type (notification, request, response, or error)
974
-
based on the presence and values of specific fields:
975
-
- A message with "method" but no "id" is a notification
976
-
- A message with "method" and "id" is a request
977
-
- A message with "id" and "result" is a response
978
-
- A message with "id" and "error" is an error
980
-
@param json The JSON message to parse, typically received from the transport layer
981
-
@return The parsed MCP message as a structured JSONRPCMessage.t value
982
-
@raise Parse error if the JSON cannot be parsed as a valid MCP message
984
-
val parse_message : Json.t -> JSONRPCMessage.t
293
+
(** Tool definition *)
297
+
description: string option;
298
+
input_schema: Json.t;
986
-
(** Create a new notification message
988
-
Notifications are one-way messages that don't expect a response.
989
-
This is a convenience wrapper around JSONRPCMessage.create_notification.
991
-
Common notifications in MCP include:
992
-
- "notifications/initialized" - Sent after initialization
993
-
- "notifications/progress" - Updates on long-running operations
994
-
- "notifications/resources/updated" - Resource content changed
995
-
- "notifications/prompts/list_changed" - Available prompts changed
996
-
- "notifications/tools/list_changed" - Available tools changed
998
-
@param params Optional parameters for the notification as a JSON value
999
-
@param meth Method type for the notification
1000
-
@return A new JSON-RPC notification message
1002
-
val create_notification : ?params:Json.t option -> meth:Method.t -> unit -> JSONRPCMessage.t
301
+
val yojson_of_t : t -> Json.t
302
+
val t_of_yojson : Json.t -> t
1004
-
(** Create a new request message
1006
-
Requests are messages that expect a corresponding response.
1007
-
This is a convenience wrapper around JSONRPCMessage.create_request.
1009
-
Common requests in MCP include:
1010
-
- "initialize" - Start the MCP lifecycle
1011
-
- "resources/list" - Discover available resources
1012
-
- "resources/read" - Retrieve resource contents
1013
-
- "tools/list" - Discover available tools
1014
-
- "tools/call" - Invoke a tool
1015
-
- "prompts/list" - Discover available prompts
1016
-
- "prompts/get" - Retrieve a prompt template
1018
-
@param params Optional parameters for the request as a JSON value
1019
-
@param progress_token Optional progress token for long-running operations
1020
-
that can report progress updates
1021
-
@param id Unique identifier for the request, used to correlate with the response
1022
-
@param meth Method type for the request
1023
-
@return A new JSON-RPC request message
1025
-
val create_request : ?params:Json.t option -> ?progress_token:ProgressToken.t option -> id:RequestId.t -> meth:Method.t -> unit -> JSONRPCMessage.t
306
+
module CallToolResult : sig
308
+
content: content list;
310
+
meta: Json.t option;
313
+
val yojson_of_t : t -> Json.t
314
+
val t_of_yojson : Json.t -> t
1027
-
(** Create a new response message
1029
-
Responses are sent in reply to requests and contain successful results.
1030
-
This is a convenience wrapper around JSONRPCMessage.create_response.
1032
-
Each response must include the same ID as its corresponding request
1033
-
to allow the client to correlate them, especially when multiple
1034
-
requests are in flight simultaneously.
1036
-
@param id ID matching the original request
1037
-
@param result Result of the successful request as a JSON value
1038
-
@return A new JSON-RPC response message
1040
-
val create_response : id:RequestId.t -> result:Json.t -> JSONRPCMessage.t
317
+
(** Resource definition *)
318
+
module Resource : sig
322
+
description: string option;
323
+
mime_type: string option;
325
+
annotations: Annotated.annotation option;
1042
-
(** Create a new error message
1044
-
Errors are sent in reply to requests when processing fails.
1045
-
This is a convenience wrapper around JSONRPCMessage.create_error.
1047
-
MCP uses standard JSON-RPC error codes as well as some protocol-specific codes:
1048
-
- -32700: Parse error (invalid JSON)
1049
-
- -32600: Invalid request (malformed JSON-RPC)
1050
-
- -32601: Method not found
1051
-
- -32602: Invalid parameters
1052
-
- -32603: Internal error
1053
-
- -32002: Resource not found (MCP-specific)
1054
-
- -32001: Authentication required (MCP-specific)
1056
-
@param id ID matching the original request
1057
-
@param code Error code indicating the type of error
1058
-
@param message Human-readable error message describing the issue
1059
-
@param data Optional additional error data providing more context
1060
-
@return A new JSON-RPC error message
1062
-
val create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> JSONRPCMessage.t
328
+
val yojson_of_t : t -> Json.t
329
+
val t_of_yojson : Json.t -> t
332
+
(** Resource Template definition *)
333
+
module ResourceTemplate : sig
336
+
uri_template: string;
337
+
description: string option;
338
+
mime_type: string option;
339
+
annotations: Annotated.annotation option;
1064
-
(** Create a new text content object
1065
-
@param text The text content
1066
-
@return A content value with the text
1068
-
val make_text_content : string -> content
342
+
val yojson_of_t : t -> Json.t
343
+
val t_of_yojson : Json.t -> t
1070
-
(** Create a new image content object
1071
-
@param data Base64-encoded image data
1072
-
@param mime_type MIME type of the image (e.g., "image/png", "image/jpeg")
1073
-
@return A content value with the image
1075
-
val make_image_content : string -> string -> content
346
+
(** Resource Reference *)
347
+
module ResourceReference : sig
1077
-
(** Create a new audio content object
1078
-
@param data Base64-encoded audio data
1079
-
@param mime_type MIME type of the audio (e.g., "audio/wav", "audio/mp3")
1080
-
@return A content value with the audio
1082
-
val make_audio_content : string -> string -> content
352
+
val yojson_of_t : t -> Json.t
353
+
val t_of_yojson : Json.t -> t
1084
-
(** Create a new text resource content object
1085
-
@param uri URI that uniquely identifies the resource
1086
-
@param text The text content of the resource
1087
-
@param mime_type Optional MIME type of the text content
1088
-
@return A content value with the text resource
1090
-
val make_resource_text_content : string -> string -> string option -> content
356
+
(** Prompt Reference *)
357
+
module PromptReference : sig
1092
-
(** Create a new binary resource content object
1093
-
@param uri URI that uniquely identifies the resource
1094
-
@param blob Base64-encoded binary data
1095
-
@param mime_type Optional MIME type of the binary content
1096
-
@return A content value with the binary resource
1098
-
val make_resource_blob_content : string -> string -> string option -> content
362
+
val yojson_of_t : t -> Json.t
363
+
val t_of_yojson : Json.t -> t
366
+
(** Completion support *)
367
+
module Completion : sig
368
+
module Argument : sig
374
+
val yojson_of_t : t -> Json.t
375
+
val t_of_yojson : Json.t -> t
378
+
module Request : sig
379
+
type reference = [ `Prompt of PromptReference.t | `Resource of ResourceReference.t ]
382
+
argument: Argument.t;
386
+
val yojson_of_t : t -> Json.t
387
+
val t_of_yojson : Json.t -> t
389
+
val yojson_of_reference : reference -> Json.t
390
+
val reference_of_yojson : Json.t -> reference
392
+
val create : argument:Argument.t -> ref:reference -> t
393
+
val to_params : t -> Json.t
396
+
module Result : sig
397
+
type completion = {
398
+
values: string list;
399
+
has_more: bool option;
404
+
completion: completion;
405
+
meta: Json.t option;
408
+
val yojson_of_completion : completion -> Json.t
409
+
val completion_of_yojson : Json.t -> completion
411
+
val yojson_of_t : t -> Json.t
412
+
val t_of_yojson : Json.t -> t
414
+
val create : completion:completion -> ?meta:Json.t -> unit -> t
415
+
val to_result : t -> Json.t
419
+
(** Parse a JSON message into an MCP message *)
420
+
val parse_message : Json.t -> JSONRPCMessage.t
422
+
(** Create JSONRPC message helpers *)
423
+
val create_notification : ?params:Json.t option -> method_:string -> unit -> JSONRPCMessage.t
424
+
val create_request : ?params:Json.t option -> ?progress_token:ProgressToken.t option -> id:RequestId.t -> method_:string -> unit -> JSONRPCMessage.t
425
+
val create_response : id:RequestId.t -> result:Json.t -> JSONRPCMessage.t
426
+
val create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> JSONRPCMessage.t
428
+
(** Helper functions for common requests/responses *)
429
+
val create_completion_request : id:RequestId.t -> argument:Completion.Argument.t -> ref:Completion.Request.reference -> JSONRPCMessage.t
430
+
val create_completion_response : id:RequestId.t -> values:string list -> ?has_more:bool option -> ?total:int option -> ?meta:Json.t option -> unit -> JSONRPCMessage.t
anil.recoil.org
