···
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
-
(** Extract a string field from JSON object or raise an error
29
-
@param fields Assoc list of fields from JSON object
30
-
@param name Field name to extract
31
-
@param json Original JSON for error context
32
-
@return The string value of the field
33
-
@raise Json.Of_json if the field is missing or not a string
35
-
val get_string_field : (string * Json.t) list -> string -> Json.t -> string
37
-
(** Extract an optional string field from JSON object
38
-
@param fields Assoc list of fields from JSON object
39
-
@param name Field name to extract
40
-
@return Some string if present and a string, None if missing
41
-
@raise Json.Of_json if the field exists but is not a string
43
-
val get_optional_string_field : (string * Json.t) list -> string -> string option
45
-
(** Extract an int field from JSON object or raise an error
46
-
@param fields Assoc list of fields from JSON object
47
-
@param name Field name to extract
48
-
@param json Original JSON for error context
49
-
@return The int value of the field
50
-
@raise Json.Of_json if the field is missing or not an int
52
-
val get_int_field : (string * Json.t) list -> string -> Json.t -> int
54
-
(** Extract a float field from JSON object or raise an error
55
-
@param fields Assoc list of fields from JSON object
56
-
@param name Field name to extract
57
-
@param json Original JSON for error context
58
-
@return The float value of the field
59
-
@raise Json.Of_json if the field is missing or not a float
61
-
val get_float_field : (string * Json.t) list -> string -> Json.t -> float
63
-
(** Extract a boolean field from JSON object or raise an error
64
-
@param fields Assoc list of fields from JSON object
65
-
@param name Field name to extract
66
-
@param json Original JSON for error context
67
-
@return The boolean value of the field
68
-
@raise Json.Of_json if the field is missing or not a boolean
70
-
val get_bool_field : (string * Json.t) list -> string -> Json.t -> bool
72
-
(** Extract an object field from JSON object or raise an error
73
-
@param fields Assoc list of fields from JSON object
74
-
@param name Field name to extract
75
-
@param json Original JSON for error context
76
-
@return The object as an assoc list
77
-
@raise Json.Of_json if the field is missing or not an object
79
-
val get_object_field : (string * Json.t) list -> string -> Json.t -> (string * Json.t) list
81
-
(** Extract a list field from JSON object or raise an error
82
-
@param fields Assoc list of fields from JSON object
83
-
@param name Field name to extract
84
-
@param json Original JSON for error context
85
-
@return The list items
86
-
@raise Json.Of_json if the field is missing or not a list
88
-
val get_list_field : (string * Json.t) list -> string -> Json.t -> Json.t list
90
-
(** Verify a specific string value in a field
91
-
@param fields Assoc list of fields from JSON object
92
-
@param name Field name to check
93
-
@param expected_value The expected string value
94
-
@param json Original JSON for error context
95
-
@raise Json.Of_json if the field is missing or not equal to expected_value
97
-
val verify_string_field : (string * Json.t) list -> string -> string -> Json.t -> unit
100
-
(** Error codes for JSON-RPC *)
5
+
(** Standard error codes *)
102
-
(** Standard JSON-RPC error codes with MCP-specific additions *)
104
-
| ParseError (** -32700 - Invalid JSON *)
105
-
| InvalidRequest (** -32600 - Invalid JSON-RPC request *)
106
-
| MethodNotFound (** -32601 - Method not available *)
107
-
| InvalidParams (** -32602 - Invalid method parameters *)
108
-
| InternalError (** -32603 - Internal JSON-RPC error *)
109
-
| ResourceNotFound (** -32002 - Custom MCP error: requested resource not found *)
110
-
| AuthRequired (** -32001 - Custom MCP error: authentication required *)
111
-
| CustomError of int (** For any other error codes *)
113
-
(** Convert the error code to its integer representation
114
-
@param code The error code to convert
115
-
@return The integer error code as defined in the JSON-RPC spec
117
-
val to_int : t -> int
119
-
(** Get error message for standard error codes
120
-
@param code The error code to get message for
121
-
@return A standard message for the error code
123
-
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
126
-
(** MCP Protocol Methods - Algebraic data type representing all MCP methods *)
127
-
module Method : sig
128
-
(** Method type representing all MCP protocol methods *)
130
-
(* Initialization and lifecycle methods *)
131
-
| Initialize (** Start the MCP lifecycle *)
132
-
| Initialized (** Signal readiness after initialization *)
134
-
(* Resource methods *)
135
-
| ResourcesList (** Discover available resources *)
136
-
| ResourcesRead (** Retrieve resource contents *)
137
-
| ResourcesTemplatesList (** List available resource templates *)
138
-
| ResourcesSubscribe (** Subscribe to resource changes *)
139
-
| ResourcesListChanged (** Resource list has changed *)
140
-
| ResourcesUpdated (** Resource has been updated *)
143
-
| ToolsList (** Discover available tools *)
144
-
| ToolsCall (** Invoke a tool *)
145
-
| ToolsListChanged (** Tool list has changed *)
147
-
(* Prompt methods *)
148
-
| PromptsList (** Discover available prompts *)
149
-
| PromptsGet (** Retrieve a prompt template with arguments *)
150
-
| PromptsListChanged (** Prompt list has changed *)
152
-
(* Progress notifications *)
153
-
| Progress (** Progress update for long-running operations *)
155
-
(** Convert method type to string representation
156
-
@param meth The method to convert
157
-
@return The string representation of the method (e.g., "initialize", "resources/list")
159
-
val to_string : t -> string
161
-
(** Convert string to method type
162
-
@param s The string representation of the method
163
-
@return The corresponding method type
164
-
@raise Failure if the string is not a valid MCP method
166
-
val of_string : string -> t
(** Roles for conversation participants *)
174
-
(** Role represents conversation participants in MCP messages.
175
-
Roles can be either 'user' or 'assistant', determining the
176
-
source of each message in a conversation. *)
type t = [ `User | `Assistant ]
178
-
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
183
-
(** Progress tokens identify long-running operations and enable
184
-
servers to provide progress updates to clients. This is used
185
-
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
192
-
(** Request IDs uniquely identify JSON-RPC requests, allowing responses
193
-
to be correlated with their originating requests. They can be either
194
-
string or integer values. *)
type t = [ `String of string | `Int of int ]
include Json.Jsonable.S with type t := t
(** Cursors for pagination *)
201
-
(** Cursors enable pagination in list operations for resources, tools, and prompts.
202
-
When a server has more items than can be returned in a single response,
203
-
it provides a cursor for the client to retrieve subsequent pages. *)
205
-
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 *)
210
-
(** Annotations provide metadata for content objects, allowing
211
-
role-specific targeting and priority settings. *)
annotations: annotation option;
audience: Role.t list option;
217
-
(** Optional list of roles that should receive this content *)
219
-
(** Optional priority value for this content *)
221
-
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
224
-
(** Text content - Core textual message representation in MCP *)
226
-
(** TextContent represents plain text messages in MCP conversations.
227
-
This is the most common content type used for natural language interactions
228
-
between users and assistants. Text content is used in prompts, tool results,
229
-
and model responses.
231
-
In JSON-RPC, this is represented as:
235
-
"text": "The text content of the message"
239
-
For security, implementations must sanitize text content to prevent
240
-
injection attacks or unauthorized access to resources. *)
243
-
(** The actual text content as a UTF-8 encoded string *)
annotations: Annotated.annotation option;
245
-
(** Optional annotations for audience targeting and priority.
246
-
Annotations can restrict content visibility to specific roles (user/assistant)
247
-
and indicate relative importance of different content elements. *)
249
-
include Json.Jsonable.S with type t := t
76
+
val yojson_of_t : t -> Json.t
77
+
val t_of_yojson : Json.t -> t
252
-
(** Image content - Visual data representation in MCP *)
80
+
(** Image content *)
module ImageContent : sig
254
-
(** ImageContent enables including visual information in MCP messages,
255
-
supporting multimodal interactions where visual context is important.
257
-
Images can be used in several scenarios:
258
-
- As user inputs for visual understanding tasks
259
-
- As context for generating descriptions or analysis
260
-
- As outputs from tools that generate visualizations
261
-
- As part of prompt templates with visual components
263
-
In JSON-RPC, this is represented as:
267
-
"data": "base64-encoded-image-data",
268
-
"mimeType": "image/png"
272
-
The data MUST be base64-encoded to ensure safe transmission in JSON.
273
-
Common mime types include image/png, image/jpeg, image/gif, and image/svg+xml. *)
276
-
(** Base64-encoded image data. All binary image data must be encoded using
277
-
standard base64 encoding (RFC 4648) to safely transmit within JSON. *)
279
-
(** MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/svg+xml").
280
-
This field is required and must accurately represent the image format to ensure
281
-
proper handling by clients. *)
annotations: Annotated.annotation option;
283
-
(** Optional annotations for audience targeting and priority.
284
-
Annotations can restrict content visibility to specific roles (user/assistant)
285
-
and indicate relative importance of different content elements. *)
287
-
include Json.Jsonable.S with type t := t
88
+
val yojson_of_t : t -> Json.t
89
+
val t_of_yojson : Json.t -> t
290
-
(** Audio content - Sound data representation in MCP *)
92
+
(** Audio content *)
module AudioContent : sig
292
-
(** AudioContent enables including audio information in MCP messages,
293
-
supporting multimodal interactions where audio context is important.
295
-
Audio can be used in several scenarios:
296
-
- As user inputs for speech recognition or audio analysis
297
-
- As context for transcription or sound classification tasks
298
-
- As outputs from tools that generate audio samples
299
-
- As part of prompt templates with audio components
301
-
In JSON-RPC, this is represented as:
305
-
"data": "base64-encoded-audio-data",
306
-
"mimeType": "audio/wav"
310
-
The data MUST be base64-encoded to ensure safe transmission in JSON.
311
-
Common mime types include audio/wav, audio/mp3, audio/ogg, and audio/mpeg. *)
314
-
(** Base64-encoded audio data. All binary audio data must be encoded using
315
-
standard base64 encoding (RFC 4648) to safely transmit within JSON. *)
317
-
(** MIME type of the audio (e.g., "audio/wav", "audio/mp3", "audio/ogg", "audio/mpeg").
318
-
This field is required and must accurately represent the audio format to ensure
319
-
proper handling by clients. *)
annotations: Annotated.annotation option;
321
-
(** Optional annotations for audience targeting and priority.
322
-
Annotations can restrict content visibility to specific roles (user/assistant)
323
-
and indicate relative importance of different content elements. *)
325
-
include Json.Jsonable.S with type t := t
100
+
val yojson_of_t : t -> Json.t
101
+
val t_of_yojson : Json.t -> t
328
-
(** Base resource contents - Core resource metadata in MCP *)
104
+
(** Base resource contents *)
module ResourceContents : sig
330
-
(** ResourceContents provides basic metadata for resources in MCP.
332
-
Resources are server-exposed data that provides context to language models,
333
-
such as files, database schemas, or application-specific information.
334
-
Each resource is uniquely identified by a URI.
336
-
The MCP resources architecture is designed to be application-driven, with
337
-
host applications determining how to incorporate context based on their needs.
339
-
In the protocol, resources are discovered via the 'resources/list' endpoint
340
-
and retrieved via the 'resources/read' endpoint. Servers that support resources
341
-
must declare the 'resources' capability during initialization. *)
344
-
(** URI that uniquely identifies the resource.
346
-
Resources use standard URI schemes including:
347
-
- file:// - For filesystem-like resources
348
-
- https:// - For web-accessible resources
349
-
- git:// - For version control integration
351
-
The URI serves as a stable identifier even if the underlying content changes. *)
mime_type: string option;
353
-
(** Optional MIME type of the resource content to aid in client rendering.
354
-
Common MIME types include text/plain, application/json, image/png, etc.
355
-
For directories, the XDG MIME type inode/directory may be used. *)
357
-
include Json.Jsonable.S with type t := t
111
+
val yojson_of_t : t -> Json.t
112
+
val t_of_yojson : Json.t -> t
360
-
(** Text resource contents - Textual resource data *)
115
+
(** Text resource contents *)
module TextResourceContents : sig
362
-
(** TextResourceContents represents a text-based resource in MCP.
364
-
Text resources are used for sharing code snippets, documentation, logs,
365
-
configuration files, and other textual information with language models.
367
-
The server handles access control and security, ensuring that only
368
-
authorized resources are shared with clients.
370
-
In JSON-RPC, this is represented as:
373
-
"uri": "file:///example.txt",
374
-
"mimeType": "text/plain",
375
-
"text": "Resource content"
381
-
(** URI that uniquely identifies the resource.
382
-
This URI can be referenced in subsequent requests to fetch updates. *)
384
-
(** The actual text content of the resource as a UTF-8 encoded string.
385
-
This may be sanitized by the server to remove sensitive information. *)
mime_type: string option;
387
-
(** Optional MIME type of the text content to aid in client rendering.
388
-
Common text MIME types include: text/plain, text/markdown, text/x-python,
389
-
application/json, text/html, text/csv, etc. *)
391
-
include Json.Jsonable.S with type t := t
123
+
val yojson_of_t : t -> Json.t
124
+
val t_of_yojson : Json.t -> t
394
-
(** Binary resource contents - Binary resource data *)
127
+
(** Binary resource contents *)
module BlobResourceContents : sig
396
-
(** BlobResourceContents represents a binary resource in MCP.
398
-
Binary resources allow sharing non-textual data like images, audio files,
399
-
PDFs, and other binary formats with language models that support processing
402
-
In JSON-RPC, this is represented as:
405
-
"uri": "file:///example.png",
406
-
"mimeType": "image/png",
407
-
"blob": "base64-encoded-data"
411
-
Binary data MUST be properly base64-encoded to ensure safe transmission
412
-
in JSON payloads. *)
415
-
(** URI that uniquely identifies the resource.
416
-
This URI can be referenced in subsequent requests to fetch updates. *)
418
-
(** Base64-encoded binary data using standard base64 encoding (RFC 4648).
419
-
This encoding ensures that binary data can be safely transmitted in JSON. *)
mime_type: string option;
421
-
(** Optional MIME type of the binary content to aid in client rendering.
422
-
Common binary MIME types include: image/png, image/jpeg, application/pdf,
423
-
audio/wav, video/mp4, application/octet-stream, etc. *)
425
-
include Json.Jsonable.S with type t := t
135
+
val yojson_of_t : t -> Json.t
136
+
val t_of_yojson : Json.t -> t
428
-
(** Embedded resource - Resource included directly in messages *)
139
+
(** Embedded resource *)
module EmbeddedResource : sig
430
-
(** EmbeddedResource allows referencing server-side resources directly
431
-
in MCP messages, enabling seamless incorporation of managed content.
433
-
Embedded resources can be included in:
434
-
- Tool results to provide rich context
435
-
- Prompt templates to include reference materials
436
-
- Messages to provide additional context to language models
438
-
In contrast to direct content (TextContent, ImageContent, AudioContent),
439
-
embedded resources have the advantage of being persistently stored on the server
440
-
with a stable URI, allowing later retrieval and updates through the resources API.
442
-
For example, a tool might return an embedded resource containing a chart or
443
-
a large dataset that the client can later reference or update. *)
resource: [ `Text of TextResourceContents.t | `Blob of BlobResourceContents.t ];
446
-
(** The resource content, either as text or binary blob. *)
annotations: Annotated.annotation option;
448
-
(** Optional annotations for audience targeting and priority.
449
-
Annotations can restrict resource visibility to specific roles (user/assistant)
450
-
and indicate relative importance of different content elements. *)
452
-
include Json.Jsonable.S with type t := t
146
+
val yojson_of_t : t -> Json.t
147
+
val t_of_yojson : Json.t -> t
455
-
(** Content type used in messages - Unified multimodal content representation in MCP *)
150
+
(** Content type used in messages *)
457
-
| Text of TextContent.t (** Text content for natural language messages. This is the most common content type for user-assistant interactions. *)
458
-
| Image of ImageContent.t (** Image content for visual data. Used for sharing visual context in multimodal conversations. *)
459
-
| Audio of AudioContent.t (** Audio content for audio data. Used for sharing audio context in multimodal conversations. *)
460
-
| 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
462
-
(** Convert content to Yojson representation
463
-
@param content The content to convert
464
-
@return JSON representation of the content
val yojson_of_content : content -> Json.t
468
-
(** Convert Yojson representation to content
469
-
@param json JSON representation of content
470
-
@return Parsed content object
val content_of_yojson : Json.t -> content
474
-
(** Message for prompts - Template messages in the MCP prompts feature *)
160
+
(** Message for prompts *)
module PromptMessage : sig
476
-
(** PromptMessage represents a message in an MCP prompt template,
477
-
containing a role and content which can be customized with arguments.
479
-
Prompt messages are part of prompt templates exposed by servers through
480
-
the prompts/get endpoint. They define structured conversation templates
481
-
that can be instantiated with user-provided arguments.
483
-
The prompt feature is designed to be user-controlled, with prompts typically
484
-
exposed through UI elements like slash commands that users can explicitly select.
486
-
In JSON-RPC, prompt messages are represented as:
492
-
"text": "Please review this code: ${code}"
497
-
Where $code would be replaced with a user-provided argument. *)
500
-
(** The role of the message sender (user or assistant).
501
-
Prompt templates typically alternate between user and assistant messages
502
-
to create a conversation structure. *)
504
-
(** The message content, which can be text, image, audio, or resource.
505
-
This unified content type supports rich multimodal prompts. *)
507
-
include Json.Jsonable.S with type t := t
167
+
val yojson_of_t : t -> Json.t
168
+
val t_of_yojson : Json.t -> t
510
-
(** Message for sampling - Messages used in LLM completion requests *)
171
+
(** Message for sampling *)
module SamplingMessage : sig
512
-
(** SamplingMessage represents a message in an MCP sampling request,
513
-
used for AI model generation based on a prompt.
515
-
The sampling feature allows clients to expose language model capabilities
516
-
to servers, enabling servers to request completions from the client's LLM.
517
-
This is effectively the reverse of the normal MCP flow, with the server
518
-
requesting generative capabilities from the client.
520
-
Sampling messages differ from prompt messages in that they don't support
521
-
embedded resources, as they represent the actual context window being
522
-
sent to the LLM rather than template definitions.
524
-
Clients that support sampling must declare the 'sampling' capability
525
-
during initialization. *)
528
-
(** The role of the message sender (user or assistant).
529
-
Typically, a sampling request will contain multiple messages
530
-
representing a conversation history, with alternating roles. *)
531
-
content: [ `Text of TextContent.t | `Image of ImageContent.t | `Audio of AudioContent.t ];
532
-
(** The message content, restricted to text, image, or audio (no resources).
533
-
Resources are not included since sampling messages represent the
534
-
actual context window for the LLM, not template definitions. *)
175
+
content: [ `Text of TextContent.t | `Image of ImageContent.t ];
536
-
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
541
-
(** Implementation provides metadata about client and server implementations,
542
-
used during the initialization phase to identify each party. *)
545
-
(** Name of the implementation *)
547
-
(** Version of the implementation *)
549
-
include Json.Jsonable.S with type t := t
189
+
val yojson_of_t : t -> Json.t
190
+
val t_of_yojson : Json.t -> t
552
-
(** JSONRPC message types - Core message protocol for MCP
554
-
MCP uses JSON-RPC 2.0 as its underlying messaging protocol.
555
-
All MCP messages are encoded as JSON-RPC 2.0 messages with UTF-8 encoding,
556
-
following the standard JSON-RPC message formats with some MCP-specific extensions.
558
-
MCP defines four message types:
559
-
1. Notifications: One-way messages that don't expect a response
560
-
2. Requests: Messages that expect a corresponding response
561
-
3. Responses: Replies to requests with successful results
562
-
4. Errors: Replies to requests with error information
564
-
These can be transported over multiple transport mechanisms:
565
-
- stdio: Communication over standard input/output
566
-
- Streamable HTTP: HTTP POST/GET with SSE for server streaming
567
-
- Custom transports: Implementation-specific transports
569
-
Messages may be sent individually or as part of a JSON-RPC batch.
193
+
(** JSONRPC message types *)
module JSONRPCMessage : sig
572
-
(** Notification represents a JSON-RPC notification (one-way message without a response).
574
-
Notifications are used for events that don't require a response, such as:
575
-
- The 'initialized' notification completing initialization
576
-
- Resource change notifications
577
-
- Progress updates for long-running operations
578
-
- List changed notifications for tools, resources, and prompts
580
-
In JSON-RPC, notifications are identified by the absence of an 'id' field:
584
-
"method": "notifications/resources/updated",
586
-
"uri": "file:///project/src/main.rs"
593
-
(** Method for the notification, using the Method.t type to ensure type safety.
594
-
Examples: Method.Initialized, Method.ResourcesUpdated *)
596
-
(** Optional parameters for the notification as arbitrary JSON.
597
-
The structure depends on the specific notification method. *)
600
-
(** Request represents a JSON-RPC request that expects a response.
602
-
Requests are used for operations that require a response, such as:
604
-
- Listing resources, tools, or prompts
605
-
- Reading resources
609
-
In JSON-RPC, requests include an 'id' field that correlates with the response:
614
-
"method": "resources/read",
616
-
"uri": "file:///project/src/main.rs"
623
-
(** Unique identifier for the request, which will be echoed in the response.
624
-
This can be a string or integer and should be unique within the session. *)
626
-
(** Method for the request, using the Method.t type to ensure type safety.
627
-
Examples: Method.Initialize, Method.ResourcesRead, Method.ToolsCall *)
629
-
(** Optional parameters for the request as arbitrary JSON.
630
-
The structure depends on the specific request method. *)
progress_token: ProgressToken.t option;
632
-
(** Optional progress token for long-running operations.
633
-
If provided, the server can send progress notifications using this token
634
-
to inform the client about the operation's status. *)
637
-
(** Response represents a successful JSON-RPC response to a request.
639
-
Responses are sent in reply to requests and contain the successful result.
640
-
Each response must include the same ID as its corresponding request.
642
-
In JSON-RPC, responses include the 'id' field matching the request:
650
-
"uri": "file:///project/src/main.rs",
651
-
"mimeType": "text/x-rust",
652
-
"text": "fn main() {\n println!(\"Hello world!\");\n}"
661
-
(** ID matching the original request, allowing clients to correlate
662
-
responses with their originating requests, especially important
663
-
when multiple requests are in flight. *)
665
-
(** Result of the successful request as arbitrary JSON.
666
-
The structure depends on the specific request method that was called. *)
669
-
(** Error represents an error response to a JSON-RPC request.
671
-
Errors are sent in reply to requests when processing fails.
672
-
Each error must include the same ID as its corresponding request.
674
-
MCP defines several standard error codes:
675
-
- Standard JSON-RPC errors (-32700 to -32603)
676
-
- MCP-specific errors (-32002 for resource not found, etc.)
678
-
In JSON-RPC, errors follow this structure:
685
-
"message": "Resource not found",
687
-
"uri": "file:///nonexistent.txt"
695
-
(** ID matching the original request, allowing clients to correlate
696
-
errors with their originating requests. *)
698
-
(** Error code indicating the type of error, following the JSON-RPC standard.
699
-
Common codes include:
700
-
- -32700: Parse error
701
-
- -32600: Invalid request
702
-
- -32601: Method not found
703
-
- -32602: Invalid params
704
-
- -32603: Internal error
705
-
- -32002: Resource not found (MCP-specific)
706
-
- -32001: Authentication required (MCP-specific) *)
708
-
(** Human-readable error message describing the issue.
709
-
This should be concise but informative enough for debugging. *)
711
-
(** Optional additional error data as arbitrary JSON.
712
-
This can provide more context about the error, such as which
713
-
resource wasn't found or which parameter was invalid. *)
716
-
(** Union type for all JSON-RPC message kinds, providing a single type
717
-
that can represent any MCP message. *)
| Notification of notification
724
-
(** Convert notification to Yojson representation
725
-
@param notification The notification to convert
726
-
@return JSON representation of the notification
val yojson_of_notification : notification -> Json.t
730
-
(** Convert request to Yojson representation
731
-
@param request The request to convert
732
-
@return JSON representation of the request
val yojson_of_request : request -> Json.t
736
-
(** Convert response to Yojson representation
737
-
@param response The response to convert
738
-
@return JSON representation of the response
val yojson_of_response : response -> Json.t
742
-
(** Convert error to Yojson representation
743
-
@param error The error to convert
744
-
@return JSON representation of the error
val yojson_of_error : error -> Json.t
748
-
(** Convert any message to Yojson representation
749
-
@param message The message to convert
750
-
@return JSON representation of the message
val yojson_of_t : t -> Json.t
754
-
(** Convert Yojson representation to notification
755
-
@param json JSON representation of a notification
756
-
@return Parsed notification object
757
-
@raise Parse error if the JSON is not a valid notification
val notification_of_yojson : Json.t -> notification
761
-
(** Convert Yojson representation to request
762
-
@param json JSON representation of a request
763
-
@return Parsed request object
764
-
@raise Parse error if the JSON is not a valid request
val request_of_yojson : Json.t -> request
768
-
(** Convert Yojson representation to response
769
-
@param json JSON representation of a response
770
-
@return Parsed response object
771
-
@raise Parse error if the JSON is not a valid response
val response_of_yojson : Json.t -> response
775
-
(** Convert Yojson representation to error
776
-
@param json JSON representation of an error
777
-
@return Parsed error object
778
-
@raise Parse error if the JSON is not a valid error
val error_of_yojson : Json.t -> error
782
-
(** Convert Yojson representation to any message
783
-
@param json JSON representation of any message type
784
-
@return Parsed message object
785
-
@raise Parse error if the JSON is not a valid message
val t_of_yojson : Json.t -> t
789
-
(** Create a new notification message
790
-
@param params Optional parameters for the notification
791
-
@param meth Method name for the notification
792
-
@return A new JSON-RPC notification message
794
-
val create_notification : ?params:Json.t option -> meth:Method.t -> unit -> t
796
-
(** Create a new request message
797
-
@param params Optional parameters for the request
798
-
@param progress_token Optional progress token for long-running operations
799
-
@param id Unique identifier for the request
800
-
@param meth Method name for the request
801
-
@return A new JSON-RPC request message
803
-
val create_request : ?params:Json.t option -> ?progress_token:ProgressToken.t option -> id:RequestId.t -> meth:Method.t -> unit -> t
805
-
(** Create a new response message
806
-
@param id ID matching the original request
807
-
@param result Result of the successful request
808
-
@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
812
-
(** Create a new error message
813
-
@param id ID matching the original request
814
-
@param code Error code indicating the type of error
815
-
@param message Human-readable error message
816
-
@param data Optional additional error data
817
-
@return A new JSON-RPC error message
val create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> t
822
-
(** Initialize request/response - The first phase of the MCP lifecycle
824
-
The initialization phase is the mandatory first interaction between client and server.
825
-
During this phase, the protocol version is negotiated and capabilities are exchanged
826
-
to determine which optional features will be available during the session.
828
-
This follows a strict sequence:
829
-
1. Client sends an InitializeRequest containing its capabilities and protocol version
830
-
2. Server responds with an InitializeResult containing its capabilities and protocol version
831
-
3. Client sends an InitializedNotification to signal it's ready for normal operations
833
-
The Initialize module handles steps 1 and 2 of this process.
243
+
(** Initialize request/response *)
(** Initialize request *)
838
-
(** InitializeRequest starts the MCP lifecycle, negotiating capabilities
839
-
and protocol versions between client and server. This is always the first
840
-
message sent by the client and MUST NOT be part of a JSON-RPC batch.
842
-
The client SHOULD send the latest protocol version it supports. If the server
843
-
does not support this version, it will respond with a version it does support,
844
-
and the client must either use that version or disconnect. *)
846
-
capabilities: Json.t; (** ClientCapabilities that define supported optional features.
847
-
This includes which optional protocol features the client supports,
848
-
such as 'roots' (filesystem access), 'sampling' (LLM generation),
849
-
and any experimental features. *)
248
+
capabilities: Json.t; (** ClientCapabilities *)
client_info: Implementation.t;
851
-
(** Client implementation details (name and version) used for identification
852
-
and debugging. Helps servers understand which client they're working with. *)
protocol_version: string;
854
-
(** MCP protocol version supported by the client, formatted as YYYY-MM-DD
855
-
according to the MCP versioning scheme. Example: "2025-03-26" *)
857
-
include Json.Jsonable.S with type t := t
253
+
val yojson_of_t : t -> Json.t
254
+
val t_of_yojson : Json.t -> t
859
-
(** Create a new initialization request
860
-
@param capabilities Client capabilities that define supported optional features
861
-
@param client_info Client implementation details
862
-
@param protocol_version MCP protocol version supported by the client
863
-
@return A new initialization request
val create : capabilities:Json.t -> client_info:Implementation.t -> protocol_version:string -> t
867
-
(** Convert to JSON-RPC message
868
-
@param id Unique request identifier
869
-
@param t Initialization request
870
-
@return JSON-RPC message containing the initialization request
val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t
877
-
(** InitializeResult is the server's response to an initialization request,
878
-
completing capability negotiation and establishing the protocol version.
880
-
After receiving this message, the client must send an InitializedNotification.
881
-
The server should not send any requests other than pings and logging before
882
-
receiving the initialized notification. *)
884
-
capabilities: Json.t; (** ServerCapabilities that define supported optional features.
885
-
This declares which server features are available, including:
886
-
- prompts: Server provides prompt templates
887
-
- resources: Server provides readable resources
888
-
- tools: Server exposes callable tools
889
-
- logging: Server emits structured log messages
891
-
Each capability may have sub-capabilities like:
892
-
- listChanged: Server will notify when available items change
893
-
- subscribe: Clients can subscribe to individual resources *)
263
+
capabilities: Json.t; (** ServerCapabilities *)
server_info: Implementation.t;
895
-
(** Server implementation details (name and version) used for identification
896
-
and debugging. Helps clients understand which server they're working with. *)
protocol_version: string;
898
-
(** MCP protocol version supported by the server, formatted as YYYY-MM-DD.
899
-
If the server supports the client's requested version, it responds with
900
-
the same version. Otherwise, it responds with a version it does support. *)
instructions: string option;
902
-
(** Optional instructions for using the server. These can provide human-readable
903
-
guidance on how to interact with this specific server implementation. *)
905
-
(** Optional additional metadata as arbitrary JSON. Can contain server-specific
906
-
information not covered by the standard fields. *)
908
-
include Json.Jsonable.S with type t := t
910
-
(** Create a new initialization result
911
-
@param capabilities Server capabilities that define supported optional features
912
-
@param server_info Server implementation details
913
-
@param protocol_version MCP protocol version supported by the server
914
-
@param instructions Optional instructions for using the server
915
-
@param meta Optional additional metadata
916
-
@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
920
-
(** Convert to JSON-RPC message
921
-
@param id ID matching the original request
922
-
@param t Initialization result
923
-
@return JSON-RPC message containing the initialization result
val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t
929
-
(** Initialized notification - Completes the initialization phase of the MCP lifecycle *)
278
+
(** Initialized notification *)
module Notification : sig
932
-
(** InitializedNotification is sent by the client after receiving the initialization
933
-
response, indicating it's ready to begin normal operations. This completes the
934
-
three-step initialization process, after which both client and server can
935
-
freely exchange messages according to the negotiated capabilities.
937
-
Only after this notification has been sent should the client begin normal operations
938
-
like listing resources, calling tools, or requesting prompts. *)
941
-
(** Optional additional metadata as arbitrary JSON. Can contain client-specific
942
-
information not covered by the standard fields. *)
944
-
include Json.Jsonable.S with type t := t
285
+
val yojson_of_t : t -> Json.t
286
+
val t_of_yojson : Json.t -> t
946
-
(** Create a new initialized notification
947
-
@param meta Optional additional metadata
948
-
@return A new initialized notification
val create : ?meta:Json.t -> unit -> t
952
-
(** Convert to JSON-RPC message
953
-
@param t Initialized notification
954
-
@return JSON-RPC message containing the initialized notification
val to_jsonrpc : t -> JSONRPCMessage.t
960
-
(** Parse a JSON message into an MCP message
962
-
This function takes a raw JSON value and parses it into a structured MCP message.
963
-
It's the primary entry point for processing incoming JSON-RPC messages in the MCP protocol.
965
-
The function determines the message type (notification, request, response, or error)
966
-
based on the presence and values of specific fields:
967
-
- A message with "method" but no "id" is a notification
968
-
- A message with "method" and "id" is a request
969
-
- A message with "id" and "result" is a response
970
-
- A message with "id" and "error" is an error
972
-
@param json The JSON message to parse, typically received from the transport layer
973
-
@return The parsed MCP message as a structured JSONRPCMessage.t value
974
-
@raise Parse error if the JSON cannot be parsed as a valid MCP message
976
-
val parse_message : Json.t -> JSONRPCMessage.t
293
+
(** Tool definition *)
297
+
description: string option;
298
+
input_schema: Json.t;
978
-
(** Create a new notification message
980
-
Notifications are one-way messages that don't expect a response.
981
-
This is a convenience wrapper around JSONRPCMessage.create_notification.
983
-
Common notifications in MCP include:
984
-
- "notifications/initialized" - Sent after initialization
985
-
- "notifications/progress" - Updates on long-running operations
986
-
- "notifications/resources/updated" - Resource content changed
987
-
- "notifications/prompts/list_changed" - Available prompts changed
988
-
- "notifications/tools/list_changed" - Available tools changed
990
-
@param params Optional parameters for the notification as a JSON value
991
-
@param meth Method type for the notification
992
-
@return A new JSON-RPC notification message
994
-
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
996
-
(** Create a new request message
998
-
Requests are messages that expect a corresponding response.
999
-
This is a convenience wrapper around JSONRPCMessage.create_request.
1001
-
Common requests in MCP include:
1002
-
- "initialize" - Start the MCP lifecycle
1003
-
- "resources/list" - Discover available resources
1004
-
- "resources/read" - Retrieve resource contents
1005
-
- "tools/list" - Discover available tools
1006
-
- "tools/call" - Invoke a tool
1007
-
- "prompts/list" - Discover available prompts
1008
-
- "prompts/get" - Retrieve a prompt template
1010
-
@param params Optional parameters for the request as a JSON value
1011
-
@param progress_token Optional progress token for long-running operations
1012
-
that can report progress updates
1013
-
@param id Unique identifier for the request, used to correlate with the response
1014
-
@param meth Method type for the request
1015
-
@return A new JSON-RPC request message
1017
-
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
1019
-
(** Create a new response message
1021
-
Responses are sent in reply to requests and contain successful results.
1022
-
This is a convenience wrapper around JSONRPCMessage.create_response.
1024
-
Each response must include the same ID as its corresponding request
1025
-
to allow the client to correlate them, especially when multiple
1026
-
requests are in flight simultaneously.
1028
-
@param id ID matching the original request
1029
-
@param result Result of the successful request as a JSON value
1030
-
@return A new JSON-RPC response message
1032
-
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;
1034
-
(** Create a new error message
1036
-
Errors are sent in reply to requests when processing fails.
1037
-
This is a convenience wrapper around JSONRPCMessage.create_error.
1039
-
MCP uses standard JSON-RPC error codes as well as some protocol-specific codes:
1040
-
- -32700: Parse error (invalid JSON)
1041
-
- -32600: Invalid request (malformed JSON-RPC)
1042
-
- -32601: Method not found
1043
-
- -32602: Invalid parameters
1044
-
- -32603: Internal error
1045
-
- -32002: Resource not found (MCP-specific)
1046
-
- -32001: Authentication required (MCP-specific)
1048
-
@param id ID matching the original request
1049
-
@param code Error code indicating the type of error
1050
-
@param message Human-readable error message describing the issue
1051
-
@param data Optional additional error data providing more context
1052
-
@return A new JSON-RPC error message
1054
-
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;
342
+
val yojson_of_t : t -> Json.t
343
+
val t_of_yojson : Json.t -> t
346
+
(** Resource Reference *)
347
+
module ResourceReference : sig
352
+
val yojson_of_t : t -> Json.t
353
+
val t_of_yojson : Json.t -> t
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;
1056
-
(** Create a new text content object
1057
-
@param text The text content
1058
-
@return A content value with the text
1060
-
val make_text_content : string -> content
404
+
completion: completion;
405
+
meta: Json.t option;
1062
-
(** Create a new image content object
1063
-
@param data Base64-encoded image data
1064
-
@param mime_type MIME type of the image (e.g., "image/png", "image/jpeg")
1065
-
@return A content value with the image
1067
-
val make_image_content : string -> string -> content
408
+
val yojson_of_completion : completion -> Json.t
409
+
val completion_of_yojson : Json.t -> completion
1069
-
(** Create a new audio content object
1070
-
@param data Base64-encoded audio data
1071
-
@param mime_type MIME type of the audio (e.g., "audio/wav", "audio/mp3")
1072
-
@return A content value with the audio
1074
-
val make_audio_content : string -> string -> content
411
+
val yojson_of_t : t -> Json.t
412
+
val t_of_yojson : Json.t -> t
1076
-
(** Create a new text resource content object
1077
-
@param uri URI that uniquely identifies the resource
1078
-
@param text The text content of the resource
1079
-
@param mime_type Optional MIME type of the text content
1080
-
@return A content value with the text resource
1082
-
val make_resource_text_content : string -> string -> string option -> content
414
+
val create : completion:completion -> ?meta:Json.t -> unit -> t
415
+
val to_result : t -> Json.t
1084
-
(** Create a new binary resource content object
1085
-
@param uri URI that uniquely identifies the resource
1086
-
@param blob Base64-encoded binary data
1087
-
@param mime_type Optional MIME type of the binary content
1088
-
@return A content value with the binary resource
1090
-
val make_resource_blob_content : string -> string -> string option -> content
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
