Model Context Protocol in OCaml
anil.recoil.org
1(** MCP SDK - Model Context Protocol SDK for OCaml *)
2
3open Mcp
4open Jsonrpc
5
6val version : string
7(** SDK version *)
8
9(** Logging utilities *)
10module Log : sig
11 type level = Debug | Info | Warning | Error
12
13 val string_of_level : level -> string
14
15 val logf : level -> ('a, out_channel, unit) format -> 'a
16 (** Format-string based logging functions *)
17
18 val debugf : ('a, out_channel, unit) format -> 'a
19 val infof : ('a, out_channel, unit) format -> 'a
20 val warningf : ('a, out_channel, unit) format -> 'a
21 val errorf : ('a, out_channel, unit) format -> 'a
22
23 val log : level -> string -> unit
24 (** Simple string logging functions (for backward compatibility) *)
25
26 val debug : string -> unit
27 val info : string -> unit
28 val warning : string -> unit
29 val error : string -> unit
30end
31
32(** Context for tools and resources *)
33module Context : sig
34 type t
35
36 val create :
37 ?request_id:RequestId.t ->
38 ?progress_token:ProgressToken.t ->
39 ?lifespan_context:(string * Json.t) list ->
40 unit ->
41 t
42
43 val get_context_value : t -> string -> Json.t option
44 val report_progress : t -> float -> float -> JSONRPCMessage.t option
45end
46
47(** Tools for the MCP server *)
48module Tool : sig
49 type handler = Context.t -> Json.t -> (Json.t, string) result
50
51 type t = {
52 name : string;
53 description : string option;
54 input_schema : Json.t;
55 handler : handler;
56 }
57
58 val create :
59 name:string ->
60 ?description:string ->
61 input_schema:Json.t ->
62 handler:handler ->
63 unit ->
64 t
65
66 val to_json : t -> Json.t
67
68 val to_rpc_tool_list_tool : t -> Mcp_rpc.ToolsList.Tool.t
69 (** Convert to Mcp_rpc.ToolsList.Tool.t *)
70
71 val to_rpc_tools_list : t list -> Mcp_rpc.ToolsList.Tool.t list
72 (** Convert a list of Tool.t to the format needed for tools/list response *)
73
74 val rpc_content_to_mcp_content :
75 Mcp_rpc.ToolsCall.ToolContent.t list -> Mcp.content list
76 (** Convert Mcp_rpc.ToolsCall response content to Mcp.content list *)
77
78 val mcp_content_to_rpc_content :
79 Mcp.content list -> Mcp_rpc.ToolsCall.ToolContent.t list
80 (** Convert Mcp.content list to Mcp_rpc.ToolsCall.ToolContent.t list *)
81
82 val create_tool_result : Mcp.content list -> is_error:bool -> Json.t
83 (** Create a tool result with content *)
84
85 val create_error_result : string -> Json.t
86 (** Create a tool error result with structured content *)
87
88 val handle_execution_error : string -> Json.t
89 (** Handle tool execution errors *)
90
91 val handle_unknown_tool_error : string -> Json.t
92 (** Handle unknown tool error *)
93
94 val handle_execution_exception : exn -> Json.t
95 (** Handle general tool execution exception *)
96end
97
98(** Resources for the MCP server *)
99module Resource : sig
100 type handler = Context.t -> string list -> (string, string) result
101
102 type t = {
103 uri : string;
104 name : string;
105 description : string option;
106 mime_type : string option;
107 handler : handler;
108 }
109
110 val create :
111 uri:string ->
112 name:string ->
113 ?description:string ->
114 ?mime_type:string ->
115 handler:handler ->
116 unit ->
117 t
118
119 val to_json : t -> Json.t
120
121 val to_rpc_resource_list_resource : t -> Mcp_rpc.ResourcesList.Resource.t
122 (** Convert to Mcp_rpc.ResourcesList.Resource.t *)
123
124 val to_rpc_resources_list : t list -> Mcp_rpc.ResourcesList.Resource.t list
125 (** Convert a list of Resource.t to the format needed for resources/list
126 response *)
127end
128
129(** Resource Templates for the MCP server *)
130module ResourceTemplate : sig
131 type handler = Context.t -> string list -> (string, string) result
132
133 type t = {
134 uri_template : string;
135 name : string;
136 description : string option;
137 mime_type : string option;
138 handler : handler;
139 }
140
141 val create :
142 uri_template:string ->
143 name:string ->
144 ?description:string ->
145 ?mime_type:string ->
146 handler:handler ->
147 unit ->
148 t
149
150 val to_json : t -> Json.t
151
152 val to_rpc_resource_template :
153 t -> Mcp_rpc.ListResourceTemplatesResult.ResourceTemplate.t
154 (** Convert to Mcp_rpc.ResourceTemplatesList.ResourceTemplate.t *)
155
156 val to_rpc_resource_templates_list :
157 t list -> Mcp_rpc.ListResourceTemplatesResult.ResourceTemplate.t list
158 (** Convert a list of ResourceTemplate.t to the format needed for
159 resources/templates/list response *)
160end
161
162(** Prompts for the MCP server *)
163module Prompt : sig
164 type argument = {
165 name : string;
166 description : string option;
167 required : bool;
168 }
169
170 type message = { role : Role.t; content : content }
171
172 type handler =
173 Context.t -> (string * string) list -> (message list, string) result
174
175 type t = {
176 name : string;
177 description : string option;
178 arguments : argument list;
179 handler : handler;
180 }
181
182 val create :
183 name:string ->
184 ?description:string ->
185 ?arguments:argument list ->
186 handler:handler ->
187 unit ->
188 t
189
190 val create_argument :
191 name:string -> ?description:string -> ?required:bool -> unit -> argument
192
193 val to_json : t -> Json.t
194
195 val argument_to_rpc_prompt_argument :
196 argument -> Mcp_rpc.PromptsList.PromptArgument.t
197 (** Convert argument to Mcp_rpc.PromptsList.PromptArgument.t *)
198
199 val to_rpc_prompt_list_prompt : t -> Mcp_rpc.PromptsList.Prompt.t
200 (** Convert to Mcp_rpc.PromptsList.Prompt.t *)
201
202 val to_rpc_prompts_list : t list -> Mcp_rpc.PromptsList.Prompt.t list
203 (** Convert a list of Prompt.t to the format needed for prompts/list response
204 *)
205
206 val message_to_rpc_prompt_message : message -> PromptMessage.t
207 (** Convert message to Mcp_rpc.PromptMessage.t *)
208
209 val messages_to_rpc_prompt_messages : message list -> PromptMessage.t list
210 (** Convert a list of messages to the format needed for prompts/get response
211 *)
212end
213
214type server
215(** Main server type *)
216
217val name : server -> string
218val version : server -> string
219val protocol_version : server -> string
220val capabilities : server -> Json.t
221val tools : server -> Tool.t list
222val resources : server -> Resource.t list
223val resource_templates : server -> ResourceTemplate.t list
224val prompts : server -> Prompt.t list
225
226val create_server :
227 name:string -> ?version:string -> ?protocol_version:string -> unit -> server
228(** Create a new server *)
229
230val default_capabilities :
231 ?with_tools:bool ->
232 ?with_resources:bool ->
233 ?with_resource_templates:bool ->
234 ?with_prompts:bool ->
235 unit ->
236 Json.t
237(** Default capabilities for the server *)
238
239val add_tool :
240 server ->
241 name:string ->
242 ?description:string ->
243 ?schema_properties:(string * string * string) list ->
244 ?schema_required:string list ->
245 (Json.t -> Json.t) ->
246 Tool.t
247(** Create and register a tool in one step *)
248
249val add_resource :
250 server ->
251 uri:string ->
252 name:string ->
253 ?description:string ->
254 ?mime_type:string ->
255 (string list -> string) ->
256 Resource.t
257(** Create and register a resource in one step *)
258
259val add_resource_template :
260 server ->
261 uri_template:string ->
262 name:string ->
263 ?description:string ->
264 ?mime_type:string ->
265 (string list -> string) ->
266 ResourceTemplate.t
267(** Create and register a resource template in one step *)
268
269val add_prompt :
270 server ->
271 name:string ->
272 ?description:string ->
273 ?arguments:(string * string option * bool) list ->
274 ((string * string) list -> Prompt.message list) ->
275 Prompt.t
276(** Create and register a prompt in one step *)
277
278val configure_server :
279 server ->
280 ?with_tools:bool ->
281 ?with_resources:bool ->
282 ?with_resource_templates:bool ->
283 ?with_prompts:bool ->
284 unit ->
285 server
286(** Configure server with default capabilities based on registered components *)
287
288val make_tool_schema : (string * string * string) list -> string list -> Json.t