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