My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** High-level MCP client session API.
2
3 This module provides a high-level client API for connecting to MCP servers.
4 It handles the initialization handshake, capability negotiation, and provides
5 typed methods for all MCP protocol operations.
6
7 {1 Example Usage}
8
9 {[
10 Eio_main.run @@ fun env ->
11 Eio.Switch.run @@ fun sw ->
12 let transport = Transport_stdio.create ~sw (module Eio.Stdenv : Eio.Stdenv.S with type t = _) env in
13
14 let config = {
15 client_info = Capabilities.Implementation.make
16 ~name:"my-client"
17 ~version:"1.0.0";
18 client_capabilities = Capabilities.Client.make
19 ~roots:(Capabilities.Roots.make ~list_changed:true ())
20 ();
21 } in
22
23 let client = Client_session.create ~sw ~transport config in
24
25 (* List available tools *)
26 let tools_result = Client_session.list_tools client () in
27 List.iter (fun tool ->
28 Printf.printf "Tool: %s\n" tool.Messages.Tools.name
29 ) tools_result.Messages.Tools.tools;
30
31 (* Call a tool *)
32 let args = `Object [("query", `String "hello")] in
33 let result = Client_session.call_tool client
34 ~name:"search"
35 ~arguments:args
36 ()
37 in
38
39 Client_session.close client
40 ]} *)
41
42(** {1 Configuration} *)
43
44type config = {
45 client_info : Capabilities.Implementation.t;
46 (** Client implementation information (name and version) *)
47 client_capabilities : Capabilities.Client.t;
48 (** Client capabilities to advertise to server *)
49}
50(** Client session configuration *)
51
52(** {1 Session Management} *)
53
54type t
55(** Client session handle *)
56
57exception Initialization_error of string
58(** Raised when initialization handshake fails *)
59
60val create :
61 sw:Eio.Switch.t ->
62 transport:Transport.t ->
63 ?timeout:float ->
64 ?clock:Session.clock ->
65 config ->
66 t
67(** Create a client session and perform the initialization handshake.
68
69 This sends an Initialize request to the server, stores the server's
70 capabilities and info, then sends an Initialized notification.
71
72 @param sw Switch for background fibers
73 @param transport Transport layer for communication
74 @param timeout Optional request timeout in seconds
75 @param clock Clock for timeout handling (required if timeout is set)
76 @param config Client configuration
77 @raise Initialization_error if the handshake fails
78 @raise Session.Remote_error if the server returns an error
79 @raise Session.Timeout if the initialize request times out *)
80
81(** {1 Server Information} *)
82
83val server_capabilities : t -> Capabilities.Server.t
84(** Get the server's advertised capabilities from initialization *)
85
86val server_info : t -> Capabilities.Implementation.t
87(** Get the server's implementation info (name and version) *)
88
89val server_instructions : t -> string option
90(** Get optional server instructions from initialization *)
91
92(** {1 Basic Operations} *)
93
94val ping : t -> unit
95(** Send a ping request to the server (keepalive).
96 @raise Session.Remote_error if the server returns an error
97 @raise Session.Timeout if the request times out
98 @raise Session.Session_closed if the session is closed *)
99
100(** {1 Resources} *)
101
102val list_resources : t -> ?cursor:string -> unit -> Messages.Resources.list_result
103(** List available resources.
104 @param cursor Optional pagination cursor
105 @raise Session.Remote_error if the server returns an error
106 @raise Session.Timeout if the request times out
107 @raise Session.Session_closed if the session is closed *)
108
109val read_resource : t -> uri:string -> Messages.Resources.read_result
110(** Read resource contents by URI.
111 @param uri Resource URI to read
112 @raise Session.Remote_error if the server returns an error
113 @raise Session.Timeout if the request times out
114 @raise Session.Session_closed if the session is closed *)
115
116val subscribe_resource : t -> uri:string -> unit
117(** Subscribe to resource update notifications.
118 @param uri Resource URI to subscribe to
119 @raise Session.Remote_error if the server returns an error
120 @raise Session.Timeout if the request times out
121 @raise Session.Session_closed if the session is closed *)
122
123val unsubscribe_resource : t -> uri:string -> unit
124(** Unsubscribe from resource update notifications.
125 @param uri Resource URI to unsubscribe from
126 @raise Session.Remote_error if the server returns an error
127 @raise Session.Timeout if the request times out
128 @raise Session.Session_closed if the session is closed *)
129
130(** {1 Tools} *)
131
132val list_tools : t -> ?cursor:string -> unit -> Messages.Tools.list_result
133(** List available tools.
134 @param cursor Optional pagination cursor
135 @raise Session.Remote_error if the server returns an error
136 @raise Session.Timeout if the request times out
137 @raise Session.Session_closed if the session is closed *)
138
139val call_tool : t -> name:string -> ?arguments:Jsont.json -> unit -> Messages.Tools.call_result
140(** Call a tool by name.
141 @param name Tool name
142 @param arguments Optional tool arguments (JSON object)
143 @raise Session.Remote_error if the server returns an error
144 @raise Session.Timeout if the request times out
145 @raise Session.Session_closed if the session is closed *)
146
147(** {1 Prompts} *)
148
149val list_prompts : t -> ?cursor:string -> unit -> Messages.Prompts.list_result
150(** List available prompts.
151 @param cursor Optional pagination cursor
152 @raise Session.Remote_error if the server returns an error
153 @raise Session.Timeout if the request times out
154 @raise Session.Session_closed if the session is closed *)
155
156val get_prompt : t -> name:string -> ?arguments:(string * string) list -> unit -> Messages.Prompts.get_result
157(** Get a prompt by name with optional arguments.
158 @param name Prompt name
159 @param arguments Optional key-value pairs for prompt arguments
160 @raise Session.Remote_error if the server returns an error
161 @raise Session.Timeout if the request times out
162 @raise Session.Session_closed if the session is closed *)
163
164(** {1 Completions} *)
165
166val complete : t -> ref:Messages.Completions.completion_ref -> argument:string -> Messages.Completions.result
167(** Request auto-completion suggestions.
168 @param ref Completion reference (prompt or resource)
169 @param argument Argument value to complete
170 @raise Session.Remote_error if the server returns an error
171 @raise Session.Timeout if the request times out
172 @raise Session.Session_closed if the session is closed *)
173
174(** {1 Logging} *)
175
176val set_log_level : t -> Messages.Logging.level -> unit
177(** Set the server's logging level.
178 Note: This sends a "logging/setLevel" request.
179 @param level Desired log level
180 @raise Session.Remote_error if the server returns an error
181 @raise Session.Timeout if the request times out
182 @raise Session.Session_closed if the session is closed *)
183
184(** {1 Notification Handlers} *)
185
186val on_resource_updated : t -> (uri:string -> unit) -> unit
187(** Register a handler for resource update notifications.
188 The handler is called when a subscribed resource is updated.
189 Only one handler can be registered at a time (replaces previous handler). *)
190
191val on_resource_list_changed : t -> (unit -> unit) -> unit
192(** Register a handler for resource list change notifications.
193 The handler is called when the list of available resources changes.
194 Only one handler can be registered at a time (replaces previous handler). *)
195
196val on_tool_list_changed : t -> (unit -> unit) -> unit
197(** Register a handler for tool list change notifications.
198 The handler is called when the list of available tools changes.
199 Only one handler can be registered at a time (replaces previous handler). *)
200
201val on_prompt_list_changed : t -> (unit -> unit) -> unit
202(** Register a handler for prompt list change notifications.
203 The handler is called when the list of available prompts changes.
204 Only one handler can be registered at a time (replaces previous handler). *)
205
206val on_log_message : t -> (level:Messages.Logging.level -> logger:string option -> data:Jsont.json -> unit) -> unit
207(** Register a handler for log message notifications from the server.
208 Only one handler can be registered at a time (replaces previous handler). *)
209
210(** {1 Session Control} *)
211
212val close : t -> unit
213(** Close the client session and underlying transport.
214 This is idempotent - safe to call multiple times. *)
215
216val is_closed : t -> bool
217(** Check if the session is closed. *)