Model Context Protocol in OCaml
anil.recoil.org
1(** MCP SDK - Model Context Protocol SDK for OCaml *)
2
3open Mcp
4open Jsonrpc
5open Mcp_message
6
7(** SDK version *)
8val version : string
9
10(** Logging utilities *)
11module Log : sig
12 type level = Debug | Info | Warning | Error
13
14 val string_of_level : level -> string
15
16 val log : level -> string -> unit
17 val debug : string -> unit
18 val info : string -> unit
19 val warning : string -> unit
20 val error : string -> unit
21end
22
23(** Context for tools and resources *)
24module Context : sig
25 type t
26
27 val create : ?request_id:RequestId.t -> ?progress_token:ProgressToken.t -> ?lifespan_context:(string * Json.t) list -> unit -> t
28 val get_context_value : t -> string -> Json.t option
29 val report_progress : t -> float -> float -> JSONRPCMessage.t option
30end
31
32(** Tools for the MCP server *)
33module Tool : sig
34 type handler = Context.t -> Json.t -> (Json.t, string) result
35
36 type t = {
37 name: string;
38 description: string option;
39 input_schema: Json.t;
40 handler: handler;
41 }
42
43 val create : name:string -> ?description:string -> input_schema:Json.t -> handler:handler -> unit -> t
44 val to_json : t -> Json.t
45end
46
47(** Resources for the MCP server *)
48module Resource : sig
49 type handler = Context.t -> string list -> (string, string) result
50
51 type t = {
52 uri_template: string;
53 description: string option;
54 mime_type: string option;
55 handler: handler;
56 }
57
58 val create : uri_template:string -> ?description:string -> ?mime_type:string -> handler:handler -> unit -> t
59 val to_json : t -> Json.t
60end
61
62(** Prompts for the MCP server *)
63module Prompt : sig
64 type argument = {
65 name: string;
66 description: string option;
67 required: bool;
68 }
69
70 type message = {
71 role: Role.t;
72 content: content;
73 }
74
75 type handler = Context.t -> (string * string) list -> (message list, string) result
76
77 type t = {
78 name: string;
79 description: string option;
80 arguments: argument list;
81 handler: handler;
82 }
83
84 val create : name:string -> ?description:string -> ?arguments:argument list -> handler:handler -> unit -> t
85 val create_argument : name:string -> ?description:string -> ?required:bool -> unit -> argument
86 val to_json : t -> Json.t
87end
88
89(** Main server type *)
90type server
91
92val name : server -> string
93val version : server -> string
94val protocol_version : server -> string
95val capabilities : server -> Json.t
96val tools : server -> Tool.t list
97val resources : server -> Resource.t list
98val prompts : server -> Prompt.t list
99
100(** Create a new server *)
101val create_server : name:string -> ?version:string -> ?protocol_version:string -> unit -> server
102
103(** Default capabilities for the server *)
104val default_capabilities : ?with_tools:bool -> ?with_resources:bool -> ?with_prompts:bool -> unit -> Json.t
105
106(** Create and register a tool in one step *)
107val add_tool : server -> name:string -> ?description:string -> ?schema_properties:(string * string * string) list -> ?schema_required:string list -> (Json.t -> Json.t) -> Tool.t
108
109(** Create and register a resource in one step *)
110val add_resource : server -> uri_template:string -> ?description:string -> ?mime_type:string -> (string list -> string) -> Resource.t
111
112(** Create and register a prompt in one step *)
113val add_prompt : server -> name:string -> ?description:string -> ?arguments:(string * string option * bool) list -> ((string * string) list -> Prompt.message list) -> Prompt.t
114
115(** Configure server with default capabilities based on registered components *)
116val configure_server : server -> ?with_tools:bool -> ?with_resources:bool -> ?with_prompts:bool -> unit -> server
117
118(** Content type constructors *)
119val make_text_content : string -> content
120val make_image_content : string -> string -> content
121val make_audio_content : string -> string -> content
122val make_resource_text_content : string -> string -> string option -> content
123val make_resource_blob_content : string -> string -> string option -> content
124
125(** Error types with standard JSON-RPC error codes *)
126type error_code =
127 | ParseError (** -32700 *)
128 | InvalidRequest (** -32600 *)
129 | MethodNotFound (** -32601 *)
130 | InvalidParams (** -32602 *)
131 | InternalError (** -32603 *)
132 | ResourceNotFound (** -32002 Custom code for MCP *)
133 | AuthenticationRequired (** -32001 Custom code for MCP *)
134 | CustomError of int
135
136val error_code_to_int : error_code -> int
137
138(** Tool result handling *)
139type tool_content =
140 | TextContent of string
141 | ImageContent of { data: string; mime_type: string }
142 | AudioContent of { data: string; mime_type: string }
143 | ResourceContent of { uri: string; data: string; is_blob: bool; mime_type: string option }
144
145val create_tool_result : tool_content list -> is_error:bool -> Json.t
146
147(** Create a rich tool result with multiple content types *)
148val create_rich_tool_result :
149 ?text:string option ->
150 ?image:(string * string) option ->
151 ?audio:(string * string) option ->
152 ?resource:(string * string * bool * string option) option ->
153 is_error:bool ->
154 unit -> Json.t
155
156(** Helper functions for creating common objects *)
157val make_tool_schema : (string * string * string) list -> string list -> Json.t
158
159(** MCP Protocol Message Helpers for handling JSON-RPC messages *)
160
161(** Resource message functions *)
162val create_resources_list_request : ?cursor:Cursor.t -> ?id:RequestId.t -> unit -> JSONRPCMessage.t
163val create_resources_list_response : id:RequestId.t -> resources:ResourcesList.Resource.t list -> ?next_cursor:Cursor.t -> unit -> JSONRPCMessage.t
164val create_resources_read_request : uri:string -> ?id:RequestId.t -> unit -> JSONRPCMessage.t
165val create_resources_read_response : id:RequestId.t -> contents:ResourcesRead.ResourceContent.t list -> unit -> JSONRPCMessage.t
166val create_resources_list_changed_notification : unit -> JSONRPCMessage.t
167val create_resources_updated_notification : uri:string -> unit -> JSONRPCMessage.t
168
169(** Tool message functions *)
170val create_tools_list_request : ?cursor:Cursor.t -> ?id:RequestId.t -> unit -> JSONRPCMessage.t
171val create_tools_list_response : id:RequestId.t -> tools:ToolsList.Tool.t list -> ?next_cursor:Cursor.t -> unit -> JSONRPCMessage.t
172val create_tools_call_request : name:string -> arguments:Json.t -> ?id:RequestId.t -> unit -> JSONRPCMessage.t
173val create_tools_call_response : id:RequestId.t -> content:ToolsCall.ToolContent.t list -> is_error:bool -> unit -> JSONRPCMessage.t
174val create_tools_list_changed_notification : unit -> JSONRPCMessage.t
175
176(** Prompt message functions *)
177val create_prompts_list_request : ?cursor:Cursor.t -> ?id:RequestId.t -> unit -> JSONRPCMessage.t
178val create_prompts_list_response : id:RequestId.t -> prompts:PromptsList.Prompt.t list -> ?next_cursor:Cursor.t -> unit -> JSONRPCMessage.t
179val create_prompts_get_request : name:string -> arguments:(string * string) list -> ?id:RequestId.t -> unit -> JSONRPCMessage.t
180val create_prompts_get_response : id:RequestId.t -> ?description:string -> messages:PromptMessage.t list -> unit -> JSONRPCMessage.t
181val create_prompts_list_changed_notification : unit -> JSONRPCMessage.t
182
183(** Progress notification *)
184val create_progress_notification : progress:float -> total:float -> progress_token:ProgressToken.t -> unit -> JSONRPCMessage.t