···
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
-
(** Error codes for JSON-RPC *)
5
+
(** Standard error codes *)
28
-
(** 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 *)
39
-
(** Convert the error code to its integer representation
40
-
@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
45
-
(** Get error message for standard error codes
46
-
@param code The error code to get message for
47
-
@return A standard message for the error code
49
-
val to_message : t -> string
52
-
(** MCP Protocol Methods - Algebraic data type representing all MCP methods *)
54
-
(** Method type representing all MCP protocol methods *)
56
-
(* Initialization and lifecycle methods *)
57
-
| Initialize (** Start the MCP lifecycle *)
58
-
| Initialized (** Signal readiness after initialization *)
60
-
(* Resource methods *)
61
-
| ResourcesList (** Discover available resources *)
62
-
| ResourcesRead (** Retrieve resource contents *)
63
-
| ResourcesTemplatesList (** List available resource templates *)
64
-
| ResourcesSubscribe (** Subscribe to resource changes *)
65
-
| ResourcesListChanged (** Resource list has changed *)
66
-
| ResourcesUpdated (** Resource has been updated *)
69
-
| ToolsList (** Discover available tools *)
70
-
| ToolsCall (** Invoke a tool *)
71
-
| ToolsListChanged (** Tool list has changed *)
73
-
(* Prompt methods *)
74
-
| PromptsList (** Discover available prompts *)
75
-
| PromptsGet (** Retrieve a prompt template with arguments *)
76
-
| PromptsListChanged (** Prompt list has changed *)
78
-
(* Progress notifications *)
79
-
| Progress (** Progress update for long-running operations *)
81
-
(** Convert method type to string representation
82
-
@param meth The method to convert
83
-
@return The string representation of the method (e.g., "initialize", "resources/list")
85
-
val to_string : t -> string
87
-
(** Convert string to method type
88
-
@param s The string representation of the method
89
-
@return The corresponding method type
90
-
@raise Failure if the string is not a valid MCP method
92
-
val of_string : string -> t
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
(** Roles for conversation participants *)
100
-
(** Role represents conversation participants in MCP messages.
101
-
Roles can be either 'user' or 'assistant', determining the
102
-
source of each message in a conversation. *)
type t = [ `User | `Assistant ]
104
-
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
109
-
(** Progress tokens identify long-running operations and enable
110
-
servers to provide progress updates to clients. This is used
111
-
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
118
-
(** Request IDs uniquely identify JSON-RPC requests, allowing responses
119
-
to be correlated with their originating requests. They can be either
120
-
string or integer values. *)
type t = [ `String of string | `Int of int ]
include Json.Jsonable.S with type t := t
(** Cursors for pagination *)
127
-
(** Cursors enable pagination in list operations for resources, tools, and prompts.
128
-
When a server has more items than can be returned in a single response,
129
-
it provides a cursor for the client to retrieve subsequent pages. *)
131
-
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 *)
136
-
(** Annotations provide metadata for content objects, allowing
137
-
role-specific targeting and priority settings. *)
annotations: annotation option;
audience: Role.t list option;
143
-
(** Optional list of roles that should receive this content *)
145
-
(** Optional priority value for this content *)
147
-
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
150
-
(** Text content - Core textual message representation in MCP *)
152
-
(** TextContent represents plain text messages in MCP conversations.
153
-
This is the most common content type used for natural language interactions
154
-
between users and assistants. Text content is used in prompts, tool results,
155
-
and model responses.
157
-
In JSON-RPC, this is represented as:
161
-
"text": "The text content of the message"
165
-
For security, implementations must sanitize text content to prevent
166
-
injection attacks or unauthorized access to resources. *)
169
-
(** The actual text content as a UTF-8 encoded string *)
annotations: Annotated.annotation option;
171
-
(** Optional annotations for audience targeting and priority.
172
-
Annotations can restrict content visibility to specific roles (user/assistant)
173
-
and indicate relative importance of different content elements. *)
175
-
include Json.Jsonable.S with type t := t
76
+
val yojson_of_t : t -> Json.t
77
+
val t_of_yojson : Json.t -> t
178
-
(** Image content - Visual data representation in MCP *)
80
+
(** Image content *)
module ImageContent : sig
180
-
(** ImageContent enables including visual information in MCP messages,
181
-
supporting multimodal interactions where visual context is important.
183
-
Images can be used in several scenarios:
184
-
- As user inputs for visual understanding tasks
185
-
- As context for generating descriptions or analysis
186
-
- As outputs from tools that generate visualizations
187
-
- As part of prompt templates with visual components
189
-
In JSON-RPC, this is represented as:
193
-
"data": "base64-encoded-image-data",
194
-
"mimeType": "image/png"
198
-
The data MUST be base64-encoded to ensure safe transmission in JSON.
199
-
Common mime types include image/png, image/jpeg, image/gif, and image/svg+xml. *)
202
-
(** Base64-encoded image data. All binary image data must be encoded using
203
-
standard base64 encoding (RFC 4648) to safely transmit within JSON. *)
205
-
(** MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/svg+xml").
206
-
This field is required and must accurately represent the image format to ensure
207
-
proper handling by clients. *)
annotations: Annotated.annotation option;
209
-
(** Optional annotations for audience targeting and priority.
210
-
Annotations can restrict content visibility to specific roles (user/assistant)
211
-
and indicate relative importance of different content elements. *)
213
-
include Json.Jsonable.S with type t := t
88
+
val yojson_of_t : t -> Json.t
89
+
val t_of_yojson : Json.t -> t
216
-
(** Audio content - Sound data representation in MCP *)
92
+
(** Audio content *)
module AudioContent : sig
218
-
(** AudioContent enables including audio information in MCP messages,
219
-
supporting multimodal interactions where audio context is important.
221
-
Audio can be used in several scenarios:
222
-
- As user inputs for speech recognition or audio analysis
223
-
- As context for transcription or sound classification tasks
224
-
- As outputs from tools that generate audio samples
225
-
- As part of prompt templates with audio components
227
-
In JSON-RPC, this is represented as:
231
-
"data": "base64-encoded-audio-data",
232
-
"mimeType": "audio/wav"
236
-
The data MUST be base64-encoded to ensure safe transmission in JSON.
237
-
Common mime types include audio/wav, audio/mp3, audio/ogg, and audio/mpeg. *)
240
-
(** Base64-encoded audio data. All binary audio data must be encoded using
241
-
standard base64 encoding (RFC 4648) to safely transmit within JSON. *)
243
-
(** MIME type of the audio (e.g., "audio/wav", "audio/mp3", "audio/ogg", "audio/mpeg").
244
-
This field is required and must accurately represent the audio format to ensure
245
-
proper handling by clients. *)
annotations: Annotated.annotation option;
247
-
(** Optional annotations for audience targeting and priority.
248
-
Annotations can restrict content visibility to specific roles (user/assistant)
249
-
and indicate relative importance of different content elements. *)
251
-
include Json.Jsonable.S with type t := t
100
+
val yojson_of_t : t -> Json.t
101
+
val t_of_yojson : Json.t -> t
254
-
(** Base resource contents - Core resource metadata in MCP *)
104
+
(** Base resource contents *)
module ResourceContents : sig
256
-
(** ResourceContents provides basic metadata for resources in MCP.
258
-
Resources are server-exposed data that provides context to language models,
259
-
such as files, database schemas, or application-specific information.
260
-
Each resource is uniquely identified by a URI.
262
-
The MCP resources architecture is designed to be application-driven, with
263
-
host applications determining how to incorporate context based on their needs.
265
-
In the protocol, resources are discovered via the 'resources/list' endpoint
266
-
and retrieved via the 'resources/read' endpoint. Servers that support resources
267
-
must declare the 'resources' capability during initialization. *)
270
-
(** URI that uniquely identifies the resource.
272
-
Resources use standard URI schemes including:
273
-
- file:// - For filesystem-like resources
274
-
- https:// - For web-accessible resources
275
-
- git:// - For version control integration
277
-
The URI serves as a stable identifier even if the underlying content changes. *)
mime_type: string option;
279
-
(** Optional MIME type of the resource content to aid in client rendering.
280
-
Common MIME types include text/plain, application/json, image/png, etc.
281
-
For directories, the XDG MIME type inode/directory may be used. *)
283
-
include Json.Jsonable.S with type t := t
111
+
val yojson_of_t : t -> Json.t
112
+
val t_of_yojson : Json.t -> t
286
-
(** Text resource contents - Textual resource data *)
115
+
(** Text resource contents *)
module TextResourceContents : sig
288
-
(** TextResourceContents represents a text-based resource in MCP.
290
-
Text resources are used for sharing code snippets, documentation, logs,
291
-
configuration files, and other textual information with language models.
293
-
The server handles access control and security, ensuring that only
294
-
authorized resources are shared with clients.
296
-
In JSON-RPC, this is represented as:
299
-
"uri": "file:///example.txt",
300
-
"mimeType": "text/plain",
301
-
"text": "Resource content"
307
-
(** URI that uniquely identifies the resource.
308
-
This URI can be referenced in subsequent requests to fetch updates. *)
310
-
(** The actual text content of the resource as a UTF-8 encoded string.
311
-
This may be sanitized by the server to remove sensitive information. *)
mime_type: string option;
313
-
(** Optional MIME type of the text content to aid in client rendering.
314
-
Common text MIME types include: text/plain, text/markdown, text/x-python,
315
-
application/json, text/html, text/csv, etc. *)
317
-
include Json.Jsonable.S with type t := t
123
+
val yojson_of_t : t -> Json.t
124
+
val t_of_yojson : Json.t -> t
320
-
(** Binary resource contents - Binary resource data *)
127
+
(** Binary resource contents *)
module BlobResourceContents : sig
322
-
(** BlobResourceContents represents a binary resource in MCP.
324
-
Binary resources allow sharing non-textual data like images, audio files,
325
-
PDFs, and other binary formats with language models that support processing
328
-
In JSON-RPC, this is represented as:
331
-
"uri": "file:///example.png",
332
-
"mimeType": "image/png",
333
-
"blob": "base64-encoded-data"
337
-
Binary data MUST be properly base64-encoded to ensure safe transmission
338
-
in JSON payloads. *)
341
-
(** URI that uniquely identifies the resource.
342
-
This URI can be referenced in subsequent requests to fetch updates. *)
344
-
(** Base64-encoded binary data using standard base64 encoding (RFC 4648).
345
-
This encoding ensures that binary data can be safely transmitted in JSON. *)
mime_type: string option;
347
-
(** Optional MIME type of the binary content to aid in client rendering.
348
-
Common binary MIME types include: image/png, image/jpeg, application/pdf,
349
-
audio/wav, video/mp4, application/octet-stream, etc. *)
351
-
include Json.Jsonable.S with type t := t
135
+
val yojson_of_t : t -> Json.t
136
+
val t_of_yojson : Json.t -> t
354
-
(** Embedded resource - Resource included directly in messages *)
139
+
(** Embedded resource *)
module EmbeddedResource : sig
356
-
(** EmbeddedResource allows referencing server-side resources directly
357
-
in MCP messages, enabling seamless incorporation of managed content.
359
-
Embedded resources can be included in:
360
-
- Tool results to provide rich context
361
-
- Prompt templates to include reference materials
362
-
- Messages to provide additional context to language models
364
-
In contrast to direct content (TextContent, ImageContent, AudioContent),
365
-
embedded resources have the advantage of being persistently stored on the server
366
-
with a stable URI, allowing later retrieval and updates through the resources API.
368
-
For example, a tool might return an embedded resource containing a chart or
369
-
a large dataset that the client can later reference or update. *)
resource: [ `Text of TextResourceContents.t | `Blob of BlobResourceContents.t ];
372
-
(** The resource content, either as text or binary blob. *)
annotations: Annotated.annotation option;
374
-
(** Optional annotations for audience targeting and priority.
375
-
Annotations can restrict resource visibility to specific roles (user/assistant)
376
-
and indicate relative importance of different content elements. *)
378
-
include Json.Jsonable.S with type t := t
146
+
val yojson_of_t : t -> Json.t
147
+
val t_of_yojson : Json.t -> t
381
-
(** Content type used in messages - Unified multimodal content representation in MCP *)
150
+
(** Content type used in messages *)
383
-
| Text of TextContent.t (** Text content for natural language messages. This is the most common content type for user-assistant interactions. *)
384
-
| Image of ImageContent.t (** Image content for visual data. Used for sharing visual context in multimodal conversations. *)
385
-
| Audio of AudioContent.t (** Audio content for audio data. Used for sharing audio context in multimodal conversations. *)
386
-
| 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
388
-
(** Convert content to Yojson representation
389
-
@param content The content to convert
390
-
@return JSON representation of the content
val yojson_of_content : content -> Json.t
394
-
(** Convert Yojson representation to content
395
-
@param json JSON representation of content
396
-
@return Parsed content object
val content_of_yojson : Json.t -> content
400
-
(** Message for prompts - Template messages in the MCP prompts feature *)
160
+
(** Message for prompts *)
module PromptMessage : sig
402
-
(** PromptMessage represents a message in an MCP prompt template,
403
-
containing a role and content which can be customized with arguments.
405
-
Prompt messages are part of prompt templates exposed by servers through
406
-
the prompts/get endpoint. They define structured conversation templates
407
-
that can be instantiated with user-provided arguments.
409
-
The prompt feature is designed to be user-controlled, with prompts typically
410
-
exposed through UI elements like slash commands that users can explicitly select.
412
-
In JSON-RPC, prompt messages are represented as:
418
-
"text": "Please review this code: ${code}"
423
-
Where $code would be replaced with a user-provided argument. *)
426
-
(** The role of the message sender (user or assistant).
427
-
Prompt templates typically alternate between user and assistant messages
428
-
to create a conversation structure. *)
430
-
(** The message content, which can be text, image, audio, or resource.
431
-
This unified content type supports rich multimodal prompts. *)
433
-
include Json.Jsonable.S with type t := t
167
+
val yojson_of_t : t -> Json.t
168
+
val t_of_yojson : Json.t -> t
436
-
(** Message for sampling - Messages used in LLM completion requests *)
171
+
(** Message for sampling *)
module SamplingMessage : sig
438
-
(** SamplingMessage represents a message in an MCP sampling request,
439
-
used for AI model generation based on a prompt.
441
-
The sampling feature allows clients to expose language model capabilities
442
-
to servers, enabling servers to request completions from the client's LLM.
443
-
This is effectively the reverse of the normal MCP flow, with the server
444
-
requesting generative capabilities from the client.
446
-
Sampling messages differ from prompt messages in that they don't support
447
-
embedded resources, as they represent the actual context window being
448
-
sent to the LLM rather than template definitions.
450
-
Clients that support sampling must declare the 'sampling' capability
451
-
during initialization. *)
454
-
(** The role of the message sender (user or assistant).
455
-
Typically, a sampling request will contain multiple messages
456
-
representing a conversation history, with alternating roles. *)
457
-
content: [ `Text of TextContent.t | `Image of ImageContent.t | `Audio of AudioContent.t ];
458
-
(** The message content, restricted to text, image, or audio (no resources).
459
-
Resources are not included since sampling messages represent the
460
-
actual context window for the LLM, not template definitions. *)
175
+
content: [ `Text of TextContent.t | `Image of ImageContent.t ];
462
-
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
467
-
(** Implementation provides metadata about client and server implementations,
468
-
used during the initialization phase to identify each party. *)
471
-
(** Name of the implementation *)
473
-
(** Version of the implementation *)
475
-
include Json.Jsonable.S with type t := t
478
-
(** JSONRPC message types - Core message protocol for MCP
189
+
val yojson_of_t : t -> Json.t
190
+
val t_of_yojson : Json.t -> t
480
-
MCP uses JSON-RPC 2.0 as its underlying messaging protocol.
481
-
All MCP messages are encoded as JSON-RPC 2.0 messages with UTF-8 encoding,
482
-
following the standard JSON-RPC message formats with some MCP-specific extensions.
484
-
MCP defines four message types:
485
-
1. Notifications: One-way messages that don't expect a response
486
-
2. Requests: Messages that expect a corresponding response
487
-
3. Responses: Replies to requests with successful results
488
-
4. Errors: Replies to requests with error information
490
-
These can be transported over multiple transport mechanisms:
491
-
- stdio: Communication over standard input/output
492
-
- Streamable HTTP: HTTP POST/GET with SSE for server streaming
493
-
- Custom transports: Implementation-specific transports
495
-
Messages may be sent individually or as part of a JSON-RPC batch.
193
+
(** JSONRPC message types *)
module JSONRPCMessage : sig
498
-
(** Notification represents a JSON-RPC notification (one-way message without a response).
500
-
Notifications are used for events that don't require a response, such as:
501
-
- The 'initialized' notification completing initialization
502
-
- Resource change notifications
503
-
- Progress updates for long-running operations
504
-
- List changed notifications for tools, resources, and prompts
506
-
In JSON-RPC, notifications are identified by the absence of an 'id' field:
510
-
"method": "notifications/resources/updated",
512
-
"uri": "file:///project/src/main.rs"
519
-
(** Method for the notification, using the Method.t type to ensure type safety.
520
-
Examples: Method.Initialized, Method.ResourcesUpdated *)
522
-
(** Optional parameters for the notification as arbitrary JSON.
523
-
The structure depends on the specific notification method. *)
526
-
(** Request represents a JSON-RPC request that expects a response.
528
-
Requests are used for operations that require a response, such as:
530
-
- Listing resources, tools, or prompts
531
-
- Reading resources
535
-
In JSON-RPC, requests include an 'id' field that correlates with the response:
540
-
"method": "resources/read",
542
-
"uri": "file:///project/src/main.rs"
549
-
(** Unique identifier for the request, which will be echoed in the response.
550
-
This can be a string or integer and should be unique within the session. *)
552
-
(** Method for the request, using the Method.t type to ensure type safety.
553
-
Examples: Method.Initialize, Method.ResourcesRead, Method.ToolsCall *)
555
-
(** Optional parameters for the request as arbitrary JSON.
556
-
The structure depends on the specific request method. *)
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. *)
563
-
(** Response represents a successful JSON-RPC response to a request.
565
-
Responses are sent in reply to requests and contain the successful result.
566
-
Each response must include the same ID as its corresponding request.
568
-
In JSON-RPC, responses include the 'id' field matching the request:
576
-
"uri": "file:///project/src/main.rs",
577
-
"mimeType": "text/x-rust",
578
-
"text": "fn main() {\n println!(\"Hello world!\");\n}"
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. *)
595
-
(** 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.
600
-
MCP defines several standard error codes:
601
-
- Standard JSON-RPC errors (-32700 to -32603)
602
-
- MCP-specific errors (-32002 for resource not found, etc.)
604
-
In JSON-RPC, errors follow this structure:
611
-
"message": "Resource not found",
613
-
"uri": "file:///nonexistent.txt"
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. *)
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. *)
| 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
val yojson_of_request : request -> Json.t
662
-
(** Convert response to Yojson representation
663
-
@param response The response to convert
664
-
@return JSON representation of the response
val yojson_of_response : response -> Json.t
668
-
(** Convert error to Yojson representation
669
-
@param error The error to convert
670
-
@return JSON representation of the error
val yojson_of_error : error -> Json.t
674
-
(** Convert any message to Yojson representation
675
-
@param message The message to convert
676
-
@return JSON representation of the message
val yojson_of_t : t -> Json.t
680
-
(** Convert Yojson representation to notification
681
-
@param json JSON representation of a notification
682
-
@return Parsed notification object
683
-
@raise Parse error if the JSON is not a valid notification
val notification_of_yojson : Json.t -> notification
687
-
(** Convert Yojson representation to request
688
-
@param json JSON representation of a request
689
-
@return Parsed request object
690
-
@raise Parse error if the JSON is not a valid request
val request_of_yojson : Json.t -> request
694
-
(** Convert Yojson representation to response
695
-
@param json JSON representation of a response
696
-
@return Parsed response object
697
-
@raise Parse error if the JSON is not a valid response
val response_of_yojson : Json.t -> response
701
-
(** Convert Yojson representation to error
702
-
@param json JSON representation of an error
703
-
@return Parsed error object
704
-
@raise Parse error if the JSON is not a valid error
val error_of_yojson : Json.t -> error
708
-
(** Convert Yojson representation to any message
709
-
@param json JSON representation of any message type
710
-
@return Parsed message object
711
-
@raise Parse error if the JSON is not a valid message
val t_of_yojson : Json.t -> t
715
-
(** Create a new notification message
716
-
@param params Optional parameters for the notification
717
-
@param meth Method name for the notification
718
-
@return A new JSON-RPC notification message
720
-
val create_notification : ?params:Json.t option -> meth:Method.t -> unit -> t
722
-
(** Create a new request message
723
-
@param params Optional parameters for the request
724
-
@param progress_token Optional progress token for long-running operations
725
-
@param id Unique identifier for the request
726
-
@param meth 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 -> meth:Method.t -> unit -> t
731
-
(** Create a new response message
732
-
@param id ID matching the original request
733
-
@param result Result of the successful request
734
-
@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
738
-
(** Create a new error message
739
-
@param id ID matching the original request
740
-
@param code Error code indicating the type of error
741
-
@param message Human-readable error message
742
-
@param data Optional additional error data
743
-
@return A new JSON-RPC error message
val create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> t
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.
243
+
(** Initialize request/response *)
(** 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. *)
248
+
capabilities: Json.t; (** ClientCapabilities *)
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. *)
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" *)
783
-
include Json.Jsonable.S with type t := t
785
-
(** Create a new initialization request
786
-
@param capabilities Client capabilities that define supported optional features
787
-
@param client_info Client implementation details
788
-
@param protocol_version MCP protocol version supported by the client
789
-
@return A new initialization request
253
+
val yojson_of_t : t -> Json.t
254
+
val t_of_yojson : Json.t -> t
val create : capabilities:Json.t -> client_info:Implementation.t -> protocol_version:string -> t
793
-
(** Convert to JSON-RPC message
794
-
@param id Unique request identifier
795
-
@param t Initialization request
796
-
@return JSON-RPC message containing the initialization request
val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t
803
-
(** InitializeResult is the server's response to an initialization request,
804
-
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 *)
263
+
capabilities: Json.t; (** ServerCapabilities *)
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. *)
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. *)
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. *)
831
-
(** Optional additional metadata as arbitrary JSON. Can contain server-specific
832
-
information not covered by the standard fields. *)
834
-
include Json.Jsonable.S with type t := t
836
-
(** Create a new initialization result
837
-
@param capabilities Server capabilities that define supported optional features
838
-
@param server_info Server implementation details
839
-
@param protocol_version MCP protocol version supported by the server
840
-
@param instructions Optional instructions for using the server
841
-
@param meta Optional additional metadata
842
-
@return A new initialization result
270
+
val yojson_of_t : t -> Json.t
271
+
val t_of_yojson : Json.t -> t
val create : capabilities:Json.t -> server_info:Implementation.t -> protocol_version:string -> ?instructions:string -> ?meta:Json.t -> unit -> t
846
-
(** Convert to JSON-RPC message
847
-
@param id ID matching the original request
848
-
@param t Initialization result
849
-
@return JSON-RPC message containing the initialization result
val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t
855
-
(** Initialized notification - Completes the initialization phase of the MCP lifecycle *)
278
+
(** Initialized notification *)
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. *)
867
-
(** Optional additional metadata as arbitrary JSON. Can contain client-specific
868
-
information not covered by the standard fields. *)
870
-
include Json.Jsonable.S with type t := t
872
-
(** Create a new initialized notification
873
-
@param meta Optional additional metadata
874
-
@return A new initialized notification
285
+
val yojson_of_t : t -> Json.t
286
+
val t_of_yojson : Json.t -> t
val create : ?meta:Json.t -> unit -> t
878
-
(** Convert to JSON-RPC message
879
-
@param t Initialized notification
880
-
@return JSON-RPC message containing the initialized notification
val to_jsonrpc : t -> JSONRPCMessage.t
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:
893
-
- A message with "method" but no "id" is a notification
894
-
- A message with "method" and "id" is a request
895
-
- A message with "id" and "result" is a response
896
-
- A message with "id" and "error" is an error
898
-
@param json The JSON message to parse, typically received from the transport layer
899
-
@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
293
+
(** Tool definition *)
297
+
description: string option;
298
+
input_schema: Json.t;
904
-
(** 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.
909
-
Common notifications in MCP include:
910
-
- "notifications/initialized" - Sent after initialization
911
-
- "notifications/progress" - Updates on long-running operations
912
-
- "notifications/resources/updated" - Resource content changed
913
-
- "notifications/prompts/list_changed" - Available prompts changed
914
-
- "notifications/tools/list_changed" - Available tools changed
916
-
@param params Optional parameters for the notification as a JSON value
917
-
@param meth Method type for the notification
918
-
@return A new JSON-RPC notification message
920
-
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
922
-
(** Create a new request message
924
-
Requests are messages that expect a corresponding response.
925
-
This is a convenience wrapper around JSONRPCMessage.create_request.
927
-
Common requests in MCP include:
928
-
- "initialize" - Start the MCP lifecycle
929
-
- "resources/list" - Discover available resources
930
-
- "resources/read" - Retrieve resource contents
931
-
- "tools/list" - Discover available tools
932
-
- "tools/call" - Invoke a tool
933
-
- "prompts/list" - Discover available prompts
934
-
- "prompts/get" - Retrieve a prompt template
936
-
@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 meth Method type for the request
941
-
@return A new JSON-RPC request message
943
-
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
945
-
(** 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.
954
-
@param id ID matching the original request
955
-
@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
317
+
(** Resource definition *)
318
+
module Resource : sig
322
+
description: string option;
323
+
mime_type: string option;
325
+
annotations: Annotated.annotation option;
960
-
(** 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:
966
-
- -32700: Parse error (invalid JSON)
967
-
- -32600: Invalid request (malformed JSON-RPC)
968
-
- -32601: Method not found
969
-
- -32602: Invalid parameters
970
-
- -32603: Internal error
971
-
- -32002: Resource not found (MCP-specific)
972
-
- -32001: Authentication required (MCP-specific)
974
-
@param id ID matching the original request
975
-
@param code Error code indicating the type of error
976
-
@param message Human-readable error message describing the issue
977
-
@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
328
+
val yojson_of_t : t -> Json.t
329
+
val t_of_yojson : Json.t -> t
982
-
(** Create a new text content object
983
-
@param text The text content
984
-
@return A content value with the text
986
-
val make_text_content : string -> content
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;
988
-
(** Create a new image content object
989
-
@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
342
+
val yojson_of_t : t -> Json.t
343
+
val t_of_yojson : Json.t -> t
995
-
(** Create a new audio content object
996
-
@param data Base64-encoded audio data
997
-
@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
346
+
(** Resource Reference *)
347
+
module ResourceReference : sig
1002
-
(** Create a new text resource content object
1003
-
@param uri URI that uniquely identifies the resource
1004
-
@param text The text content of the resource
1005
-
@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
352
+
val yojson_of_t : t -> Json.t
353
+
val t_of_yojson : Json.t -> t
1010
-
(** Create a new binary resource content object
1011
-
@param uri URI that uniquely identifies the resource
1012
-
@param blob Base64-encoded binary data
1013
-
@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
356
+
(** Prompt Reference *)
357
+
module PromptReference : sig
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
