Model Context Protocol in OCaml
anil.recoil.org
1(** MCP - Model Context Protocol implementation *)
2
3open Jsonrpc
4
5(** Standard error codes *)
6module ErrorCode : sig
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
15end
16
17(** Common types *)
18
19(** Roles for conversation participants *)
20module Role : sig
21 type t = [ `User | `Assistant ]
22
23 val to_string : t -> string
24 val of_string : string -> t
25
26 val yojson_of_t : t -> Json.t
27 val t_of_yojson : Json.t -> t
28end
29
30(** Progress tokens for long-running operations *)
31module ProgressToken : sig
32 type t = [ `String of string | `Int of int ]
33
34 include Json.Jsonable.S with type t := t
35end
36
37(** Request IDs *)
38module RequestId : sig
39 type t = [ `String of string | `Int of int ]
40
41 include Json.Jsonable.S with type t := t
42end
43
44(** Cursors for pagination *)
45module Cursor : sig
46 type t = string
47
48 val yojson_of_t : t -> Json.t
49 val t_of_yojson : Json.t -> t
50end
51
52(** Annotations for objects *)
53module Annotated : sig
54 type t = {
55 annotations: annotation option;
56 }
57 and annotation = {
58 audience: Role.t list option;
59 priority: float option;
60 }
61
62 val yojson_of_annotation : annotation -> Json.t
63 val annotation_of_yojson : Json.t -> annotation
64
65 val yojson_of_t : t -> Json.t
66 val t_of_yojson : Json.t -> t
67end
68
69(** Text content *)
70module TextContent : sig
71 type t = {
72 text: string;
73 annotations: Annotated.annotation option;
74 }
75
76 val yojson_of_t : t -> Json.t
77 val t_of_yojson : Json.t -> t
78end
79
80(** Image content *)
81module ImageContent : sig
82 type t = {
83 data: string;
84 mime_type: string;
85 annotations: Annotated.annotation option;
86 }
87
88 val yojson_of_t : t -> Json.t
89 val t_of_yojson : Json.t -> t
90end
91
92(** Audio content *)
93module AudioContent : sig
94 type t = {
95 data: string;
96 mime_type: string;
97 annotations: Annotated.annotation option;
98 }
99
100 val yojson_of_t : t -> Json.t
101 val t_of_yojson : Json.t -> t
102end
103
104(** Base resource contents *)
105module ResourceContents : sig
106 type t = {
107 uri: string;
108 mime_type: string option;
109 }
110
111 val yojson_of_t : t -> Json.t
112 val t_of_yojson : Json.t -> t
113end
114
115(** Text resource contents *)
116module TextResourceContents : sig
117 type t = {
118 uri: string;
119 text: string;
120 mime_type: string option;
121 }
122
123 val yojson_of_t : t -> Json.t
124 val t_of_yojson : Json.t -> t
125end
126
127(** Binary resource contents *)
128module BlobResourceContents : sig
129 type t = {
130 uri: string;
131 blob: string;
132 mime_type: string option;
133 }
134
135 val yojson_of_t : t -> Json.t
136 val t_of_yojson : Json.t -> t
137end
138
139(** Embedded resource *)
140module EmbeddedResource : sig
141 type t = {
142 resource: [ `Text of TextResourceContents.t | `Blob of BlobResourceContents.t ];
143 annotations: Annotated.annotation option;
144 }
145
146 val yojson_of_t : t -> Json.t
147 val t_of_yojson : Json.t -> t
148end
149
150(** Content type used in messages *)
151type content =
152 | Text of TextContent.t
153 | Image of ImageContent.t
154 | Audio of AudioContent.t
155 | Resource of EmbeddedResource.t
156
157val yojson_of_content : content -> Json.t
158val content_of_yojson : Json.t -> content
159
160(** Message for prompts *)
161module PromptMessage : sig
162 type t = {
163 role: Role.t;
164 content: content;
165 }
166
167 val yojson_of_t : t -> Json.t
168 val t_of_yojson : Json.t -> t
169end
170
171(** Message for sampling *)
172module SamplingMessage : sig
173 type t = {
174 role: Role.t;
175 content: [ `Text of TextContent.t | `Image of ImageContent.t ];
176 }
177
178 val yojson_of_t : t -> Json.t
179 val t_of_yojson : Json.t -> t
180end
181
182(** Implementation information *)
183module Implementation : sig
184 type t = {
185 name: string;
186 version: string;
187 }
188
189 val yojson_of_t : t -> Json.t
190 val t_of_yojson : Json.t -> t
191end
192
193(** JSONRPC message types *)
194module JSONRPCMessage : sig
195 type notification = {
196 method_: string;
197 params: Json.t option;
198 }
199
200 type request = {
201 id: RequestId.t;
202 method_: string;
203 params: Json.t option;
204 progress_token: ProgressToken.t option;
205 }
206
207 type response = {
208 id: RequestId.t;
209 result: Json.t;
210 }
211
212 type error = {
213 id: RequestId.t;
214 code: int;
215 message: string;
216 data: Json.t option;
217 }
218
219 type t =
220 | Notification of notification
221 | Request of request
222 | Response of response
223 | Error of error
224
225 val yojson_of_notification : notification -> Json.t
226 val yojson_of_request : request -> Json.t
227 val yojson_of_response : response -> Json.t
228 val yojson_of_error : error -> Json.t
229 val yojson_of_t : t -> Json.t
230
231 val notification_of_yojson : Json.t -> notification
232 val request_of_yojson : Json.t -> request
233 val response_of_yojson : Json.t -> response
234 val error_of_yojson : Json.t -> error
235 val t_of_yojson : Json.t -> t
236
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
239 val create_response : id:RequestId.t -> result:Json.t -> t
240 val create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> t
241end
242
243(** Initialize request/response *)
244module Initialize : sig
245 (** Initialize request *)
246 module Request : sig
247 type t = {
248 capabilities: Json.t; (** ClientCapabilities *)
249 client_info: Implementation.t;
250 protocol_version: string;
251 }
252
253 val yojson_of_t : t -> Json.t
254 val t_of_yojson : Json.t -> t
255
256 val create : capabilities:Json.t -> client_info:Implementation.t -> protocol_version:string -> t
257 val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t
258 end
259
260 (** Initialize result *)
261 module Result : sig
262 type t = {
263 capabilities: Json.t; (** ServerCapabilities *)
264 server_info: Implementation.t;
265 protocol_version: string;
266 instructions: string option;
267 meta: Json.t option;
268 }
269
270 val yojson_of_t : t -> Json.t
271 val t_of_yojson : Json.t -> t
272
273 val create : capabilities:Json.t -> server_info:Implementation.t -> protocol_version:string -> ?instructions:string -> ?meta:Json.t -> unit -> t
274 val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t
275 end
276end
277
278(** Initialized notification *)
279module Initialized : sig
280 module Notification : sig
281 type t = {
282 meta: Json.t option;
283 }
284
285 val yojson_of_t : t -> Json.t
286 val t_of_yojson : Json.t -> t
287
288 val create : ?meta:Json.t -> unit -> t
289 val to_jsonrpc : t -> JSONRPCMessage.t
290 end
291end
292
293(** Tool definition *)
294module Tool : sig
295 type t = {
296 name: string;
297 description: string option;
298 input_schema: Json.t;
299 }
300
301 val yojson_of_t : t -> Json.t
302 val t_of_yojson : Json.t -> t
303end
304
305(** Tool result *)
306module CallToolResult : sig
307 type t = {
308 content: content list;
309 is_error: bool;
310 meta: Json.t option;
311 }
312
313 val yojson_of_t : t -> Json.t
314 val t_of_yojson : Json.t -> t
315end
316
317(** Resource definition *)
318module Resource : sig
319 type t = {
320 name: string;
321 uri: string;
322 description: string option;
323 mime_type: string option;
324 size: int option;
325 annotations: Annotated.annotation option;
326 }
327
328 val yojson_of_t : t -> Json.t
329 val t_of_yojson : Json.t -> t
330end
331
332(** Resource Template definition *)
333module ResourceTemplate : sig
334 type t = {
335 name: string;
336 uri_template: string;
337 description: string option;
338 mime_type: string option;
339 annotations: Annotated.annotation option;
340 }
341
342 val yojson_of_t : t -> Json.t
343 val t_of_yojson : Json.t -> t
344end
345
346(** Resource Reference *)
347module ResourceReference : sig
348 type t = {
349 uri: string;
350 }
351
352 val yojson_of_t : t -> Json.t
353 val t_of_yojson : Json.t -> t
354end
355
356(** Prompt Reference *)
357module PromptReference : sig
358 type t = {
359 name: string;
360 }
361
362 val yojson_of_t : t -> Json.t
363 val t_of_yojson : Json.t -> t
364end
365
366(** Completion support *)
367module Completion : sig
368 module Argument : sig
369 type t = {
370 name: string;
371 value: string;
372 }
373
374 val yojson_of_t : t -> Json.t
375 val t_of_yojson : Json.t -> t
376 end
377
378 module Request : sig
379 type reference = [ `Prompt of PromptReference.t | `Resource of ResourceReference.t ]
380
381 type t = {
382 argument: Argument.t;
383 ref: reference;
384 }
385
386 val yojson_of_t : t -> Json.t
387 val t_of_yojson : Json.t -> t
388
389 val yojson_of_reference : reference -> Json.t
390 val reference_of_yojson : Json.t -> reference
391
392 val create : argument:Argument.t -> ref:reference -> t
393 val to_params : t -> Json.t
394 end
395
396 module Result : sig
397 type completion = {
398 values: string list;
399 has_more: bool option;
400 total: int option;
401 }
402
403 type t = {
404 completion: completion;
405 meta: Json.t option;
406 }
407
408 val yojson_of_completion : completion -> Json.t
409 val completion_of_yojson : Json.t -> completion
410
411 val yojson_of_t : t -> Json.t
412 val t_of_yojson : Json.t -> t
413
414 val create : completion:completion -> ?meta:Json.t -> unit -> t
415 val to_result : t -> Json.t
416 end
417end
418
419(** Parse a JSON message into an MCP message *)
420val parse_message : Json.t -> JSONRPCMessage.t
421
422(** Create JSONRPC message helpers *)
423val create_notification : ?params:Json.t option -> method_:string -> unit -> JSONRPCMessage.t
424val create_request : ?params:Json.t option -> ?progress_token:ProgressToken.t option -> id:RequestId.t -> method_:string -> unit -> JSONRPCMessage.t
425val create_response : id:RequestId.t -> result:Json.t -> JSONRPCMessage.t
426val create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> JSONRPCMessage.t
427
428(** Helper functions for common requests/responses *)
429val create_completion_request : id:RequestId.t -> argument:Completion.Argument.t -> ref:Completion.Request.reference -> JSONRPCMessage.t
430val create_completion_response : id:RequestId.t -> values:string list -> ?has_more:bool option -> ?total:int option -> ?meta:Json.t option -> unit -> JSONRPCMessage.t