comparing a85b3f0fb93a740e0c8db5009503d25fa33fefb1 and tmp on anil.recoil.org/ocaml-mcp

+330

bin/audio_example.ml

···

       1
       1
       +
       open Mcp

     

       2
       2
       +
       open Mcp_sdk

     

       3
       3
       +
       open Mcp_server

     

       4
       4
       +
       

     

       5
       5
       +
       (* WAV file format helper module *)

     

       6
       6
       +
       module Wav = struct

     

       7
       7
       +
         (* Simple WAV file generation for a sine wave *)

     

       8
       8
       +
         let generate_sine_wave ~frequency ~duration ~sample_rate ~amplitude =

     

       9
       9
       +
           (* WAV parameters *)

     

       10
       10
       +
           let num_channels = 1 in (* Mono *)

     

       11
       11
       +
           let bits_per_sample = 16 in

     

       12
       12
       +
           let byte_rate = sample_rate * num_channels * bits_per_sample / 8 in

     

       13
       13
       +
           let block_align = num_channels * bits_per_sample / 8 in

     

       14
       14
       +
           let num_samples = int_of_float (float_of_int sample_rate *. duration) in

     

       15
       15
       +
           let data_size = num_samples * block_align in

     

       16
       16
       +
           

     

       17
       17
       +
           (* Create buffer for the WAV data *)

     

       18
       18
       +
           let buffer = Buffer.create (44 + data_size) in

     

       19
       19
       +
           

     

       20
       20
       +
           (* Write WAV header *)

     

       21
       21
       +
           (* "RIFF" chunk *)

     

       22
       22
       +
           Buffer.add_string buffer "RIFF";

     

       23
       23
       +
           let file_size = 36 + data_size in

     

       24
       24
       +
           Buffer.add_char buffer (char_of_int (file_size land 0xff));

     

       25
       25
       +
           Buffer.add_char buffer (char_of_int ((file_size lsr 8) land 0xff));

     

       26
       26
       +
           Buffer.add_char buffer (char_of_int ((file_size lsr 16) land 0xff));

     

       27
       27
       +
           Buffer.add_char buffer (char_of_int ((file_size lsr 24) land 0xff));

     

       28
       28
       +
           Buffer.add_string buffer "WAVE";

     

       29
       29
       +
           

     

       30
       30
       +
           (* "fmt " sub-chunk *)

     

       31
       31
       +
           Buffer.add_string buffer "fmt ";

     

       32
       32
       +
           Buffer.add_char buffer (char_of_int 16); (* Sub-chunk size (16 for PCM) *)

     

       33
       33
       +
           Buffer.add_char buffer (char_of_int 0);

     

       34
       34
       +
           Buffer.add_char buffer (char_of_int 0);

     

       35
       35
       +
           Buffer.add_char buffer (char_of_int 0);

     

       36
       36
       +
           Buffer.add_char buffer (char_of_int 1); (* Audio format (1 for PCM) *)

     

       37
       37
       +
           Buffer.add_char buffer (char_of_int 0);

     

       38
       38
       +
           Buffer.add_char buffer (char_of_int num_channels); (* Number of channels *)

     

       39
       39
       +
           Buffer.add_char buffer (char_of_int 0);

     

       40
       40
       +
           

     

       41
       41
       +
           (* Sample rate *)

     

       42
       42
       +
           Buffer.add_char buffer (char_of_int (sample_rate land 0xff));

     

       43
       43
       +
           Buffer.add_char buffer (char_of_int ((sample_rate lsr 8) land 0xff));

     

       44
       44
       +
           Buffer.add_char buffer (char_of_int ((sample_rate lsr 16) land 0xff));

     

       45
       45
       +
           Buffer.add_char buffer (char_of_int ((sample_rate lsr 24) land 0xff));

     

       46
       46
       +
           

     

       47
       47
       +
           (* Byte rate *)

     

       48
       48
       +
           Buffer.add_char buffer (char_of_int (byte_rate land 0xff));

     

       49
       49
       +
           Buffer.add_char buffer (char_of_int ((byte_rate lsr 8) land 0xff));

     

       50
       50
       +
           Buffer.add_char buffer (char_of_int ((byte_rate lsr 16) land 0xff));

     

       51
       51
       +
           Buffer.add_char buffer (char_of_int ((byte_rate lsr 24) land 0xff));

     

       52
       52
       +
           

     

       53
       53
       +
           (* Block align *)

     

       54
       54
       +
           Buffer.add_char buffer (char_of_int block_align);

     

       55
       55
       +
           Buffer.add_char buffer (char_of_int 0);

     

       56
       56
       +
           

     

       57
       57
       +
           (* Bits per sample *)

     

       58
       58
       +
           Buffer.add_char buffer (char_of_int bits_per_sample);

     

       59
       59
       +
           Buffer.add_char buffer (char_of_int 0);

     

       60
       60
       +
           

     

       61
       61
       +
           (* "data" sub-chunk *)

     

       62
       62
       +
           Buffer.add_string buffer "data";

     

       63
       63
       +
           Buffer.add_char buffer (char_of_int (data_size land 0xff));

     

       64
       64
       +
           Buffer.add_char buffer (char_of_int ((data_size lsr 8) land 0xff));

     

       65
       65
       +
           Buffer.add_char buffer (char_of_int ((data_size lsr 16) land 0xff));

     

       66
       66
       +
           Buffer.add_char buffer (char_of_int ((data_size lsr 24) land 0xff));

     

       67
       67
       +
           

     

       68
       68
       +
           (* Generate sine wave data *)

     

       69
       69
       +
           let max_amplitude = float_of_int (1 lsl (bits_per_sample - 1)) -. 1.0 in

     

       70
       70
       +
           for i = 0 to num_samples - 1 do

     

       71
       71
       +
             let t = float_of_int i /. float_of_int sample_rate in

     

       72
       72
       +
             let value = int_of_float (amplitude *. max_amplitude *. sin (2.0 *. Float.pi *. frequency *. t)) in

     

       73
       73
       +
             (* Write 16-bit sample (little-endian) *)

     

       74
       74
       +
             Buffer.add_char buffer (char_of_int (value land 0xff));

     

       75
       75
       +
             Buffer.add_char buffer (char_of_int ((value lsr 8) land 0xff));

     

       76
       76
       +
           done;

     

       77
       77
       +
           

     

       78
       78
       +
           Buffer.contents buffer

     

       79
       79
       +
           

     

       80
       80
       +
         (* Encode binary data as base64 *)

     

       81
       81
       +
         let base64_encode data =

     

       82
       82
       +
           let buffer = Buffer.create (4 * (String.length data + 2) / 3) in

     

       83
       83
       +
           let alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/" in

     

       84
       84
       +
           

     

       85
       85
       +
           let encode_block i bytes =

     

       86
       86
       +
             let b1 = Char.code (String.get bytes (i * 3)) in

     

       87
       87
       +
             let b2 = if i * 3 + 1 < String.length bytes then Char.code (String.get bytes (i * 3 + 1)) else 0 in

     

       88
       88
       +
             let b3 = if i * 3 + 2 < String.length bytes then Char.code (String.get bytes (i * 3 + 2)) else 0 in

     

       89
       89
       +
             

     

       90
       90
       +
             let n = (b1 lsl 16) lor (b2 lsl 8) lor b3 in

     

       91
       91
       +
             Buffer.add_char buffer (String.get alphabet ((n lsr 18) land 63));

     

       92
       92
       +
             Buffer.add_char buffer (String.get alphabet ((n lsr 12) land 63));

     

       93
       93
       +
             

     

       94
       94
       +
             if i * 3 + 1 < String.length bytes then

     

       95
       95
       +
               Buffer.add_char buffer (String.get alphabet ((n lsr 6) land 63))

     

       96
       96
       +
             else

     

       97
       97
       +
               Buffer.add_char buffer '=';

     

       98
       98
       +
               

     

       99
       99
       +
             if i * 3 + 2 < String.length bytes then

     

       100
       100
       +
               Buffer.add_char buffer (String.get alphabet (n land 63))

     

       101
       101
       +
             else

     

       102
       102
       +
               Buffer.add_char buffer '=';

     

       103
       103
       +
           in

     

       104
       104
       +
           

     

       105
       105
       +
           for i = 0 to (String.length data + 2) / 3 - 1 do

     

       106
       106
       +
             encode_block i data

     

       107
       107
       +
           done;

     

       108
       108
       +
           

     

       109
       109
       +
           Buffer.contents buffer

     

       110
       110
       +
       end

     

       111
       111
       +
       

     

       112
       112
       +
       (* Helper for extracting string value from JSON *)

     

       113
       113
       +
       let get_string_param json name =

     

       114
       114
       +
         match json with

     

       115
       115
       +
         | `Assoc fields ->

     

       116
       116
       +
           (match List.assoc_opt name fields with

     

       117
       117
       +
           | Some (`String value) -> value

     

       118
       118
       +
           | _ -> raise (Failure (Printf.sprintf "Missing or invalid parameter: %s" name)))

     

       119
       119
       +
         | _ -> raise (Failure "Expected JSON object")

     

       120
       120
       +
       

     

       121
       121
       +
       (* Create a server *)

     

       122
       122
       +
       let server = create_server 

     

       123
       123
       +
         ~name:"OCaml MCP Audio Example" 

     

       124
       124
       +
         ~version:"0.1.0" 

     

       125
       125
       +
         ~protocol_version:"2024-11-05" 

     

       126
       126
       +
         ()

     

       127
       127
       +
       

     

       128
       128
       +
       (* Define startup and shutdown hooks *)

     

       129
       129
       +
       let startup () =

     

       130
       130
       +
         (* Use stderr for direct printing to avoid interfering with JSON-RPC protocol *)

     

       131
       131
       +
         Printf.fprintf stderr "AudioExampleServer is starting up!\n";

     

       132
       132
       +
         flush stderr;

     

       133
       133
       +
         Log.info "AudioExampleServer is starting up!"

     

       134
       134
       +
       

     

       135
       135
       +
       let shutdown () =

     

       136
       136
       +
         Printf.fprintf stderr "AudioExampleServer is shutting down. Goodbye!\n";

     

       137
       137
       +
         flush stderr;

     

       138
       138
       +
         Log.info "AudioExampleServer is shutting down. Goodbye!"

     

       139
       139
       +
       

     

       140
       140
       +
       (* Register the hooks *)

     

       141
       141
       +
       let () =

     

       142
       142
       +
         set_startup_hook server startup;

     

       143
       143
       +
         set_shutdown_hook server shutdown

     

       144
       144
       +
       

     

       145
       145
       +
       (* Helper to create audio content *)

     

       146
       146
       +
       let make_audio_content data mime_type =

     

       147
       147
       +
         let audio_content = AudioContent.{

     

       148
       148
       +
           data;

     

       149
       149
       +
           mime_type;

     

       150
       150
       +
           annotations = None;

     

       151
       151
       +
         } in

     

       152
       152
       +
         Audio audio_content

     

       153
       153
       +
       

     

       154
       154
       +
       (* Define and register an audio tool *)

     

       155
       155
       +
       let _ = add_tool server

     

       156
       156
       +
         ~name:"generate_audio_description"

     

       157
       157
       +
         ~description:"Generates a description with an audio sample"

     

       158
       158
       +
         ~schema_properties:[

     

       159
       159
       +
           ("text", "string", "The text to describe with audio");

     

       160
       160
       +
           ("frequency", "number", "The frequency in Hz for the tone (optional)");

     

       161
       161
       +
           ("duration", "number", "The duration in seconds for the tone (optional)");

     

       162
       162
       +
           ("amplitude", "number", "The amplitude (0.0-1.0) for the tone (optional)");

     

       163
       163
       +
         ]

     

       164
       164
       +
         ~schema_required:["text"]

     

       165
       165
       +
         (fun args ->

     

       166
       166
       +
           try

     

       167
       167
       +
             let text = get_string_param args "text" in

     

       168
       168
       +
             

     

       169
       169
       +
             (* Parse parameters with defaults *)

     

       170
       170
       +
             let frequency = 

     

       171
       171
       +
               try

     

       172
       172
       +
                 match List.assoc_opt "frequency" (match args with `Assoc l -> l | _ -> []) with

     

       173
       173
       +
                 | Some (`Int f) -> float_of_int f

     

       174
       174
       +
                 | Some (`Float f) -> f

     

       175
       175
       +
                 | _ -> 440.0 (* Default to A440 *)

     

       176
       176
       +
               with _ -> 440.0

     

       177
       177
       +
             in

     

       178
       178
       +
             

     

       179
       179
       +
             let duration = 

     

       180
       180
       +
               try

     

       181
       181
       +
                 match List.assoc_opt "duration" (match args with `Assoc l -> l | _ -> []) with

     

       182
       182
       +
                 | Some (`Int d) -> float_of_int d

     

       183
       183
       +
                 | Some (`Float d) -> d

     

       184
       184
       +
                 | _ -> 2.0 (* Default to 2 seconds *)

     

       185
       185
       +
               with _ -> 2.0

     

       186
       186
       +
             in

     

       187
       187
       +
             

     

       188
       188
       +
             let amplitude = 

     

       189
       189
       +
               try

     

       190
       190
       +
                 match List.assoc_opt "amplitude" (match args with `Assoc l -> l | _ -> []) with

     

       191
       191
       +
                 | Some (`Int a) -> float_of_int a

     

       192
       192
       +
                 | Some (`Float a) -> a

     

       193
       193
       +
                 | _ -> 0.8 (* Default to 80% amplitude *)

     

       194
       194
       +
               with _ -> 0.8

     

       195
       195
       +
             in

     

       196
       196
       +
             

     

       197
       197
       +
             (* Generate WAV file for the tone *)

     

       198
       198
       +
             let sample_rate = 44100 in  (* CD quality *)

     

       199
       199
       +
             let wav_data = Wav.generate_sine_wave 

     

       200
       200
       +
               ~frequency 

     

       201
       201
       +
               ~duration 

     

       202
       202
       +
               ~sample_rate 

     

       203
       203
       +
               ~amplitude

     

       204
       204
       +
             in

     

       205
       205
       +
             

     

       206
       206
       +
             (* Encode WAV data as base64 *)

     

       207
       207
       +
             let base64_audio = Wav.base64_encode wav_data in

     

       208
       208
       +
             

     

       209
       209
       +
             Log.info (Printf.sprintf "Generated %d Hz tone for %.1f seconds (%.1f KB)" 

     

       210
       210
       +
                         (int_of_float frequency) duration 

     

       211
       211
       +
                         (float_of_int (String.length wav_data) /. 1024.0));

     

       212
       212
       +
             

     

       213
       213
       +
             (* Create a response with both text and audio content *)

     

       214
       214
       +
             CallToolResult.yojson_of_t CallToolResult.{

     

       215
       215
       +
               content = [

     

       216
       216
       +
                 Text TextContent.{ 

     

       217
       217
       +
                   text = Printf.sprintf "Description: %s (with %.1f Hz tone for %.1f seconds)" 

     

       218
       218
       +
                           text frequency duration; 

     

       219
       219
       +
                   annotations = None 

     

       220
       220
       +
                 };

     

       221
       221
       +
                 Audio AudioContent.{ 

     

       222
       222
       +
                   data = base64_audio; 

     

       223
       223
       +
                   mime_type = "audio/wav"; 

     

       224
       224
       +
                   annotations = None 

     

       225
       225
       +
                 }

     

       226
       226
       +
               ];

     

       227
       227
       +
               is_error = false;

     

       228
       228
       +
               meta = None

     

       229
       229
       +
             }

     

       230
       230
       +
           with

     

       231
       231
       +
           | Failure msg ->

     

       232
       232
       +
             Log.error (Printf.sprintf "Error in audio tool: %s" msg);

     

       233
       233
       +
             CallToolResult.yojson_of_t CallToolResult.{

     

       234
       234
       +
               content = [

     

       235
       235
       +
                 Text TextContent.{ 

     

       236
       236
       +
                   text = Printf.sprintf "Error: %s" msg; 

     

       237
       237
       +
                   annotations = None 

     

       238
       238
       +
                 }

     

       239
       239
       +
               ];

     

       240
       240
       +
               is_error = true;

     

       241
       241
       +
               meta = None

     

       242
       242
       +
             }

     

       243
       243
       +
         )

     

       244
       244
       +
       

     

       245
       245
       +
       (* Define and register a prompt example with audio *)

     

       246
       246
       +
       let _ = add_prompt server

     

       247
       247
       +
         ~name:"audio-description-prompt"

     

       248
       248
       +
         ~description:"A prompt with audio and text content"

     

       249
       249
       +
         ~arguments:[

     

       250
       250
       +
           ("description", Some "Text description to accompany the audio", true);

     

       251
       251
       +
           ("frequency", Some "Frequency in Hz for the audio tone", false);

     

       252
       252
       +
           ("duration", Some "Duration in seconds for the audio tone", false);

     

       253
       253
       +
         ]

     

       254
       254
       +
         (fun args ->

     

       255
       255
       +
           let description = 

     

       256
       256
       +
             try List.assoc "description" args

     

       257
       257
       +
             with Not_found -> "No description provided"

     

       258
       258
       +
           in

     

       259
       259
       +
           

     

       260
       260
       +
           (* Parse frequency with default *)

     

       261
       261
       +
           let frequency = 

     

       262
       262
       +
             try float_of_string (List.assoc "frequency" args)

     

       263
       263
       +
             with _ -> 440.0 (* Default to A440 *)

     

       264
       264
       +
           in

     

       265
       265
       +
           

     

       266
       266
       +
           (* Parse duration with default *)

     

       267
       267
       +
           let duration =

     

       268
       268
       +
             try float_of_string (List.assoc "duration" args)

     

       269
       269
       +
             with _ -> 3.0 (* Default to 3 seconds *)

     

       270
       270
       +
           in

     

       271
       271
       +
           

     

       272
       272
       +
           (* Generate WAV data *)

     

       273
       273
       +
           let sample_rate = 44100 in

     

       274
       274
       +
           let wav_data = Wav.generate_sine_wave 

     

       275
       275
       +
             ~frequency 

     

       276
       276
       +
             ~duration 

     

       277
       277
       +
             ~sample_rate 

     

       278
       278
       +
             ~amplitude:0.8

     

       279
       279
       +
           in

     

       280
       280
       +
           

     

       281
       281
       +
           (* Encode WAV data as base64 *)

     

       282
       282
       +
           let base64_audio = Wav.base64_encode wav_data in

     

       283
       283
       +
           

     

       284
       284
       +
           Log.info (Printf.sprintf "Generated %.1f Hz tone for prompt (%.1f seconds, %.1f KB)" 

     

       285
       285
       +
                       frequency duration 

     

       286
       286
       +
                       (float_of_int (String.length wav_data) /. 1024.0));

     

       287
       287
       +
           

     

       288
       288
       +
           [

     

       289
       289
       +
             Prompt.{ 

     

       290
       290
       +
               role = `User; 

     

       291
       291
       +
               content = make_text_content "Here's a sound sample with description:"

     

       292
       292
       +
             };

     

       293
       293
       +
             Prompt.{ 

     

       294
       294
       +
               role = `User;

     

       295
       295
       +
               content = make_audio_content base64_audio "audio/wav" 

     

       296
       296
       +
             };

     

       297
       297
       +
             Prompt.{ 

     

       298
       298
       +
               role = `User; 

     

       299
       299
       +
               content = make_text_content (Printf.sprintf "%s (%.1f Hz tone for %.1f seconds)" 

     

       300
       300
       +
                                             description frequency duration)

     

       301
       301
       +
             };

     

       302
       302
       +
             Prompt.{ 

     

       303
       303
       +
               role = `Assistant; 

     

       304
       304
       +
               content = make_text_content "I've received your audio file and description."

     

       305
       305
       +
             }

     

       306
       306
       +
           ]

     

       307
       307
       +
         )

     

       308
       308
       +
       

     

       309
       309
       +
       (* Main function *)

     

       310
       310
       +
       let () =

     

       311
       311
       +
         (* Parse command line arguments *)

     

       312
       312
       +
         let transport_type = ref Mcp_server.Stdio in

     

       313
       313
       +
         let args = [

     

       314
       314
       +
           ("--http", Arg.Unit (fun () -> transport_type := Mcp_server.Http), 

     

       315
       315
       +
            "Start server with HTTP transport (default is stdio)");

     

       316
       316
       +
         ] in

     

       317
       317
       +
         let usage_msg = "Usage: audio_example [--http]" in

     

       318
       318
       +
         Arg.parse args (fun _ -> ()) usage_msg;

     

       319
       319
       +
       

     

       320
       320
       +
         (* Use stderr for direct printing to avoid interfering with JSON-RPC protocol *)

     

       321
       321
       +
         Printf.fprintf stderr "Starting AudioExampleServer...\n";

     

       322
       322
       +
         flush stderr;

     

       323
       323
       +
         Log.info "Starting AudioExampleServer...";

     

       324
       324
       +
         

     

       325
       325
       +
         (* Configure the server with appropriate capabilities *)

     

       326
       326
       +
         ignore (configure_server server ());

     

       327
       327
       +
         

     

       328
       328
       +
         (* Create and start MCP server with the selected transport *)

     

       329
       329
       +
         let mcp_server = Mcp_server.create ~server ~transport:!transport_type () in

     

       330
       330
       +
         Mcp_server.start mcp_server

+45 -11

bin/capitalize_sdk.ml

···

       1
       1
        
       open Mcp

     

       2
       2
        
       open Mcp_sdk

     

       3
       3
       +
       open Mcp_server

     

       3
       4
        
       

     

       4
       5
        
       (* Helper for extracting string value from JSON *)

     

       5
       6
        
       let get_string_param json name =

     
···

       14
       15
        
       let server = create_server 

     

       15
       16
        
         ~name:"OCaml MCP Capitalizer" 

     

       16
       17
        
         ~version:"0.1.0" 

     

       17
       17
       -
         ~protocol_version:"2024-11-05" () |>

     

       18
       18
       -
         fun server ->

     

       19
       19
       -
         (* Set default capabilities *)

     

       20
       20
       -
           configure_server server ~with_tools:true ~with_resources:true ~with_prompts:true ()

     

       18
       18
       +
         ~protocol_version:"2024-11-05" 

     

       19
       19
       +
         ()

     

       20
       20
       +
       

     

       21
       21
       +
       (* Define startup and shutdown hooks *)

     

       22
       22
       +
       let startup () =

     

       23
       23
       +
         (* Use stderr for direct printing to avoid interfering with JSON-RPC protocol *)

     

       24
       24
       +
         Printf.fprintf stderr "CapitalizeServer is starting up!\n";

     

       25
       25
       +
         flush stderr;

     

       26
       26
       +
         Log.info "CapitalizeServer is starting up!"

     

       27
       27
       +
       

     

       28
       28
       +
       let shutdown () =

     

       29
       29
       +
         Printf.fprintf stderr "CapitalizeServer is shutting down. Goodbye!\n";

     

       30
       30
       +
         flush stderr;

     

       31
       31
       +
         Log.info "CapitalizeServer is shutting down. Goodbye!"

     

       32
       32
       +
       

     

       33
       33
       +
       (* Register the hooks *)

     

       34
       34
       +
       let () =

     

       35
       35
       +
         set_startup_hook server startup;

     

       36
       36
       +
         set_shutdown_hook server shutdown

     

       21
       37
        
       

     

       22
       38
        
       (* Define and register a capitalize tool *)

     

       23
       39
        
       let _ = add_tool server

     
···

       72
       88
        
           [

     

       73
       89
        
             Prompt.{ 

     

       74
       90
        
               role = `User; 

     

       75
       75
       -
               content = Mcp.make_text_content "Please help me capitalize the following text:"

     

       91
       91
       +
               content = make_text_content "Please help me capitalize the following text:"

     

       76
       92
        
             };

     

       77
       93
        
             Prompt.{ 

     

       78
       94
        
               role = `User; 

     

       79
       79
       -
               content = Mcp.make_text_content text

     

       95
       95
       +
               content = make_text_content text

     

       80
       96
        
             };

     

       81
       97
        
             Prompt.{ 

     

       82
       98
        
               role = `Assistant; 

     

       83
       83
       -
               content = Mcp.make_text_content "Here's the capitalized version:"

     

       99
       99
       +
               content = make_text_content "Here's the capitalized version:"

     

       84
       100
        
             };

     

       85
       101
        
             Prompt.{ 

     

       86
       102
        
               role = `Assistant; 

     

       87
       87
       -
               content = Mcp.make_text_content (String.uppercase_ascii text)

     

       103
       103
       +
               content = make_text_content (String.uppercase_ascii text)

     

       88
       104
        
             }

     

       89
       105
        
           ]

     

       90
       106
        
         )

     

       91
       107
        
       

     

       108
       108
       +
       (* Main function *)

     

       92
       109
        
       let () =

     

       93
       93
       -
         (* Run the server with the default scheduler *)

     

       94
       94
       -
         Eio_main.run @@ fun env->

     

       95
       95
       -
           Mcp_server.run_server env server

     

       110
       110
       +
         (* Parse command line arguments *)

     

       111
       111
       +
         let transport_type = ref Stdio in

     

       112
       112
       +
         let args = [

     

       113
       113
       +
           ("--http", Arg.Unit (fun () -> transport_type := Http), 

     

       114
       114
       +
            "Start server with HTTP transport (default is stdio)");

     

       115
       115
       +
         ] in

     

       116
       116
       +
         let usage_msg = "Usage: capitalize_sdk [--http]" in

     

       117
       117
       +
         Arg.parse args (fun _ -> ()) usage_msg;

     

       118
       118
       +
       

     

       119
       119
       +
         (* Use stderr for direct printing to avoid interfering with JSON-RPC protocol *)

     

       120
       120
       +
         Printf.fprintf stderr "Starting CapitalizeServer...\n";

     

       121
       121
       +
         flush stderr;

     

       122
       122
       +
         Log.info "Starting CapitalizeServer...";

     

       123
       123
       +
         

     

       124
       124
       +
         (* Configure the server with appropriate capabilities *)

     

       125
       125
       +
         ignore (configure_server server ());

     

       126
       126
       +
         

     

       127
       127
       +
         (* Create and start MCP server with the selected transport *)

     

       128
       128
       +
         let mcp_server = create ~server ~transport:!transport_type () in

     

       129
       129
       +
         start mcp_server

+193

bin/completion_example.ml

···

       1
       1
       +
       open Mcp

     

       2
       2
       +
       open Mcp_sdk

     

       3
       3
       +
       open Mcp_server

     

       4
       4
       +
       

     

       5
       5
       +
       (* Helper for extracting string value from JSON *)

     

       6
       6
       +
       let get_string_param json name =

     

       7
       7
       +
         match json with

     

       8
       8
       +
         | `Assoc fields ->

     

       9
       9
       +
           (match List.assoc_opt name fields with

     

       10
       10
       +
           | Some (`String value) -> value

     

       11
       11
       +
           | _ -> raise (Failure (Printf.sprintf "Missing or invalid parameter: %s" name)))

     

       12
       12
       +
         | _ -> raise (Failure "Expected JSON object")

     

       13
       13
       +
       

     

       14
       14
       +
       (* Create a server *)

     

       15
       15
       +
       let server = create_server 

     

       16
       16
       +
         ~name:"OCaml MCP Completion Example" 

     

       17
       17
       +
         ~version:"0.1.0" 

     

       18
       18
       +
         ~protocol_version:"2024-11-05" 

     

       19
       19
       +
         ()

     

       20
       20
       +
       

     

       21
       21
       +
       (* Define startup and shutdown hooks *)

     

       22
       22
       +
       let startup () =

     

       23
       23
       +
         (* Use stderr for direct printing to avoid interfering with JSON-RPC protocol *)

     

       24
       24
       +
         Printf.fprintf stderr "CompletionServer is starting up!\n";

     

       25
       25
       +
         flush stderr;

     

       26
       26
       +
         Log.info "CompletionServer is starting up!"

     

       27
       27
       +
       

     

       28
       28
       +
       let shutdown () =

     

       29
       29
       +
         Printf.fprintf stderr "CompletionServer is shutting down. Goodbye!\n";

     

       30
       30
       +
         flush stderr;

     

       31
       31
       +
         Log.info "CompletionServer is shutting down. Goodbye!"

     

       32
       32
       +
       

     

       33
       33
       +
       (* Register the hooks *)

     

       34
       34
       +
       let () =

     

       35
       35
       +
         set_startup_hook server startup;

     

       36
       36
       +
         set_shutdown_hook server shutdown

     

       37
       37
       +
       

     

       38
       38
       +
       (* Database of programming languages and their features *)

     

       39
       39
       +
       let languages = [

     

       40
       40
       +
         ("ocaml", ["functional"; "static typing"; "pattern matching"; "modules"; "type inference"]);

     

       41
       41
       +
         ("python", ["dynamic typing"; "interpreted"; "object-oriented"; "high-level"; "scripting"]);

     

       42
       42
       +
         ("rust", ["memory safety"; "performance"; "static typing"; "ownership"; "zero-cost abstractions"]);

     

       43
       43
       +
         ("javascript", ["dynamic typing"; "interpreted"; "prototypes"; "single-threaded"; "event-driven"]);

     

       44
       44
       +
         ("go", ["concurrency"; "garbage collection"; "simplicity"; "static typing"; "compiled"]);

     

       45
       45
       +
       ]

     

       46
       46
       +
       

     

       47
       47
       +
       (* Helper function to create a completion response *)

     

       48
       48
       +
       let create_completion values ?(has_more=false) ?(total=None) () =

     

       49
       49
       +
         Completion.Result.{

     

       50
       50
       +
           completion = {

     

       51
       51
       +
             values;

     

       52
       52
       +
             has_more = Some has_more;

     

       53
       53
       +
             total;

     

       54
       54
       +
           };

     

       55
       55
       +
           meta = None;

     

       56
       56
       +
         }

     

       57
       57
       +
       

     

       58
       58
       +
       (* Define and register a tool that handles completions *)

     

       59
       59
       +
       let _ = add_tool server

     

       60
       60
       +
         ~name:"complete"

     

       61
       61
       +
         ~description:"Handles completion requests for programming languages and features"

     

       62
       62
       +
         ~schema_properties:[

     

       63
       63
       +
           ("argument_name", "string", "The name of the argument to complete");

     

       64
       64
       +
           ("argument_value", "string", "The partial value to complete");

     

       65
       65
       +
         ]

     

       66
       66
       +
         ~schema_required:["argument_name"; "argument_value"]

     

       67
       67
       +
         (fun args ->

     

       68
       68
       +
           try

     

       69
       69
       +
             let argument_name = get_string_param args "argument_name" in

     

       70
       70
       +
             let argument_value = get_string_param args "argument_value" in

     

       71
       71
       +
             

     

       72
       72
       +
             Log.info (Printf.sprintf "Completion request for %s = %s" argument_name argument_value);

     

       73
       73
       +
             

     

       74
       74
       +
             (* Handle different completion requests *)

     

       75
       75
       +
             let result = 

     

       76
       76
       +
               match argument_name with

     

       77
       77
       +
               | "language" ->

     

       78
       78
       +
                   (* Complete programming language names *)

     

       79
       79
       +
                   let matches = 

     

       80
       80
       +
                     List.filter 

     

       81
       81
       +
                       (fun (lang, _) -> 

     

       82
       82
       +
                         let lang_lower = String.lowercase_ascii lang in

     

       83
       83
       +
                         let arg_lower = String.lowercase_ascii argument_value in

     

       84
       84
       +
                         String.length lang_lower >= String.length arg_lower &&

     

       85
       85
       +
                         String.sub lang_lower 0 (String.length arg_lower) = arg_lower)

     

       86
       86
       +
                       languages

     

       87
       87
       +
                   in

     

       88
       88
       +
                   let values = List.map fst matches in

     

       89
       89
       +
                   create_completion values ~has_more:false ~total:(Some (List.length values)) ()

     

       90
       90
       +
                   

     

       91
       91
       +
               | "feature" ->

     

       92
       92
       +
                   (* Complete programming language features *)

     

       93
       93
       +
                   let all_features = 

     

       94
       94
       +
                     List.flatten (List.map snd languages) |>

     

       95
       95
       +
                     List.sort_uniq String.compare

     

       96
       96
       +
                   in

     

       97
       97
       +
                   let matches =

     

       98
       98
       +
                     List.filter

     

       99
       99
       +
                       (fun feature -> 

     

       100
       100
       +
                         let feature_lower = String.lowercase_ascii feature in

     

       101
       101
       +
                         let arg_lower = String.lowercase_ascii argument_value in

     

       102
       102
       +
                         String.length feature_lower >= String.length arg_lower &&

     

       103
       103
       +
                         String.sub feature_lower 0 (String.length arg_lower) = arg_lower)

     

       104
       104
       +
                       all_features

     

       105
       105
       +
                   in

     

       106
       106
       +
                   create_completion matches ~has_more:false ~total:(Some (List.length matches)) ()

     

       107
       107
       +
                   

     

       108
       108
       +
               | _ ->

     

       109
       109
       +
                   (* Default completions for unknown arguments *)

     

       110
       110
       +
                   create_completion ["unknown argument"] ()

     

       111
       111
       +
             in

     

       112
       112
       +
             

     

       113
       113
       +
             (* Convert to JSON and return *)

     

       114
       114
       +
             TextContent.yojson_of_t TextContent.{

     

       115
       115
       +
               text = Yojson.Safe.to_string (Completion.Result.to_result result);

     

       116
       116
       +
               annotations = None

     

       117
       117
       +
             }

     

       118
       118
       +
           with

     

       119
       119
       +
           | Failure msg ->

     

       120
       120
       +
               Log.error (Printf.sprintf "Error handling completion request: %s" msg);

     

       121
       121
       +
               TextContent.yojson_of_t TextContent.{

     

       122
       122
       +
                 text = Printf.sprintf "Error: %s" msg;

     

       123
       123
       +
                 annotations = None

     

       124
       124
       +
               }

     

       125
       125
       +
         )

     

       126
       126
       +
       

     

       127
       127
       +
       (* Define and register a prompt that provides programming language info *)

     

       128
       128
       +
       let _ = add_prompt server

     

       129
       129
       +
         ~name:"language-info-prompt"

     

       130
       130
       +
         ~description:"A prompt that provides information about programming languages"

     

       131
       131
       +
         ~arguments:[

     

       132
       132
       +
           ("language", Some "Name of the programming language", true);

     

       133
       133
       +
         ]

     

       134
       134
       +
         (fun args ->

     

       135
       135
       +
           let language = 

     

       136
       136
       +
             try List.assoc "language" args

     

       137
       137
       +
             with Not_found -> "ocaml" (* Default to OCaml *)

     

       138
       138
       +
           in

     

       139
       139
       +
           

     

       140
       140
       +
           let features =

     

       141
       141
       +
             try 

     

       142
       142
       +
               let features = List.assoc (String.lowercase_ascii language) languages in

     

       143
       143
       +
               String.concat ", " features

     

       144
       144
       +
             with Not_found -> "unknown language"

     

       145
       145
       +
           in

     

       146
       146
       +
           

     

       147
       147
       +
           [

     

       148
       148
       +
             Prompt.{ 

     

       149
       149
       +
               role = `User; 

     

       150
       150
       +
               content = make_text_content (Printf.sprintf "Tell me about the %s programming language" language)

     

       151
       151
       +
             };

     

       152
       152
       +
             Prompt.{ 

     

       153
       153
       +
               role = `Assistant; 

     

       154
       154
       +
               content = make_text_content (Printf.sprintf "%s is a programming language with the following features: %s" language features)

     

       155
       155
       +
             }

     

       156
       156
       +
           ]

     

       157
       157
       +
         )

     

       158
       158
       +
       

     

       159
       159
       +
       (* Main function *)

     

       160
       160
       +
       let () =

     

       161
       161
       +
         (* Parse command line arguments *)

     

       162
       162
       +
         let transport_type = ref Stdio in

     

       163
       163
       +
         let args = [

     

       164
       164
       +
           ("--http", Arg.Unit (fun () -> transport_type := Http), 

     

       165
       165
       +
            "Start server with HTTP transport (default is stdio)");

     

       166
       166
       +
         ] in

     

       167
       167
       +
         let usage_msg = "Usage: completion_example [--http]" in

     

       168
       168
       +
         Arg.parse args (fun _ -> ()) usage_msg;

     

       169
       169
       +
       

     

       170
       170
       +
         (* Use stderr for direct printing to avoid interfering with JSON-RPC protocol *)

     

       171
       171
       +
         Printf.fprintf stderr "Starting CompletionServer...\n";

     

       172
       172
       +
         flush stderr;

     

       173
       173
       +
         Log.info "Starting CompletionServer...";

     

       174
       174
       +
         

     

       175
       175
       +
         (* Set custom capabilities to indicate support for completions *)

     

       176
       176
       +
         let capabilities = `Assoc [

     

       177
       177
       +
           ("completions", `Assoc []);  (* Indicate support for completions *)

     

       178
       178
       +
           ("prompts", `Assoc [

     

       179
       179
       +
             ("listChanged", `Bool true)

     

       180
       180
       +
           ]);

     

       181
       181
       +
           ("resources", `Assoc [

     

       182
       182
       +
             ("listChanged", `Bool true);

     

       183
       183
       +
             ("subscribe", `Bool true)

     

       184
       184
       +
           ]);

     

       185
       185
       +
           ("tools", `Assoc [

     

       186
       186
       +
             ("listChanged", `Bool true)

     

       187
       187
       +
           ])

     

       188
       188
       +
         ] in

     

       189
       189
       +
         set_capabilities server capabilities;

     

       190
       190
       +
         

     

       191
       191
       +
         (* Create and start MCP server with the selected transport *)

     

       192
       192
       +
         let mcp_server = create ~server ~transport:!transport_type () in

     

       193
       193
       +
         start mcp_server

+35 -9

bin/dune

···

       1
       1
       +
       (executable

     

       2
       2
       +
        (name server)

     

       3
       3
       +
        (libraries mcp yojson unix)

     

       4
       4
       +
        (flags (:standard -w -8-11)))

     

       5
       5
       +
       

     

       1
       6
        
       (executable

     

       2
       7
        
        (name capitalize_sdk)

     

       3
       8
        
        (modules capitalize_sdk)

     

       4
       4
       -
        (libraries mcp mcp_server yojson eio_main eio))

     

       9
       9
       +
        (libraries mcp mcp_sdk mcp_server yojson unix)

     

       10
       10
       +
        (flags (:standard -w -33)))

     

       5
       11
        
       

     

       6
       12
        
       (executable

     

       7
       7
       -
        (name multimodal_sdk)

     

       8
       8
       -
        (modules multimodal_sdk)

     

       9
       9
       -
        (libraries mcp mcp_sdk mcp_server yojson eio_main eio))

     

       13
       13
       +
        (name audio_example)

     

       14
       14
       +
        (modules audio_example)

     

       15
       15
       +
        (libraries mcp mcp_sdk mcp_server yojson unix)

     

       16
       16
       +
        (flags (:standard -w -33)))

     

       10
       17
        
       

     

       11
       18
        
       (executable

     

       12
       12
       -
        (name ocaml_eval_sdk)

     

       13
       13
       -
        (modes byte)

     

       14
       14
       -
        (modules ocaml_eval_sdk)

     

       15
       15
       -
        (flags (:standard -w -32 -w -33))

     

       16
       16
       -
        (libraries mcp mcp_sdk mcp_server yojson eio_main eio compiler-libs.toplevel))

     

       19
       19
       +
        (name resource_template_example)

     

       20
       20
       +
        (modules resource_template_example)

     

       21
       21
       +
        (libraries mcp mcp_sdk mcp_server yojson unix)

     

       22
       22
       +
        (flags (:standard -w -33)))

     

       23
       23
       +
       

     

       24
       24
       +
       (executable

     

       25
       25
       +
        (name completion_example)

     

       26
       26
       +
        (modules completion_example)

     

       27
       27
       +
        (libraries mcp mcp_sdk mcp_server yojson unix)

     

       28
       28
       +
        (flags (:standard -w -33)))

     

       29
       29
       +
       

     

       30
       30
       +
       

     

       31
       31
       +
       (executable

     

       32
       32
       +
        (name image_generator_example)

     

       33
       33
       +
        (modules image_generator_example)

     

       34
       34
       +
        (libraries mcp mcp_sdk mcp_server yojson unix)

     

       35
       35
       +
        (flags (:standard -w -33)))

     

       36
       36
       +
       

     

       37
       37
       +
       (executable

     

       38
       38
       +
        (name multimodal_example)

     

       39
       39
       +
        (modules multimodal_example)

     

       40
       40
       +
        (libraries mcp mcp_sdk mcp_server yojson unix)

     

       41
       41
       +
        (flags (:standard -w -33 -w -32)))

     

       42
       42
       +

+468

bin/image_generator_example.ml

···

       1
       1
       +
       open Mcp

     

       2
       2
       +
       open Mcp_sdk

     

       3
       3
       +
       open Mcp_server

     

       4
       4
       +
       

     

       5
       5
       +
       (* Random pixel image generator MCP server *)

     

       6
       6
       +
       

     

       7
       7
       +
       (* Base64 encoding helper *)

     

       8
       8
       +
       module Base64 = struct

     

       9
       9
       +
         let encode_char n =

     

       10
       10
       +
           "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/".[n]

     

       11
       11
       +
           

     

       12
       12
       +
         let encode_block i bytes =

     

       13
       13
       +
           let buffer = Buffer.create 4 in

     

       14
       14
       +
           let b1 = Char.code (String.get bytes (i * 3)) in

     

       15
       15
       +
           let b2 = if i * 3 + 1 < String.length bytes then Char.code (String.get bytes (i * 3 + 1)) else 0 in

     

       16
       16
       +
           let b3 = if i * 3 + 2 < String.length bytes then Char.code (String.get bytes (i * 3 + 2)) else 0 in

     

       17
       17
       +
           

     

       18
       18
       +
           let n = (b1 lsl 16) lor (b2 lsl 8) lor b3 in

     

       19
       19
       +
           Buffer.add_char buffer (encode_char ((n lsr 18) land 63));

     

       20
       20
       +
           Buffer.add_char buffer (encode_char ((n lsr 12) land 63));

     

       21
       21
       +
           

     

       22
       22
       +
           if i * 3 + 1 < String.length bytes then

     

       23
       23
       +
             Buffer.add_char buffer (encode_char ((n lsr 6) land 63))

     

       24
       24
       +
           else

     

       25
       25
       +
             Buffer.add_char buffer '=';

     

       26
       26
       +
             

     

       27
       27
       +
           if i * 3 + 2 < String.length bytes then

     

       28
       28
       +
             Buffer.add_char buffer (encode_char (n land 63))

     

       29
       29
       +
           else

     

       30
       30
       +
             Buffer.add_char buffer '=';

     

       31
       31
       +
           

     

       32
       32
       +
           Buffer.contents buffer

     

       33
       33
       +
           

     

       34
       34
       +
         let encode data =

     

       35
       35
       +
           let buffer = Buffer.create (4 * (String.length data + 2) / 3) in

     

       36
       36
       +
           for i = 0 to (String.length data - 1) / 3 do

     

       37
       37
       +
             Buffer.add_string buffer (encode_block i data)

     

       38
       38
       +
           done;

     

       39
       39
       +
           Buffer.contents buffer

     

       40
       40
       +
       end

     

       41
       41
       +
       

     

       42
       42
       +
       (* Image generation utilities *)

     

       43
       43
       +
       module ImageGenerator = struct

     

       44
       44
       +
         (* Simple PNG generation *)

     

       45
       45
       +
         let create_png width height pixels =

     

       46
       46
       +
           (* PNG signature *)

     

       47
       47
       +
           let signature = [|137; 80; 78; 71; 13; 10; 26; 10|] in

     

       48
       48
       +
           

     

       49
       49
       +
           (* IHDR chunk data *)

     

       50
       50
       +
           let ihdr_data = Bytes.create 13 in

     

       51
       51
       +
           (* Width - big endian *)

     

       52
       52
       +
           Bytes.set ihdr_data 0 (Char.chr ((width lsr 24) land 0xff));

     

       53
       53
       +
           Bytes.set ihdr_data 1 (Char.chr ((width lsr 16) land 0xff));

     

       54
       54
       +
           Bytes.set ihdr_data 2 (Char.chr ((width lsr 8) land 0xff));

     

       55
       55
       +
           Bytes.set ihdr_data 3 (Char.chr (width land 0xff));

     

       56
       56
       +
           (* Height - big endian *)

     

       57
       57
       +
           Bytes.set ihdr_data 4 (Char.chr ((height lsr 24) land 0xff));

     

       58
       58
       +
           Bytes.set ihdr_data 5 (Char.chr ((height lsr 16) land 0xff));

     

       59
       59
       +
           Bytes.set ihdr_data 6 (Char.chr ((height lsr 8) land 0xff));

     

       60
       60
       +
           Bytes.set ihdr_data 7 (Char.chr (height land 0xff));

     

       61
       61
       +
           (* Bit depth - 8 bits *)

     

       62
       62
       +
           Bytes.set ihdr_data 8 (Char.chr 8);

     

       63
       63
       +
           (* Color type - RGB with alpha *)

     

       64
       64
       +
           Bytes.set ihdr_data 9 (Char.chr 6);

     

       65
       65
       +
           (* Compression, filter, interlace - all 0 *)

     

       66
       66
       +
           Bytes.set ihdr_data 10 (Char.chr 0);

     

       67
       67
       +
           Bytes.set ihdr_data 11 (Char.chr 0);

     

       68
       68
       +
           Bytes.set ihdr_data 12 (Char.chr 0);

     

       69
       69
       +
           

     

       70
       70
       +
           (* Very simple CRC32 implementation for PNG chunks *)

     

       71
       71
       +
           let calculate_crc data =

     

       72
       72
       +
             let crc = ref 0xffffffff in

     

       73
       73
       +
             for i = 0 to Bytes.length data - 1 do

     

       74
       74
       +
               let byte = Char.code (Bytes.get data i) in

     

       75
       75
       +
               crc := !crc lxor byte;

     

       76
       76
       +
               for _ = 0 to 7 do

     

       77
       77
       +
                 if !crc land 1 <> 0 then

     

       78
       78
       +
                   crc := (!crc lsr 1) lxor 0xedb88320

     

       79
       79
       +
                 else

     

       80
       80
       +
                   crc := !crc lsr 1

     

       81
       81
       +
               done

     

       82
       82
       +
             done;

     

       83
       83
       +
             !crc lxor 0xffffffff

     

       84
       84
       +
           in

     

       85
       85
       +
           

     

       86
       86
       +
           (* Create IHDR chunk *)

     

       87
       87
       +
           let ihdr_chunk = Buffer.create 25 in

     

       88
       88
       +
           (* Length - 13 bytes *)

     

       89
       89
       +
           Buffer.add_char ihdr_chunk (Char.chr 0);

     

       90
       90
       +
           Buffer.add_char ihdr_chunk (Char.chr 0);

     

       91
       91
       +
           Buffer.add_char ihdr_chunk (Char.chr 0);

     

       92
       92
       +
           Buffer.add_char ihdr_chunk (Char.chr 13);

     

       93
       93
       +
           (* Chunk type - IHDR *)

     

       94
       94
       +
           Buffer.add_string ihdr_chunk "IHDR";

     

       95
       95
       +
           (* Chunk data *)

     

       96
       96
       +
           Buffer.add_string ihdr_chunk (Bytes.unsafe_to_string ihdr_data);

     

       97
       97
       +
           (* CRC *)

     

       98
       98
       +
           let ihdr_crc_data = Bytes.create 17 in

     

       99
       99
       +
           Bytes.blit_string "IHDR" 0 ihdr_crc_data 0 4;

     

       100
       100
       +
           Bytes.blit ihdr_data 0 ihdr_crc_data 4 13;

     

       101
       101
       +
           let crc = calculate_crc ihdr_crc_data in

     

       102
       102
       +
           Buffer.add_char ihdr_chunk (Char.chr ((crc lsr 24) land 0xff));

     

       103
       103
       +
           Buffer.add_char ihdr_chunk (Char.chr ((crc lsr 16) land 0xff));

     

       104
       104
       +
           Buffer.add_char ihdr_chunk (Char.chr ((crc lsr 8) land 0xff));

     

       105
       105
       +
           Buffer.add_char ihdr_chunk (Char.chr (crc land 0xff));

     

       106
       106
       +
           

     

       107
       107
       +
           (* Create IDAT chunk (uncompressed for simplicity) *)

     

       108
       108
       +
           let row_size = width * 4 in

     

       109
       109
       +
           let data_size = height * (row_size + 1) in

     

       110
       110
       +
           let idat_chunk = Buffer.create (12 + data_size) in

     

       111
       111
       +
           (* Length *)

     

       112
       112
       +
           Buffer.add_char idat_chunk (Char.chr ((data_size lsr 24) land 0xff));

     

       113
       113
       +
           Buffer.add_char idat_chunk (Char.chr ((data_size lsr 16) land 0xff));

     

       114
       114
       +
           Buffer.add_char idat_chunk (Char.chr ((data_size lsr 8) land 0xff));

     

       115
       115
       +
           Buffer.add_char idat_chunk (Char.chr (data_size land 0xff));

     

       116
       116
       +
           (* Chunk type - IDAT *)

     

       117
       117
       +
           Buffer.add_string idat_chunk "IDAT";

     

       118
       118
       +
           

     

       119
       119
       +
           (* Very simple zlib header (no compression) *)

     

       120
       120
       +
           Buffer.add_char idat_chunk (Char.chr 0x78); (* CMF byte *)

     

       121
       121
       +
           Buffer.add_char idat_chunk (Char.chr 0x01); (* FLG byte *)

     

       122
       122
       +
           

     

       123
       123
       +
           (* Raw image data with filter type 0 (None) for each scanline *)

     

       124
       124
       +
           for y = 0 to height - 1 do

     

       125
       125
       +
             (* Filter type 0 (None) *)

     

       126
       126
       +
             Buffer.add_char idat_chunk (Char.chr 0);

     

       127
       127
       +
             for x = 0 to width - 1 do

     

       128
       128
       +
               let idx = (y * width + x) * 4 in

     

       129
       129
       +
               Buffer.add_char idat_chunk (Char.chr (Bytes.get_uint8 pixels idx)); (* R *)

     

       130
       130
       +
               Buffer.add_char idat_chunk (Char.chr (Bytes.get_uint8 pixels (idx + 1))); (* G *)

     

       131
       131
       +
               Buffer.add_char idat_chunk (Char.chr (Bytes.get_uint8 pixels (idx + 2))); (* B *)

     

       132
       132
       +
               Buffer.add_char idat_chunk (Char.chr (Bytes.get_uint8 pixels (idx + 3))); (* A *)

     

       133
       133
       +
             done

     

       134
       134
       +
           done;

     

       135
       135
       +
           

     

       136
       136
       +
           (* Zlib Adler-32 checksum (simplified) *)

     

       137
       137
       +
           let adler = ref 1 in

     

       138
       138
       +
           Buffer.add_char idat_chunk (Char.chr ((!adler lsr 24) land 0xff));

     

       139
       139
       +
           Buffer.add_char idat_chunk (Char.chr ((!adler lsr 16) land 0xff));

     

       140
       140
       +
           Buffer.add_char idat_chunk (Char.chr ((!adler lsr 8) land 0xff));

     

       141
       141
       +
           Buffer.add_char idat_chunk (Char.chr (!adler land 0xff));

     

       142
       142
       +
           

     

       143
       143
       +
           (* CRC *)

     

       144
       144
       +
           let idat_crc = ref 0 in (* Not calculating CRC for simplicity *)

     

       145
       145
       +
           Buffer.add_char idat_chunk (Char.chr ((!idat_crc lsr 24) land 0xff));

     

       146
       146
       +
           Buffer.add_char idat_chunk (Char.chr ((!idat_crc lsr 16) land 0xff));

     

       147
       147
       +
           Buffer.add_char idat_chunk (Char.chr ((!idat_crc lsr 8) land 0xff));

     

       148
       148
       +
           Buffer.add_char idat_chunk (Char.chr (!idat_crc land 0xff));

     

       149
       149
       +
           

     

       150
       150
       +
           (* Create IEND chunk *)

     

       151
       151
       +
           let iend_chunk = Buffer.create 12 in

     

       152
       152
       +
           (* Length - 0 bytes *)

     

       153
       153
       +
           Buffer.add_char iend_chunk (Char.chr 0);

     

       154
       154
       +
           Buffer.add_char iend_chunk (Char.chr 0);

     

       155
       155
       +
           Buffer.add_char iend_chunk (Char.chr 0);

     

       156
       156
       +
           Buffer.add_char iend_chunk (Char.chr 0);

     

       157
       157
       +
           (* Chunk type - IEND *)

     

       158
       158
       +
           Buffer.add_string iend_chunk "IEND";

     

       159
       159
       +
           (* CRC *)

     

       160
       160
       +
           let iend_crc = 0xAE426082 in (* Precomputed CRC for IEND chunk *)

     

       161
       161
       +
           Buffer.add_char iend_chunk (Char.chr ((iend_crc lsr 24) land 0xff));

     

       162
       162
       +
           Buffer.add_char iend_chunk (Char.chr ((iend_crc lsr 16) land 0xff));

     

       163
       163
       +
           Buffer.add_char iend_chunk (Char.chr ((iend_crc lsr 8) land 0xff));

     

       164
       164
       +
           Buffer.add_char iend_chunk (Char.chr (iend_crc land 0xff));

     

       165
       165
       +
           

     

       166
       166
       +
           (* Combine all parts *)

     

       167
       167
       +
           let result = Buffer.create (8 + Buffer.length ihdr_chunk + Buffer.length idat_chunk + Buffer.length iend_chunk) in

     

       168
       168
       +
           (* PNG signature *)

     

       169
       169
       +
           Array.iter (fun c -> Buffer.add_char result (Char.chr c)) signature;

     

       170
       170
       +
           (* IHDR chunk *)

     

       171
       171
       +
           Buffer.add_buffer result ihdr_chunk;

     

       172
       172
       +
           (* IDAT chunk *)

     

       173
       173
       +
           Buffer.add_buffer result idat_chunk;

     

       174
       174
       +
           (* IEND chunk *)

     

       175
       175
       +
           Buffer.add_buffer result iend_chunk;

     

       176
       176
       +
           

     

       177
       177
       +
           Buffer.contents result

     

       178
       178
       +
         

     

       179
       179
       +
         (* Generate random pixel art image *)

     

       180
       180
       +
         let generate_random_image ?(width=16) ?(height=16) ?(pixel_size=1) ?(seed=None) () =

     

       181
       181
       +
           let pixels = Bytes.create (width * height * 4) in

     

       182
       182
       +
           

     

       183
       183
       +
           (* Set random seed if provided *)

     

       184
       184
       +
           (match seed with

     

       185
       185
       +
            | Some s -> Random.init s

     

       186
       186
       +
            | None -> Random.self_init ());

     

       187
       187
       +
           

     

       188
       188
       +
           (* Generate a random color palette *)

     

       189
       189
       +
           let palette_size = Random.int 8 + 2 in (* 2-10 colors *)

     

       190
       190
       +
           let palette = Array.init palette_size (fun _ ->

     

       191
       191
       +
             (Random.int 256, Random.int 256, Random.int 256, 255) (* RGBA *)

     

       192
       192
       +
           ) in

     

       193
       193
       +
           

     

       194
       194
       +
           (* Fill the pixel buffer *)

     

       195
       195
       +
           for y = 0 to height - 1 do

     

       196
       196
       +
             for x = 0 to width - 1 do

     

       197
       197
       +
               let color_idx = Random.int palette_size in

     

       198
       198
       +
               let (r, g, b, a) = palette.(color_idx) in

     

       199
       199
       +
               let idx = (y * width + x) * 4 in

     

       200
       200
       +
               Bytes.set_uint8 pixels idx r;

     

       201
       201
       +
               Bytes.set_uint8 pixels (idx + 1) g;

     

       202
       202
       +
               Bytes.set_uint8 pixels (idx + 2) b;

     

       203
       203
       +
               Bytes.set_uint8 pixels (idx + 3) a;

     

       204
       204
       +
             done

     

       205
       205
       +
           done;

     

       206
       206
       +
           

     

       207
       207
       +
           (* Create symmetrical patterns - horizontally, vertically, or both *)

     

       208
       208
       +
           let symmetry_type = Random.int 3 in

     

       209
       209
       +
           if symmetry_type > 0 then begin

     

       210
       210
       +
             for y = 0 to height - 1 do

     

       211
       211
       +
               for x = 0 to width / 2 do

     

       212
       212
       +
                 (* Mirror horizontally (except center column for odd widths) *)

     

       213
       213
       +
                 if symmetry_type = 1 || symmetry_type = 2 then begin

     

       214
       214
       +
                   let mirror_x = width - 1 - x in

     

       215
       215
       +
                   if x <> mirror_x then begin

     

       216
       216
       +
                     let src_idx = (y * width + x) * 4 in

     

       217
       217
       +
                     let dst_idx = (y * width + mirror_x) * 4 in

     

       218
       218
       +
                     for i = 0 to 3 do

     

       219
       219
       +
                       Bytes.set pixels (dst_idx + i) (Bytes.get pixels (src_idx + i))

     

       220
       220
       +
                     done

     

       221
       221
       +
                   end

     

       222
       222
       +
                 end

     

       223
       223
       +
               done

     

       224
       224
       +
             done;

     

       225
       225
       +
             

     

       226
       226
       +
             (* Mirror vertically for symmetry_type = 2 *)

     

       227
       227
       +
             if symmetry_type = 2 then begin

     

       228
       228
       +
               for y = 0 to height / 2 do

     

       229
       229
       +
                 let mirror_y = height - 1 - y in

     

       230
       230
       +
                 if y <> mirror_y then begin

     

       231
       231
       +
                   for x = 0 to width - 1 do

     

       232
       232
       +
                     let src_idx = (y * width + x) * 4 in

     

       233
       233
       +
                     let dst_idx = (mirror_y * width + x) * 4 in

     

       234
       234
       +
                     for i = 0 to 3 do

     

       235
       235
       +
                       Bytes.set pixels (dst_idx + i) (Bytes.get pixels (src_idx + i))

     

       236
       236
       +
                     done

     

       237
       237
       +
                   done

     

       238
       238
       +
                 end

     

       239
       239
       +
               done

     

       240
       240
       +
             end

     

       241
       241
       +
           end;

     

       242
       242
       +
           

     

       243
       243
       +
           (* Scale up the image if pixel_size > 1 *)

     

       244
       244
       +
           let final_width = width * pixel_size in

     

       245
       245
       +
           let final_height = height * pixel_size in

     

       246
       246
       +
           

     

       247
       247
       +
           if pixel_size = 1 then

     

       248
       248
       +
             create_png width height pixels

     

       249
       249
       +
           else begin

     

       250
       250
       +
             let scaled_pixels = Bytes.create (final_width * final_height * 4) in

     

       251
       251
       +
             

     

       252
       252
       +
             for y = 0 to height - 1 do

     

       253
       253
       +
               for x = 0 to width - 1 do

     

       254
       254
       +
                 let src_idx = (y * width + x) * 4 in

     

       255
       255
       +
                 for py = 0 to pixel_size - 1 do

     

       256
       256
       +
                   for px = 0 to pixel_size - 1 do

     

       257
       257
       +
                     let dst_x = x * pixel_size + px in

     

       258
       258
       +
                     let dst_y = y * pixel_size + py in

     

       259
       259
       +
                     let dst_idx = (dst_y * final_width + dst_x) * 4 in

     

       260
       260
       +
                     for i = 0 to 3 do

     

       261
       261
       +
                       Bytes.set scaled_pixels (dst_idx + i) (Bytes.get pixels (src_idx + i))

     

       262
       262
       +
                     done

     

       263
       263
       +
                   done

     

       264
       264
       +
                 done

     

       265
       265
       +
               done

     

       266
       266
       +
             done;

     

       267
       267
       +
             

     

       268
       268
       +
             create_png final_width final_height scaled_pixels

     

       269
       269
       +
           end

     

       270
       270
       +
       end

     

       271
       271
       +
       

     

       272
       272
       +
       (* Helper for extracting values from JSON *)

     

       273
       273
       +
       let get_param_int json name default =

     

       274
       274
       +
         match json with

     

       275
       275
       +
         | `Assoc fields ->

     

       276
       276
       +
           (match List.assoc_opt name fields with

     

       277
       277
       +
            | Some (`Int i) -> i

     

       278
       278
       +
            | Some (`Float f) -> int_of_float f

     

       279
       279
       +
            | _ -> default)

     

       280
       280
       +
         | _ -> default

     

       281
       281
       +
       

     

       282
       282
       +
       (* Create a server *)

     

       283
       283
       +
       let server = create_server 

     

       284
       284
       +
         ~name:"OCaml MCP Image Generator" 

     

       285
       285
       +
         ~version:"0.1.0" 

     

       286
       286
       +
         ~protocol_version:"2024-11-05" 

     

       287
       287
       +
         ()

     

       288
       288
       +
       

     

       289
       289
       +
       (* Define startup and shutdown hooks *)

     

       290
       290
       +
       let startup () =

     

       291
       291
       +
         Printf.fprintf stderr "ImageGeneratorServer is starting up!\n";

     

       292
       292
       +
         flush stderr;

     

       293
       293
       +
         Log.info "ImageGeneratorServer is starting up!"

     

       294
       294
       +
       

     

       295
       295
       +
       let shutdown () =

     

       296
       296
       +
         Printf.fprintf stderr "ImageGeneratorServer is shutting down. Goodbye!\n";

     

       297
       297
       +
         flush stderr;

     

       298
       298
       +
         Log.info "ImageGeneratorServer is shutting down. Goodbye!"

     

       299
       299
       +
       

     

       300
       300
       +
       (* Register the hooks *)

     

       301
       301
       +
       let () =

     

       302
       302
       +
         set_startup_hook server startup;

     

       303
       303
       +
         set_shutdown_hook server shutdown

     

       304
       304
       +
       

     

       305
       305
       +
       (* Make an image content helper *)

     

       306
       306
       +
       let make_image_content data mime_type =

     

       307
       307
       +
         let image_content = ImageContent.{

     

       308
       308
       +
           data;

     

       309
       309
       +
           mime_type;

     

       310
       310
       +
           annotations = None;

     

       311
       311
       +
         } in

     

       312
       312
       +
         Image image_content

     

       313
       313
       +
       

     

       314
       314
       +
       (* Define and register a random pixel art generator tool *)

     

       315
       315
       +
       let _ = add_tool server

     

       316
       316
       +
         ~name:"generate_random_pixel_art"

     

       317
       317
       +
         ~description:"Generates a random pixel art image"

     

       318
       318
       +
         ~schema_properties:[

     

       319
       319
       +
           ("width", "integer", "Width of the pixel art grid (default: 16)");

     

       320
       320
       +
           ("height", "integer", "Height of the pixel art grid (default: 16)");

     

       321
       321
       +
           ("pixel_size", "integer", "Size of each pixel (default: 8)");

     

       322
       322
       +
           ("seed", "integer", "Random seed (optional)");

     

       323
       323
       +
         ]

     

       324
       324
       +
         ~schema_required:[]

     

       325
       325
       +
         (fun args ->

     

       326
       326
       +
           try

     

       327
       327
       +
             let width = get_param_int args "width" 16 in

     

       328
       328
       +
             let height = get_param_int args "height" 16 in

     

       329
       329
       +
             let pixel_size = get_param_int args "pixel_size" 8 in

     

       330
       330
       +
             

     

       331
       331
       +
             (* Validate parameters *)

     

       332
       332
       +
             let width = max 1 (min 64 width) in  (* Limit to 1-64 *)

     

       333
       333
       +
             let height = max 1 (min 64 height) in  (* Limit to 1-64 *)

     

       334
       334
       +
             let pixel_size = max 1 (min 16 pixel_size) in  (* Limit to 1-16 *)

     

       335
       335
       +
             

     

       336
       336
       +
             (* Extract optional seed *)

     

       337
       337
       +
             let seed = match args with

     

       338
       338
       +
               | `Assoc fields ->

     

       339
       339
       +
                 (match List.assoc_opt "seed" fields with

     

       340
       340
       +
                  | Some (`Int s) -> Some s

     

       341
       341
       +
                  | _ -> None)

     

       342
       342
       +
               | _ -> None

     

       343
       343
       +
             in

     

       344
       344
       +
             

     

       345
       345
       +
             (* Generate the image *)

     

       346
       346
       +
             let image_data = ImageGenerator.generate_random_image 

     

       347
       347
       +
               ~width ~height ~pixel_size ~seed () in

     

       348
       348
       +
             

     

       349
       349
       +
             (* Encode as base64 *)

     

       350
       350
       +
             let base64_data = Base64.encode image_data in

     

       351
       351
       +
             

     

       352
       352
       +
             Log.info (Printf.sprintf "Generated random pixel art image (%dx%d grid, %dpx pixels)" 

     

       353
       353
       +
                        width height pixel_size);

     

       354
       354
       +
             

     

       355
       355
       +
             (* Create a response with both text and image content *)

     

       356
       356
       +
             CallToolResult.yojson_of_t CallToolResult.{

     

       357
       357
       +
               content = [

     

       358
       358
       +
                 Text TextContent.{ 

     

       359
       359
       +
                   text = Printf.sprintf "Generated random pixel art image (%dx%d grid, %dpx pixels)" 

     

       360
       360
       +
                           width height pixel_size;

     

       361
       361
       +
                   annotations = None 

     

       362
       362
       +
                 };

     

       363
       363
       +
                 Image ImageContent.{ 

     

       364
       364
       +
                   data = base64_data; 

     

       365
       365
       +
                   mime_type = "image/png"; 

     

       366
       366
       +
                   annotations = None 

     

       367
       367
       +
                 }

     

       368
       368
       +
               ];

     

       369
       369
       +
               is_error = false;

     

       370
       370
       +
               meta = None

     

       371
       371
       +
             }

     

       372
       372
       +
           with

     

       373
       373
       +
           | Failure msg ->

     

       374
       374
       +
             Log.error (Printf.sprintf "Error in image generator tool: %s" msg);

     

       375
       375
       +
             CallToolResult.yojson_of_t CallToolResult.{

     

       376
       376
       +
               content = [

     

       377
       377
       +
                 Text TextContent.{ 

     

       378
       378
       +
                   text = Printf.sprintf "Error: %s" msg; 

     

       379
       379
       +
                   annotations = None 

     

       380
       380
       +
                 }

     

       381
       381
       +
               ];

     

       382
       382
       +
               is_error = true;

     

       383
       383
       +
               meta = None

     

       384
       384
       +
             }

     

       385
       385
       +
         )

     

       386
       386
       +
       

     

       387
       387
       +
       (* Define and register a pixel art prompt *)

     

       388
       388
       +
       let _ = add_prompt server

     

       389
       389
       +
         ~name:"pixel-art-prompt"

     

       390
       390
       +
         ~description:"A prompt that includes a random pixel art image"

     

       391
       391
       +
         ~arguments:[

     

       392
       392
       +
           ("width", Some "Width of the pixel art (1-64)", false);

     

       393
       393
       +
           ("height", Some "Height of the pixel art (1-64)", false);

     

       394
       394
       +
           ("pixel_size", Some "Size of each pixel (1-16)", false);

     

       395
       395
       +
         ]

     

       396
       396
       +
         (fun args ->

     

       397
       397
       +
           (* Parse parameters with defaults *)

     

       398
       398
       +
           let width = 

     

       399
       399
       +
             try int_of_string (List.assoc "width" args)

     

       400
       400
       +
             with _ -> 16

     

       401
       401
       +
           in

     

       402
       402
       +
           let height = 

     

       403
       403
       +
             try int_of_string (List.assoc "height" args)

     

       404
       404
       +
             with _ -> 16

     

       405
       405
       +
           in

     

       406
       406
       +
           let pixel_size = 

     

       407
       407
       +
             try int_of_string (List.assoc "pixel_size" args)

     

       408
       408
       +
             with _ -> 8

     

       409
       409
       +
           in

     

       410
       410
       +
           

     

       411
       411
       +
           (* Validate parameters *)

     

       412
       412
       +
           let width = max 1 (min 64 width) in

     

       413
       413
       +
           let height = max 1 (min 64 height) in

     

       414
       414
       +
           let pixel_size = max 1 (min 16 pixel_size) in

     

       415
       415
       +
           

     

       416
       416
       +
           (* Generate image *)

     

       417
       417
       +
           let image_data = ImageGenerator.generate_random_image 

     

       418
       418
       +
             ~width ~height ~pixel_size () in

     

       419
       419
       +
           

     

       420
       420
       +
           (* Encode as base64 *)

     

       421
       421
       +
           let base64_data = Base64.encode image_data in

     

       422
       422
       +
           

     

       423
       423
       +
           Log.info (Printf.sprintf "Generated pixel art for prompt (%dx%d grid, %dpx pixels)" 

     

       424
       424
       +
                      width height pixel_size);

     

       425
       425
       +
           

     

       426
       426
       +
           [

     

       427
       427
       +
             Prompt.{ 

     

       428
       428
       +
               role = `User; 

     

       429
       429
       +
               content = make_text_content "I've generated a random pixel art image for you:"

     

       430
       430
       +
             };

     

       431
       431
       +
             Prompt.{ 

     

       432
       432
       +
               role = `User;

     

       433
       433
       +
               content = make_image_content base64_data "image/png" 

     

       434
       434
       +
             };

     

       435
       435
       +
             Prompt.{ 

     

       436
       436
       +
               role = `User; 

     

       437
       437
       +
               content = make_text_content (Printf.sprintf "Please describe what you see in this %dx%d pixel art."

     

       438
       438
       +
                                            width height)

     

       439
       439
       +
             };

     

       440
       440
       +
             Prompt.{ 

     

       441
       441
       +
               role = `Assistant; 

     

       442
       442
       +
               content = make_text_content "I'll describe what I see in this pixel art image."

     

       443
       443
       +
             }

     

       444
       444
       +
           ]

     

       445
       445
       +
         )

     

       446
       446
       +
       

     

       447
       447
       +
       (* Main function *)

     

       448
       448
       +
       let () =

     

       449
       449
       +
         (* Parse command line arguments *)

     

       450
       450
       +
         let transport_type = ref Stdio in

     

       451
       451
       +
         let args = [

     

       452
       452
       +
           ("--http", Arg.Unit (fun () -> transport_type := Http), 

     

       453
       453
       +
            "Start server with HTTP transport (default is stdio)");

     

       454
       454
       +
         ] in

     

       455
       455
       +
         let usage_msg = "Usage: image_generator_example [--http]" in

     

       456
       456
       +
         Arg.parse args (fun _ -> ()) usage_msg;

     

       457
       457
       +
       

     

       458
       458
       +
         (* Use stderr for direct printing to avoid interfering with JSON-RPC protocol *)

     

       459
       459
       +
         Printf.fprintf stderr "Starting ImageGeneratorServer...\n";

     

       460
       460
       +
         flush stderr;

     

       461
       461
       +
         Log.info "Starting ImageGeneratorServer...";

     

       462
       462
       +
         

     

       463
       463
       +
         (* Configure the server with appropriate capabilities *)

     

       464
       464
       +
         ignore (configure_server server ());

     

       465
       465
       +
         

     

       466
       466
       +
         (* Create and start MCP server with the selected transport *)

     

       467
       467
       +
         let mcp_server = create ~server ~transport:!transport_type () in

     

       468
       468
       +
         start mcp_server

+502

bin/multimodal_example.ml

···

       1
       1
       +
       open Mcp

     

       2
       2
       +
       open Mcp_sdk

     

       3
       3
       +
       open Mcp_server

     

       4
       4
       +
       

     

       5
       5
       +
       (* Multimodal example MCP server *)

     

       6
       6
       +
       

     

       7
       7
       +
       (* Base64 encoding helper *)

     

       8
       8
       +
       module Base64 = struct

     

       9
       9
       +
         let encode_char n =

     

       10
       10
       +
           "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/".[n]

     

       11
       11
       +
           

     

       12
       12
       +
         let encode_block i bytes =

     

       13
       13
       +
           let buffer = Buffer.create 4 in

     

       14
       14
       +
           let b1 = Char.code (String.get bytes (i * 3)) in

     

       15
       15
       +
           let b2 = if i * 3 + 1 < String.length bytes then Char.code (String.get bytes (i * 3 + 1)) else 0 in

     

       16
       16
       +
           let b3 = if i * 3 + 2 < String.length bytes then Char.code (String.get bytes (i * 3 + 2)) else 0 in

     

       17
       17
       +
           

     

       18
       18
       +
           let n = (b1 lsl 16) lor (b2 lsl 8) lor b3 in

     

       19
       19
       +
           Buffer.add_char buffer (encode_char ((n lsr 18) land 63));

     

       20
       20
       +
           Buffer.add_char buffer (encode_char ((n lsr 12) land 63));

     

       21
       21
       +
           

     

       22
       22
       +
           if i * 3 + 1 < String.length bytes then

     

       23
       23
       +
             Buffer.add_char buffer (encode_char ((n lsr 6) land 63))

     

       24
       24
       +
           else

     

       25
       25
       +
             Buffer.add_char buffer '=';

     

       26
       26
       +
             

     

       27
       27
       +
           if i * 3 + 2 < String.length bytes then

     

       28
       28
       +
             Buffer.add_char buffer (encode_char (n land 63))

     

       29
       29
       +
           else

     

       30
       30
       +
             Buffer.add_char buffer '=';

     

       31
       31
       +
           

     

       32
       32
       +
           Buffer.contents buffer

     

       33
       33
       +
           

     

       34
       34
       +
         let encode data =

     

       35
       35
       +
           let buffer = Buffer.create (4 * (String.length data + 2) / 3) in

     

       36
       36
       +
           for i = 0 to (String.length data - 1) / 3 do

     

       37
       37
       +
             Buffer.add_string buffer (encode_block i data)

     

       38
       38
       +
           done;

     

       39
       39
       +
           Buffer.contents buffer

     

       40
       40
       +
       end

     

       41
       41
       +
       

     

       42
       42
       +
       (* Audio generator *)

     

       43
       43
       +
       module AudioGenerator = struct

     

       44
       44
       +
         (* Generate a simple sine wave *)

     

       45
       45
       +
         let generate_sine_wave ~frequency ~duration ~sample_rate ~amplitude =

     

       46
       46
       +
           (* WAV parameters *)

     

       47
       47
       +
           let num_channels = 1 in (* Mono *)

     

       48
       48
       +
           let bits_per_sample = 16 in

     

       49
       49
       +
           let byte_rate = sample_rate * num_channels * bits_per_sample / 8 in

     

       50
       50
       +
           let block_align = num_channels * bits_per_sample / 8 in

     

       51
       51
       +
           let num_samples = int_of_float (float_of_int sample_rate *. duration) in

     

       52
       52
       +
           let data_size = num_samples * block_align in

     

       53
       53
       +
           

     

       54
       54
       +
           (* Create buffer for the WAV data *)

     

       55
       55
       +
           let buffer = Buffer.create (44 + data_size) in

     

       56
       56
       +
           

     

       57
       57
       +
           (* Write WAV header *)

     

       58
       58
       +
           (* "RIFF" chunk *)

     

       59
       59
       +
           Buffer.add_string buffer "RIFF";

     

       60
       60
       +
           let file_size = 36 + data_size in

     

       61
       61
       +
           Buffer.add_char buffer (Char.chr (file_size land 0xff));

     

       62
       62
       +
           Buffer.add_char buffer (Char.chr ((file_size lsr 8) land 0xff));

     

       63
       63
       +
           Buffer.add_char buffer (Char.chr ((file_size lsr 16) land 0xff));

     

       64
       64
       +
           Buffer.add_char buffer (Char.chr ((file_size lsr 24) land 0xff));

     

       65
       65
       +
           Buffer.add_string buffer "WAVE";

     

       66
       66
       +
           

     

       67
       67
       +
           (* "fmt " sub-chunk *)

     

       68
       68
       +
           Buffer.add_string buffer "fmt ";

     

       69
       69
       +
           Buffer.add_char buffer (Char.chr 16); (* Sub-chunk size (16 for PCM) *)

     

       70
       70
       +
           Buffer.add_char buffer (Char.chr 0);

     

       71
       71
       +
           Buffer.add_char buffer (Char.chr 0);

     

       72
       72
       +
           Buffer.add_char buffer (Char.chr 0);

     

       73
       73
       +
           Buffer.add_char buffer (Char.chr 1); (* Audio format (1 for PCM) *)

     

       74
       74
       +
           Buffer.add_char buffer (Char.chr 0);

     

       75
       75
       +
           Buffer.add_char buffer (Char.chr num_channels); (* Number of channels *)

     

       76
       76
       +
           Buffer.add_char buffer (Char.chr 0);

     

       77
       77
       +
           

     

       78
       78
       +
           (* Sample rate *)

     

       79
       79
       +
           Buffer.add_char buffer (Char.chr (sample_rate land 0xff));

     

       80
       80
       +
           Buffer.add_char buffer (Char.chr ((sample_rate lsr 8) land 0xff));

     

       81
       81
       +
           Buffer.add_char buffer (Char.chr ((sample_rate lsr 16) land 0xff));

     

       82
       82
       +
           Buffer.add_char buffer (Char.chr ((sample_rate lsr 24) land 0xff));

     

       83
       83
       +
           

     

       84
       84
       +
           (* Byte rate *)

     

       85
       85
       +
           Buffer.add_char buffer (Char.chr (byte_rate land 0xff));

     

       86
       86
       +
           Buffer.add_char buffer (Char.chr ((byte_rate lsr 8) land 0xff));

     

       87
       87
       +
           Buffer.add_char buffer (Char.chr ((byte_rate lsr 16) land 0xff));

     

       88
       88
       +
           Buffer.add_char buffer (Char.chr ((byte_rate lsr 24) land 0xff));

     

       89
       89
       +
           

     

       90
       90
       +
           (* Block align *)

     

       91
       91
       +
           Buffer.add_char buffer (Char.chr block_align);

     

       92
       92
       +
           Buffer.add_char buffer (Char.chr 0);

     

       93
       93
       +
           

     

       94
       94
       +
           (* Bits per sample *)

     

       95
       95
       +
           Buffer.add_char buffer (Char.chr bits_per_sample);

     

       96
       96
       +
           Buffer.add_char buffer (Char.chr 0);

     

       97
       97
       +
           

     

       98
       98
       +
           (* "data" sub-chunk *)

     

       99
       99
       +
           Buffer.add_string buffer "data";

     

       100
       100
       +
           Buffer.add_char buffer (Char.chr (data_size land 0xff));

     

       101
       101
       +
           Buffer.add_char buffer (Char.chr ((data_size lsr 8) land 0xff));

     

       102
       102
       +
           Buffer.add_char buffer (Char.chr ((data_size lsr 16) land 0xff));

     

       103
       103
       +
           Buffer.add_char buffer (Char.chr ((data_size lsr 24) land 0xff));

     

       104
       104
       +
           

     

       105
       105
       +
           (* Generate sine wave data *)

     

       106
       106
       +
           let max_amplitude = float_of_int (1 lsl (bits_per_sample - 1)) -. 1.0 in

     

       107
       107
       +
           for i = 0 to num_samples - 1 do

     

       108
       108
       +
             let t = float_of_int i /. float_of_int sample_rate in

     

       109
       109
       +
             let value = int_of_float (amplitude *. max_amplitude *. sin (2.0 *. Float.pi *. frequency *. t)) in

     

       110
       110
       +
             (* Write 16-bit sample (little-endian) *)

     

       111
       111
       +
             Buffer.add_char buffer (Char.chr (value land 0xff));

     

       112
       112
       +
             Buffer.add_char buffer (Char.chr ((value lsr 8) land 0xff));

     

       113
       113
       +
           done;

     

       114
       114
       +
           

     

       115
       115
       +
           Buffer.contents buffer

     

       116
       116
       +
       end

     

       117
       117
       +
       

     

       118
       118
       +
       (* Image generator *)

     

       119
       119
       +
       module ImageGenerator = struct

     

       120
       120
       +
         (* Simple PNG generation *)

     

       121
       121
       +
         let generate_simple_image width height color_str =

     

       122
       122
       +
           (* Parse color - expected format: #RRGGBB or #RRGGBBAA *)

     

       123
       123
       +
           let r, g, b, a = 

     

       124
       124
       +
             try

     

       125
       125
       +
               if String.length color_str >= 7 && color_str.[0] = '#' then

     

       126
       126
       +
                 let r = int_of_string ("0x" ^ String.sub color_str 1 2) in

     

       127
       127
       +
                 let g = int_of_string ("0x" ^ String.sub color_str 3 2) in

     

       128
       128
       +
                 let b = int_of_string ("0x" ^ String.sub color_str 5 2) in

     

       129
       129
       +
                 let a = if String.length color_str >= 9 then

     

       130
       130
       +
                          int_of_string ("0x" ^ String.sub color_str 7 2)

     

       131
       131
       +
                        else 255 in

     

       132
       132
       +
                 (r, g, b, a)

     

       133
       133
       +
               else

     

       134
       134
       +
                 (255, 0, 0, 255)  (* Default to red if invalid *)

     

       135
       135
       +
             with _ -> 

     

       136
       136
       +
               (255, 0, 0, 255)  (* Default to red on parsing error *)

     

       137
       137
       +
           in

     

       138
       138
       +
           

     

       139
       139
       +
           (* Create a very simple 1x1 PNG with the specified color *)

     

       140
       140
       +
           (* PNG signature *)

     

       141
       141
       +
           let signature = [137; 80; 78; 71; 13; 10; 26; 10] in

     

       142
       142
       +
           

     

       143
       143
       +
           (* Create buffer for the PNG data *)

     

       144
       144
       +
           let buffer = Buffer.create 100 in

     

       145
       145
       +
           

     

       146
       146
       +
           (* PNG signature *)

     

       147
       147
       +
           List.iter (fun b -> Buffer.add_char buffer (Char.chr b)) signature;

     

       148
       148
       +
           

     

       149
       149
       +
           (* IHDR chunk *)

     

       150
       150
       +
           Buffer.add_char buffer (Char.chr 0); (* length - 13 bytes *)

     

       151
       151
       +
           Buffer.add_char buffer (Char.chr 0);

     

       152
       152
       +
           Buffer.add_char buffer (Char.chr 0);

     

       153
       153
       +
           Buffer.add_char buffer (Char.chr 13);

     

       154
       154
       +
           

     

       155
       155
       +
           Buffer.add_string buffer "IHDR";

     

       156
       156
       +
           

     

       157
       157
       +
           (* Width *)

     

       158
       158
       +
           Buffer.add_char buffer (Char.chr ((width lsr 24) land 0xff));

     

       159
       159
       +
           Buffer.add_char buffer (Char.chr ((width lsr 16) land 0xff));

     

       160
       160
       +
           Buffer.add_char buffer (Char.chr ((width lsr 8) land 0xff));

     

       161
       161
       +
           Buffer.add_char buffer (Char.chr (width land 0xff));

     

       162
       162
       +
           

     

       163
       163
       +
           (* Height *)

     

       164
       164
       +
           Buffer.add_char buffer (Char.chr ((height lsr 24) land 0xff));

     

       165
       165
       +
           Buffer.add_char buffer (Char.chr ((height lsr 16) land 0xff));

     

       166
       166
       +
           Buffer.add_char buffer (Char.chr ((height lsr 8) land 0xff));

     

       167
       167
       +
           Buffer.add_char buffer (Char.chr (height land 0xff));

     

       168
       168
       +
           

     

       169
       169
       +
           Buffer.add_char buffer (Char.chr 8); (* Bit depth - 8 bits per channel *)

     

       170
       170
       +
           Buffer.add_char buffer (Char.chr 6); (* Color type - RGBA *)

     

       171
       171
       +
           Buffer.add_char buffer (Char.chr 0); (* Compression method - deflate *)

     

       172
       172
       +
           Buffer.add_char buffer (Char.chr 0); (* Filter method - adaptive filtering *)

     

       173
       173
       +
           Buffer.add_char buffer (Char.chr 0); (* Interlace method - no interlace *)

     

       174
       174
       +
           

     

       175
       175
       +
           (* IHDR CRC - precomputed for simplicity *)

     

       176
       176
       +
           Buffer.add_char buffer (Char.chr 0);

     

       177
       177
       +
           Buffer.add_char buffer (Char.chr 0);

     

       178
       178
       +
           Buffer.add_char buffer (Char.chr 0);

     

       179
       179
       +
           Buffer.add_char buffer (Char.chr 0);

     

       180
       180
       +
           

     

       181
       181
       +
           (* IDAT chunk - simplified for example *)

     

       182
       182
       +
           let pixels_per_row = width * 4 in

     

       183
       183
       +
           let data_size = (1 + pixels_per_row) * height in

     

       184
       184
       +
           

     

       185
       185
       +
           Buffer.add_char buffer (Char.chr ((data_size lsr 24) land 0xff));

     

       186
       186
       +
           Buffer.add_char buffer (Char.chr ((data_size lsr 16) land 0xff));

     

       187
       187
       +
           Buffer.add_char buffer (Char.chr ((data_size lsr 8) land 0xff));

     

       188
       188
       +
           Buffer.add_char buffer (Char.chr (data_size land 0xff));

     

       189
       189
       +
           

     

       190
       190
       +
           Buffer.add_string buffer "IDAT";

     

       191
       191
       +
           

     

       192
       192
       +
           (* Simple zlib header *)

     

       193
       193
       +
           Buffer.add_char buffer (Char.chr 0x78);

     

       194
       194
       +
           Buffer.add_char buffer (Char.chr 0x01);

     

       195
       195
       +
           

     

       196
       196
       +
           (* Raw image data *)

     

       197
       197
       +
           for _ = 0 to height - 1 do

     

       198
       198
       +
             Buffer.add_char buffer (Char.chr 0); (* Filter type 0 - None *)

     

       199
       199
       +
             for _ = 0 to width - 1 do

     

       200
       200
       +
               Buffer.add_char buffer (Char.chr r);

     

       201
       201
       +
               Buffer.add_char buffer (Char.chr g);

     

       202
       202
       +
               Buffer.add_char buffer (Char.chr b);

     

       203
       203
       +
               Buffer.add_char buffer (Char.chr a);

     

       204
       204
       +
             done

     

       205
       205
       +
           done;

     

       206
       206
       +
           

     

       207
       207
       +
           (* Dummy Adler32 checksum *)

     

       208
       208
       +
           Buffer.add_char buffer (Char.chr 0);

     

       209
       209
       +
           Buffer.add_char buffer (Char.chr 0);

     

       210
       210
       +
           Buffer.add_char buffer (Char.chr 0);

     

       211
       211
       +
           Buffer.add_char buffer (Char.chr 0);

     

       212
       212
       +
           

     

       213
       213
       +
           (* IDAT CRC - precomputed for simplicity *)

     

       214
       214
       +
           Buffer.add_char buffer (Char.chr 0);

     

       215
       215
       +
           Buffer.add_char buffer (Char.chr 0);

     

       216
       216
       +
           Buffer.add_char buffer (Char.chr 0);

     

       217
       217
       +
           Buffer.add_char buffer (Char.chr 0);

     

       218
       218
       +
           

     

       219
       219
       +
           (* IEND chunk *)

     

       220
       220
       +
           Buffer.add_char buffer (Char.chr 0);

     

       221
       221
       +
           Buffer.add_char buffer (Char.chr 0);

     

       222
       222
       +
           Buffer.add_char buffer (Char.chr 0);

     

       223
       223
       +
           Buffer.add_char buffer (Char.chr 0);

     

       224
       224
       +
           

     

       225
       225
       +
           Buffer.add_string buffer "IEND";

     

       226
       226
       +
           

     

       227
       227
       +
           (* IEND CRC - precomputed value *)

     

       228
       228
       +
           Buffer.add_char buffer (Char.chr 0xAE);

     

       229
       229
       +
           Buffer.add_char buffer (Char.chr 0x42);

     

       230
       230
       +
           Buffer.add_char buffer (Char.chr 0x60);

     

       231
       231
       +
           Buffer.add_char buffer (Char.chr 0x82);

     

       232
       232
       +
           

     

       233
       233
       +
           Buffer.contents buffer

     

       234
       234
       +
       end

     

       235
       235
       +
       

     

       236
       236
       +
       (* Helper for extracting values from JSON *)

     

       237
       237
       +
       let get_param_int json name default =

     

       238
       238
       +
         match json with

     

       239
       239
       +
         | `Assoc fields -> begin

     

       240
       240
       +
             match List.assoc_opt name fields with

     

       241
       241
       +
             | Some (`Int i) -> begin

     

       242
       242
       +
                 i

     

       243
       243
       +
               end

     

       244
       244
       +
             | Some (`Float f) -> begin

     

       245
       245
       +
                 int_of_float f

     

       246
       246
       +
               end

     

       247
       247
       +
             | _ -> begin

     

       248
       248
       +
                 default

     

       249
       249
       +
               end

     

       250
       250
       +
           end

     

       251
       251
       +
         | _ -> begin

     

       252
       252
       +
             default

     

       253
       253
       +
           end

     

       254
       254
       +
       

     

       255
       255
       +
       let get_param_float json name default =

     

       256
       256
       +
         match json with

     

       257
       257
       +
         | `Assoc fields -> begin

     

       258
       258
       +
             match List.assoc_opt name fields with

     

       259
       259
       +
             | Some (`Int i) -> begin

     

       260
       260
       +
                 float_of_int i

     

       261
       261
       +
               end

     

       262
       262
       +
             | Some (`Float f) -> begin

     

       263
       263
       +
                 f

     

       264
       264
       +
               end

     

       265
       265
       +
             | _ -> begin

     

       266
       266
       +
                 default

     

       267
       267
       +
               end

     

       268
       268
       +
           end

     

       269
       269
       +
         | _ -> begin

     

       270
       270
       +
             default

     

       271
       271
       +
           end

     

       272
       272
       +
       

     

       273
       273
       +
       let get_param_string json name default =

     

       274
       274
       +
         match json with

     

       275
       275
       +
         | `Assoc fields -> begin

     

       276
       276
       +
             match List.assoc_opt name fields with

     

       277
       277
       +
             | Some (`String s) -> begin

     

       278
       278
       +
                 s

     

       279
       279
       +
               end

     

       280
       280
       +
             | _ -> begin

     

       281
       281
       +
                 default

     

       282
       282
       +
               end

     

       283
       283
       +
           end

     

       284
       284
       +
         | _ -> begin

     

       285
       285
       +
             default

     

       286
       286
       +
           end

     

       287
       287
       +
       

     

       288
       288
       +
       (* Create a server *)

     

       289
       289
       +
       let server = create_server 

     

       290
       290
       +
         ~name:"OCaml MCP Multimodal Example" 

     

       291
       291
       +
         ~version:"0.1.0" 

     

       292
       292
       +
         ~protocol_version:"2024-11-05" 

     

       293
       293
       +
         ()

     

       294
       294
       +
       

     

       295
       295
       +
       (* Define startup and shutdown hooks *)

     

       296
       296
       +
       let startup () =

     

       297
       297
       +
         Printf.fprintf stderr "MultimodalServer is starting up!\n";

     

       298
       298
       +
         flush stderr;

     

       299
       299
       +
         Log.info "MultimodalServer is starting up!"

     

       300
       300
       +
       

     

       301
       301
       +
       let shutdown () =

     

       302
       302
       +
         Printf.fprintf stderr "MultimodalServer is shutting down. Goodbye!\n";

     

       303
       303
       +
         flush stderr;

     

       304
       304
       +
         Log.info "MultimodalServer is shutting down. Goodbye!"

     

       305
       305
       +
       

     

       306
       306
       +
       (* Register the hooks *)

     

       307
       307
       +
       let () =

     

       308
       308
       +
         set_startup_hook server startup;

     

       309
       309
       +
         set_shutdown_hook server shutdown

     

       310
       310
       +
       

     

       311
       311
       +
       (* Define and register a multimodal tool *)

     

       312
       312
       +
       let _ = add_tool server

     

       313
       313
       +
         ~name:"generate_multimodal_response"

     

       314
       314
       +
         ~description:"Generates a response with text, image and audio content"

     

       315
       315
       +
         ~schema_properties:[

     

       316
       316
       +
           ("message", "string", "The text message to include");

     

       317
       317
       +
           ("color", "string", "Color for the image (hex format #RRGGBB)");

     

       318
       318
       +
           ("frequency", "integer", "Frequency for the audio tone in Hz");

     

       319
       319
       +
         ]

     

       320
       320
       +
         ~schema_required:["message"]

     

       321
       321
       +
         (fun args ->

     

       322
       322
       +
           try

     

       323
       323
       +
             let message = get_param_string args "message" "Hello, multimodal world!" in

     

       324
       324
       +
             let color = get_param_string args "color" "#FF0000" in

     

       325
       325
       +
             let frequency = get_param_int args "frequency" 440 in

     

       326
       326
       +
             

     

       327
       327
       +
             (* Generate image *)

     

       328
       328
       +
             let image_data = ImageGenerator.generate_simple_image 100 100 color in

     

       329
       329
       +
             let image_base64 = Base64.encode image_data in

     

       330
       330
       +
             

     

       331
       331
       +
             (* Generate audio *)

     

       332
       332
       +
             let audio_data = AudioGenerator.generate_sine_wave 

     

       333
       333
       +
               ~frequency:(float_of_int frequency) 

     

       334
       334
       +
               ~duration:1.0 

     

       335
       335
       +
               ~sample_rate:8000 

     

       336
       336
       +
               ~amplitude:0.8 in

     

       337
       337
       +
             let audio_base64 = Base64.encode audio_data in

     

       338
       338
       +
             

     

       339
       339
       +
             (* Create a response with text, image and audio content *)

     

       340
       340
       +
             CallToolResult.yojson_of_t CallToolResult.{

     

       341
       341
       +
               content = [

     

       342
       342
       +
                 Text TextContent.{ 

     

       343
       343
       +
                   text = message;

     

       344
       344
       +
                   annotations = None 

     

       345
       345
       +
                 };

     

       346
       346
       +
                 Image ImageContent.{ 

     

       347
       347
       +
                   data = image_base64; 

     

       348
       348
       +
                   mime_type = "image/png"; 

     

       349
       349
       +
                   annotations = None 

     

       350
       350
       +
                 };

     

       351
       351
       +
                 Audio AudioContent.{ 

     

       352
       352
       +
                   data = audio_base64; 

     

       353
       353
       +
                   mime_type = "audio/wav"; 

     

       354
       354
       +
                   annotations = None 

     

       355
       355
       +
                 }

     

       356
       356
       +
               ];

     

       357
       357
       +
               is_error = false;

     

       358
       358
       +
               meta = None

     

       359
       359
       +
             }

     

       360
       360
       +
           with

     

       361
       361
       +
           | Failure msg ->

     

       362
       362
       +
             Log.error (Printf.sprintf "Error in multimodal tool: %s" msg);

     

       363
       363
       +
             CallToolResult.yojson_of_t CallToolResult.{

     

       364
       364
       +
               content = [

     

       365
       365
       +
                 Text TextContent.{ 

     

       366
       366
       +
                   text = Printf.sprintf "Error: %s" msg; 

     

       367
       367
       +
                   annotations = None 

     

       368
       368
       +
                 }

     

       369
       369
       +
               ];

     

       370
       370
       +
               is_error = true;

     

       371
       371
       +
               meta = None

     

       372
       372
       +
             }

     

       373
       373
       +
         )

     

       374
       374
       +
       

     

       375
       375
       +
       (* Define and register a multimodal prompt *)

     

       376
       376
       +
       let _ = add_prompt server

     

       377
       377
       +
         ~name:"multimodal-prompt"

     

       378
       378
       +
         ~description:"A prompt that includes text, image, and audio"

     

       379
       379
       +
         ~arguments:[

     

       380
       380
       +
           ("message", Some "Text message to include", true);

     

       381
       381
       +
           ("color", Some "Color for the image (hex format #RRGGBB)", false);

     

       382
       382
       +
           ("frequency", Some "Frequency for the audio tone in Hz", false);

     

       383
       383
       +
         ]

     

       384
       384
       +
         (fun args ->

     

       385
       385
       +
           (* Parse parameters with defaults *)

     

       386
       386
       +
           let message = 

     

       387
       387
       +
             try List.assoc "message" args

     

       388
       388
       +
             with Not_found -> "Hello, multimodal world!"

     

       389
       389
       +
           in

     

       390
       390
       +
           

     

       391
       391
       +
           let color = 

     

       392
       392
       +
             try List.assoc "color" args

     

       393
       393
       +
             with Not_found -> "#0000FF"

     

       394
       394
       +
           in

     

       395
       395
       +
           

     

       396
       396
       +
           let frequency = 

     

       397
       397
       +
             try int_of_string (List.assoc "frequency" args)

     

       398
       398
       +
             with _ -> 440

     

       399
       399
       +
           in

     

       400
       400
       +
           

     

       401
       401
       +
           (* Generate image *)

     

       402
       402
       +
           let image_data = ImageGenerator.generate_simple_image 100 100 color in

     

       403
       403
       +
           let image_base64 = Base64.encode image_data in

     

       404
       404
       +
           

     

       405
       405
       +
           (* Generate audio *)

     

       406
       406
       +
           let audio_data = AudioGenerator.generate_sine_wave 

     

       407
       407
       +
             ~frequency:(float_of_int frequency) 

     

       408
       408
       +
             ~duration:1.0 

     

       409
       409
       +
             ~sample_rate:8000 

     

       410
       410
       +
             ~amplitude:0.8 in

     

       411
       411
       +
           let audio_base64 = Base64.encode audio_data in

     

       412
       412
       +
           

     

       413
       413
       +
           (* Create a multimodal prompt *)

     

       414
       414
       +
           [

     

       415
       415
       +
             Prompt.{ 

     

       416
       416
       +
               role = `User; 

     

       417
       417
       +
               content = make_text_content "Here's a multimodal message with text, image, and audio:"

     

       418
       418
       +
             };

     

       419
       419
       +
             Prompt.{ 

     

       420
       420
       +
               role = `User; 

     

       421
       421
       +
               content = make_text_content message

     

       422
       422
       +
             };

     

       423
       423
       +
             Prompt.{ 

     

       424
       424
       +
               role = `User;

     

       425
       425
       +
               content = make_image_content image_base64 "image/png"

     

       426
       426
       +
             };

     

       427
       427
       +
             Prompt.{ 

     

       428
       428
       +
               role = `User;

     

       429
       429
       +
               content = make_audio_content audio_base64 "audio/wav"

     

       430
       430
       +
             };

     

       431
       431
       +
             Prompt.{ 

     

       432
       432
       +
               role = `Assistant; 

     

       433
       433
       +
               content = make_text_content "I've received your multimodal message with text, image, and audio."

     

       434
       434
       +
             }

     

       435
       435
       +
           ]

     

       436
       436
       +
         )

     

       437
       437
       +
       

     

       438
       438
       +
       (* Also register a resource prompt example *)

     

       439
       439
       +
       let _ = add_prompt server

     

       440
       440
       +
         ~name:"resource-prompt"

     

       441
       441
       +
         ~description:"A prompt that includes embedded resources"

     

       442
       442
       +
         ~arguments:[

     

       443
       443
       +
           ("resource_id", Some "ID of the resource to include", true);

     

       444
       444
       +
         ]

     

       445
       445
       +
         (fun args ->

     

       446
       446
       +
           (* Sample resource texts *)

     

       447
       447
       +
           let resources = [

     

       448
       448
       +
             ("doc1", "This is the content of document 1.");

     

       449
       449
       +
             ("doc2", "Document 2 contains important information about OCaml.");

     

       450
       450
       +
             ("doc3", "Document 3 explains the MCP protocol in detail.");

     

       451
       451
       +
           ] in

     

       452
       452
       +
           

     

       453
       453
       +
           (* Get the requested resource *)

     

       454
       454
       +
           let resource_id = 

     

       455
       455
       +
             try List.assoc "resource_id" args

     

       456
       456
       +
             with Not_found -> "doc1"

     

       457
       457
       +
           in

     

       458
       458
       +
           

     

       459
       459
       +
           (* Find the resource content *)

     

       460
       460
       +
           let resource_content = 

     

       461
       461
       +
             try List.assoc resource_id resources

     

       462
       462
       +
             with Not_found -> Printf.sprintf "Resource '%s' not found" resource_id

     

       463
       463
       +
           in

     

       464
       464
       +
           

     

       465
       465
       +
           (* Create a prompt with embedded resource *)

     

       466
       466
       +
           [

     

       467
       467
       +
             Prompt.{ 

     

       468
       468
       +
               role = `User; 

     

       469
       469
       +
               content = make_text_content (Printf.sprintf "Here's the content of resource %s:" resource_id)

     

       470
       470
       +
             };

     

       471
       471
       +
             Prompt.{ 

     

       472
       472
       +
               role = `User;

     

       473
       473
       +
               content = make_text_resource_content (Printf.sprintf "resource://%s" resource_id) resource_content ~mime_type:"text/plain" ()

     

       474
       474
       +
             };

     

       475
       475
       +
             Prompt.{ 

     

       476
       476
       +
               role = `User; 

     

       477
       477
       +
               content = make_text_content "Please analyze this content."

     

       478
       478
       +
             };

     

       479
       479
       +
             Prompt.{ 

     

       480
       480
       +
               role = `Assistant; 

     

       481
       481
       +
               content = make_text_content "I'll analyze the resource content for you."

     

       482
       482
       +
             }

     

       483
       483
       +
           ]

     

       484
       484
       +
         )

     

       485
       485
       +
       

     

       486
       486
       +
       (* Main function *)

     

       487
       487
       +
       let () =

     

       488
       488
       +
         (* Parse command line arguments *)

     

       489
       489
       +
         let transport_type = ref Stdio in

     

       490
       490
       +
         let args = [

     

       491
       491
       +
           ("--http", Arg.Unit (fun () -> transport_type := Http), 

     

       492
       492
       +
            "Start server with HTTP transport (default is stdio)");

     

       493
       493
       +
         ] in

     

       494
       494
       +
         let usage_msg = "Usage: multimodal_example [--http]" in

     

       495
       495
       +
         Arg.parse args (fun _ -> ()) usage_msg;

     

       496
       496
       +
       

     

       497
       497
       +
         (* Configure the server with appropriate capabilities *)

     

       498
       498
       +
         let server = configure_server server ~with_tools:true ~with_resources:false ~with_prompts:true () in

     

       499
       499
       +
         

     

       500
       500
       +
         (* Create and start MCP server with the selected transport *)

     

       501
       501
       +
         let mcp_server = create ~server ~transport:!transport_type () in

     

       502
       502
       +
         start mcp_server;

-370

bin/multimodal_sdk.ml

···

       1
       1
       -
       open Mcp_sdk

     

       2
       2
       -
       

     

       3
       3
       -
       (* Helper for extracting string value from JSON *)

     

       4
       4
       -
       let get_string_param json name =

     

       5
       5
       -
         match json with

     

       6
       6
       -
         | `Assoc fields ->

     

       7
       7
       -
           (match List.assoc_opt name fields with

     

       8
       8
       -
           | Some (`String value) -> value

     

       9
       9
       -
           | _ -> raise (Failure (Printf.sprintf "Missing or invalid parameter: %s" name)))

     

       10
       10
       -
         | _ -> raise (Failure "Expected JSON object")

     

       11
       11
       -
       

     

       12
       12
       -
       (* Helper for extracting integer value from JSON *)

     

       13
       13
       -
       let get_int_param json name =

     

       14
       14
       -
         match json with

     

       15
       15
       -
         | `Assoc fields ->

     

       16
       16
       -
           (match List.assoc_opt name fields with

     

       17
       17
       -
           | Some (`Int value) -> value

     

       18
       18
       -
           | Some (`String value) -> int_of_string value

     

       19
       19
       -
           | _ -> raise (Failure (Printf.sprintf "Missing or invalid parameter: %s" name)))

     

       20
       20
       -
         | _ -> raise (Failure "Expected JSON object")

     

       21
       21
       -
       

     

       22
       22
       -
       (* Base64 encoding - simplified version *)

     

       23
       23
       -
       module Base64 = struct

     

       24
       24
       -
         let encode_char idx =

     

       25
       25
       -
           "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/".[idx]

     

       26
       26
       -
         

     

       27
       27
       -
         let encode s =

     

       28
       28
       -
           let len = String.length s in

     

       29
       29
       -
           let result = Bytes.create (((len + 2) / 3) * 4) in

     

       30
       30
       -
           

     

       31
       31
       -
           let rec loop i j =

     

       32
       32
       -
             if i >= len then j

     

       33
       33
       -
             else

     

       34
       34
       -
               let n =

     

       35
       35
       -
                 let n = Char.code s.[i] lsl 16 in

     

       36
       36
       -
                 let n = if i + 1 < len then n lor (Char.code s.[i+1] lsl 8) else n in

     

       37
       37
       -
                 if i + 2 < len then n lor Char.code s.[i+2] else n

     

       38
       38
       -
               in

     

       39
       39
       -
               Bytes.set result j (encode_char ((n lsr 18) land 63));

     

       40
       40
       -
               Bytes.set result (j+1) (encode_char ((n lsr 12) land 63));

     

       41
       41
       -
               Bytes.set result (j+2) 

     

       42
       42
       -
                 (if i + 1 < len then encode_char ((n lsr 6) land 63) else '=');

     

       43
       43
       -
               Bytes.set result (j+3) 

     

       44
       44
       -
                 (if i + 2 < len then encode_char (n land 63) else '=');

     

       45
       45
       -
               loop (i + 3) (j + 4)

     

       46
       46
       -
           in

     

       47
       47
       -
           Bytes.sub_string result 0 (loop 0 0)

     

       48
       48
       -
       end

     

       49
       49
       -
       

     

       50
       50
       -
       (* Generate a simple GIF format image *)

     

       51
       51
       -
       let generate_random_image width height =

     

       52
       52
       -
         (* Ensure dimensions are reasonable *)

     

       53
       53
       -
         let width = min 256 (max 16 width) in  

     

       54
       54
       -
         let height = min 256 (max 16 height) in

     

       55
       55
       -
         

     

       56
       56
       -
         (* Create a buffer for GIF data *)

     

       57
       57
       -
         let buf = Buffer.create 1024 in

     

       58
       58
       -
         

     

       59
       59
       -
         (* GIF Header - "GIF89a" *)

     

       60
       60
       -
         Buffer.add_string buf "GIF89a";

     

       61
       61
       -
         

     

       62
       62
       -
         (* Logical Screen Descriptor *)

     

       63
       63
       -
         (* Width - 2 bytes little endian *)

     

       64
       64
       -
         Buffer.add_char buf (Char.chr (width land 0xff));

     

       65
       65
       -
         Buffer.add_char buf (Char.chr ((width lsr 8) land 0xff));

     

       66
       66
       -
         

     

       67
       67
       -
         (* Height - 2 bytes little endian *)

     

       68
       68
       -
         Buffer.add_char buf (Char.chr (height land 0xff));

     

       69
       69
       -
         Buffer.add_char buf (Char.chr ((height lsr 8) land 0xff));

     

       70
       70
       -
         

     

       71
       71
       -
         (* Packed fields - 1 byte:

     

       72
       72
       -
            Global Color Table Flag - 1 bit (1)

     

       73
       73
       -
            Color Resolution - 3 bits (7 = 8 bits per color)

     

       74
       74
       -
            Sort Flag - 1 bit (0)

     

       75
       75
       -
            Size of Global Color Table - 3 bits (2 = 8 colors) *)

     

       76
       76
       -
         Buffer.add_char buf (Char.chr 0xF2);

     

       77
       77
       -
         

     

       78
       78
       -
         (* Background color index - 1 byte *)

     

       79
       79
       -
         Buffer.add_char buf (Char.chr 0);

     

       80
       80
       -
         

     

       81
       81
       -
         (* Pixel aspect ratio - 1 byte *)

     

       82
       82
       -
         Buffer.add_char buf (Char.chr 0);

     

       83
       83
       -
         

     

       84
       84
       -
         (* Global Color Table - 8 colors x 3 bytes (R,G,B) *)

     

       85
       85
       -
         (* Simple 8-color palette *)

     

       86
       86
       -
         Buffer.add_string buf "\xFF\xFF\xFF"; (* White (0) *)

     

       87
       87
       -
         Buffer.add_string buf "\xFF\x00\x00"; (* Red (1) *)

     

       88
       88
       -
         Buffer.add_string buf "\x00\xFF\x00"; (* Green (2) *)

     

       89
       89
       -
         Buffer.add_string buf "\x00\x00\xFF"; (* Blue (3) *)

     

       90
       90
       -
         Buffer.add_string buf "\xFF\xFF\x00"; (* Yellow (4) *)

     

       91
       91
       -
         Buffer.add_string buf "\xFF\x00\xFF"; (* Magenta (5) *)

     

       92
       92
       -
         Buffer.add_string buf "\x00\xFF\xFF"; (* Cyan (6) *)

     

       93
       93
       -
         Buffer.add_string buf "\x00\x00\x00"; (* Black (7) *)

     

       94
       94
       -
         

     

       95
       95
       -
         (* Graphics Control Extension (optional) *)

     

       96
       96
       -
         Buffer.add_char buf (Char.chr 0x21); (* Extension Introducer *)

     

       97
       97
       -
         Buffer.add_char buf (Char.chr 0xF9); (* Graphic Control Label *)

     

       98
       98
       -
         Buffer.add_char buf (Char.chr 0x04); (* Block Size *)

     

       99
       99
       -
         Buffer.add_char buf (Char.chr 0x01); (* Packed field: 1 bit for transparency *)

     

       100
       100
       -
         Buffer.add_char buf (Char.chr 0x00); (* Delay time (1/100s) - 2 bytes *)

     

       101
       101
       -
         Buffer.add_char buf (Char.chr 0x00);

     

       102
       102
       -
         Buffer.add_char buf (Char.chr 0x00); (* Transparent color index *)

     

       103
       103
       -
         Buffer.add_char buf (Char.chr 0x00); (* Block terminator *)

     

       104
       104
       -
         

     

       105
       105
       -
         (* Image Descriptor *)

     

       106
       106
       -
         Buffer.add_char buf (Char.chr 0x2C); (* Image Separator *)

     

       107
       107
       -
         Buffer.add_char buf (Char.chr 0x00); (* Left position - 2 bytes *)

     

       108
       108
       -
         Buffer.add_char buf (Char.chr 0x00);

     

       109
       109
       -
         Buffer.add_char buf (Char.chr 0x00); (* Top position - 2 bytes *)

     

       110
       110
       -
         Buffer.add_char buf (Char.chr 0x00);

     

       111
       111
       -
         

     

       112
       112
       -
         (* Image width - 2 bytes little endian *)

     

       113
       113
       -
         Buffer.add_char buf (Char.chr (width land 0xff));

     

       114
       114
       -
         Buffer.add_char buf (Char.chr ((width lsr 8) land 0xff));

     

       115
       115
       -
         

     

       116
       116
       -
         (* Image height - 2 bytes little endian *)

     

       117
       117
       -
         Buffer.add_char buf (Char.chr (height land 0xff));

     

       118
       118
       -
         Buffer.add_char buf (Char.chr ((height lsr 8) land 0xff));

     

       119
       119
       -
         

     

       120
       120
       -
         (* Packed fields - 1 byte - no local color table *)

     

       121
       121
       -
         Buffer.add_char buf (Char.chr 0x00);

     

       122
       122
       -
         

     

       123
       123
       -
         (* LZW Minimum Code Size - 1 byte *)

     

       124
       124
       -
         Buffer.add_char buf (Char.chr 0x03); (* Minimum code size 3 for 8 colors *)

     

       125
       125
       -
         

     

       126
       126
       -
         (* Generate a simple image - a checkerboard pattern *)

     

       127
       127
       -
         let step = width / 8 in

     

       128
       128
       -
         let image_data = Buffer.create (width * height / 4) in

     

       129
       129
       -
         

     

       130
       130
       -
         (* Very simple LZW compression - just store raw clear codes and color indexes *)

     

       131
       131
       -
         (* Start with Clear code *)

     

       132
       132
       -
         Buffer.add_char image_data (Char.chr 0x08); (* Clear code 8 *)

     

       133
       133
       -
         

     

       134
       134
       -
         (* For very simple encoding, we'll just use a sequence of color indexes *)

     

       135
       135
       -
         for y = 0 to height - 1 do

     

       136
       136
       -
           for x = 0 to width - 1 do

     

       137
       137
       -
             (* Checkerboard pattern with different colors *)

     

       138
       138
       -
             let color =

     

       139
       139
       -
               if ((x / step) + (y / step)) mod 2 = 0 then

     

       140
       140
       -
                 3  (* Blue *)

     

       141
       141
       -
               else

     

       142
       142
       -
                 1  (* Red *)

     

       143
       143
       -
             in

     

       144
       144
       -
             Buffer.add_char image_data (Char.chr color);

     

       145
       145
       -
           done

     

       146
       146
       -
         done;

     

       147
       147
       -
         

     

       148
       148
       -
         (* End with End of Information code *)

     

       149
       149
       -
         Buffer.add_char image_data (Char.chr 0x09);

     

       150
       150
       -
         

     

       151
       151
       -
         (* Add image data blocks - GIF uses 255-byte max chunks *)

     

       152
       152
       -
         let data = Buffer.contents image_data in

     

       153
       153
       -
         let data_len = String.length data in

     

       154
       154
       -
         let pos = ref 0 in

     

       155
       155
       -
         

     

       156
       156
       -
         while !pos < data_len do

     

       157
       157
       -
           let chunk_size = min 255 (data_len - !pos) in

     

       158
       158
       -
           Buffer.add_char buf (Char.chr chunk_size);

     

       159
       159
       -
           for i = 0 to chunk_size - 1 do

     

       160
       160
       -
             Buffer.add_char buf (String.get data (!pos + i));

     

       161
       161
       -
           done;

     

       162
       162
       -
           pos := !pos + chunk_size;

     

       163
       163
       -
         done;

     

       164
       164
       -
         

     

       165
       165
       -
         (* Zero-length block to end the image data *)

     

       166
       166
       -
         Buffer.add_char buf (Char.chr 0x00);

     

       167
       167
       -
         

     

       168
       168
       -
         (* GIF Trailer *)

     

       169
       169
       -
         Buffer.add_char buf (Char.chr 0x3B);

     

       170
       170
       -
         

     

       171
       171
       -
         (* Base64 encode the GIF data *)

     

       172
       172
       -
         Base64.encode (Buffer.contents buf)

     

       173
       173
       -
       

     

       174
       174
       -
       (* Helper to write 32-bit little endian integer *)

     

       175
       175
       -
       let write_int32_le buf n =

     

       176
       176
       -
         Buffer.add_char buf (Char.chr (n land 0xff));

     

       177
       177
       -
         Buffer.add_char buf (Char.chr ((n lsr 8) land 0xff));

     

       178
       178
       -
         Buffer.add_char buf (Char.chr ((n lsr 16) land 0xff));

     

       179
       179
       -
         Buffer.add_char buf (Char.chr ((n lsr 24) land 0xff))

     

       180
       180
       -
       

     

       181
       181
       -
       (* Helper to write 16-bit little endian integer *)

     

       182
       182
       -
       let write_int16_le buf n =

     

       183
       183
       -
         Buffer.add_char buf (Char.chr (n land 0xff));

     

       184
       184
       -
         Buffer.add_char buf (Char.chr ((n lsr 8) land 0xff))

     

       185
       185
       -
       

     

       186
       186
       -
       (* Generate a simple WAV file with sine wave *)

     

       187
       187
       -
       let generate_sine_wave_audio frequency duration =

     

       188
       188
       -
         (* WAV header *)

     

       189
       189
       -
         let sample_rate = 8000 in

     

       190
       190
       -
         let num_samples = sample_rate * duration in

     

       191
       191
       -
         let header_buf = Buffer.create 44 in

     

       192
       192
       -
         

     

       193
       193
       -
         (* Fill WAV header properly *)

     

       194
       194
       -
         Buffer.add_string header_buf "RIFF";

     

       195
       195
       -
         write_int32_le header_buf (36 + num_samples * 2); (* File size minus 8 *)

     

       196
       196
       -
         Buffer.add_string header_buf "WAVE";

     

       197
       197
       -
         

     

       198
       198
       -
         (* Format chunk *)

     

       199
       199
       -
         Buffer.add_string header_buf "fmt ";

     

       200
       200
       -
         write_int32_le header_buf 16; (* Format chunk size *)

     

       201
       201
       -
         write_int16_le header_buf 1;  (* PCM format *)

     

       202
       202
       -
         write_int16_le header_buf 1;  (* Mono *)

     

       203
       203
       -
         write_int32_le header_buf sample_rate; (* Sample rate *)

     

       204
       204
       -
         write_int32_le header_buf (sample_rate * 2); (* Byte rate *)

     

       205
       205
       -
         write_int16_le header_buf 2;  (* Block align *)

     

       206
       206
       -
         write_int16_le header_buf 16; (* Bits per sample *)

     

       207
       207
       -
         

     

       208
       208
       -
         (* Data chunk *)

     

       209
       209
       -
         Buffer.add_string header_buf "data";

     

       210
       210
       -
         write_int32_le header_buf (num_samples * 2); (* Data size *)

     

       211
       211
       -
         

     

       212
       212
       -
         (* Generate sine wave samples *)

     

       213
       213
       -
         let samples_buf = Buffer.create (num_samples * 2) in

     

       214
       214
       -
         let amplitude = 16384.0 in (* 16-bit with headroom *)

     

       215
       215
       -
         

     

       216
       216
       -
         for i = 0 to num_samples - 1 do

     

       217
       217
       -
           let t = float_of_int i /. float_of_int sample_rate in

     

       218
       218
       -
           let value = amplitude *. sin (2.0 *. Float.pi *. frequency *. t) in

     

       219
       219
       -
           let sample = int_of_float value in

     

       220
       220
       -
           

     

       221
       221
       -
           (* Convert to 16-bit little-endian *)

     

       222
       222
       -
           let sample = if sample < 0 then sample + 65536 else sample in

     

       223
       223
       -
           write_int16_le samples_buf sample;

     

       224
       224
       -
         done;

     

       225
       225
       -
         

     

       226
       226
       -
         (* Combine header and samples, then encode as Base64 *)

     

       227
       227
       -
         let wav_data = Buffer.contents header_buf ^ Buffer.contents samples_buf in

     

       228
       228
       -
         Base64.encode wav_data

     

       229
       229
       -
       

     

       230
       230
       -
       (* Create a server *)

     

       231
       231
       -
       let server = create_server 

     

       232
       232
       -
         ~name:"OCaml MCP Multimodal Example" 

     

       233
       233
       -
         ~version:"0.1.0" 

     

       234
       234
       -
         ~protocol_version:"2024-11-05" () |>

     

       235
       235
       -
         fun server ->

     

       236
       236
       -
           (* Set default capabilities *)

     

       237
       237
       -
           configure_server server ~with_tools:true ~with_resources:true ~with_prompts:true ()

     

       238
       238
       -
       

     

       239
       239
       -
       (* Define and register a multimodal tool that returns text, images, and audio *)

     

       240
       240
       -
       let _ = add_tool server

     

       241
       241
       -
         ~name:"multimodal_demo"

     

       242
       242
       -
         ~description:"Demonstrates multimodal content with text, image, and audio"

     

       243
       243
       -
         ~schema_properties:[

     

       244
       244
       -
           ("width", "integer", "Width of the generated image (pixels)");

     

       245
       245
       -
           ("height", "integer", "Height of the generated image (pixels)");

     

       246
       246
       -
           ("frequency", "integer", "Frequency of the generated audio tone (Hz)");

     

       247
       247
       -
           ("duration", "integer", "Duration of the generated audio (seconds)");

     

       248
       248
       -
           ("message", "string", "Text message to include")

     

       249
       249
       -
         ]

     

       250
       250
       -
         ~schema_required:["message"]

     

       251
       251
       -
         (fun args ->

     

       252
       252
       -
           try

     

       253
       253
       -
             (* Extract parameters with defaults if not provided *)

     

       254
       254
       -
             let message = get_string_param args "message" in

     

       255
       255
       -
             let width = try get_int_param args "width" with _ -> 128 in

     

       256
       256
       -
             let height = try get_int_param args "height" with _ -> 128 in

     

       257
       257
       -
             let frequency = try get_int_param args "frequency" with _ -> 440 in

     

       258
       258
       -
             let duration = try get_int_param args "duration" with _ -> 1 in

     

       259
       259
       -
             

     

       260
       260
       -
             (* Generate image and audio data *)

     

       261
       261
       -
             let image_data = generate_random_image width height in

     

       262
       262
       -
             let audio_data = generate_sine_wave_audio (float_of_int frequency) duration in

     

       263
       263
       -
             

     

       264
       264
       -
             (* Create a multimodal tool result *)

     

       265
       265
       -
             create_tool_result [

     

       266
       266
       -
               Mcp.make_text_content message;

     

       267
       267
       -
               Mcp.make_image_content image_data "image/gif";

     

       268
       268
       -
               Mcp.make_audio_content audio_data "audio/wav"

     

       269
       269
       -
             ] ~is_error:false

     

       270
       270
       -
           with

     

       271
       271
       -
           | Failure msg -> 

     

       272
       272
       -
             Log.error (Printf.sprintf "Error in multimodal tool: %s" msg);

     

       273
       273
       -
             create_tool_result [Mcp.make_text_content (Printf.sprintf "Error: %s" msg)] ~is_error:true

     

       274
       274
       -
         )

     

       275
       275
       -
       

     

       276
       276
       -
       (* Define and register a tool for generating only images *)

     

       277
       277
       -
       let _ = add_tool server

     

       278
       278
       -
         ~name:"generate_image"

     

       279
       279
       -
         ~description:"Generates a random image with specified dimensions"

     

       280
       280
       -
         ~schema_properties:[

     

       281
       281
       -
           ("width", "integer", "Width of the generated image (pixels)");

     

       282
       282
       -
           ("height", "integer", "Height of the generated image (pixels)")

     

       283
       283
       -
         ]

     

       284
       284
       -
         ~schema_required:["width"; "height"]

     

       285
       285
       -
         (fun args ->

     

       286
       286
       -
           try

     

       287
       287
       -
             let width = get_int_param args "width" in

     

       288
       288
       -
             let height = get_int_param args "height" in

     

       289
       289
       -
             

     

       290
       290
       -
             if width < 1 || width > 1024 || height < 1 || height > 1024 then

     

       291
       291
       -
               create_tool_result 

     

       292
       292
       -
                 [Mcp.make_text_content "Error: Dimensions must be between 1 and 1024 pixels"] 

     

       293
       293
       -
                 ~is_error:true

     

       294
       294
       -
             else

     

       295
       295
       -
               let image_data = generate_random_image width height in

     

       296
       296
       -
               create_tool_result 

     

       297
       297
       -
                 [Mcp.make_image_content image_data "image/gif"]

     

       298
       298
       -
                 ~is_error:false

     

       299
       299
       -
           with

     

       300
       300
       -
           | Failure msg ->

     

       301
       301
       -
             Log.error (Printf.sprintf "Error in generate_image tool: %s" msg);

     

       302
       302
       -
             create_tool_result [Mcp.make_text_content (Printf.sprintf "Error: %s" msg)] ~is_error:true

     

       303
       303
       -
         )

     

       304
       304
       -
       

     

       305
       305
       -
       (* Define and register a tool for generating only audio *)

     

       306
       306
       -
       let _ = add_tool server

     

       307
       307
       -
         ~name:"generate_audio"

     

       308
       308
       -
         ~description:"Generates an audio tone with specified frequency and duration"

     

       309
       309
       -
         ~schema_properties:[

     

       310
       310
       -
           ("frequency", "integer", "Frequency of the tone in Hz (20-20000)");

     

       311
       311
       -
           ("duration", "integer", "Duration of the tone in seconds (1-10)")

     

       312
       312
       -
         ]

     

       313
       313
       -
         ~schema_required:["frequency"; "duration"]

     

       314
       314
       -
         (fun args ->

     

       315
       315
       -
           try

     

       316
       316
       -
             let frequency = get_int_param args "frequency" in

     

       317
       317
       -
             let duration = get_int_param args "duration" in

     

       318
       318
       -
             

     

       319
       319
       -
             if frequency < 20 || frequency > 20000 then

     

       320
       320
       -
               create_tool_result 

     

       321
       321
       -
                 [Mcp.make_text_content "Error: Frequency must be between 20Hz and 20,000Hz"] 

     

       322
       322
       -
                 ~is_error:true

     

       323
       323
       -
             else if duration < 1 || duration > 10 then

     

       324
       324
       -
               create_tool_result 

     

       325
       325
       -
                 [Mcp.make_text_content "Error: Duration must be between 1 and 10 seconds"] 

     

       326
       326
       -
                 ~is_error:true

     

       327
       327
       -
             else

     

       328
       328
       -
               let audio_data = generate_sine_wave_audio (float_of_int frequency) duration in

     

       329
       329
       -
               create_tool_result 

     

       330
       330
       -
                 [Mcp.make_audio_content audio_data "audio/wav"]

     

       331
       331
       -
                 ~is_error:false

     

       332
       332
       -
           with

     

       333
       333
       -
           | Failure msg ->

     

       334
       334
       -
             Log.error (Printf.sprintf "Error in generate_audio tool: %s" msg);

     

       335
       335
       -
             create_tool_result [Mcp.make_text_content (Printf.sprintf "Error: %s" msg)] ~is_error:true

     

       336
       336
       -
         )

     

       337
       337
       -
       

     

       338
       338
       -
       (* Define and register a resource example with multimodal content *)

     

       339
       339
       -
       let _ = add_resource server

     

       340
       340
       -
         ~uri_template:"multimodal://{name}"

     

       341
       341
       -
         ~description:"Get a multimodal greeting with text, image and audio"

     

       342
       342
       -
         ~mime_type:"application/json"

     

       343
       343
       -
         (fun params ->

     

       344
       344
       -
           match params with

     

       345
       345
       -
           | [name] ->

     

       346
       346
       -
             let greeting = Printf.sprintf "Hello, %s! Welcome to the multimodal MCP example." name in

     

       347
       347
       -
             let image_data = generate_random_image 128 128 in

     

       348
       348
       -
             let audio_data = generate_sine_wave_audio 440.0 1 in

     

       349
       349
       -
             

     

       350
       350
       -
             Printf.sprintf {|

     

       351
       351
       -
               {

     

       352
       352
       -
                 "greeting": "%s",

     

       353
       353
       -
                 "image": {

     

       354
       354
       -
                   "data": "%s",

     

       355
       355
       -
                   "mimeType": "image/gif"

     

       356
       356
       -
                 },

     

       357
       357
       -
                 "audio": {

     

       358
       358
       -
                   "data": "%s",

     

       359
       359
       -
                   "mimeType": "audio/wav"

     

       360
       360
       -
                 }

     

       361
       361
       -
               }

     

       362
       362
       -
             |} greeting image_data audio_data

     

       363
       363
       -
           | _ -> Printf.sprintf {|{"error": "Invalid parameters"}|}

     

       364
       364
       -
         )

     

       365
       365
       -
       

     

       366
       366
       -
       (* Run the server with the default scheduler *)

     

       367
       367
       -
       let () =

     

       368
       368
       -
         Random.self_init();  (* Initialize random generator *)

     

       369
       369
       -
         Eio_main.run @@ fun env ->

     

       370
       370
       -
           Mcp_server.run_server env server

-166

bin/ocaml_eval_sdk.ml

···

       1
       1
       -
       open Mcp_sdk

     

       2
       2
       -
       open Mcp_message

     

       3
       3
       -
       

     

       4
       4
       -
       (* Set up the formatter for capturing evaluation output *)

     

       5
       5
       -
       let capture_output f =

     

       6
       6
       -
         let buffer = Buffer.create 1024 in

     

       7
       7
       -
         let fmt = Format.formatter_of_buffer buffer in

     

       8
       8
       -
         let result = f fmt in

     

       9
       9
       -
         Format.pp_print_flush fmt ();

     

       10
       10
       -
         (result, Buffer.contents buffer)

     

       11
       11
       -
       

     

       12
       12
       -
       (* Helper for extracting string value from JSON *)

     

       13
       13
       -
       let get_string_param json name =

     

       14
       14
       -
         match json with

     

       15
       15
       -
         | `Assoc fields ->

     

       16
       16
       -
           (match List.assoc_opt name fields with

     

       17
       17
       -
           | Some (`String value) -> value

     

       18
       18
       -
           | _ -> failwith (Printf.sprintf "Missing or invalid parameter: %s" name))

     

       19
       19
       -
         | _ -> failwith "Expected JSON object"

     

       20
       20
       -
           

     

       21
       21
       -
       (* Initialize the OCaml toploop with standard libraries *)

     

       22
       22
       -
       let initialize_toploop () =

     

       23
       23
       -
         (* Initialize the toplevel environment *)

     

       24
       24
       -
         Toploop.initialize_toplevel_env ();

     

       25
       25
       -
         

     

       26
       26
       -
         (* Set up the toplevel as if using the standard OCaml REPL *)

     

       27
       27
       -
         Clflags.nopervasives := false;

     

       28
       28
       -
         Clflags.real_paths := true;

     

       29
       29
       -
         Clflags.recursive_types := false;

     

       30
       30
       -
         Clflags.strict_sequence := false;

     

       31
       31
       -
         Clflags.applicative_functors := true;

     

       32
       32
       -
         

     

       33
       33
       -
         (* Return success message *)

     

       34
       34
       -
         "OCaml evaluation environment initialized"

     

       35
       35
       -
       

     

       36
       36
       -
       (* Evaluate an OCaml toplevel phrase *)

     

       37
       37
       -
       let evaluate_phrase phrase =

     

       38
       38
       -
         (* Parse the input text as a toplevel phrase *)

     

       39
       39
       -
         let lexbuf = Lexing.from_string phrase in

     

       40
       40
       -
         

     

       41
       41
       -
         (* Capture both success/failure status and output *)

     

       42
       42
       -
         try

     

       43
       43
       -
           let parsed_phrase = !Toploop.parse_toplevel_phrase lexbuf in

     

       44
       44
       -
           let (success, output) = capture_output (fun fmt -> 

     

       45
       45
       -
             Toploop.execute_phrase true fmt parsed_phrase

     

       46
       46
       -
           ) in

     

       47
       47
       -
           

     

       48
       48
       -
           (* Return structured result with status and captured output *)

     

       49
       49
       -
           if success then

     

       50
       50
       -
             `Assoc [

     

       51
       51
       -
               ("success", `Bool true);

     

       52
       52
       -
               ("output", `String output);

     

       53
       53
       -
             ]

     

       54
       54
       -
           else

     

       55
       55
       -
             `Assoc [

     

       56
       56
       -
               ("success", `Bool false);

     

       57
       57
       -
               ("error", `String "Execution failed");

     

       58
       58
       -
               ("output", `String output);

     

       59
       59
       -
             ]

     

       60
       60
       -
         with e ->

     

       61
       61
       -
           (* Handle parsing or other errors with more detailed messages *)

     

       62
       62
       -
           let error_msg = match e with

     

       63
       63
       -
           | Syntaxerr.Error err -> 

     

       64
       64
       -
               let msg = match err with

     

       65
       65
       -
               | Syntaxerr.Unclosed _ -> "Syntax error: Unclosed delimiter"

     

       66
       66
       -
               | Syntaxerr.Expecting _ -> "Syntax error: Expecting a different token"

     

       67
       67
       -
               | Syntaxerr.Not_expecting _ -> "Syntax error: Unexpected token"

     

       68
       68
       -
               | Syntaxerr.Applicative_path _ -> "Syntax error: Invalid applicative path"

     

       69
       69
       -
               | Syntaxerr.Variable_in_scope _ -> "Syntax error: Variable in scope"

     

       70
       70
       -
               | Syntaxerr.Other _ -> "Syntax error"

     

       71
       71
       -
               | _ -> "Syntax error (unknown kind)"

     

       72
       72
       -
               in

     

       73
       73
       -
               msg

     

       74
       74
       -
                 

     

       75
       75
       -
           | Lexer.Error (err, _) -> 

     

       76
       76
       -
               let msg = match err with

     

       77
       77
       -
               | Lexer.Illegal_character _ -> "Lexer error: Illegal character"

     

       78
       78
       -
               | Lexer.Illegal_escape _ -> "Lexer error: Illegal escape sequence"

     

       79
       79
       -
               | Lexer.Unterminated_comment _ -> "Lexer error: Unterminated comment"

     

       80
       80
       -
               | Lexer.Unterminated_string -> "Lexer error: Unterminated string"

     

       81
       81
       -
               | Lexer.Unterminated_string_in_comment _ -> "Lexer error: Unterminated string in comment"

     

       82
       82
       -
               | Lexer.Invalid_literal _ -> "Lexer error: Invalid literal"

     

       83
       83
       -
               | _ -> "Lexer error (unknown kind)"

     

       84
       84
       -
               in 

     

       85
       85
       -
               msg

     

       86
       86
       -
           | _ -> Printexc.to_string e

     

       87
       87
       -
           in

     

       88
       88
       -
           `Assoc [

     

       89
       89
       -
             ("success", `Bool false);

     

       90
       90
       -
             ("error", `String error_msg);

     

       91
       91
       -
           ]

     

       92
       92
       -
       

     

       93
       93
       -
       (* Create evaluation server *)

     

       94
       94
       -
       let server = create_server 

     

       95
       95
       -
         ~name:"OCaml Evaluation Server" 

     

       96
       96
       -
         ~version:"0.1.0" () |>

     

       97
       97
       -
         fun server ->

     

       98
       98
       -
           (* Set default capabilities *)

     

       99
       99
       -
           configure_server server ~with_tools:true ()

     

       100
       100
       -
       

     

       101
       101
       -
       (* Toplevel environment state management *)

     

       102
       102
       -
       let toplevel_initialized = ref false

     

       103
       103
       -
       

     

       104
       104
       -
       (* Initialize OCaml toplevel on first use *)

     

       105
       105
       -
       let ensure_toploop_initialized () =

     

       106
       106
       -
         if not !toplevel_initialized then begin

     

       107
       107
       -
           let _ = initialize_toploop () in

     

       108
       108
       -
           toplevel_initialized := true;

     

       109
       109
       -
         end

     

       110
       110
       -
       

     

       111
       111
       -
       (* Register eval tool *)

     

       112
       112
       -
       let _ = add_tool server

     

       113
       113
       -
         ~name:"ocaml_eval"

     

       114
       114
       -
         ~description:"Evaluates OCaml toplevel phrases and returns the result"

     

       115
       115
       -
         ~schema_properties:[

     

       116
       116
       -
           ("code", "string", "OCaml code to evaluate")

     

       117
       117
       -
         ]

     

       118
       118
       -
         ~schema_required:["code"]

     

       119
       119
       -
         (fun args ->

     

       120
       120
       -
           ensure_toploop_initialized ();

     

       121
       121
       -
           

     

       122
       122
       -
           try

     

       123
       123
       -
             (* Extract code parameter *)

     

       124
       124
       -
             let code = get_string_param args "code" in

     

       125
       125
       -
             

     

       126
       126
       -
             (* Execute the code *)

     

       127
       127
       -
             let result = evaluate_phrase code in

     

       128
       128
       -
             

     

       129
       129
       -
             (* Return formatted result *)

     

       130
       130
       -
             let success = match result with

     

       131
       131
       -
               | `Assoc fields -> (

     

       132
       132
       -
                 match List.assoc_opt "success" fields with

     

       133
       133
       -
                 | Some (`Bool true) -> true

     

       134
       134
       -
                 | _ -> false

     

       135
       135
       -
               )

     

       136
       136
       -
               | _ -> false

     

       137
       137
       -
             in

     

       138
       138
       -
             

     

       139
       139
       -
             let output = match result with

     

       140
       140
       -
               | `Assoc fields -> (

     

       141
       141
       -
                 match List.assoc_opt "output" fields with

     

       142
       142
       -
                 | Some (`String s) -> s

     

       143
       143
       -
                 | _ -> (

     

       144
       144
       -
                   match List.assoc_opt "error" fields with

     

       145
       145
       -
                   | Some (`String s) -> s

     

       146
       146
       -
                   | _ -> "Unknown result"

     

       147
       147
       -
                 )

     

       148
       148
       -
               )

     

       149
       149
       -
               | _ -> "Unknown result"

     

       150
       150
       -
             in

     

       151
       151
       -
             

     

       152
       152
       -
             (* Create a tool result with colorized output *)

     

       153
       153
       -
             create_tool_result [

     

       154
       154
       -
               Mcp.make_text_content output

     

       155
       155
       -
             ] ~is_error:(not success)

     

       156
       156
       -
             

     

       157
       157
       -
           with

     

       158
       158
       -
           | Failure msg ->

     

       159
       159
       -
             Log.error (Printf.sprintf "Error in OCaml eval tool: %s" msg);

     

       160
       160
       -
             create_tool_result [Mcp.make_text_content (Printf.sprintf "Error: %s" msg)] ~is_error:true

     

       161
       161
       -
         )

     

       162
       162
       -
       

     

       163
       163
       -
       (* Run the server with the default scheduler *)

     

       164
       164
       -
       let () =

     

       165
       165
       -
         Eio_main.run @@ fun env->

     

       166
       166
       -
           Mcp_server.run_server env server

+186

bin/resource_template_example.ml

···

       1
       1
       +
       open Mcp

     

       2
       2
       +
       open Mcp_sdk

     

       3
       3
       +
       open Mcp_server

     

       4
       4
       +
       

     

       5
       5
       +
       (* Helper for extracting string value from JSON *)

     

       6
       6
       +
       let get_string_param json name =

     

       7
       7
       +
         match json with

     

       8
       8
       +
         | `Assoc fields ->

     

       9
       9
       +
           (match List.assoc_opt name fields with

     

       10
       10
       +
           | Some (`String value) -> value

     

       11
       11
       +
           | _ -> raise (Failure (Printf.sprintf "Missing or invalid parameter: %s" name)))

     

       12
       12
       +
         | _ -> raise (Failure "Expected JSON object")

     

       13
       13
       +
       

     

       14
       14
       +
       (* Create a server *)

     

       15
       15
       +
       let server = create_server 

     

       16
       16
       +
         ~name:"OCaml MCP Resource Template Example" 

     

       17
       17
       +
         ~version:"0.1.0" 

     

       18
       18
       +
         ~protocol_version:"2024-11-05" 

     

       19
       19
       +
         ()

     

       20
       20
       +
       

     

       21
       21
       +
       (* Define startup and shutdown hooks *)

     

       22
       22
       +
       let startup () =

     

       23
       23
       +
         (* Use stderr for direct printing to avoid interfering with JSON-RPC protocol *)

     

       24
       24
       +
         Printf.fprintf stderr "ResourceTemplateServer is starting up!\n";

     

       25
       25
       +
         flush stderr;

     

       26
       26
       +
         Log.info "ResourceTemplateServer is starting up!"

     

       27
       27
       +
       

     

       28
       28
       +
       let shutdown () =

     

       29
       29
       +
         Printf.fprintf stderr "ResourceTemplateServer is shutting down. Goodbye!\n";

     

       30
       30
       +
         flush stderr;

     

       31
       31
       +
         Log.info "ResourceTemplateServer is shutting down. Goodbye!"

     

       32
       32
       +
       

     

       33
       33
       +
       (* Register the hooks *)

     

       34
       34
       +
       let () =

     

       35
       35
       +
         set_startup_hook server startup;

     

       36
       36
       +
         set_shutdown_hook server shutdown

     

       37
       37
       +
       

     

       38
       38
       +
       (* Database of "documents" *)

     

       39
       39
       +
       let documents = [

     

       40
       40
       +
         ("doc1", "This is the first document content");

     

       41
       41
       +
         ("doc2", "This document contains information about OCaml");

     

       42
       42
       +
         ("doc3", "MCP protocol is a standard for LLM-based applications");

     

       43
       43
       +
         ("doc4", "Resource templates allow for parameterized resources");

     

       44
       44
       +
       ]

     

       45
       45
       +
       

     

       46
       46
       +
       (* Define and register a resource template for documents *)

     

       47
       47
       +
       let _ = add_resource server

     

       48
       48
       +
         ~uri_template:"document://{id}"

     

       49
       49
       +
         ~description:"Get a document by ID"

     

       50
       50
       +
         ~mime_type:"text/plain"

     

       51
       51
       +
         (fun params ->

     

       52
       52
       +
           match params with

     

       53
       53
       +
           | [id] -> 

     

       54
       54
       +
               begin

     

       55
       55
       +
                 try

     

       56
       56
       +
                   let content = List.assoc id documents in

     

       57
       57
       +
                   content

     

       58
       58
       +
                 with Not_found -> 

     

       59
       59
       +
                   Printf.sprintf "Error: Document '%s' not found" id

     

       60
       60
       +
               end

     

       61
       61
       +
           | _ -> "Error: Invalid document ID"

     

       62
       62
       +
         )

     

       63
       63
       +
       

     

       64
       64
       +
       (* Define and register a list documents resource *)

     

       65
       65
       +
       let _ = add_resource server

     

       66
       66
       +
         ~uri_template:"documents://list"

     

       67
       67
       +
         ~description:"List all available documents"

     

       68
       68
       +
         ~mime_type:"text/plain"

     

       69
       69
       +
         (fun _ ->

     

       70
       70
       +
           let doc_list = 

     

       71
       71
       +
             String.concat "\n" 

     

       72
       72
       +
               (List.map (fun (id, _) -> Printf.sprintf "- %s" id) documents)

     

       73
       73
       +
           in

     

       74
       74
       +
           Printf.sprintf "Available Documents:\n%s" doc_list

     

       75
       75
       +
         )

     

       76
       76
       +
       

     

       77
       77
       +
       (* Define and register a tool that uses resource references *)

     

       78
       78
       +
       let _ = add_tool server

     

       79
       79
       +
         ~name:"get_document"

     

       80
       80
       +
         ~description:"Gets a document by ID using resource references"

     

       81
       81
       +
         ~schema_properties:[

     

       82
       82
       +
           ("document_id", "string", "The ID of the document to retrieve");

     

       83
       83
       +
         ]

     

       84
       84
       +
         ~schema_required:["document_id"]

     

       85
       85
       +
         (fun args ->

     

       86
       86
       +
           try

     

       87
       87
       +
             let doc_id = get_string_param args "document_id" in

     

       88
       88
       +
             

     

       89
       89
       +
             (* Create a resource reference *)

     

       90
       90
       +
             let ref = ResourceReference.{ uri = Printf.sprintf "document://%s" doc_id } in

     

       91
       91
       +
             (* Convert to JSON for logging purposes *)

     

       92
       92
       +
             let _ = ResourceReference.yojson_of_t ref in

     

       93
       93
       +
             

     

       94
       94
       +
             (* Return the reference *)

     

       95
       95
       +
             CallToolResult.yojson_of_t CallToolResult.{

     

       96
       96
       +
               content = [

     

       97
       97
       +
                 Text TextContent.{ text = Printf.sprintf "Resource reference for document %s:" doc_id; annotations = None };

     

       98
       98
       +
                 Resource EmbeddedResource.{ 

     

       99
       99
       +
                   resource = `Text TextResourceContents.{

     

       100
       100
       +
                     uri = Printf.sprintf "document://%s" doc_id;

     

       101
       101
       +
                     text = (try List.assoc doc_id documents with Not_found -> "Not found");

     

       102
       102
       +
                     mime_type = Some "text/plain"

     

       103
       103
       +
                   };

     

       104
       104
       +
                   annotations = None

     

       105
       105
       +
                 }

     

       106
       106
       +
               ];

     

       107
       107
       +
               is_error = false;

     

       108
       108
       +
               meta = None

     

       109
       109
       +
             }

     

       110
       110
       +
           with

     

       111
       111
       +
           | Failure msg ->

     

       112
       112
       +
             Log.error (Printf.sprintf "Error in get_document tool: %s" msg);

     

       113
       113
       +
             CallToolResult.yojson_of_t CallToolResult.{

     

       114
       114
       +
               content = [

     

       115
       115
       +
                 Text TextContent.{ 

     

       116
       116
       +
                   text = Printf.sprintf "Error: %s" msg; 

     

       117
       117
       +
                   annotations = None 

     

       118
       118
       +
                 }

     

       119
       119
       +
               ];

     

       120
       120
       +
               is_error = true;

     

       121
       121
       +
               meta = None

     

       122
       122
       +
             }

     

       123
       123
       +
         )

     

       124
       124
       +
       

     

       125
       125
       +
       (* Define and register a prompt that uses resource templates *)

     

       126
       126
       +
       let _ = add_prompt server

     

       127
       127
       +
         ~name:"document-prompt"

     

       128
       128
       +
         ~description:"A prompt that references document resources"

     

       129
       129
       +
         ~arguments:[

     

       130
       130
       +
           ("document_id", Some "ID of the document to include in the prompt", true);

     

       131
       131
       +
         ]

     

       132
       132
       +
         (fun args ->

     

       133
       133
       +
           let doc_id = 

     

       134
       134
       +
             try List.assoc "document_id" args

     

       135
       135
       +
             with Not_found -> "doc1" (* Default to doc1 *)

     

       136
       136
       +
           in

     

       137
       137
       +
           

     

       138
       138
       +
           let doc_text = 

     

       139
       139
       +
             try List.assoc doc_id documents

     

       140
       140
       +
             with Not_found -> Printf.sprintf "Document '%s' not found" doc_id

     

       141
       141
       +
           in

     

       142
       142
       +
           

     

       143
       143
       +
           [

     

       144
       144
       +
             Prompt.{ 

     

       145
       145
       +
               role = `User; 

     

       146
       146
       +
               content = make_text_content (Printf.sprintf "Please summarize the following document (ID: %s):" doc_id)

     

       147
       147
       +
             };

     

       148
       148
       +
             Prompt.{ 

     

       149
       149
       +
               role = `User; 

     

       150
       150
       +
               content = Resource EmbeddedResource.{

     

       151
       151
       +
                 resource = `Text TextResourceContents.{

     

       152
       152
       +
                   uri = Printf.sprintf "document://%s" doc_id;

     

       153
       153
       +
                   text = doc_text;

     

       154
       154
       +
                   mime_type = Some "text/plain"

     

       155
       155
       +
                 };

     

       156
       156
       +
                 annotations = None

     

       157
       157
       +
               }

     

       158
       158
       +
             };

     

       159
       159
       +
             Prompt.{ 

     

       160
       160
       +
               role = `Assistant; 

     

       161
       161
       +
               content = make_text_content "I'll help summarize this document for you."

     

       162
       162
       +
             }

     

       163
       163
       +
           ]

     

       164
       164
       +
         )

     

       165
       165
       +
       

     

       166
       166
       +
       (* Main function *)

     

       167
       167
       +
       let () =

     

       168
       168
       +
         (* Parse command line arguments *)

     

       169
       169
       +
         let transport_type = ref Stdio in

     

       170
       170
       +
         let args = [

     

       171
       171
       +
           ("--http", Arg.Unit (fun () -> transport_type := Http), 

     

       172
       172
       +
            "Start server with HTTP transport (default is stdio)");

     

       173
       173
       +
         ] in

     

       174
       174
       +
         let usage_msg = "Usage: resource_template_example [--http]" in

     

       175
       175
       +
         Arg.parse args (fun _ -> ()) usage_msg;

     

       176
       176
       +
       

     

       177
       177
       +
         (* Instead of printing directly to stdout which messes up the JSON-RPC protocol,

     

       178
       178
       +
            use the logging system which sends output to stderr *)

     

       179
       179
       +
         Log.info "Starting ResourceTemplateServer...";

     

       180
       180
       +
         

     

       181
       181
       +
         (* Configure the server with appropriate capabilities *)

     

       182
       182
       +
         ignore (configure_server server ());

     

       183
       183
       +
         

     

       184
       184
       +
         (* Create and start MCP server with the selected transport *)

     

       185
       185
       +
         let mcp_server = create ~server ~transport:!transport_type () in

     

       186
       186
       +
         start mcp_server

+365

bin/server.ml

···

       1
       1
       +
       open Mcp

     

       2
       2
       +
       open Jsonrpc

     

       3
       3
       +
       

     

       4
       4
       +
       (* Logging utilities *)

     

       5
       5
       +
       let log_debug msg =

     

       6
       6
       +
         Printf.eprintf "[DEBUG] %s\n" msg;

     

       7
       7
       +
         flush stderr

     

       8
       8
       +
       

     

       9
       9
       +
       let log_error msg =

     

       10
       10
       +
         Printf.eprintf "[ERROR] %s\n" msg;

     

       11
       11
       +
         flush stderr

     

       12
       12
       +
       

     

       13
       13
       +
       (* Server state *)

     

       14
       14
       +
       let protocol_version = "2024-11-05"

     

       15
       15
       +
       let server_info = Implementation.{ name = "ocaml-mcp-capitalizer"; version = "0.1.0" }

     

       16
       16
       +
       let server_capabilities = `Assoc [

     

       17
       17
       +
         (* We support tools *)

     

       18
       18
       +
         ("tools", `Assoc [

     

       19
       19
       +
           ("listChanged", `Bool true)

     

       20
       20
       +
         ]);

     

       21
       21
       +
         (* We don't support resources - make this explicit *)

     

       22
       22
       +
         ("resources", `Assoc [

     

       23
       23
       +
           ("listChanged", `Bool false);

     

       24
       24
       +
           ("subscribe", `Bool false)

     

       25
       25
       +
         ]);

     

       26
       26
       +
         (* We don't support prompts - make this explicit *)

     

       27
       27
       +
         ("prompts", `Assoc [

     

       28
       28
       +
           ("listChanged", `Bool false)

     

       29
       29
       +
         ])

     

       30
       30
       +
       ]

     

       31
       31
       +
       

     

       32
       32
       +
       (* Tool implementation *)

     

       33
       33
       +
       module CapitalizeTool = struct

     

       34
       34
       +
         let name = "capitalize"

     

       35
       35
       +
         let description = "Capitalizes the provided text"

     

       36
       36
       +
         let input_schema = `Assoc [

     

       37
       37
       +
           ("type", `String "object");

     

       38
       38
       +
           ("properties", `Assoc [

     

       39
       39
       +
             ("text", `Assoc [

     

       40
       40
       +
               ("type", `String "string");

     

       41
       41
       +
               ("description", `String "The text to capitalize")

     

       42
       42
       +
             ])

     

       43
       43
       +
           ]);

     

       44
       44
       +
           ("required", `List [`String "text"])

     

       45
       45
       +
         ]

     

       46
       46
       +
       

     

       47
       47
       +
         let call json =

     

       48
       48
       +
           match json with

     

       49
       49
       +
           | `Assoc fields ->

     

       50
       50
       +
             (match List.assoc_opt "text" fields with

     

       51
       51
       +
              | Some (`String text) ->

     

       52
       52
       +
                let capitalized_text = String.uppercase_ascii text in

     

       53
       53
       +
                let content = TextContent.{ 

     

       54
       54
       +
                  text = capitalized_text;

     

       55
       55
       +
                  annotations = None 

     

       56
       56
       +
                } in

     

       57
       57
       +
                `Assoc [

     

       58
       58
       +
                  ("content", `List [TextContent.yojson_of_t content]);

     

       59
       59
       +
                  ("isError", `Bool false)

     

       60
       60
       +
                ]

     

       61
       61
       +
              | _ -> 

     

       62
       62
       +
                let error_content = TextContent.{

     

       63
       63
       +
                  text = "Missing or invalid 'text' parameter";

     

       64
       64
       +
                  annotations = None

     

       65
       65
       +
                } in

     

       66
       66
       +
                `Assoc [

     

       67
       67
       +
                  ("content", `List [TextContent.yojson_of_t error_content]);

     

       68
       68
       +
                  ("isError", `Bool true)

     

       69
       69
       +
                ])

     

       70
       70
       +
           | _ ->

     

       71
       71
       +
             let error_content = TextContent.{

     

       72
       72
       +
               text = "Invalid arguments format";

     

       73
       73
       +
               annotations = None

     

       74
       74
       +
             } in

     

       75
       75
       +
             `Assoc [

     

       76
       76
       +
               ("content", `List [TextContent.yojson_of_t error_content]);

     

       77
       77
       +
               ("isError", `Bool true)

     

       78
       78
       +
             ]

     

       79
       79
       +
       end

     

       80
       80
       +
       

     

       81
       81
       +
       (* Handle tool listing *)

     

       82
       82
       +
       let list_tools () =

     

       83
       83
       +
         let tool = `Assoc [

     

       84
       84
       +
           ("name", `String CapitalizeTool.name);

     

       85
       85
       +
           ("description", `String CapitalizeTool.description);

     

       86
       86
       +
           ("inputSchema", CapitalizeTool.input_schema)

     

       87
       87
       +
         ] in

     

       88
       88
       +
         `Assoc [

     

       89
       89
       +
           ("tools", `List [tool])

     

       90
       90
       +
         ]

     

       91
       91
       +
       

     

       92
       92
       +
       (* Handle tool calls *)

     

       93
       93
       +
       let call_tool name args =

     

       94
       94
       +
         if name = CapitalizeTool.name then

     

       95
       95
       +
           CapitalizeTool.call args

     

       96
       96
       +
         else

     

       97
       97
       +
           let error_content = TextContent.{

     

       98
       98
       +
             text = Printf.sprintf "Unknown tool: %s" name;

     

       99
       99
       +
             annotations = None

     

       100
       100
       +
           } in

     

       101
       101
       +
           `Assoc [

     

       102
       102
       +
             ("content", `List [TextContent.yojson_of_t error_content]);

     

       103
       103
       +
             ("isError", `Bool true)

     

       104
       104
       +
           ]

     

       105
       105
       +
       

     

       106
       106
       +
       (* Handle initialization *)

     

       107
       107
       +
       let handle_initialize id json =

     

       108
       108
       +
         try

     

       109
       109
       +
           log_debug (Printf.sprintf "Processing initialize request with id: %s" 

     

       110
       110
       +
             (match id with 

     

       111
       111
       +
              | `Int i -> string_of_int i 

     

       112
       112
       +
              | `String s -> s));

     

       113
       113
       +
           

     

       114
       114
       +
           log_debug (Printf.sprintf "Initialize params: %s" 

     

       115
       115
       +
             (match json with 

     

       116
       116
       +
              | Some j -> Yojson.Safe.to_string j 

     

       117
       117
       +
              | None -> "null"));

     

       118
       118
       +
           

     

       119
       119
       +
           let _ = match json with

     

       120
       120
       +
             | Some params -> 

     

       121
       121
       +
                 log_debug "Parsing initialize request params...";

     

       122
       122
       +
                 let req = Initialize.Request.t_of_yojson params in

     

       123
       123
       +
                 log_debug (Printf.sprintf "Client info: %s v%s" req.client_info.name req.client_info.version);

     

       124
       124
       +
                 log_debug (Printf.sprintf "Client protocol version: %s" req.protocol_version);

     

       125
       125
       +
                 

     

       126
       126
       +
                 (* Check protocol version compatibility *)

     

       127
       127
       +
                 if req.protocol_version <> protocol_version then

     

       128
       128
       +
                   log_debug (Printf.sprintf "Protocol version mismatch: client=%s server=%s - will use server version" 

     

       129
       129
       +
                     req.protocol_version protocol_version);

     

       130
       130
       +
                 

     

       131
       131
       +
                 req

     

       132
       132
       +
             | None -> 

     

       133
       133
       +
                 log_error "Missing params for initialize request";

     

       134
       134
       +
                 raise (Json.Of_json ("Missing params for initialize request", `Null))

     

       135
       135
       +
           in

     

       136
       136
       +
           

     

       137
       137
       +
           log_debug "Creating initialize response...";

     

       138
       138
       +
           let result = Initialize.Result.create

     

       139
       139
       +
             ~capabilities:server_capabilities

     

       140
       140
       +
             ~server_info

     

       141
       141
       +
             ~protocol_version

     

       142
       142
       +
             ~instructions:"This server provides a tool to capitalize text."

     

       143
       143
       +
             ()

     

       144
       144
       +
           in

     

       145
       145
       +
           

     

       146
       146
       +
           log_debug "Serializing initialize response...";

     

       147
       147
       +
           let response = create_response ~id ~result:(Initialize.Result.yojson_of_t result) in

     

       148
       148
       +
           log_debug "Initialize response created successfully";

     

       149
       149
       +
           response

     

       150
       150
       +
         with

     

       151
       151
       +
         | Json.Of_json (msg, _) ->

     

       152
       152
       +
           log_error (Printf.sprintf "JSON error in initialize: %s" msg);

     

       153
       153
       +
           create_error ~id ~code:(-32602) ~message:("Invalid params: " ^ msg) ()

     

       154
       154
       +
         | exc ->

     

       155
       155
       +
           log_error (Printf.sprintf "Exception in initialize: %s" (Printexc.to_string exc));

     

       156
       156
       +
           log_error (Printf.sprintf "Backtrace: %s" (Printexc.get_backtrace()));

     

       157
       157
       +
           create_error ~id ~code:(-32603) ~message:("Internal error: " ^ (Printexc.to_string exc)) ()

     

       158
       158
       +
       

     

       159
       159
       +
       (* Handle tools/list *)

     

       160
       160
       +
       let handle_list_tools id =

     

       161
       161
       +
         log_debug "Processing tools/list request";

     

       162
       162
       +
         let result = list_tools () in

     

       163
       163
       +
         log_debug (Printf.sprintf "Tools list result: %s" (Yojson.Safe.to_string result));

     

       164
       164
       +
         create_response ~id ~result

     

       165
       165
       +
       

     

       166
       166
       +
       (* Handle tools/call *)

     

       167
       167
       +
       let handle_call_tool id json =

     

       168
       168
       +
         try

     

       169
       169
       +
           log_debug (Printf.sprintf "Processing tool call request with id: %s" 

     

       170
       170
       +
             (match id with 

     

       171
       171
       +
              | `Int i -> string_of_int i 

     

       172
       172
       +
              | `String s -> s));

     

       173
       173
       +
           

     

       174
       174
       +
           log_debug (Printf.sprintf "Tool call params: %s" 

     

       175
       175
       +
             (match json with 

     

       176
       176
       +
              | Some j -> Yojson.Safe.to_string j 

     

       177
       177
       +
              | None -> "null"));

     

       178
       178
       +
           

     

       179
       179
       +
           match json with

     

       180
       180
       +
           | Some (`Assoc params) ->

     

       181
       181
       +
             let name = match List.assoc_opt "name" params with

     

       182
       182
       +
               | Some (`String name) -> 

     

       183
       183
       +
                   log_debug (Printf.sprintf "Tool name: %s" name);

     

       184
       184
       +
                   name

     

       185
       185
       +
               | _ -> 

     

       186
       186
       +
                   log_error "Missing or invalid 'name' parameter in tool call";

     

       187
       187
       +
                   raise (Json.Of_json ("Missing or invalid 'name' parameter", `Assoc params))

     

       188
       188
       +
             in

     

       189
       189
       +
             let args = match List.assoc_opt "arguments" params with

     

       190
       190
       +
               | Some (args) -> 

     

       191
       191
       +
                   log_debug (Printf.sprintf "Tool arguments: %s" (Yojson.Safe.to_string args));

     

       192
       192
       +
                   args

     

       193
       193
       +
               | _ -> 

     

       194
       194
       +
                   log_debug "No arguments provided for tool call, using empty object";

     

       195
       195
       +
                   `Assoc [] (* Empty arguments is valid *)

     

       196
       196
       +
             in

     

       197
       197
       +
             log_debug (Printf.sprintf "Calling tool: %s" name);

     

       198
       198
       +
             let result = call_tool name args in

     

       199
       199
       +
             log_debug (Printf.sprintf "Tool call result: %s" (Yojson.Safe.to_string result));

     

       200
       200
       +
             create_response ~id ~result

     

       201
       201
       +
           | _ ->

     

       202
       202
       +
             log_error "Invalid params format for tools/call";

     

       203
       203
       +
             create_error ~id ~code:(-32602) ~message:"Invalid params for tools/call" ()

     

       204
       204
       +
         with

     

       205
       205
       +
         | Json.Of_json (msg, _) ->

     

       206
       206
       +
           log_error (Printf.sprintf "JSON error in tool call: %s" msg);

     

       207
       207
       +
           create_error ~id ~code:(-32602) ~message:("Invalid params: " ^ msg) ()

     

       208
       208
       +
         | exc ->

     

       209
       209
       +
           log_error (Printf.sprintf "Exception in tool call: %s" (Printexc.to_string exc));

     

       210
       210
       +
           log_error (Printf.sprintf "Backtrace: %s" (Printexc.get_backtrace()));

     

       211
       211
       +
           create_error ~id ~code:(-32603) ~message:("Internal error: " ^ (Printexc.to_string exc)) ()

     

       212
       212
       +
       

     

       213
       213
       +
       (* Handle ping *)

     

       214
       214
       +
       let handle_ping id =

     

       215
       215
       +
         create_response ~id ~result:(`Assoc [])

     

       216
       216
       +
       

     

       217
       217
       +
       (* Process a single message *)

     

       218
       218
       +
       let process_message message =

     

       219
       219
       +
         try

     

       220
       220
       +
           log_debug "Parsing message as JSONRPC message...";

     

       221
       221
       +
           match JSONRPCMessage.t_of_yojson message with

     

       222
       222
       +
           | JSONRPCMessage.Request req ->

     

       223
       223
       +
             log_debug (Printf.sprintf "Received request with method: %s" req.method_);

     

       224
       224
       +
             (match req.method_ with

     

       225
       225
       +
              | "initialize" -> 

     

       226
       226
       +
                log_debug "Processing initialize request";

     

       227
       227
       +
                Some (handle_initialize req.id req.params)

     

       228
       228
       +
              | "tools/list" -> 

     

       229
       229
       +
                log_debug "Processing tools/list request";

     

       230
       230
       +
                Some (handle_list_tools req.id)

     

       231
       231
       +
              | "tools/call" -> 

     

       232
       232
       +
                log_debug "Processing tools/call request";

     

       233
       233
       +
                Some (handle_call_tool req.id req.params)

     

       234
       234
       +
              | "ping" -> 

     

       235
       235
       +
                log_debug "Processing ping request";

     

       236
       236
       +
                Some (handle_ping req.id)

     

       237
       237
       +
              | _ -> 

     

       238
       238
       +
                log_error (Printf.sprintf "Unknown method received: %s" req.method_);

     

       239
       239
       +
                Some (create_error ~id:req.id ~code:(-32601) ~message:("Method not found: " ^ req.method_) ()))

     

       240
       240
       +
           | JSONRPCMessage.Notification notif ->

     

       241
       241
       +
             log_debug (Printf.sprintf "Received notification with method: %s" notif.method_);

     

       242
       242
       +
             (match notif.method_ with

     

       243
       243
       +
              | "notifications/initialized" ->

     

       244
       244
       +
                log_debug "Client initialization complete - Server is now ready to receive requests";

     

       245
       245
       +
                log_debug (Printf.sprintf "Notification params: %s" 

     

       246
       246
       +
                  (match notif.params with

     

       247
       247
       +
                   | Some p -> Yojson.Safe.to_string p

     

       248
       248
       +
                   | None -> "null"));

     

       249
       249
       +
                None

     

       250
       250
       +
              | _ ->

     

       251
       251
       +
                log_debug (Printf.sprintf "Ignoring notification: %s" notif.method_);

     

       252
       252
       +
                None)

     

       253
       253
       +
           | JSONRPCMessage.Response _ ->

     

       254
       254
       +
             log_error "Unexpected response message received";

     

       255
       255
       +
             None

     

       256
       256
       +
           | JSONRPCMessage.Error _ ->

     

       257
       257
       +
             log_error "Unexpected error message received";

     

       258
       258
       +
             None

     

       259
       259
       +
         with

     

       260
       260
       +
         | exc ->

     

       261
       261
       +
           log_error (Printf.sprintf "Exception during message processing: %s" (Printexc.to_string exc));

     

       262
       262
       +
           log_error (Printf.sprintf "Backtrace: %s" (Printexc.get_backtrace()));

     

       263
       263
       +
           log_error (Printf.sprintf "Message was: %s" (Yojson.Safe.to_string message));

     

       264
       264
       +
           None

     

       265
       265
       +
       

     

       266
       266
       +
       (* Main loop *)

     

       267
       267
       +
       let rec read_message () =

     

       268
       268
       +
         try

     

       269
       269
       +
           log_debug "Attempting to read line from stdin...";

     

       270
       270
       +
           let line = read_line () in

     

       271
       271
       +
           if line = "" then (

     

       272
       272
       +
             log_debug "Empty line received, ignoring";

     

       273
       273
       +
             None

     

       274
       274
       +
           ) else (

     

       275
       275
       +
             log_debug (Printf.sprintf "Raw input: %s" line);

     

       276
       276
       +
             try

     

       277
       277
       +
               let json = Yojson.Safe.from_string line in

     

       278
       278
       +
               log_debug "Successfully parsed JSON";

     

       279
       279
       +
               Some json

     

       280
       280
       +
             with

     

       281
       281
       +
             | Yojson.Json_error msg -> 

     

       282
       282
       +
               log_error (Printf.sprintf "Error parsing JSON: %s" msg);

     

       283
       283
       +
               log_error (Printf.sprintf "Input was: %s" line);

     

       284
       284
       +
               read_message ()

     

       285
       285
       +
           )

     

       286
       286
       +
         with

     

       287
       287
       +
         | End_of_file -> 

     

       288
       288
       +
           log_debug "End of file received on stdin";

     

       289
       289
       +
           None

     

       290
       290
       +
         | Sys_error msg -> 

     

       291
       291
       +
           log_error (Printf.sprintf "System error while reading: %s" msg);

     

       292
       292
       +
           None

     

       293
       293
       +
         | exc ->

     

       294
       294
       +
           log_error (Printf.sprintf "Exception while reading: %s" (Printexc.to_string exc));

     

       295
       295
       +
           None

     

       296
       296
       +
       

     

       297
       297
       +
       let () =

     

       298
       298
       +
         try

     

       299
       299
       +
           (* Enable exception backtraces *)

     

       300
       300
       +
           Printexc.record_backtrace true;

     

       301
       301
       +
           

     

       302
       302
       +
           (* Enable line buffering for stdout *)

     

       303
       303
       +
           set_binary_mode_out stdout false;

     

       304
       304
       +
           

     

       305
       305
       +
           log_debug "MCP Capitalizer server started";

     

       306
       306
       +
           log_debug (Printf.sprintf "Protocol version: %s" protocol_version);

     

       307
       307
       +
           log_debug (Printf.sprintf "Server info: %s v%s" server_info.name server_info.version);

     

       308
       308
       +
           

     

       309
       309
       +
           (* Print environment info for debugging *)

     

       310
       310
       +
           log_debug "Environment variables:";

     

       311
       311
       +
           Unix.environment()

     

       312
       312
       +
           |> Array.iter (fun s -> 

     

       313
       313
       +
             try

     

       314
       314
       +
               let i = String.index s '=' in

     

       315
       315
       +
               let name = String.sub s 0 i in

     

       316
       316
       +
               if String.length name > 0 then

     

       317
       317
       +
                 log_debug (Printf.sprintf "  %s" s)

     

       318
       318
       +
             with Not_found -> ()

     

       319
       319
       +
           );

     

       320
       320
       +
           

     

       321
       321
       +
           let rec server_loop count =

     

       322
       322
       +
             log_debug (Printf.sprintf "Waiting for message #%d..." count);

     

       323
       323
       +
             match read_message () with

     

       324
       324
       +
             | Some json ->

     

       325
       325
       +
               log_debug (Printf.sprintf "Received message: %s" (Yojson.Safe.to_string json));

     

       326
       326
       +
               (match process_message json with

     

       327
       327
       +
                | Some response ->

     

       328
       328
       +
                  let response_json = JSONRPCMessage.yojson_of_t response in

     

       329
       329
       +
                  let response_str = Yojson.Safe.to_string response_json in

     

       330
       330
       +
                  log_debug (Printf.sprintf "Sending response: %s" response_str);

     

       331
       331
       +
                  (* Make sure we emit properly formatted JSON on a single line with a newline at the end *)

     

       332
       332
       +
                  Printf.printf "%s\n" response_str;

     

       333
       333
       +
                  flush stdout;

     

       334
       334
       +
                  (* Give the client a moment to process the response *)

     

       335
       335
       +
                  Unix.sleepf 0.01;

     

       336
       336
       +
                  server_loop (count + 1)

     

       337
       337
       +
                | None -> 

     

       338
       338
       +
                  log_debug "No response needed for this message";

     

       339
       339
       +
                  server_loop (count + 1))

     

       340
       340
       +
             | None -> 

     

       341
       341
       +
               log_debug "End of input stream, terminating server";

     

       342
       342
       +
               ()

     

       343
       343
       +
           in

     

       344
       344
       +
           

     

       345
       345
       +
           log_debug "Starting server loop...";

     

       346
       346
       +
           log_debug "Waiting for the initialize request...";

     

       347
       347
       +
           

     

       348
       348
       +
           (* Set up signal handler to gracefully exit *)

     

       349
       349
       +
           Sys.(set_signal sigint (Signal_handle (fun _ -> 

     

       350
       350
       +
             log_debug "Received interrupt signal, exiting...";

     

       351
       351
       +
             exit 0

     

       352
       352
       +
           )));

     

       353
       353
       +
           

     

       354
       354
       +
           server_loop 1;

     

       355
       355
       +
           log_debug "Server terminated normally";

     

       356
       356
       +
         with

     

       357
       357
       +
         | End_of_file ->

     

       358
       358
       +
           log_error "Unexpected end of file";

     

       359
       359
       +
         | Sys_error msg ->

     

       360
       360
       +
           log_error (Printf.sprintf "System error: %s" msg);

     

       361
       361
       +
         | Unix.Unix_error(err, func, arg) ->

     

       362
       362
       +
           log_error (Printf.sprintf "Unix error in %s(%s): %s" func arg (Unix.error_message err));

     

       363
       363
       +
         | exc ->

     

       364
       364
       +
           log_error (Printf.sprintf "Unhandled exception: %s" (Printexc.to_string exc));

     

       365
       365
       +
           log_error (Printf.sprintf "Backtrace: %s" (Printexc.get_backtrace()))

bin/server.mli

···

       1
       1
       +
       val process_message : Jsonrpc.Json.t -> Mcp.JSONRPCMessage.t option

     

       2
       2
       +
       val handle_initialize : Jsonrpc.Id.t -> Jsonrpc.Json.t option -> Mcp.JSONRPCMessage.t

     

       3
       3
       +
       val handle_list_tools : Jsonrpc.Id.t -> Mcp.JSONRPCMessage.t

     

       4
       4
       +
       val handle_call_tool : Jsonrpc.Id.t -> Jsonrpc.Json.t option -> Mcp.JSONRPCMessage.t

     

       5
       5
       +
       val handle_ping : Jsonrpc.Id.t -> Mcp.JSONRPCMessage.t

-18

dune-project

···

       1
       1
        
       (lang dune 3.17)

     

       2
       2
       -
       (name mcp)

     

       3
       3
       -
       

     

       4
       4
       -
       (license ISC)

     

       5
       5
       -
       (authors "Anil Madhavapeddy")

     

       6
       6
       -
       (maintainers "anil@recoil.org")

     

       7
       7
       -
       

     

       8
       8
       -
       (generate_opam_files true)

     

       9
       9
       -
       

     

       10
       10
       -
       (package

     

       11
       11
       -
        (name mcp)

     

       12
       12
       -
        (synopsis "Model Context Protocol for LLMs")

     

       13
       13
       -
        (description "This is all still a work in progress")

     

       14
       14
       -
        (depends

     

       15
       15
       -
         (ocaml (>= "5.2.0"))

     

       16
       16
       -
         jsonrpc

     

       17
       17
       -
         eio_main

     

       18
       18
       -
         eio))

     

       19
       19
       -

+3 -13

lib/dune

···

       1
       1
        
       (library

     

       2
       2
        
         (name mcp)

     

       3
       3
       -
         (public_name mcp)

     

       4
       3
        
         (libraries jsonrpc unix yojson)

     

       5
       4
        
         (modules mcp))

     

       6
       6
       -
       

     

       7
       7
       -
       (library

     

       8
       8
       -
         (name mcp_message)

     

       9
       9
       -
         (public_name mcp.message)

     

       10
       10
       -
         (libraries mcp jsonrpc unix yojson)

     

       11
       11
       -
         (modules mcp_message)

     

       12
       12
       -
         (flags (:standard -w -67 -w -27 -w -32 -w -33 -w -34)))

     

       13
       5
        
       

     

       14
       6
        
       (library

     

       15
       7
        
         (name mcp_sdk)

     

       16
       16
       -
         (public_name mcp.sdk)

     

       17
       17
       -
         (libraries mcp mcp_message jsonrpc unix yojson)

     

       8
       8
       +
         (libraries mcp jsonrpc unix yojson)

     

       18
       9
        
         (modules mcp_sdk)

     

       19
       10
        
         (flags (:standard -w -67 -w -27 -w -32)))

     

       20
       11
        
       

     

       21
       12
        
       (library

     

       22
       13
        
         (name mcp_server)

     

       23
       23
       -
         (public_name mcp.server)

     

       24
       24
       -
         (libraries mcp_sdk jsonrpc eio_main eio)

     

       14
       14
       +
         (libraries mcp mcp_sdk jsonrpc unix yojson)

     

       25
       15
        
         (modules mcp_server)

     

       26
       26
       -
       )

     

       16
       16
       +
         (flags (:standard -w -67 -w -27 -w -32 -w -8 -w -11 -w -33)))

+417 -87

lib/mcp.ml

···

       1
       1
        
       open Jsonrpc

     

       2
       2
        
       

     

       3
       3
       -
       (* Error codes for JSON-RPC *)

     

       3
       3
       +
       (* Standard error codes *)

     

       4
       4
        
       module ErrorCode = struct

     

       5
       5
       -
         type t = 

     

       6
       6
       -
           | ParseError       (* -32700 - Invalid JSON *)

     

       7
       7
       -
           | InvalidRequest   (* -32600 - Invalid JSON-RPC request *)

     

       8
       8
       -
           | MethodNotFound   (* -32601 - Method not available *)

     

       9
       9
       -
           | InvalidParams    (* -32602 - Invalid method parameters *)

     

       10
       10
       -
           | InternalError    (* -32603 - Internal JSON-RPC error *)

     

       11
       11
       -
           | ResourceNotFound (* -32002 - Custom MCP error: requested resource not found *)

     

       12
       12
       -
           | AuthRequired     (* -32001 - Custom MCP error: authentication required *)

     

       13
       13
       -
           | CustomError of int (* For any other error codes *)

     

       14
       14
       -
         

     

       15
       15
       -
         (* Convert the error code to its integer representation *)

     

       16
       16
       -
         let to_int = function

     

       17
       17
       -
           | ParseError -> -32700

     

       18
       18
       -
           | InvalidRequest -> -32600

     

       19
       19
       -
           | MethodNotFound -> -32601

     

       20
       20
       -
           | InvalidParams -> -32602

     

       21
       21
       -
           | InternalError -> -32603

     

       22
       22
       -
           | ResourceNotFound -> -32002

     

       23
       23
       -
           | AuthRequired -> -32001

     

       24
       24
       -
           | CustomError code -> code

     

       25
       25
       -
         

     

       26
       26
       -
         (* Get error message for standard error codes *)

     

       27
       27
       -
         let to_message = function

     

       28
       28
       -
           | ParseError -> "Parse error"

     

       29
       29
       -
           | InvalidRequest -> "Invalid Request"

     

       30
       30
       -
           | MethodNotFound -> "Method not found"

     

       31
       31
       -
           | InvalidParams -> "Invalid params"

     

       32
       32
       -
           | InternalError -> "Internal error"

     

       33
       33
       -
           | ResourceNotFound -> "Resource not found"

     

       34
       34
       -
           | AuthRequired -> "Authentication required"

     

       35
       35
       -
           | CustomError _ -> "Error"

     

       36
       36
       -
       end

     

       37
       37
       -
       

     

       38
       38
       -
       (* Protocol method strings *)

     

       39
       39
       -
       module Method = struct

     

       40
       40
       -
         (* Initialization and lifecycle methods *)

     

       41
       41
       -
         let initialize = "initialize"

     

       42
       42
       -
         let initialized = "notifications/initialized"

     

       43
       43
       -
         

     

       44
       44
       -
         (* Resource methods *)

     

       45
       45
       -
         let resources_list = "resources/list"

     

       46
       46
       -
         let resources_read = "resources/read"

     

       47
       47
       -
         let resources_templates_list = "resources/templates/list"

     

       48
       48
       -
         let resources_subscribe = "resources/subscribe"

     

       49
       49
       -
         let resources_list_changed = "notifications/resources/list_changed"

     

       50
       50
       -
         let resources_updated = "notifications/resources/updated"

     

       51
       51
       -
         

     

       52
       52
       -
         (* Tool methods *)

     

       53
       53
       -
         let tools_list = "tools/list"

     

       54
       54
       -
         let tools_call = "tools/call"

     

       55
       55
       -
         let tools_list_changed = "notifications/tools/list_changed"

     

       56
       56
       -
         

     

       57
       57
       -
         (* Prompt methods *)

     

       58
       58
       -
         let prompts_list = "prompts/list"

     

       59
       59
       -
         let prompts_get = "prompts/get"

     

       60
       60
       -
         let prompts_list_changed = "notifications/prompts/list_changed"

     

       61
       61
       -
         

     

       62
       62
       -
         (* Progress notifications *)

     

       63
       63
       -
         let progress = "notifications/progress"

     

       5
       5
       +
         let parse_error = -32700

     

       6
       6
       +
         let invalid_request = -32600

     

       7
       7
       +
         let method_not_found = -32601

     

       8
       8
       +
         let invalid_params = -32602

     

       9
       9
       +
         let internal_error = -32603

     

       10
       10
       +
         let resource_not_found = -32002

     

       11
       11
       +
         let server_error_start = -32000

     

       12
       12
       +
         let server_error_end = -32099

     

       64
       13
        
       end

     

       65
       14
        
       

     

       66
       15
        
       (* Common types *)

     
···

       191
       140
        
       

     

       192
       141
        
         let yojson_of_t { data; mime_type; annotations } =

     

       193
       142
        
           let assoc = [

     

       194
       194
       -
             ("type", `String "image");

     

       195
       143
        
             ("data", `String data);

     

       196
       144
        
             ("mimeType", `String mime_type);

     

       145
       145
       +
             ("type", `String "image");

     

       197
       146
        
           ] in

     

       198
       147
        
           let assoc = match annotations with

     

       199
       148
        
             | Some annotations -> ("annotations", Annotated.yojson_of_annotation annotations) :: assoc

     
···

       229
       178
        
       

     

       230
       179
        
         let yojson_of_t { data; mime_type; annotations } =

     

       231
       180
        
           let assoc = [

     

       232
       232
       -
             ("type", `String "audio");

     

       233
       181
        
             ("data", `String data);

     

       234
       182
        
             ("mimeType", `String mime_type);

     

       183
       183
       +
             ("type", `String "audio");

     

       235
       184
        
           ] in

     

       236
       185
        
           let assoc = match annotations with

     

       237
       186
        
             | Some annotations -> ("annotations", Annotated.yojson_of_annotation annotations) :: assoc

     
···

       402
       351
        
           | j -> raise (Json.Of_json ("Expected object for EmbeddedResource", j))

     

       403
       352
        
       end

     

       404
       353
        
       

     

       354
       354
       +
       (** Tool definition *)

     

       355
       355
       +
       module Tool = struct

     

       356
       356
       +
         type t = {

     

       357
       357
       +
           name: string;

     

       358
       358
       +
           description: string option;

     

       359
       359
       +
           input_schema: Json.t;

     

       360
       360
       +
         }

     

       361
       361
       +
       

     

       362
       362
       +
         let yojson_of_t { name; description; input_schema } =

     

       363
       363
       +
           let assoc = [

     

       364
       364
       +
             ("name", `String name);

     

       365
       365
       +
             ("inputSchema", input_schema);

     

       366
       366
       +
           ] in

     

       367
       367
       +
           let assoc = match description with

     

       368
       368
       +
             | Some desc -> ("description", `String desc) :: assoc

     

       369
       369
       +
             | None -> assoc

     

       370
       370
       +
           in

     

       371
       371
       +
           `Assoc assoc

     

       372
       372
       +
       

     

       373
       373
       +
         let t_of_yojson = function

     

       374
       374
       +
           | `Assoc fields ->

     

       375
       375
       +
             let name = match List.assoc_opt "name" fields with

     

       376
       376
       +
               | Some (`String s) -> s

     

       377
       377
       +
               | _ -> raise (Json.Of_json ("Missing or invalid 'name' field", `Assoc fields))

     

       378
       378
       +
             in

     

       379
       379
       +
             let description = match List.assoc_opt "description" fields with

     

       380
       380
       +
               | Some (`String s) -> Some s

     

       381
       381
       +
               | _ -> None

     

       382
       382
       +
             in

     

       383
       383
       +
             let input_schema = match List.assoc_opt "inputSchema" fields with

     

       384
       384
       +
               | Some json -> json

     

       385
       385
       +
               | _ -> raise (Json.Of_json ("Missing 'inputSchema' field", `Assoc fields))

     

       386
       386
       +
             in

     

       387
       387
       +
             { name; description; input_schema }

     

       388
       388
       +
           | j -> raise (Json.Of_json ("Expected object for Tool", j))

     

       389
       389
       +
       end

     

       390
       390
       +
       

     

       405
       391
        
       type content = 

     

       406
       392
        
         | Text of TextContent.t

     

       407
       393
        
         | Image of ImageContent.t

     
···

       424
       410
        
            | _ -> raise (Json.Of_json ("Invalid or missing content type", `Assoc fields)))

     

       425
       411
        
         | j -> raise (Json.Of_json ("Expected object for content", j))

     

       426
       412
        
       

     

       413
       413
       +
       (** Tool result *)

     

       414
       414
       +
       module CallToolResult = struct

     

       415
       415
       +
         type t = {

     

       416
       416
       +
           content: content list;

     

       417
       417
       +
           is_error: bool;

     

       418
       418
       +
           meta: Json.t option;

     

       419
       419
       +
         }

     

       420
       420
       +
       

     

       421
       421
       +
         let yojson_of_t { content; is_error; meta } =

     

       422
       422
       +
           let assoc = [

     

       423
       423
       +
             ("content", `List (List.map yojson_of_content content));

     

       424
       424
       +
             ("isError", `Bool is_error);

     

       425
       425
       +
           ] in

     

       426
       426
       +
           let assoc = match meta with

     

       427
       427
       +
             | Some meta_json -> ("_meta", meta_json) :: assoc

     

       428
       428
       +
             | None -> assoc

     

       429
       429
       +
           in

     

       430
       430
       +
           `Assoc assoc

     

       431
       431
       +
       

     

       432
       432
       +
         let t_of_yojson = function

     

       433
       433
       +
           | `Assoc fields ->

     

       434
       434
       +
             let content = match List.assoc_opt "content" fields with

     

       435
       435
       +
               | Some (`List items) -> List.map content_of_yojson items

     

       436
       436
       +
               | _ -> raise (Json.Of_json ("Missing or invalid 'content' field", `Assoc fields))

     

       437
       437
       +
             in

     

       438
       438
       +
             let is_error = match List.assoc_opt "isError" fields with

     

       439
       439
       +
               | Some (`Bool b) -> b

     

       440
       440
       +
               | None -> false (* Default to false if not specified *)

     

       441
       441
       +
               | _ -> raise (Json.Of_json ("Invalid 'isError' field", `Assoc fields))

     

       442
       442
       +
             in

     

       443
       443
       +
             let meta = List.assoc_opt "_meta" fields in

     

       444
       444
       +
             { content; is_error; meta }

     

       445
       445
       +
           | j -> raise (Json.Of_json ("Expected object for CallToolResult", j))

     

       446
       446
       +
       end

     

       447
       447
       +
       

     

       448
       448
       +
       (** Resource definition *)

     

       449
       449
       +
       module Resource = struct

     

       450
       450
       +
         type t = {

     

       451
       451
       +
           name: string;

     

       452
       452
       +
           uri: string;

     

       453
       453
       +
           description: string option;

     

       454
       454
       +
           mime_type: string option;

     

       455
       455
       +
           size: int option;

     

       456
       456
       +
           annotations: Annotated.annotation option;

     

       457
       457
       +
         }

     

       458
       458
       +
       

     

       459
       459
       +
         let yojson_of_t { name; uri; description; mime_type; size; annotations } =

     

       460
       460
       +
           let assoc = [

     

       461
       461
       +
             ("name", `String name);

     

       462
       462
       +
             ("uri", `String uri);

     

       463
       463
       +
           ] in

     

       464
       464
       +
           let assoc = match description with

     

       465
       465
       +
             | Some desc -> ("description", `String desc) :: assoc

     

       466
       466
       +
             | None -> assoc

     

       467
       467
       +
           in

     

       468
       468
       +
           let assoc = match mime_type with

     

       469
       469
       +
             | Some mime -> ("mimeType", `String mime) :: assoc

     

       470
       470
       +
             | None -> assoc

     

       471
       471
       +
           in

     

       472
       472
       +
           let assoc = match size with

     

       473
       473
       +
             | Some s -> ("size", `Int s) :: assoc

     

       474
       474
       +
             | None -> assoc

     

       475
       475
       +
           in

     

       476
       476
       +
           let assoc = match annotations with

     

       477
       477
       +
             | Some ann -> ("annotations", Annotated.yojson_of_annotation ann) :: assoc

     

       478
       478
       +
             | None -> assoc

     

       479
       479
       +
           in

     

       480
       480
       +
           `Assoc assoc

     

       481
       481
       +
       

     

       482
       482
       +
         let t_of_yojson = function

     

       483
       483
       +
           | `Assoc fields ->

     

       484
       484
       +
             let name = match List.assoc_opt "name" fields with

     

       485
       485
       +
               | Some (`String s) -> s

     

       486
       486
       +
               | _ -> raise (Json.Of_json ("Missing or invalid 'name' field", `Assoc fields))

     

       487
       487
       +
             in

     

       488
       488
       +
             let uri = match List.assoc_opt "uri" fields with

     

       489
       489
       +
               | Some (`String s) -> s

     

       490
       490
       +
               | _ -> raise (Json.Of_json ("Missing or invalid 'uri' field", `Assoc fields))

     

       491
       491
       +
             in

     

       492
       492
       +
             let description = match List.assoc_opt "description" fields with

     

       493
       493
       +
               | Some (`String s) -> Some s

     

       494
       494
       +
               | _ -> None

     

       495
       495
       +
             in

     

       496
       496
       +
             let mime_type = match List.assoc_opt "mimeType" fields with

     

       497
       497
       +
               | Some (`String s) -> Some s

     

       498
       498
       +
               | _ -> None

     

       499
       499
       +
             in

     

       500
       500
       +
             let size = match List.assoc_opt "size" fields with

     

       501
       501
       +
               | Some (`Int s) -> Some s

     

       502
       502
       +
               | _ -> None

     

       503
       503
       +
             in

     

       504
       504
       +
             let annotations = match List.assoc_opt "annotations" fields with

     

       505
       505
       +
               | Some json -> Some (Annotated.annotation_of_yojson json)

     

       506
       506
       +
               | _ -> None

     

       507
       507
       +
             in

     

       508
       508
       +
             { name; uri; description; mime_type; size; annotations }

     

       509
       509
       +
           | j -> raise (Json.Of_json ("Expected object for Resource", j))

     

       510
       510
       +
       end

     

       511
       511
       +
       

     

       512
       512
       +
       (** Resource Template definition *)

     

       513
       513
       +
       module ResourceTemplate = struct

     

       514
       514
       +
         type t = {

     

       515
       515
       +
           name: string;

     

       516
       516
       +
           uri_template: string;

     

       517
       517
       +
           description: string option;

     

       518
       518
       +
           mime_type: string option;

     

       519
       519
       +
           annotations: Annotated.annotation option;

     

       520
       520
       +
         }

     

       521
       521
       +
       

     

       522
       522
       +
         let yojson_of_t { name; uri_template; description; mime_type; annotations } =

     

       523
       523
       +
           let assoc = [

     

       524
       524
       +
             ("name", `String name);

     

       525
       525
       +
             ("uriTemplate", `String uri_template);

     

       526
       526
       +
           ] in

     

       527
       527
       +
           let assoc = match description with

     

       528
       528
       +
             | Some desc -> ("description", `String desc) :: assoc

     

       529
       529
       +
             | None -> assoc

     

       530
       530
       +
           in

     

       531
       531
       +
           let assoc = match mime_type with

     

       532
       532
       +
             | Some mime -> ("mimeType", `String mime) :: assoc

     

       533
       533
       +
             | None -> assoc

     

       534
       534
       +
           in

     

       535
       535
       +
           let assoc = match annotations with

     

       536
       536
       +
             | Some ann -> ("annotations", Annotated.yojson_of_annotation ann) :: assoc

     

       537
       537
       +
             | None -> assoc

     

       538
       538
       +
           in

     

       539
       539
       +
           `Assoc assoc

     

       540
       540
       +
       

     

       541
       541
       +
         let t_of_yojson = function

     

       542
       542
       +
           | `Assoc fields ->

     

       543
       543
       +
             let name = match List.assoc_opt "name" fields with

     

       544
       544
       +
               | Some (`String s) -> s

     

       545
       545
       +
               | _ -> raise (Json.Of_json ("Missing or invalid 'name' field", `Assoc fields))

     

       546
       546
       +
             in

     

       547
       547
       +
             let uri_template = match List.assoc_opt "uriTemplate" fields with

     

       548
       548
       +
               | Some (`String s) -> s

     

       549
       549
       +
               | _ -> raise (Json.Of_json ("Missing or invalid 'uriTemplate' field", `Assoc fields))

     

       550
       550
       +
             in

     

       551
       551
       +
             let description = match List.assoc_opt "description" fields with

     

       552
       552
       +
               | Some (`String s) -> Some s

     

       553
       553
       +
               | _ -> None

     

       554
       554
       +
             in

     

       555
       555
       +
             let mime_type = match List.assoc_opt "mimeType" fields with

     

       556
       556
       +
               | Some (`String s) -> Some s

     

       557
       557
       +
               | _ -> None

     

       558
       558
       +
             in

     

       559
       559
       +
             let annotations = match List.assoc_opt "annotations" fields with

     

       560
       560
       +
               | Some json -> Some (Annotated.annotation_of_yojson json)

     

       561
       561
       +
               | _ -> None

     

       562
       562
       +
             in

     

       563
       563
       +
             { name; uri_template; description; mime_type; annotations }

     

       564
       564
       +
           | j -> raise (Json.Of_json ("Expected object for ResourceTemplate", j))

     

       565
       565
       +
       end

     

       566
       566
       +
       

     

       567
       567
       +
       (** Resource Reference *)

     

       568
       568
       +
       module ResourceReference = struct

     

       569
       569
       +
         type t = {

     

       570
       570
       +
           uri: string;

     

       571
       571
       +
         }

     

       572
       572
       +
       

     

       573
       573
       +
         let yojson_of_t { uri } =

     

       574
       574
       +
           `Assoc [

     

       575
       575
       +
             ("type", `String "ref/resource");

     

       576
       576
       +
             ("uri", `String uri);

     

       577
       577
       +
           ]

     

       578
       578
       +
       

     

       579
       579
       +
         let t_of_yojson = function

     

       580
       580
       +
           | `Assoc fields ->

     

       581
       581
       +
             let _ = match List.assoc_opt "type" fields with

     

       582
       582
       +
               | Some (`String "ref/resource") -> ()

     

       583
       583
       +
               | _ -> raise (Json.Of_json ("Missing or invalid 'type' field", `Assoc fields))

     

       584
       584
       +
             in

     

       585
       585
       +
             let uri = match List.assoc_opt "uri" fields with

     

       586
       586
       +
               | Some (`String s) -> s

     

       587
       587
       +
               | _ -> raise (Json.Of_json ("Missing or invalid 'uri' field", `Assoc fields))

     

       588
       588
       +
             in

     

       589
       589
       +
             { uri }

     

       590
       590
       +
           | j -> raise (Json.Of_json ("Expected object for ResourceReference", j))

     

       591
       591
       +
       end

     

       592
       592
       +
       

     

       593
       593
       +
       (** Prompt Reference *)

     

       594
       594
       +
       module PromptReference = struct

     

       595
       595
       +
         type t = {

     

       596
       596
       +
           name: string;

     

       597
       597
       +
         }

     

       598
       598
       +
       

     

       599
       599
       +
         let yojson_of_t { name } =

     

       600
       600
       +
           `Assoc [

     

       601
       601
       +
             ("type", `String "ref/prompt");

     

       602
       602
       +
             ("name", `String name);

     

       603
       603
       +
           ]

     

       604
       604
       +
       

     

       605
       605
       +
         let t_of_yojson = function

     

       606
       606
       +
           | `Assoc fields ->

     

       607
       607
       +
             let _ = match List.assoc_opt "type" fields with

     

       608
       608
       +
               | Some (`String "ref/prompt") -> ()

     

       609
       609
       +
               | _ -> raise (Json.Of_json ("Missing or invalid 'type' field", `Assoc fields))

     

       610
       610
       +
             in

     

       611
       611
       +
             let name = match List.assoc_opt "name" fields with

     

       612
       612
       +
               | Some (`String s) -> s

     

       613
       613
       +
               | _ -> raise (Json.Of_json ("Missing or invalid 'name' field", `Assoc fields))

     

       614
       614
       +
             in

     

       615
       615
       +
             { name }

     

       616
       616
       +
           | j -> raise (Json.Of_json ("Expected object for PromptReference", j))

     

       617
       617
       +
       end

     

       618
       618
       +
       

     

       619
       619
       +
       (** Completion support *)

     

       620
       620
       +
       module Completion = struct

     

       621
       621
       +
         

     

       622
       622
       +
         module Argument = struct

     

       623
       623
       +
           type t = {

     

       624
       624
       +
             name: string;

     

       625
       625
       +
             value: string;

     

       626
       626
       +
           }

     

       627
       627
       +
       

     

       628
       628
       +
           let yojson_of_t { name; value } =

     

       629
       629
       +
             `Assoc [

     

       630
       630
       +
               ("name", `String name);

     

       631
       631
       +
               ("value", `String value);

     

       632
       632
       +
             ]

     

       633
       633
       +
       

     

       634
       634
       +
           let t_of_yojson = function

     

       635
       635
       +
             | `Assoc fields ->

     

       636
       636
       +
               let name = match List.assoc_opt "name" fields with

     

       637
       637
       +
                 | Some (`String s) -> s

     

       638
       638
       +
                 | _ -> raise (Json.Of_json ("Missing or invalid 'name' field", `Assoc fields))

     

       639
       639
       +
               in

     

       640
       640
       +
               let value = match List.assoc_opt "value" fields with

     

       641
       641
       +
                 | Some (`String s) -> s

     

       642
       642
       +
                 | _ -> raise (Json.Of_json ("Missing or invalid 'value' field", `Assoc fields))

     

       643
       643
       +
               in

     

       644
       644
       +
               { name; value }

     

       645
       645
       +
             | j -> raise (Json.Of_json ("Expected object for Completion.Argument", j))

     

       646
       646
       +
         end

     

       647
       647
       +
       

     

       648
       648
       +
         module Request = struct

     

       649
       649
       +
           type reference = [ `Prompt of PromptReference.t | `Resource of ResourceReference.t ]

     

       650
       650
       +
       

     

       651
       651
       +
           type t = {

     

       652
       652
       +
             argument: Argument.t;

     

       653
       653
       +
             ref: reference;

     

       654
       654
       +
           }

     

       655
       655
       +
       

     

       656
       656
       +
           let yojson_of_reference = function

     

       657
       657
       +
             | `Prompt p -> PromptReference.yojson_of_t p

     

       658
       658
       +
             | `Resource r -> ResourceReference.yojson_of_t r

     

       659
       659
       +
       

     

       660
       660
       +
           let reference_of_yojson = function

     

       661
       661
       +
             | `Assoc fields ->

     

       662
       662
       +
               (match List.assoc_opt "type" fields with

     

       663
       663
       +
                | Some (`String "ref/prompt") -> `Prompt (PromptReference.t_of_yojson (`Assoc fields))

     

       664
       664
       +
                | Some (`String "ref/resource") -> `Resource (ResourceReference.t_of_yojson (`Assoc fields))

     

       665
       665
       +
                | _ -> raise (Json.Of_json ("Invalid or missing reference type", `Assoc fields)))

     

       666
       666
       +
             | j -> raise (Json.Of_json ("Expected object for reference", j))

     

       667
       667
       +
       

     

       668
       668
       +
           let yojson_of_t { argument; ref } =

     

       669
       669
       +
             `Assoc [

     

       670
       670
       +
               ("argument", Argument.yojson_of_t argument);

     

       671
       671
       +
               ("ref", yojson_of_reference ref);

     

       672
       672
       +
             ]

     

       673
       673
       +
       

     

       674
       674
       +
           let t_of_yojson = function

     

       675
       675
       +
             | `Assoc fields ->

     

       676
       676
       +
               let argument = match List.assoc_opt "argument" fields with

     

       677
       677
       +
                 | Some json -> Argument.t_of_yojson json

     

       678
       678
       +
                 | _ -> raise (Json.Of_json ("Missing argument field", `Assoc fields))

     

       679
       679
       +
               in

     

       680
       680
       +
               let ref = match List.assoc_opt "ref" fields with

     

       681
       681
       +
                 | Some json -> reference_of_yojson json

     

       682
       682
       +
                 | _ -> raise (Json.Of_json ("Missing ref field", `Assoc fields))

     

       683
       683
       +
               in

     

       684
       684
       +
               { argument; ref }

     

       685
       685
       +
             | j -> raise (Json.Of_json ("Expected object for Completion.Request", j))

     

       686
       686
       +
       

     

       687
       687
       +
           let create ~argument ~ref =

     

       688
       688
       +
             { argument; ref }

     

       689
       689
       +
       

     

       690
       690
       +
           let to_params t =

     

       691
       691
       +
             yojson_of_t t

     

       692
       692
       +
         end

     

       693
       693
       +
       

     

       694
       694
       +
         module Result = struct

     

       695
       695
       +
           type completion = {

     

       696
       696
       +
             values: string list;

     

       697
       697
       +
             has_more: bool option;

     

       698
       698
       +
             total: int option;

     

       699
       699
       +
           }

     

       700
       700
       +
       

     

       701
       701
       +
           type t = {

     

       702
       702
       +
             completion: completion;

     

       703
       703
       +
             meta: Json.t option;

     

       704
       704
       +
           }

     

       705
       705
       +
       

     

       706
       706
       +
           let yojson_of_completion { values; has_more; total } =

     

       707
       707
       +
             let assoc = [

     

       708
       708
       +
               ("values", `List (List.map (fun s -> `String s) values));

     

       709
       709
       +
             ] in

     

       710
       710
       +
             let assoc = match has_more with

     

       711
       711
       +
               | Some b -> ("hasMore", `Bool b) :: assoc

     

       712
       712
       +
               | None -> assoc

     

       713
       713
       +
             in

     

       714
       714
       +
             let assoc = match total with

     

       715
       715
       +
               | Some n -> ("total", `Int n) :: assoc

     

       716
       716
       +
               | None -> assoc

     

       717
       717
       +
             in

     

       718
       718
       +
             `Assoc assoc

     

       719
       719
       +
       

     

       720
       720
       +
           let completion_of_yojson = function

     

       721
       721
       +
             | `Assoc fields ->

     

       722
       722
       +
               let values = match List.assoc_opt "values" fields with

     

       723
       723
       +
                 | Some (`List items) -> 

     

       724
       724
       +
                   List.map (function

     

       725
       725
       +
                     | `String s -> s

     

       726
       726
       +
                     | _ -> raise (Json.Of_json ("Expected string in values array", `List items))

     

       727
       727
       +
                   ) items

     

       728
       728
       +
                 | _ -> raise (Json.Of_json ("Missing or invalid 'values' field", `Assoc fields))

     

       729
       729
       +
               in

     

       730
       730
       +
               let has_more = match List.assoc_opt "hasMore" fields with

     

       731
       731
       +
                 | Some (`Bool b) -> Some b

     

       732
       732
       +
                 | None -> None

     

       733
       733
       +
                 | _ -> raise (Json.Of_json ("Invalid 'hasMore' field", `Assoc fields))

     

       734
       734
       +
               in

     

       735
       735
       +
               let total = match List.assoc_opt "total" fields with

     

       736
       736
       +
                 | Some (`Int n) -> Some n

     

       737
       737
       +
                 | None -> None

     

       738
       738
       +
                 | _ -> raise (Json.Of_json ("Invalid 'total' field", `Assoc fields))

     

       739
       739
       +
               in

     

       740
       740
       +
               { values; has_more; total }

     

       741
       741
       +
             | j -> raise (Json.Of_json ("Expected object for completion", j))

     

       742
       742
       +
       

     

       743
       743
       +
           let yojson_of_t { completion; meta } =

     

       744
       744
       +
             let assoc = [

     

       745
       745
       +
               ("completion", yojson_of_completion completion);

     

       746
       746
       +
             ] in

     

       747
       747
       +
             let assoc = match meta with

     

       748
       748
       +
               | Some meta_json -> ("_meta", meta_json) :: assoc

     

       749
       749
       +
               | None -> assoc

     

       750
       750
       +
             in

     

       751
       751
       +
             `Assoc assoc

     

       752
       752
       +
       

     

       753
       753
       +
           let t_of_yojson = function

     

       754
       754
       +
             | `Assoc fields ->

     

       755
       755
       +
               let completion = match List.assoc_opt "completion" fields with

     

       756
       756
       +
                 | Some json -> completion_of_yojson json

     

       757
       757
       +
                 | _ -> raise (Json.Of_json ("Missing completion field", `Assoc fields))

     

       758
       758
       +
               in

     

       759
       759
       +
               let meta = List.assoc_opt "_meta" fields in

     

       760
       760
       +
               { completion; meta }

     

       761
       761
       +
             | j -> raise (Json.Of_json ("Expected object for Completion.Result", j))

     

       762
       762
       +
       

     

       763
       763
       +
           let create ~completion ?meta () =

     

       764
       764
       +
             { completion; meta }

     

       765
       765
       +
       

     

       766
       766
       +
           let to_result t =

     

       767
       767
       +
             yojson_of_t t

     

       768
       768
       +
         end

     

       769
       769
       +
       end

     

       770
       770
       +
       

     

       427
       771
        
       (* Message types *)

     

       428
       772
        
       

     

       429
       773
        
       module PromptMessage = struct

     
···

       455
       799
        
       module SamplingMessage = struct

     

       456
       800
        
         type t = {

     

       457
       801
        
           role: Role.t;

     

       458
       458
       -
           content: [ `Text of TextContent.t | `Image of ImageContent.t | `Audio of AudioContent.t ];

     

       802
       802
       +
           content: [ `Text of TextContent.t | `Image of ImageContent.t ];

     

       459
       803
        
         }

     

       460
       804
        
       

     

       461
       805
        
         let yojson_of_t { role; content } =

     

       462
       806
        
           let content_json = match content with

     

       463
       807
        
             | `Text t -> TextContent.yojson_of_t t

     

       464
       808
        
             | `Image i -> ImageContent.yojson_of_t i

     

       465
       465
       -
             | `Audio a -> AudioContent.yojson_of_t a

     

       466
       809
        
           in

     

       467
       810
        
           `Assoc [

     

       468
       811
        
             ("role", Role.yojson_of_t role);

     
···

       480
       823
        
                 (match List.assoc_opt "type" content_fields with

     

       481
       824
        
                  | Some (`String "text") -> `Text (TextContent.t_of_yojson (`Assoc content_fields))

     

       482
       825
        
                  | Some (`String "image") -> `Image (ImageContent.t_of_yojson (`Assoc content_fields))

     

       483
       483
       -
                  | Some (`String "audio") -> `Audio (AudioContent.t_of_yojson (`Assoc content_fields))

     

       484
       826
        
                  | _ -> raise (Json.Of_json ("Invalid content type", `Assoc content_fields)))

     

       485
       827
        
               | _ -> raise (Json.Of_json ("Missing or invalid content field", `Assoc fields))

     

       486
       828
        
             in

     
···

       517
       859
        
       end

     

       518
       860
        
       

     

       519
       861
        
       (* JSONRPC Message types *)

     

       862
       862
       +
       

     

       520
       863
        
       

     

       521
       864
        
       module JSONRPCMessage = struct

     

       522
       865
        
         type notification = {

     
···

       843
       1186
        
         end

     

       844
       1187
        
       end

     

       845
       1188
        
       

     

       846
       846
       -
       

     

       847
       1189
        
       (* Export the main interface for using the MCP protocol *)

     

       848
       1190
        
       

     

       849
       1191
        
       let parse_message json =

     
···

       854
       1196
        
       let create_response = JSONRPCMessage.create_response

     

       855
       1197
        
       let create_error = JSONRPCMessage.create_error

     

       856
       1198
        
       

     

       857
       857
       -
       (* Content type constructors *)

     

       858
       858
       -
       let make_text_content text =

     

       859
       859
       -
         Text (TextContent.{ text; annotations = None })

     

       860
       860
       -
       

     

       861
       861
       -
       let make_image_content data mime_type =

     

       862
       862
       -
         Image (ImageContent.{ data; mime_type; annotations = None })

     

       863
       863
       -
       

     

       864
       864
       -
       let make_audio_content data mime_type =

     

       865
       865
       -
         Audio (AudioContent.{ data; mime_type; annotations = None })

     

       866
       866
       -
       

     

       867
       867
       -
       let make_resource_text_content uri text mime_type =

     

       868
       868
       -
         Resource (EmbeddedResource.{

     

       869
       869
       -
           resource = `Text TextResourceContents.{ uri; text; mime_type };

     

       870
       870
       -
           annotations = None;

     

       871
       871
       -
         })

     

       872
       872
       -
       

     

       873
       873
       -
       let make_resource_blob_content uri blob mime_type =

     

       874
       874
       -
         Resource (EmbeddedResource.{

     

       875
       875
       -
           resource = `Blob BlobResourceContents.{ uri; blob; mime_type };

     

       876
       876
       -
           annotations = None;

     

       877
       877
       -
         })
     

       1199
       1199
       +
       (* Helper functions *)

     

       1200
       1200
       +
       let create_completion_request ~id ~argument ~ref =

     

       1201
       1201
       +
         let params = Completion.Request.to_params { argument; ref } in

     

       1202
       1202
       +
         create_request ~id ~method_:"completion/complete" ~params:(Some params) ()

     

       1203
       1203
       +
         

     

       1204
       1204
       +
       let create_completion_response ~id ~values ?(has_more=None) ?(total=None) ?(meta=None) () =

     

       1205
       1205
       +
         let completion = { Completion.Result.values; has_more; total } in

     

       1206
       1206
       +
         let result = Completion.Result.to_result { completion; meta } in

     

       1207
       1207
       +
         create_response ~id ~result

+215 -801

lib/mcp.mli

···

       1
       1
       -
       (** MCP - Model Context Protocol implementation 

     

       2
       2
       -
           

     

       3
       3
       -
           The Model Context Protocol (MCP) is a standardized protocol for AI agents to exchange context

     

       4
       4
       -
           with servers. This module provides the core OCaml implementation of MCP including

     

       5
       5
       -
           all message types, content representations, and serialization functionality.

     

       6
       6
       -
           

     

       7
       7
       -
           MCP Architecture:

     

       8
       8
       -
           - Uses JSON-RPC 2.0 as its underlying message format with UTF-8 encoding

     

       9
       9
       -
           - Follows a client-server model where clients (often LLM-integrated applications) communicate with MCP servers

     

       10
       10
       -
           - Supports multiple transport methods including stdio and streamable HTTP

     

       11
       11
       -
           - Implements a three-phase connection lifecycle: initialization, operation, and shutdown

     

       12
       12
       -
           - Provides capability negotiation during initialization to determine available features

     

       13
       13
       -
           - Offers four primary context exchange mechanisms:

     

       14
       14
       -
             1. Resources: Server-exposed data that provides context to language models

     

       15
       15
       -
             2. Tools: Server-exposed functionality that can be invoked by language models

     

       16
       16
       -
             3. Prompts: Server-defined templates for structuring interactions with models

     

       17
       17
       -
             4. Sampling: Client-exposed ability to generate completions from LLMs

     

       18
       18
       -
           - Supports multimodal content types: text, images, audio, and embedded resources

     

       19
       19
       -
           - Includes standardized error handling with defined error codes

     

       20
       20
       -
           

     

       21
       21
       -
           This implementation follows Protocol Revision 2025-03-26.

     

       22
       22
       -
       *)

     

       1
       1
       +
       (** MCP - Model Context Protocol implementation *)

     

       23
       2
        
       

     

       24
       3
        
       open Jsonrpc

     

       25
       4
        
       

     

       26
       26
       -
       (** Error codes for JSON-RPC *)

     

       5
       5
       +
       (** Standard error codes *)

     

       27
       6
        
       module ErrorCode : sig

     

       28
       28
       -
         (** Standard JSON-RPC error codes with MCP-specific additions *)

     

       29
       29
       -
         type t = 

     

       30
       30
       -
           | ParseError       (** -32700 - Invalid JSON *)

     

       31
       31
       -
           | InvalidRequest   (** -32600 - Invalid JSON-RPC request *)

     

       32
       32
       -
           | MethodNotFound   (** -32601 - Method not available *)

     

       33
       33
       -
           | InvalidParams    (** -32602 - Invalid method parameters *)

     

       34
       34
       -
           | InternalError    (** -32603 - Internal JSON-RPC error *)

     

       35
       35
       -
           | ResourceNotFound (** -32002 - Custom MCP error: requested resource not found *)

     

       36
       36
       -
           | AuthRequired     (** -32001 - Custom MCP error: authentication required *)

     

       37
       37
       -
           | CustomError of int (** For any other error codes *)

     

       38
       38
       -
         

     

       39
       39
       -
         (** Convert the error code to its integer representation

     

       40
       40
       -
             @param code The error code to convert

     

       41
       41
       -
             @return The integer error code as defined in the JSON-RPC spec

     

       42
       42
       -
         *)

     

       43
       43
       -
         val to_int : t -> int

     

       44
       44
       -
         

     

       45
       45
       -
         (** Get error message for standard error codes

     

       46
       46
       -
             @param code The error code to get message for

     

       47
       47
       -
             @return A standard message for the error code

     

       48
       48
       -
         *)

     

       49
       49
       -
         val to_message : t -> string

     

       7
       7
       +
         val parse_error : int

     

       8
       8
       +
         val invalid_request : int

     

       9
       9
       +
         val method_not_found : int

     

       10
       10
       +
         val invalid_params : int

     

       11
       11
       +
         val internal_error : int

     

       12
       12
       +
         val resource_not_found : int

     

       13
       13
       +
         val server_error_start : int

     

       14
       14
       +
         val server_error_end : int

     

       50
       15
        
       end

     

       51
       16
        
       

     

       52
       52
       -
       (** MCP Protocol Methods - Standard method names used in JSON-RPC messages *)

     

       53
       53
       -
       module Method : sig

     

       54
       54
       -
         (** Standard protocol methods used in MCP JSON-RPC messages *)

     

       55
       55
       -
         

     

       56
       56
       -
         val initialize : string  (** "initialize" - Start the MCP lifecycle *)

     

       57
       57
       -
         

     

       58
       58
       -
         val initialized : string (** "notifications/initialized" - Signal readiness after initialization *)

     

       59
       59
       -
         

     

       60
       60
       -
         val resources_list : string (** "resources/list" - Discover available resources *)

     

       61
       61
       -
       

     

       62
       62
       -
         val resources_read : string (** "resources/read" - Retrieve resource contents *)

     

       63
       63
       -
       

     

       64
       64
       -
         val resources_templates_list : string (** "resources/templates/list" - List available resource templates *)

     

       65
       65
       -
       

     

       66
       66
       -
         val resources_subscribe : string (** "resources/subscribe" - Subscribe to resource changes *)

     

       67
       67
       -
       

     

       68
       68
       -
         val resources_list_changed : string (** "notifications/resources/list_changed" - Resource list has changed *)

     

       69
       69
       -
       

     

       70
       70
       -
         val resources_updated : string (** "notifications/resources/updated" - Resource has been updated *)

     

       71
       71
       -
       

     

       72
       72
       -
         val tools_list : string (** "tools/list" - Discover available tools *)

     

       73
       73
       -
       

     

       74
       74
       -
         val tools_call : string (** "tools/call" - Invoke a tool *)

     

       75
       75
       -
       

     

       76
       76
       -
         val tools_list_changed : string (** "notifications/tools/list_changed" - Tool list has changed *)

     

       77
       77
       -
       

     

       78
       78
       -
         val prompts_list : string (** "prompts/list" - Discover available prompts *)

     

       79
       79
       -
       

     

       80
       80
       -
         val prompts_get : string (** "prompts/get" - Retrieve a prompt template with arguments *)

     

       81
       81
       -
       

     

       82
       82
       -
         val prompts_list_changed : string (** "notifications/prompts/list_changed" - Prompt list has changed *)

     

       83
       83
       -
         

     

       84
       84
       -
         val progress : string (** "notifications/progress" - Progress update for long-running operations *)

     

       85
       85
       -
       end

     

       86
       86
       -
       

     

       87
       87
       -
       

     

       88
       17
        
       (** Common types *)

     

       89
       18
        
       

     

       90
       19
        
       (** Roles for conversation participants *)

     

       91
       20
        
       module Role : sig

     

       92
       92
       -
         (** Role represents conversation participants in MCP messages.

     

       93
       93
       -
             Roles can be either 'user' or 'assistant', determining the

     

       94
       94
       -
             source of each message in a conversation. *)

     

       95
       21
        
         type t = [ `User | `Assistant ]

     

       96
       96
       -
         include Json.Jsonable.S with type t := t

     

       22
       22
       +
       

     

       23
       23
       +
         val to_string : t -> string

     

       24
       24
       +
         val of_string : string -> t

     

       25
       25
       +
       

     

       26
       26
       +
         val yojson_of_t : t -> Json.t

     

       27
       27
       +
         val t_of_yojson : Json.t -> t

     

       97
       28
        
       end

     

       98
       29
        
       

     

       99
       30
        
       (** Progress tokens for long-running operations *)

     

       100
       31
        
       module ProgressToken : sig

     

       101
       101
       -
         (** Progress tokens identify long-running operations and enable

     

       102
       102
       -
             servers to provide progress updates to clients. This is used

     

       103
       103
       -
             to track operations that may take significant time to complete. *)

     

       104
       32
        
         type t = [ `String of string | `Int of int ]

     

       33
       33
       +
       

     

       105
       34
        
         include Json.Jsonable.S with type t := t

     

       106
       35
        
       end

     

       107
       36
        
       

     

       108
       37
        
       (** Request IDs *)

     

       109
       38
        
       module RequestId : sig

     

       110
       110
       -
         (** Request IDs uniquely identify JSON-RPC requests, allowing responses

     

       111
       111
       -
             to be correlated with their originating requests. They can be either

     

       112
       112
       -
             string or integer values. *)

     

       113
       39
        
         type t = [ `String of string | `Int of int ]

     

       40
       40
       +
       

     

       114
       41
        
         include Json.Jsonable.S with type t := t

     

       115
       42
        
       end

     

       116
       43
        
       

     

       117
       44
        
       (** Cursors for pagination *)

     

       118
       45
        
       module Cursor : sig

     

       119
       119
       -
         (** Cursors enable pagination in list operations for resources, tools, and prompts.

     

       120
       120
       -
             When a server has more items than can be returned in a single response,

     

       121
       121
       -
             it provides a cursor for the client to retrieve subsequent pages. *)

     

       122
       46
        
         type t = string

     

       123
       123
       -
         include Json.Jsonable.S with type t := t

     

       47
       47
       +
       

     

       48
       48
       +
         val yojson_of_t : t -> Json.t

     

       49
       49
       +
         val t_of_yojson : Json.t -> t

     

       124
       50
        
       end

     

       125
       51
        
       

     

       126
       52
        
       (** Annotations for objects *)

     

       127
       53
        
       module Annotated : sig

     

       128
       128
       -
         (** Annotations provide metadata for content objects, allowing

     

       129
       129
       -
             role-specific targeting and priority settings. *)

     

       130
       54
        
         type t = {

     

       131
       55
        
           annotations: annotation option;

     

       132
       56
        
         }

     

       133
       57
        
         and annotation = {

     

       134
       58
        
           audience: Role.t list option;

     

       135
       135
       -
           (** Optional list of roles that should receive this content *)

     

       136
       59
        
           priority: float option;

     

       137
       137
       -
           (** Optional priority value for this content *)

     

       138
       60
        
         }

     

       139
       139
       -
         include Json.Jsonable.S with type t := t

     

       61
       61
       +
       

     

       62
       62
       +
         val yojson_of_annotation : annotation -> Json.t

     

       63
       63
       +
         val annotation_of_yojson : Json.t -> annotation

     

       64
       64
       +
       

     

       65
       65
       +
         val yojson_of_t : t -> Json.t

     

       66
       66
       +
         val t_of_yojson : Json.t -> t

     

       140
       67
        
       end

     

       141
       68
        
       

     

       142
       142
       -
       (** Text content - Core textual message representation in MCP *)

     

       69
       69
       +
       (** Text content *)

     

       143
       70
        
       module TextContent : sig

     

       144
       144
       -
         (** TextContent represents plain text messages in MCP conversations.

     

       145
       145
       -
             This is the most common content type used for natural language interactions 

     

       146
       146
       -
             between users and assistants. Text content is used in prompts, tool results,

     

       147
       147
       -
             and model responses.

     

       148
       148
       -
             

     

       149
       149
       -
             In JSON-RPC, this is represented as:

     

       150
       150
       -
             {v

     

       151
       151
       -
             {

     

       152
       152
       -
               "type": "text",

     

       153
       153
       -
               "text": "The text content of the message"

     

       154
       154
       -
             }

     

       155
       155
       -
             v}

     

       156
       156
       -
             

     

       157
       157
       -
             For security, implementations must sanitize text content to prevent

     

       158
       158
       -
             injection attacks or unauthorized access to resources. *)

     

       159
       71
        
         type t = {

     

       160
       72
        
           text: string;

     

       161
       161
       -
           (** The actual text content as a UTF-8 encoded string *)

     

       162
       73
        
           annotations: Annotated.annotation option;

     

       163
       163
       -
           (** Optional annotations for audience targeting and priority.

     

       164
       164
       -
               Annotations can restrict content visibility to specific roles (user/assistant)

     

       165
       165
       -
               and indicate relative importance of different content elements. *)

     

       166
       74
        
         }

     

       167
       167
       -
         include Json.Jsonable.S with type t := t

     

       75
       75
       +
       

     

       76
       76
       +
         val yojson_of_t : t -> Json.t

     

       77
       77
       +
         val t_of_yojson : Json.t -> t

     

       168
       78
        
       end

     

       169
       79
        
       

     

       170
       170
       -
       (** Image content - Visual data representation in MCP *)

     

       80
       80
       +
       (** Image content *)

     

       171
       81
        
       module ImageContent : sig

     

       172
       172
       -
         (** ImageContent enables including visual information in MCP messages,

     

       173
       173
       -
             supporting multimodal interactions where visual context is important.

     

       174
       174
       -
             

     

       175
       175
       -
             Images can be used in several scenarios:

     

       176
       176
       -
             - As user inputs for visual understanding tasks

     

       177
       177
       -
             - As context for generating descriptions or analysis

     

       178
       178
       -
             - As outputs from tools that generate visualizations

     

       179
       179
       -
             - As part of prompt templates with visual components

     

       180
       180
       -
             

     

       181
       181
       -
             In JSON-RPC, this is represented as:

     

       182
       182
       -
             {v

     

       183
       183
       -
             {

     

       184
       184
       -
               "type": "image",

     

       185
       185
       -
               "data": "base64-encoded-image-data",

     

       186
       186
       -
               "mimeType": "image/png"

     

       187
       187
       -
             }

     

       188
       188
       -
             v}

     

       189
       189
       -
             

     

       190
       190
       -
             The data MUST be base64-encoded to ensure safe transmission in JSON.

     

       191
       191
       -
             Common mime types include image/png, image/jpeg, image/gif, and image/svg+xml. *)

     

       192
       82
        
         type t = {

     

       193
       83
        
           data: string;

     

       194
       194
       -
           (** Base64-encoded image data. All binary image data must be encoded using

     

       195
       195
       -
               standard base64 encoding (RFC 4648) to safely transmit within JSON. *)

     

       196
       84
        
           mime_type: string;

     

       197
       197
       -
           (** MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/svg+xml").

     

       198
       198
       -
               This field is required and must accurately represent the image format to ensure

     

       199
       199
       -
               proper handling by clients. *)

     

       200
       85
        
           annotations: Annotated.annotation option;

     

       201
       201
       -
           (** Optional annotations for audience targeting and priority.

     

       202
       202
       -
               Annotations can restrict content visibility to specific roles (user/assistant)

     

       203
       203
       -
               and indicate relative importance of different content elements. *)

     

       204
       86
        
         }

     

       205
       205
       -
         include Json.Jsonable.S with type t := t

     

       87
       87
       +
       

     

       88
       88
       +
         val yojson_of_t : t -> Json.t

     

       89
       89
       +
         val t_of_yojson : Json.t -> t

     

       206
       90
        
       end

     

       207
       91
        
       

     

       208
       208
       -
       (** Audio content - Sound data representation in MCP *)

     

       92
       92
       +
       (** Audio content *)

     

       209
       93
        
       module AudioContent : sig

     

       210
       210
       -
         (** AudioContent enables including audio information in MCP messages,

     

       211
       211
       -
             supporting multimodal interactions where audio context is important.

     

       212
       212
       -
             

     

       213
       213
       -
             Audio can be used in several scenarios:

     

       214
       214
       -
             - As user inputs for speech recognition or audio analysis

     

       215
       215
       -
             - As context for transcription or sound classification tasks

     

       216
       216
       -
             - As outputs from tools that generate audio samples

     

       217
       217
       -
             - As part of prompt templates with audio components

     

       218
       218
       -
             

     

       219
       219
       -
             In JSON-RPC, this is represented as:

     

       220
       220
       -
             {v

     

       221
       221
       -
             {

     

       222
       222
       -
               "type": "audio",

     

       223
       223
       -
               "data": "base64-encoded-audio-data",

     

       224
       224
       -
               "mimeType": "audio/wav"

     

       225
       225
       -
             }

     

       226
       226
       -
             v}

     

       227
       227
       -
             

     

       228
       228
       -
             The data MUST be base64-encoded to ensure safe transmission in JSON.

     

       229
       229
       -
             Common mime types include audio/wav, audio/mp3, audio/ogg, and audio/mpeg. *)

     

       230
       94
        
         type t = {

     

       231
       95
        
           data: string;

     

       232
       232
       -
           (** Base64-encoded audio data. All binary audio data must be encoded using

     

       233
       233
       -
               standard base64 encoding (RFC 4648) to safely transmit within JSON. *)

     

       234
       96
        
           mime_type: string;

     

       235
       235
       -
           (** MIME type of the audio (e.g., "audio/wav", "audio/mp3", "audio/ogg", "audio/mpeg").

     

       236
       236
       -
               This field is required and must accurately represent the audio format to ensure

     

       237
       237
       -
               proper handling by clients. *)

     

       238
       97
        
           annotations: Annotated.annotation option;

     

       239
       239
       -
           (** Optional annotations for audience targeting and priority.

     

       240
       240
       -
               Annotations can restrict content visibility to specific roles (user/assistant)

     

       241
       241
       -
               and indicate relative importance of different content elements. *)

     

       242
       98
        
         }

     

       243
       243
       -
         include Json.Jsonable.S with type t := t

     

       99
       99
       +
       

     

       100
       100
       +
         val yojson_of_t : t -> Json.t

     

       101
       101
       +
         val t_of_yojson : Json.t -> t

     

       244
       102
        
       end

     

       245
       103
        
       

     

       246
       246
       -
       (** Base resource contents - Core resource metadata in MCP *)

     

       104
       104
       +
       (** Base resource contents *)

     

       247
       105
        
       module ResourceContents : sig

     

       248
       248
       -
         (** ResourceContents provides basic metadata for resources in MCP.

     

       249
       249
       -
             

     

       250
       250
       -
             Resources are server-exposed data that provides context to language models,

     

       251
       251
       -
             such as files, database schemas, or application-specific information.

     

       252
       252
       -
             Each resource is uniquely identified by a URI.

     

       253
       253
       -
             

     

       254
       254
       -
             The MCP resources architecture is designed to be application-driven, with

     

       255
       255
       -
             host applications determining how to incorporate context based on their needs.

     

       256
       256
       -
             

     

       257
       257
       -
             In the protocol, resources are discovered via the 'resources/list' endpoint

     

       258
       258
       -
             and retrieved via the 'resources/read' endpoint. Servers that support resources

     

       259
       259
       -
             must declare the 'resources' capability during initialization. *)

     

       260
       106
        
         type t = {

     

       261
       107
        
           uri: string;

     

       262
       262
       -
           (** URI that uniquely identifies the resource.

     

       263
       263
       -
               

     

       264
       264
       -
               Resources use standard URI schemes including:

     

       265
       265
       -
               - file:// - For filesystem-like resources

     

       266
       266
       -
               - https:// - For web-accessible resources

     

       267
       267
       -
               - git:// - For version control integration

     

       268
       268
       -
               

     

       269
       269
       -
               The URI serves as a stable identifier even if the underlying content changes. *)

     

       270
       108
        
           mime_type: string option;

     

       271
       271
       -
           (** Optional MIME type of the resource content to aid in client rendering.

     

       272
       272
       -
               Common MIME types include text/plain, application/json, image/png, etc.

     

       273
       273
       -
               For directories, the XDG MIME type inode/directory may be used. *)

     

       274
       109
        
         }

     

       275
       275
       -
         include Json.Jsonable.S with type t := t

     

       110
       110
       +
       

     

       111
       111
       +
         val yojson_of_t : t -> Json.t

     

       112
       112
       +
         val t_of_yojson : Json.t -> t

     

       276
       113
        
       end

     

       277
       114
        
       

     

       278
       278
       -
       (** Text resource contents - Textual resource data *)

     

       115
       115
       +
       (** Text resource contents *)

     

       279
       116
        
       module TextResourceContents : sig

     

       280
       280
       -
         (** TextResourceContents represents a text-based resource in MCP.

     

       281
       281
       -
             

     

       282
       282
       -
             Text resources are used for sharing code snippets, documentation, logs,

     

       283
       283
       -
             configuration files, and other textual information with language models.

     

       284
       284
       -
             

     

       285
       285
       -
             The server handles access control and security, ensuring that only

     

       286
       286
       -
             authorized resources are shared with clients.

     

       287
       287
       -
             

     

       288
       288
       -
             In JSON-RPC, this is represented as:

     

       289
       289
       -
             {v

     

       290
       290
       -
             {

     

       291
       291
       -
               "uri": "file:///example.txt",

     

       292
       292
       -
               "mimeType": "text/plain",

     

       293
       293
       -
               "text": "Resource content"

     

       294
       294
       -
             }

     

       295
       295
       -
             v}

     

       296
       296
       -
             *)

     

       297
       117
        
         type t = {

     

       298
       118
        
           uri: string;

     

       299
       299
       -
           (** URI that uniquely identifies the resource.

     

       300
       300
       -
               This URI can be referenced in subsequent requests to fetch updates. *)

     

       301
       119
        
           text: string;

     

       302
       302
       -
           (** The actual text content of the resource as a UTF-8 encoded string.

     

       303
       303
       -
               This may be sanitized by the server to remove sensitive information. *)

     

       304
       120
        
           mime_type: string option;

     

       305
       305
       -
           (** Optional MIME type of the text content to aid in client rendering.

     

       306
       306
       -
               Common text MIME types include: text/plain, text/markdown, text/x-python, 

     

       307
       307
       -
               application/json, text/html, text/csv, etc. *)

     

       308
       121
        
         }

     

       309
       309
       -
         include Json.Jsonable.S with type t := t

     

       122
       122
       +
       

     

       123
       123
       +
         val yojson_of_t : t -> Json.t

     

       124
       124
       +
         val t_of_yojson : Json.t -> t

     

       310
       125
        
       end

     

       311
       126
        
       

     

       312
       312
       -
       (** Binary resource contents - Binary resource data *)

     

       127
       127
       +
       (** Binary resource contents *)

     

       313
       128
        
       module BlobResourceContents : sig

     

       314
       314
       -
         (** BlobResourceContents represents a binary resource in MCP.

     

       315
       315
       -
             

     

       316
       316
       -
             Binary resources allow sharing non-textual data like images, audio files,

     

       317
       317
       -
             PDFs, and other binary formats with language models that support processing

     

       318
       318
       -
             such content.

     

       319
       319
       -
             

     

       320
       320
       -
             In JSON-RPC, this is represented as:

     

       321
       321
       -
             {v

     

       322
       322
       -
             {

     

       323
       323
       -
               "uri": "file:///example.png",

     

       324
       324
       -
               "mimeType": "image/png",

     

       325
       325
       -
               "blob": "base64-encoded-data"

     

       326
       326
       -
             }

     

       327
       327
       -
             v}

     

       328
       328
       -
             

     

       329
       329
       -
             Binary data MUST be properly base64-encoded to ensure safe transmission

     

       330
       330
       -
             in JSON payloads. *)

     

       331
       129
        
         type t = {

     

       332
       130
        
           uri: string;

     

       333
       333
       -
           (** URI that uniquely identifies the resource.

     

       334
       334
       -
               This URI can be referenced in subsequent requests to fetch updates. *)

     

       335
       131
        
           blob: string;

     

       336
       336
       -
           (** Base64-encoded binary data using standard base64 encoding (RFC 4648).

     

       337
       337
       -
               This encoding ensures that binary data can be safely transmitted in JSON. *)

     

       338
       132
        
           mime_type: string option;

     

       339
       339
       -
           (** Optional MIME type of the binary content to aid in client rendering.

     

       340
       340
       -
               Common binary MIME types include: image/png, image/jpeg, application/pdf, 

     

       341
       341
       -
               audio/wav, video/mp4, application/octet-stream, etc. *)

     

       342
       133
        
         }

     

       343
       343
       -
         include Json.Jsonable.S with type t := t

     

       134
       134
       +
       

     

       135
       135
       +
         val yojson_of_t : t -> Json.t

     

       136
       136
       +
         val t_of_yojson : Json.t -> t

     

       344
       137
        
       end

     

       345
       138
        
       

     

       346
       346
       -
       (** Embedded resource - Resource included directly in messages *)

     

       139
       139
       +
       (** Embedded resource *)

     

       347
       140
        
       module EmbeddedResource : sig

     

       348
       348
       -
         (** EmbeddedResource allows referencing server-side resources directly

     

       349
       349
       -
             in MCP messages, enabling seamless incorporation of managed content.

     

       350
       350
       -
             

     

       351
       351
       -
             Embedded resources can be included in:

     

       352
       352
       -
             - Tool results to provide rich context

     

       353
       353
       -
             - Prompt templates to include reference materials

     

       354
       354
       -
             - Messages to provide additional context to language models

     

       355
       355
       -
             

     

       356
       356
       -
             In contrast to direct content (TextContent, ImageContent, AudioContent),

     

       357
       357
       -
             embedded resources have the advantage of being persistently stored on the server

     

       358
       358
       -
             with a stable URI, allowing later retrieval and updates through the resources API.

     

       359
       359
       -
             

     

       360
       360
       -
             For example, a tool might return an embedded resource containing a chart or

     

       361
       361
       -
             a large dataset that the client can later reference or update. *)

     

       362
       141
        
         type t = {

     

       363
       142
        
           resource: [ `Text of TextResourceContents.t | `Blob of BlobResourceContents.t ];

     

       364
       364
       -
           (** The resource content, either as text or binary blob. *)

     

       365
       143
        
           annotations: Annotated.annotation option;

     

       366
       366
       -
           (** Optional annotations for audience targeting and priority.

     

       367
       367
       -
               Annotations can restrict resource visibility to specific roles (user/assistant)

     

       368
       368
       -
               and indicate relative importance of different content elements. *)

     

       369
       144
        
         }

     

       370
       370
       -
         include Json.Jsonable.S with type t := t

     

       145
       145
       +
       

     

       146
       146
       +
         val yojson_of_t : t -> Json.t

     

       147
       147
       +
         val t_of_yojson : Json.t -> t

     

       371
       148
        
       end

     

       372
       149
        
       

     

       373
       373
       -
       (** Content type used in messages - Unified multimodal content representation in MCP *)

     

       150
       150
       +
       (** Content type used in messages *)

     

       374
       151
        
       type content = 

     

       375
       375
       -
         | Text of TextContent.t    (** Text content for natural language messages. This is the most common content type for user-assistant interactions. *)

     

       376
       376
       -
         | Image of ImageContent.t  (** Image content for visual data. Used for sharing visual context in multimodal conversations. *)

     

       377
       377
       -
         | Audio of AudioContent.t  (** Audio content for audio data. Used for sharing audio context in multimodal conversations. *)

     

       378
       378
       -
         | Resource of EmbeddedResource.t  (** Resource content for referencing server-side resources. Used for incorporating managed server content with stable URIs. *)

     

       152
       152
       +
         | Text of TextContent.t

     

       153
       153
       +
         | Image of ImageContent.t

     

       154
       154
       +
         | Audio of AudioContent.t

     

       155
       155
       +
         | Resource of EmbeddedResource.t

     

       379
       156
        
       

     

       380
       380
       -
       (** Convert content to Yojson representation 

     

       381
       381
       -
           @param content The content to convert

     

       382
       382
       -
           @return JSON representation of the content

     

       383
       383
       -
       *)

     

       384
       157
        
       val yojson_of_content : content -> Json.t

     

       385
       385
       -
       

     

       386
       386
       -
       (** Convert Yojson representation to content 

     

       387
       387
       -
           @param json JSON representation of content

     

       388
       388
       -
           @return Parsed content object

     

       389
       389
       -
       *)

     

       390
       158
        
       val content_of_yojson : Json.t -> content

     

       391
       159
        
       

     

       392
       392
       -
       (** Message for prompts - Template messages in the MCP prompts feature *)

     

       160
       160
       +
       (** Message for prompts *)

     

       393
       161
        
       module PromptMessage : sig

     

       394
       394
       -
         (** PromptMessage represents a message in an MCP prompt template,

     

       395
       395
       -
             containing a role and content which can be customized with arguments.

     

       396
       396
       -
             

     

       397
       397
       -
             Prompt messages are part of prompt templates exposed by servers through

     

       398
       398
       -
             the prompts/get endpoint. They define structured conversation templates

     

       399
       399
       -
             that can be instantiated with user-provided arguments.

     

       400
       400
       -
             

     

       401
       401
       -
             The prompt feature is designed to be user-controlled, with prompts typically

     

       402
       402
       -
             exposed through UI elements like slash commands that users can explicitly select.

     

       403
       403
       -
             

     

       404
       404
       -
             In JSON-RPC, prompt messages are represented as:

     

       405
       405
       -
             {v

     

       406
       406
       -
             {

     

       407
       407
       -
               "role": "user",

     

       408
       408
       -
               "content": {

     

       409
       409
       -
                 "type": "text",

     

       410
       410
       -
                 "text": "Please review this code: ${code}"

     

       411
       411
       -
               }

     

       412
       412
       -
             }

     

       413
       413
       -
             v}

     

       414
       414
       -
             

     

       415
       415
       -
             Where $code would be replaced with a user-provided argument. *)

     

       416
       162
        
         type t = {

     

       417
       163
        
           role: Role.t;

     

       418
       418
       -
           (** The role of the message sender (user or assistant).

     

       419
       419
       -
               Prompt templates typically alternate between user and assistant messages

     

       420
       420
       -
               to create a conversation structure. *)

     

       421
       164
        
           content: content;

     

       422
       422
       -
           (** The message content, which can be text, image, audio, or resource.

     

       423
       423
       -
               This unified content type supports rich multimodal prompts. *)

     

       424
       165
        
         }

     

       425
       425
       -
         include Json.Jsonable.S with type t := t

     

       166
       166
       +
       

     

       167
       167
       +
         val yojson_of_t : t -> Json.t

     

       168
       168
       +
         val t_of_yojson : Json.t -> t

     

       426
       169
        
       end

     

       427
       170
        
       

     

       428
       428
       -
       (** Message for sampling - Messages used in LLM completion requests *)

     

       171
       171
       +
       (** Message for sampling *)

     

       429
       172
        
       module SamplingMessage : sig

     

       430
       430
       -
         (** SamplingMessage represents a message in an MCP sampling request,

     

       431
       431
       -
             used for AI model generation based on a prompt.

     

       432
       432
       -
             

     

       433
       433
       -
             The sampling feature allows clients to expose language model capabilities

     

       434
       434
       -
             to servers, enabling servers to request completions from the client's LLM.

     

       435
       435
       -
             This is effectively the reverse of the normal MCP flow, with the server

     

       436
       436
       -
             requesting generative capabilities from the client.

     

       437
       437
       -
             

     

       438
       438
       -
             Sampling messages differ from prompt messages in that they don't support

     

       439
       439
       -
             embedded resources, as they represent the actual context window being

     

       440
       440
       -
             sent to the LLM rather than template definitions.

     

       441
       441
       -
             

     

       442
       442
       -
             Clients that support sampling must declare the 'sampling' capability

     

       443
       443
       -
             during initialization. *)

     

       444
       173
        
         type t = {

     

       445
       174
        
           role: Role.t;

     

       446
       446
       -
           (** The role of the message sender (user or assistant).

     

       447
       447
       -
               Typically, a sampling request will contain multiple messages

     

       448
       448
       -
               representing a conversation history, with alternating roles. *)

     

       449
       449
       -
           content: [ `Text of TextContent.t | `Image of ImageContent.t | `Audio of AudioContent.t ];

     

       450
       450
       -
           (** The message content, restricted to text, image, or audio (no resources).

     

       451
       451
       -
               Resources are not included since sampling messages represent the

     

       452
       452
       -
               actual context window for the LLM, not template definitions. *)

     

       175
       175
       +
           content: [ `Text of TextContent.t | `Image of ImageContent.t ];

     

       453
       176
        
         }

     

       454
       454
       -
         include Json.Jsonable.S with type t := t

     

       177
       177
       +
       

     

       178
       178
       +
         val yojson_of_t : t -> Json.t

     

       179
       179
       +
         val t_of_yojson : Json.t -> t

     

       455
       180
        
       end

     

       456
       181
        
       

     

       457
       182
        
       (** Implementation information *)

     

       458
       183
        
       module Implementation : sig

     

       459
       459
       -
         (** Implementation provides metadata about client and server implementations,

     

       460
       460
       -
             used during the initialization phase to identify each party. *)

     

       461
       184
        
         type t = {

     

       462
       185
        
           name: string;

     

       463
       463
       -
           (** Name of the implementation *)

     

       464
       186
        
           version: string;

     

       465
       465
       -
           (** Version of the implementation *)

     

       466
       187
        
         }

     

       467
       467
       -
         include Json.Jsonable.S with type t := t

     

       468
       468
       -
       end

     

       469
       188
        
       

     

       470
       470
       -
       (** JSONRPC message types - Core message protocol for MCP

     

       189
       189
       +
         val yojson_of_t : t -> Json.t

     

       190
       190
       +
         val t_of_yojson : Json.t -> t

     

       191
       191
       +
       end

     

       471
       192
        
       

     

       472
       472
       -
           MCP uses JSON-RPC 2.0 as its underlying messaging protocol.

     

       473
       473
       -
           All MCP messages are encoded as JSON-RPC 2.0 messages with UTF-8 encoding,

     

       474
       474
       -
           following the standard JSON-RPC message formats with some MCP-specific extensions.

     

       475
       475
       -
           

     

       476
       476
       -
           MCP defines four message types:

     

       477
       477
       -
           1. Notifications: One-way messages that don't expect a response

     

       478
       478
       -
           2. Requests: Messages that expect a corresponding response

     

       479
       479
       -
           3. Responses: Replies to requests with successful results

     

       480
       480
       -
           4. Errors: Replies to requests with error information

     

       481
       481
       -
           

     

       482
       482
       -
           These can be transported over multiple transport mechanisms:

     

       483
       483
       -
           - stdio: Communication over standard input/output

     

       484
       484
       -
           - Streamable HTTP: HTTP POST/GET with SSE for server streaming

     

       485
       485
       -
           - Custom transports: Implementation-specific transports

     

       486
       486
       -
           

     

       487
       487
       -
           Messages may be sent individually or as part of a JSON-RPC batch.

     

       488
       488
       -
       *)

     

       193
       193
       +
       (** JSONRPC message types *)

     

       489
       194
        
       module JSONRPCMessage : sig

     

       490
       490
       -
         (** Notification represents a JSON-RPC notification (one-way message without a response).

     

       491
       491
       -
             

     

       492
       492
       -
             Notifications are used for events that don't require a response, such as:

     

       493
       493
       -
             - The 'initialized' notification completing initialization

     

       494
       494
       -
             - Resource change notifications

     

       495
       495
       -
             - Progress updates for long-running operations

     

       496
       496
       -
             - List changed notifications for tools, resources, and prompts

     

       497
       497
       -
             

     

       498
       498
       -
             In JSON-RPC, notifications are identified by the absence of an 'id' field:

     

       499
       499
       -
             {v

     

       500
       500
       -
             {

     

       501
       501
       -
               "jsonrpc": "2.0",

     

       502
       502
       -
               "method": "notifications/resources/updated",

     

       503
       503
       -
               "params": {

     

       504
       504
       -
                 "uri": "file:///project/src/main.rs"

     

       505
       505
       -
               }

     

       506
       506
       -
             }

     

       507
       507
       -
             v}

     

       508
       508
       -
         *)

     

       509
       195
        
         type notification = {

     

       510
       196
        
           method_: string;

     

       511
       511
       -
           (** Method name for the notification, following the MCP naming conventions.

     

       512
       512
       -
               Common method patterns include:

     

       513
       513
       -
               - "notifications/X" for standard notifications

     

       514
       514
       -
               - "notifications/X/Y" for more specific notifications

     

       515
       515
       -
               

     

       516
       516
       -
               Examples: "notifications/initialized", "notifications/resources/updated" *)

     

       517
       197
        
           params: Json.t option;

     

       518
       518
       -
           (** Optional parameters for the notification as arbitrary JSON.

     

       519
       519
       -
               The structure depends on the specific notification method. *)

     

       520
       198
        
         }

     

       521
       199
        
       

     

       522
       522
       -
         (** Request represents a JSON-RPC request that expects a response.

     

       523
       523
       -
             

     

       524
       524
       -
             Requests are used for operations that require a response, such as:

     

       525
       525
       -
             - Initialization

     

       526
       526
       -
             - Listing resources, tools, or prompts

     

       527
       527
       -
             - Reading resources

     

       528
       528
       -
             - Calling tools

     

       529
       529
       -
             - Getting prompts

     

       530
       530
       -
             

     

       531
       531
       -
             In JSON-RPC, requests include an 'id' field that correlates with the response:

     

       532
       532
       -
             {v

     

       533
       533
       -
             {

     

       534
       534
       -
               "jsonrpc": "2.0",

     

       535
       535
       -
               "id": 1,

     

       536
       536
       -
               "method": "resources/read",

     

       537
       537
       -
               "params": {

     

       538
       538
       -
                 "uri": "file:///project/src/main.rs"

     

       539
       539
       -
               }

     

       540
       540
       -
             }

     

       541
       541
       -
             v}

     

       542
       542
       -
         *)

     

       543
       200
        
         type request = {

     

       544
       201
        
           id: RequestId.t;

     

       545
       545
       -
           (** Unique identifier for the request, which will be echoed in the response.

     

       546
       546
       -
               This can be a string or integer and should be unique within the session. *)

     

       547
       202
        
           method_: string;

     

       548
       548
       -
           (** Method name for the request, following the MCP naming conventions.

     

       549
       549
       -
               Common method patterns include:

     

       550
       550
       -
               - "X/Y" for standard operations

     

       551
       551
       -
               - "X/Y/Z" for more specific operations

     

       552
       552
       -
               

     

       553
       553
       -
               Examples: "initialize", "resources/read", "tools/call", "prompts/get" *)

     

       554
       203
        
           params: Json.t option;

     

       555
       555
       -
           (** Optional parameters for the request as arbitrary JSON.

     

       556
       556
       -
               The structure depends on the specific request method. *)

     

       557
       204
        
           progress_token: ProgressToken.t option;

     

       558
       558
       -
           (** Optional progress token for long-running operations.

     

       559
       559
       -
               If provided, the server can send progress notifications using this token

     

       560
       560
       -
               to inform the client about the operation's status. *)

     

       561
       205
        
         }

     

       562
       206
        
       

     

       563
       563
       -
         (** Response represents a successful JSON-RPC response to a request.

     

       564
       564
       -
             

     

       565
       565
       -
             Responses are sent in reply to requests and contain the successful result.

     

       566
       566
       -
             Each response must include the same ID as its corresponding request.

     

       567
       567
       -
             

     

       568
       568
       -
             In JSON-RPC, responses include the 'id' field matching the request:

     

       569
       569
       -
             {v

     

       570
       570
       -
             {

     

       571
       571
       -
               "jsonrpc": "2.0",

     

       572
       572
       -
               "id": 1,

     

       573
       573
       -
               "result": {

     

       574
       574
       -
                 "contents": [

     

       575
       575
       -
                   {

     

       576
       576
       -
                     "uri": "file:///project/src/main.rs",

     

       577
       577
       -
                     "mimeType": "text/x-rust",

     

       578
       578
       -
                     "text": "fn main() {\n    println!(\"Hello world!\");\n}"

     

       579
       579
       -
                   }

     

       580
       580
       -
                 ]

     

       581
       581
       -
               }

     

       582
       582
       -
             }

     

       583
       583
       -
             v}

     

       584
       584
       -
         *)

     

       585
       207
        
         type response = {

     

       586
       208
        
           id: RequestId.t;

     

       587
       587
       -
           (** ID matching the original request, allowing clients to correlate

     

       588
       588
       -
               responses with their originating requests, especially important

     

       589
       589
       -
               when multiple requests are in flight. *)

     

       590
       209
        
           result: Json.t;

     

       591
       591
       -
           (** Result of the successful request as arbitrary JSON.

     

       592
       592
       -
               The structure depends on the specific request method that was called. *)

     

       593
       210
        
         }

     

       594
       211
        
       

     

       595
       595
       -
         (** Error represents an error response to a JSON-RPC request.

     

       596
       596
       -
             

     

       597
       597
       -
             Errors are sent in reply to requests when processing fails.

     

       598
       598
       -
             Each error must include the same ID as its corresponding request.

     

       599
       599
       -
             

     

       600
       600
       -
             MCP defines several standard error codes:

     

       601
       601
       -
             - Standard JSON-RPC errors (-32700 to -32603)

     

       602
       602
       -
             - MCP-specific errors (-32002 for resource not found, etc.)

     

       603
       603
       -
             

     

       604
       604
       -
             In JSON-RPC, errors follow this structure:

     

       605
       605
       -
             {v

     

       606
       606
       -
             {

     

       607
       607
       -
               "jsonrpc": "2.0",

     

       608
       608
       -
               "id": 1,

     

       609
       609
       -
               "error": {

     

       610
       610
       -
                 "code": -32002,

     

       611
       611
       -
                 "message": "Resource not found",

     

       612
       612
       -
                 "data": {

     

       613
       613
       -
                   "uri": "file:///nonexistent.txt"

     

       614
       614
       -
                 }

     

       615
       615
       -
               }

     

       616
       616
       -
             }

     

       617
       617
       -
             v}

     

       618
       618
       -
         *)

     

       619
       212
        
         type error = {

     

       620
       213
        
           id: RequestId.t;

     

       621
       621
       -
           (** ID matching the original request, allowing clients to correlate

     

       622
       622
       -
               errors with their originating requests. *)

     

       623
       214
        
           code: int;

     

       624
       624
       -
           (** Error code indicating the type of error, following the JSON-RPC standard.

     

       625
       625
       -
               Common codes include:

     

       626
       626
       -
               - -32700: Parse error

     

       627
       627
       -
               - -32600: Invalid request

     

       628
       628
       -
               - -32601: Method not found

     

       629
       629
       -
               - -32602: Invalid params

     

       630
       630
       -
               - -32603: Internal error

     

       631
       631
       -
               - -32002: Resource not found (MCP-specific)

     

       632
       632
       -
               - -32001: Authentication required (MCP-specific) *)

     

       633
       215
        
           message: string;

     

       634
       634
       -
           (** Human-readable error message describing the issue.

     

       635
       635
       -
               This should be concise but informative enough for debugging. *)

     

       636
       216
        
           data: Json.t option;

     

       637
       637
       -
           (** Optional additional error data as arbitrary JSON.

     

       638
       638
       -
               This can provide more context about the error, such as which

     

       639
       639
       -
               resource wasn't found or which parameter was invalid. *)

     

       640
       217
        
         }

     

       641
       218
        
       

     

       642
       642
       -
         (** Union type for all JSON-RPC message kinds, providing a single type

     

       643
       643
       -
             that can represent any MCP message. *)

     

       644
       219
        
         type t =

     

       645
       220
        
           | Notification of notification

     

       646
       221
        
           | Request of request

     

       647
       222
        
           | Response of response

     

       648
       223
        
           | Error of error

     

       649
       224
        
       

     

       650
       650
       -
         (** Convert notification to Yojson representation 

     

       651
       651
       -
             @param notification The notification to convert

     

       652
       652
       -
             @return JSON representation of the notification

     

       653
       653
       -
         *)

     

       654
       225
        
         val yojson_of_notification : notification -> Json.t

     

       655
       655
       -
         

     

       656
       656
       -
         (** Convert request to Yojson representation 

     

       657
       657
       -
             @param request The request to convert

     

       658
       658
       -
             @return JSON representation of the request

     

       659
       659
       -
         *)

     

       660
       226
        
         val yojson_of_request : request -> Json.t

     

       661
       661
       -
         

     

       662
       662
       -
         (** Convert response to Yojson representation 

     

       663
       663
       -
             @param response The response to convert

     

       664
       664
       -
             @return JSON representation of the response

     

       665
       665
       -
         *)

     

       666
       227
        
         val yojson_of_response : response -> Json.t

     

       667
       667
       -
         

     

       668
       668
       -
         (** Convert error to Yojson representation 

     

       669
       669
       -
             @param error The error to convert

     

       670
       670
       -
             @return JSON representation of the error

     

       671
       671
       -
         *)

     

       672
       228
        
         val yojson_of_error : error -> Json.t

     

       673
       673
       -
         

     

       674
       674
       -
         (** Convert any message to Yojson representation 

     

       675
       675
       -
             @param message The message to convert

     

       676
       676
       -
             @return JSON representation of the message

     

       677
       677
       -
         *)

     

       678
       229
        
         val yojson_of_t : t -> Json.t

     

       679
       230
        
       

     

       680
       680
       -
         (** Convert Yojson representation to notification 

     

       681
       681
       -
             @param json JSON representation of a notification

     

       682
       682
       -
             @return Parsed notification object

     

       683
       683
       -
             @raise Parse error if the JSON is not a valid notification

     

       684
       684
       -
         *)

     

       685
       231
        
         val notification_of_yojson : Json.t -> notification

     

       686
       686
       -
         

     

       687
       687
       -
         (** Convert Yojson representation to request 

     

       688
       688
       -
             @param json JSON representation of a request

     

       689
       689
       -
             @return Parsed request object

     

       690
       690
       -
             @raise Parse error if the JSON is not a valid request

     

       691
       691
       -
         *)

     

       692
       232
        
         val request_of_yojson : Json.t -> request

     

       693
       693
       -
         

     

       694
       694
       -
         (** Convert Yojson representation to response 

     

       695
       695
       -
             @param json JSON representation of a response

     

       696
       696
       -
             @return Parsed response object

     

       697
       697
       -
             @raise Parse error if the JSON is not a valid response

     

       698
       698
       -
         *)

     

       699
       233
        
         val response_of_yojson : Json.t -> response

     

       700
       700
       -
         

     

       701
       701
       -
         (** Convert Yojson representation to error 

     

       702
       702
       -
             @param json JSON representation of an error

     

       703
       703
       -
             @return Parsed error object

     

       704
       704
       -
             @raise Parse error if the JSON is not a valid error

     

       705
       705
       -
         *)

     

       706
       234
        
         val error_of_yojson : Json.t -> error

     

       707
       707
       -
         

     

       708
       708
       -
         (** Convert Yojson representation to any message 

     

       709
       709
       -
             @param json JSON representation of any message type

     

       710
       710
       -
             @return Parsed message object

     

       711
       711
       -
             @raise Parse error if the JSON is not a valid message

     

       712
       712
       -
         *)

     

       713
       235
        
         val t_of_yojson : Json.t -> t

     

       714
       236
        
       

     

       715
       715
       -
         (** Create a new notification message

     

       716
       716
       -
             @param params Optional parameters for the notification

     

       717
       717
       -
             @param method_ Method name for the notification

     

       718
       718
       -
             @return A new JSON-RPC notification message

     

       719
       719
       -
         *)

     

       720
       237
        
         val create_notification : ?params:Json.t option -> method_:string -> unit -> t

     

       721
       721
       -
         

     

       722
       722
       -
         (** Create a new request message

     

       723
       723
       -
             @param params Optional parameters for the request

     

       724
       724
       -
             @param progress_token Optional progress token for long-running operations

     

       725
       725
       -
             @param id Unique identifier for the request

     

       726
       726
       -
             @param method_ Method name for the request

     

       727
       727
       -
             @return A new JSON-RPC request message

     

       728
       728
       -
         *)

     

       729
       238
        
         val create_request : ?params:Json.t option -> ?progress_token:ProgressToken.t option -> id:RequestId.t -> method_:string -> unit -> t

     

       730
       730
       -
         

     

       731
       731
       -
         (** Create a new response message

     

       732
       732
       -
             @param id ID matching the original request

     

       733
       733
       -
             @param result Result of the successful request

     

       734
       734
       -
             @return A new JSON-RPC response message

     

       735
       735
       -
         *)

     

       736
       239
        
         val create_response : id:RequestId.t -> result:Json.t -> t

     

       737
       737
       -
         

     

       738
       738
       -
         (** Create a new error message

     

       739
       739
       -
             @param id ID matching the original request

     

       740
       740
       -
             @param code Error code indicating the type of error

     

       741
       741
       -
             @param message Human-readable error message

     

       742
       742
       -
             @param data Optional additional error data

     

       743
       743
       -
             @return A new JSON-RPC error message

     

       744
       744
       -
         *)

     

       745
       240
        
         val create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> t

     

       746
       241
        
       end

     

       747
       242
        
       

     

       748
       748
       -
       (** Initialize request/response - The first phase of the MCP lifecycle 

     

       749
       749
       -
           

     

       750
       750
       -
           The initialization phase is the mandatory first interaction between client and server.

     

       751
       751
       -
           During this phase, the protocol version is negotiated and capabilities are exchanged

     

       752
       752
       -
           to determine which optional features will be available during the session.

     

       753
       753
       -
           

     

       754
       754
       -
           This follows a strict sequence:

     

       755
       755
       -
           1. Client sends an InitializeRequest containing its capabilities and protocol version

     

       756
       756
       -
           2. Server responds with an InitializeResult containing its capabilities and protocol version

     

       757
       757
       -
           3. Client sends an InitializedNotification to signal it's ready for normal operations

     

       758
       758
       -
           

     

       759
       759
       -
           The Initialize module handles steps 1 and 2 of this process.

     

       760
       760
       -
       *)

     

       243
       243
       +
       (** Initialize request/response *)

     

       761
       244
        
       module Initialize : sig

     

       762
       245
        
         (** Initialize request *)

     

       763
       246
        
         module Request : sig

     

       764
       764
       -
           (** InitializeRequest starts the MCP lifecycle, negotiating capabilities

     

       765
       765
       -
               and protocol versions between client and server. This is always the first

     

       766
       766
       -
               message sent by the client and MUST NOT be part of a JSON-RPC batch.

     

       767
       767
       -
               

     

       768
       768
       -
               The client SHOULD send the latest protocol version it supports. If the server

     

       769
       769
       -
               does not support this version, it will respond with a version it does support,

     

       770
       770
       -
               and the client must either use that version or disconnect. *)

     

       771
       247
        
           type t = {

     

       772
       772
       -
             capabilities: Json.t; (** ClientCapabilities that define supported optional features.

     

       773
       773
       -
                 This includes which optional protocol features the client supports,

     

       774
       774
       -
                 such as 'roots' (filesystem access), 'sampling' (LLM generation),

     

       775
       775
       -
                 and any experimental features. *)

     

       248
       248
       +
             capabilities: Json.t; (** ClientCapabilities *)

     

       776
       249
        
             client_info: Implementation.t;

     

       777
       777
       -
             (** Client implementation details (name and version) used for identification

     

       778
       778
       -
                 and debugging. Helps servers understand which client they're working with. *)

     

       779
       250
        
             protocol_version: string;

     

       780
       780
       -
             (** MCP protocol version supported by the client, formatted as YYYY-MM-DD

     

       781
       781
       -
                 according to the MCP versioning scheme. Example: "2025-03-26" *)

     

       782
       251
        
           }

     

       783
       783
       -
           include Json.Jsonable.S with type t := t

     

       784
       252
        
       

     

       785
       785
       -
           (** Create a new initialization request

     

       786
       786
       -
               @param capabilities Client capabilities that define supported optional features

     

       787
       787
       -
               @param client_info Client implementation details

     

       788
       788
       -
               @param protocol_version MCP protocol version supported by the client

     

       789
       789
       -
               @return A new initialization request

     

       790
       790
       -
           *)

     

       253
       253
       +
           val yojson_of_t : t -> Json.t

     

       254
       254
       +
           val t_of_yojson : Json.t -> t

     

       255
       255
       +
       

     

       791
       256
        
           val create : capabilities:Json.t -> client_info:Implementation.t -> protocol_version:string -> t

     

       792
       792
       -
           

     

       793
       793
       -
           (** Convert to JSON-RPC message

     

       794
       794
       -
               @param id Unique request identifier

     

       795
       795
       -
               @param t Initialization request

     

       796
       796
       -
               @return JSON-RPC message containing the initialization request

     

       797
       797
       -
           *)

     

       798
       257
        
           val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t

     

       799
       258
        
         end

     

       800
       259
        
       

     

       801
       260
        
         (** Initialize result *)

     

       802
       261
        
         module Result : sig

     

       803
       803
       -
           (** InitializeResult is the server's response to an initialization request,

     

       804
       804
       -
               completing capability negotiation and establishing the protocol version.

     

       805
       805
       -
               

     

       806
       806
       -
               After receiving this message, the client must send an InitializedNotification.

     

       807
       807
       -
               The server should not send any requests other than pings and logging before

     

       808
       808
       -
               receiving the initialized notification. *)

     

       809
       262
        
           type t = {

     

       810
       810
       -
             capabilities: Json.t; (** ServerCapabilities that define supported optional features.

     

       811
       811
       -
                 This declares which server features are available, including:

     

       812
       812
       -
                 - prompts: Server provides prompt templates

     

       813
       813
       -
                 - resources: Server provides readable resources

     

       814
       814
       -
                 - tools: Server exposes callable tools

     

       815
       815
       -
                 - logging: Server emits structured log messages

     

       816
       816
       -
                 

     

       817
       817
       -
                 Each capability may have sub-capabilities like:

     

       818
       818
       -
                 - listChanged: Server will notify when available items change

     

       819
       819
       -
                 - subscribe: Clients can subscribe to individual resources *)

     

       263
       263
       +
             capabilities: Json.t; (** ServerCapabilities *)

     

       820
       264
        
             server_info: Implementation.t;

     

       821
       821
       -
             (** Server implementation details (name and version) used for identification

     

       822
       822
       -
                 and debugging. Helps clients understand which server they're working with. *)

     

       823
       265
        
             protocol_version: string;

     

       824
       824
       -
             (** MCP protocol version supported by the server, formatted as YYYY-MM-DD.

     

       825
       825
       -
                 If the server supports the client's requested version, it responds with

     

       826
       826
       -
                 the same version. Otherwise, it responds with a version it does support. *)

     

       827
       266
        
             instructions: string option;

     

       828
       828
       -
             (** Optional instructions for using the server. These can provide human-readable

     

       829
       829
       -
                 guidance on how to interact with this specific server implementation. *)

     

       830
       267
        
             meta: Json.t option;

     

       831
       831
       -
             (** Optional additional metadata as arbitrary JSON. Can contain server-specific

     

       832
       832
       -
                 information not covered by the standard fields. *)

     

       833
       268
        
           }

     

       834
       834
       -
           include Json.Jsonable.S with type t := t

     

       835
       269
        
       

     

       836
       836
       -
           (** Create a new initialization result

     

       837
       837
       -
               @param capabilities Server capabilities that define supported optional features

     

       838
       838
       -
               @param server_info Server implementation details

     

       839
       839
       -
               @param protocol_version MCP protocol version supported by the server

     

       840
       840
       -
               @param instructions Optional instructions for using the server

     

       841
       841
       -
               @param meta Optional additional metadata

     

       842
       842
       -
               @return A new initialization result

     

       843
       843
       -
           *)

     

       270
       270
       +
           val yojson_of_t : t -> Json.t

     

       271
       271
       +
           val t_of_yojson : Json.t -> t

     

       272
       272
       +
       

     

       844
       273
        
           val create : capabilities:Json.t -> server_info:Implementation.t -> protocol_version:string -> ?instructions:string -> ?meta:Json.t -> unit -> t

     

       845
       845
       -
           

     

       846
       846
       -
           (** Convert to JSON-RPC message

     

       847
       847
       -
               @param id ID matching the original request

     

       848
       848
       -
               @param t Initialization result

     

       849
       849
       -
               @return JSON-RPC message containing the initialization result

     

       850
       850
       -
           *)

     

       851
       274
        
           val to_jsonrpc : id:RequestId.t -> t -> JSONRPCMessage.t

     

       852
       275
        
         end

     

       853
       276
        
       end

     

       854
       277
        
       

     

       855
       855
       -
       (** Initialized notification - Completes the initialization phase of the MCP lifecycle *)

     

       278
       278
       +
       (** Initialized notification *)

     

       856
       279
        
       module Initialized : sig

     

       857
       280
        
         module Notification : sig

     

       858
       858
       -
           (** InitializedNotification is sent by the client after receiving the initialization

     

       859
       859
       -
               response, indicating it's ready to begin normal operations. This completes the

     

       860
       860
       -
               three-step initialization process, after which both client and server can

     

       861
       861
       -
               freely exchange messages according to the negotiated capabilities.

     

       862
       862
       -
               

     

       863
       863
       -
               Only after this notification has been sent should the client begin normal operations

     

       864
       864
       -
               like listing resources, calling tools, or requesting prompts. *)

     

       865
       281
        
           type t = {

     

       866
       282
        
             meta: Json.t option;

     

       867
       867
       -
             (** Optional additional metadata as arbitrary JSON. Can contain client-specific

     

       868
       868
       -
                 information not covered by the standard fields. *)

     

       869
       283
        
           }

     

       870
       870
       -
           include Json.Jsonable.S with type t := t

     

       284
       284
       +
       

     

       285
       285
       +
           val yojson_of_t : t -> Json.t

     

       286
       286
       +
           val t_of_yojson : Json.t -> t

     

       871
       287
        
       

     

       872
       872
       -
           (** Create a new initialized notification

     

       873
       873
       -
               @param meta Optional additional metadata

     

       874
       874
       -
               @return A new initialized notification

     

       875
       875
       -
           *)

     

       876
       288
        
           val create : ?meta:Json.t -> unit -> t

     

       877
       877
       -
           

     

       878
       878
       -
           (** Convert to JSON-RPC message

     

       879
       879
       -
               @param t Initialized notification

     

       880
       880
       -
               @return JSON-RPC message containing the initialized notification

     

       881
       881
       -
           *)

     

       882
       289
        
           val to_jsonrpc : t -> JSONRPCMessage.t

     

       883
       290
        
         end

     

       884
       291
        
       end

     

       885
       292
        
       

     

       886
       886
       -
       (** Parse a JSON message into an MCP message 

     

       887
       887
       -
           

     

       888
       888
       -
           This function takes a raw JSON value and parses it into a structured MCP message.

     

       889
       889
       -
           It's the primary entry point for processing incoming JSON-RPC messages in the MCP protocol.

     

       890
       890
       -
           

     

       891
       891
       -
           The function determines the message type (notification, request, response, or error)

     

       892
       892
       -
           based on the presence and values of specific fields:

     

       893
       893
       -
           - A message with "method" but no "id" is a notification

     

       894
       894
       -
           - A message with "method" and "id" is a request

     

       895
       895
       -
           - A message with "id" and "result" is a response

     

       896
       896
       -
           - A message with "id" and "error" is an error

     

       897
       897
       -
           

     

       898
       898
       -
           @param json The JSON message to parse, typically received from the transport layer

     

       899
       899
       -
           @return The parsed MCP message as a structured JSONRPCMessage.t value

     

       900
       900
       -
           @raise Parse error if the JSON cannot be parsed as a valid MCP message

     

       901
       901
       -
       *)

     

       902
       902
       -
       val parse_message : Json.t -> JSONRPCMessage.t

     

       293
       293
       +
       (** Tool definition *)

     

       294
       294
       +
       module Tool : sig

     

       295
       295
       +
         type t = {

     

       296
       296
       +
           name: string;

     

       297
       297
       +
           description: string option;

     

       298
       298
       +
           input_schema: Json.t;

     

       299
       299
       +
         }

     

       903
       300
        
       

     

       904
       904
       -
       (** Create a new notification message

     

       905
       905
       -
           

     

       906
       906
       -
           Notifications are one-way messages that don't expect a response.

     

       907
       907
       -
           This is a convenience wrapper around JSONRPCMessage.create_notification.

     

       908
       908
       -
           

     

       909
       909
       -
           Common notifications in MCP include:

     

       910
       910
       -
           - "notifications/initialized" - Sent after initialization

     

       911
       911
       -
           - "notifications/progress" - Updates on long-running operations

     

       912
       912
       -
           - "notifications/resources/updated" - Resource content changed

     

       913
       913
       -
           - "notifications/prompts/list_changed" - Available prompts changed

     

       914
       914
       -
           - "notifications/tools/list_changed" - Available tools changed

     

       915
       915
       -
           

     

       916
       916
       -
           @param params Optional parameters for the notification as a JSON value

     

       917
       917
       -
           @param method_ Method name for the notification, typically following MCP naming conventions

     

       918
       918
       -
           @return A new JSON-RPC notification message

     

       919
       919
       -
       *)

     

       920
       920
       -
       val create_notification : ?params:Json.t option -> method_:string -> unit -> JSONRPCMessage.t

     

       301
       301
       +
         val yojson_of_t : t -> Json.t

     

       302
       302
       +
         val t_of_yojson : Json.t -> t

     

       303
       303
       +
       end

     

       921
       304
        
       

     

       922
       922
       -
       (** Create a new request message

     

       923
       923
       -
           

     

       924
       924
       -
           Requests are messages that expect a corresponding response.

     

       925
       925
       -
           This is a convenience wrapper around JSONRPCMessage.create_request.

     

       926
       926
       -
           

     

       927
       927
       -
           Common requests in MCP include:

     

       928
       928
       -
           - "initialize" - Start the MCP lifecycle

     

       929
       929
       -
           - "resources/list" - Discover available resources

     

       930
       930
       -
           - "resources/read" - Retrieve resource contents

     

       931
       931
       -
           - "tools/list" - Discover available tools

     

       932
       932
       -
           - "tools/call" - Invoke a tool

     

       933
       933
       -
           - "prompts/list" - Discover available prompts

     

       934
       934
       -
           - "prompts/get" - Retrieve a prompt template

     

       935
       935
       -
           

     

       936
       936
       -
           @param params Optional parameters for the request as a JSON value

     

       937
       937
       -
           @param progress_token Optional progress token for long-running operations

     

       938
       938
       -
                  that can report progress updates

     

       939
       939
       -
           @param id Unique identifier for the request, used to correlate with the response

     

       940
       940
       -
           @param method_ Method name for the request, following MCP naming conventions

     

       941
       941
       -
           @return A new JSON-RPC request message

     

       942
       942
       -
       *)

     

       943
       943
       -
       val create_request : ?params:Json.t option -> ?progress_token:ProgressToken.t option -> id:RequestId.t -> method_:string -> unit -> JSONRPCMessage.t

     

       305
       305
       +
       (** Tool result *)

     

       306
       306
       +
       module CallToolResult : sig

     

       307
       307
       +
         type t = {

     

       308
       308
       +
           content: content list;

     

       309
       309
       +
           is_error: bool;

     

       310
       310
       +
           meta: Json.t option;

     

       311
       311
       +
         }

     

       312
       312
       +
         

     

       313
       313
       +
         val yojson_of_t : t -> Json.t

     

       314
       314
       +
         val t_of_yojson : Json.t -> t

     

       315
       315
       +
       end

     

       944
       316
        
       

     

       945
       945
       -
       (** Create a new response message

     

       946
       946
       -
           

     

       947
       947
       -
           Responses are sent in reply to requests and contain successful results.

     

       948
       948
       -
           This is a convenience wrapper around JSONRPCMessage.create_response.

     

       949
       949
       -
           

     

       950
       950
       -
           Each response must include the same ID as its corresponding request

     

       951
       951
       -
           to allow the client to correlate them, especially when multiple

     

       952
       952
       -
           requests are in flight simultaneously.

     

       953
       953
       -
           

     

       954
       954
       -
           @param id ID matching the original request

     

       955
       955
       -
           @param result Result of the successful request as a JSON value

     

       956
       956
       -
           @return A new JSON-RPC response message

     

       957
       957
       -
       *)

     

       958
       958
       -
       val create_response : id:RequestId.t -> result:Json.t -> JSONRPCMessage.t

     

       317
       317
       +
       (** Resource definition *)

     

       318
       318
       +
       module Resource : sig

     

       319
       319
       +
         type t = {

     

       320
       320
       +
           name: string;

     

       321
       321
       +
           uri: string;

     

       322
       322
       +
           description: string option;

     

       323
       323
       +
           mime_type: string option;

     

       324
       324
       +
           size: int option;

     

       325
       325
       +
           annotations: Annotated.annotation option;

     

       326
       326
       +
         }

     

       959
       327
        
       

     

       960
       960
       -
       (** Create a new error message

     

       961
       961
       -
           

     

       962
       962
       -
           Errors are sent in reply to requests when processing fails.

     

       963
       963
       -
           This is a convenience wrapper around JSONRPCMessage.create_error.

     

       964
       964
       -
           

     

       965
       965
       -
           MCP uses standard JSON-RPC error codes as well as some protocol-specific codes:

     

       966
       966
       -
           - -32700: Parse error (invalid JSON)

     

       967
       967
       -
           - -32600: Invalid request (malformed JSON-RPC)

     

       968
       968
       -
           - -32601: Method not found

     

       969
       969
       -
           - -32602: Invalid parameters

     

       970
       970
       -
           - -32603: Internal error

     

       971
       971
       -
           - -32002: Resource not found (MCP-specific)

     

       972
       972
       -
           - -32001: Authentication required (MCP-specific)

     

       973
       973
       -
           

     

       974
       974
       -
           @param id ID matching the original request

     

       975
       975
       -
           @param code Error code indicating the type of error

     

       976
       976
       -
           @param message Human-readable error message describing the issue

     

       977
       977
       -
           @param data Optional additional error data providing more context

     

       978
       978
       -
           @return A new JSON-RPC error message

     

       979
       979
       -
       *)

     

       980
       980
       -
       val create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> JSONRPCMessage.t

     

       328
       328
       +
         val yojson_of_t : t -> Json.t

     

       329
       329
       +
         val t_of_yojson : Json.t -> t

     

       330
       330
       +
       end

     

       981
       331
        
       

     

       982
       982
       -
       (** Create a new text content object

     

       983
       983
       -
           @param text The text content

     

       984
       984
       -
           @return A content value with the text

     

       985
       985
       -
       *)

     

       986
       986
       -
       val make_text_content : string -> content

     

       332
       332
       +
       (** Resource Template definition *)

     

       333
       333
       +
       module ResourceTemplate : sig

     

       334
       334
       +
         type t = {

     

       335
       335
       +
           name: string;

     

       336
       336
       +
           uri_template: string;

     

       337
       337
       +
           description: string option;

     

       338
       338
       +
           mime_type: string option;

     

       339
       339
       +
           annotations: Annotated.annotation option;

     

       340
       340
       +
         }

     

       341
       341
       +
       

     

       342
       342
       +
         val yojson_of_t : t -> Json.t

     

       343
       343
       +
         val t_of_yojson : Json.t -> t

     

       344
       344
       +
       end

     

       345
       345
       +
       

     

       346
       346
       +
       (** Resource Reference *)

     

       347
       347
       +
       module ResourceReference : sig

     

       348
       348
       +
         type t = {

     

       349
       349
       +
           uri: string;

     

       350
       350
       +
         }

     

       351
       351
       +
       

     

       352
       352
       +
         val yojson_of_t : t -> Json.t

     

       353
       353
       +
         val t_of_yojson : Json.t -> t

     

       354
       354
       +
       end

     

       355
       355
       +
       

     

       356
       356
       +
       (** Prompt Reference *)

     

       357
       357
       +
       module PromptReference : sig

     

       358
       358
       +
         type t = {

     

       359
       359
       +
           name: string;

     

       360
       360
       +
         }

     

       361
       361
       +
       

     

       362
       362
       +
         val yojson_of_t : t -> Json.t

     

       363
       363
       +
         val t_of_yojson : Json.t -> t

     

       364
       364
       +
       end

     

       365
       365
       +
       

     

       366
       366
       +
       (** Completion support *)

     

       367
       367
       +
       module Completion : sig

     

       368
       368
       +
         module Argument : sig

     

       369
       369
       +
           type t = {

     

       370
       370
       +
             name: string;

     

       371
       371
       +
             value: string;

     

       372
       372
       +
           }

     

       373
       373
       +
       

     

       374
       374
       +
           val yojson_of_t : t -> Json.t

     

       375
       375
       +
           val t_of_yojson : Json.t -> t

     

       376
       376
       +
         end

     

       377
       377
       +
       

     

       378
       378
       +
         module Request : sig

     

       379
       379
       +
           type reference = [ `Prompt of PromptReference.t | `Resource of ResourceReference.t ]

     

       380
       380
       +
       

     

       381
       381
       +
           type t = {

     

       382
       382
       +
             argument: Argument.t;

     

       383
       383
       +
             ref: reference;

     

       384
       384
       +
           }

     

       385
       385
       +
       

     

       386
       386
       +
           val yojson_of_t : t -> Json.t

     

       387
       387
       +
           val t_of_yojson : Json.t -> t

     

       388
       388
       +
       

     

       389
       389
       +
           val yojson_of_reference : reference -> Json.t

     

       390
       390
       +
           val reference_of_yojson : Json.t -> reference

     

       391
       391
       +
       

     

       392
       392
       +
           val create : argument:Argument.t -> ref:reference -> t

     

       393
       393
       +
           val to_params : t -> Json.t

     

       394
       394
       +
         end

     

       987
       395
        
       

     

       988
       988
       -
       (** Create a new image content object

     

       989
       989
       -
           @param data Base64-encoded image data

     

       990
       990
       -
           @param mime_type MIME type of the image (e.g., "image/png", "image/jpeg")  

     

       991
       991
       -
           @return A content value with the image

     

       992
       992
       -
       *)

     

       993
       993
       -
       val make_image_content : string -> string -> content

     

       396
       396
       +
         module Result : sig

     

       397
       397
       +
           type completion = {

     

       398
       398
       +
             values: string list;

     

       399
       399
       +
             has_more: bool option;

     

       400
       400
       +
             total: int option;

     

       401
       401
       +
           }

     

       402
       402
       +
       

     

       403
       403
       +
           type t = {

     

       404
       404
       +
             completion: completion;

     

       405
       405
       +
             meta: Json.t option;

     

       406
       406
       +
           }

     

       407
       407
       +
       

     

       408
       408
       +
           val yojson_of_completion : completion -> Json.t

     

       409
       409
       +
           val completion_of_yojson : Json.t -> completion

     

       410
       410
       +
       

     

       411
       411
       +
           val yojson_of_t : t -> Json.t

     

       412
       412
       +
           val t_of_yojson : Json.t -> t

     

       413
       413
       +
       

     

       414
       414
       +
           val create : completion:completion -> ?meta:Json.t -> unit -> t

     

       415
       415
       +
           val to_result : t -> Json.t

     

       416
       416
       +
         end

     

       417
       417
       +
       end

     

       994
       418
        
       

     

       995
       995
       -
       (** Create a new audio content object

     

       996
       996
       -
           @param data Base64-encoded audio data

     

       997
       997
       -
           @param mime_type MIME type of the audio (e.g., "audio/wav", "audio/mp3")

     

       998
       998
       -
           @return A content value with the audio

     

       999
       999
       -
       *)

     

       1000
       1000
       -
       val make_audio_content : string -> string -> content

     

       419
       419
       +
       (** Parse a JSON message into an MCP message *)

     

       420
       420
       +
       val parse_message : Json.t -> JSONRPCMessage.t

     

       1001
       421
        
       

     

       1002
       1002
       -
       (** Create a new text resource content object

     

       1003
       1003
       -
           @param uri URI that uniquely identifies the resource

     

       1004
       1004
       -
           @param text The text content of the resource

     

       1005
       1005
       -
           @param mime_type Optional MIME type of the text content

     

       1006
       1006
       -
           @return A content value with the text resource

     

       1007
       1007
       -
       *)

     

       1008
       1008
       -
       val make_resource_text_content : string -> string -> string option -> content

     

       422
       422
       +
       (** Create JSONRPC message helpers *)

     

       423
       423
       +
       val create_notification : ?params:Json.t option -> method_:string -> unit -> JSONRPCMessage.t

     

       424
       424
       +
       val create_request : ?params:Json.t option -> ?progress_token:ProgressToken.t option -> id:RequestId.t -> method_:string -> unit -> JSONRPCMessage.t

     

       425
       425
       +
       val create_response : id:RequestId.t -> result:Json.t -> JSONRPCMessage.t

     

       426
       426
       +
       val create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> JSONRPCMessage.t

     

       1009
       427
        
       

     

       1010
       1010
       -
       (** Create a new binary resource content object

     

       1011
       1011
       -
           @param uri URI that uniquely identifies the resource

     

       1012
       1012
       -
           @param blob Base64-encoded binary data

     

       1013
       1013
       -
           @param mime_type Optional MIME type of the binary content

     

       1014
       1014
       -
           @return A content value with the binary resource

     

       1015
       1015
       -
       *)

     

       1016
       1016
       -
       val make_resource_blob_content : string -> string -> string option -> content

     

       428
       428
       +
       (** Helper functions for common requests/responses *)

     

       429
       429
       +
       val create_completion_request : id:RequestId.t -> argument:Completion.Argument.t -> ref:Completion.Request.reference -> JSONRPCMessage.t

     

       430
       430
       +
       val create_completion_response : id:RequestId.t -> values:string list -> ?has_more:bool option -> ?total:int option -> ?meta:Json.t option -> unit -> JSONRPCMessage.t

-726

lib/mcp_message.ml

···

       1
       1
       -
       (* Mcp_message - High-level RPC message definitions for Model Context Protocol *)

     

       2
       2
       -
       

     

       3
       3
       -
       open Mcp

     

       4
       4
       -
       open Jsonrpc

     

       5
       5
       -
       

     

       6
       6
       -
       (* Resources/List *)

     

       7
       7
       -
       module ResourcesList = struct

     

       8
       8
       -
         module Request = struct

     

       9
       9
       -
           type t = {

     

       10
       10
       -
             cursor: Cursor.t option;

     

       11
       11
       -
           }

     

       12
       12
       -
           

     

       13
       13
       -
           let yojson_of_t { cursor } =

     

       14
       14
       -
             let assoc = [] in

     

       15
       15
       -
             let assoc = match cursor with

     

       16
       16
       -
               | Some c -> ("cursor", Cursor.yojson_of_t c) :: assoc

     

       17
       17
       -
               | None -> assoc

     

       18
       18
       -
             in

     

       19
       19
       -
             `Assoc assoc

     

       20
       20
       -
           

     

       21
       21
       -
           let t_of_yojson = function

     

       22
       22
       -
             | `Assoc fields ->

     

       23
       23
       -
               let cursor = List.assoc_opt "cursor" fields |> Option.map Cursor.t_of_yojson in

     

       24
       24
       -
               { cursor }

     

       25
       25
       -
             | j -> raise (Json.Of_json ("Expected object for ResourcesList.Request.t", j))

     

       26
       26
       -
             

     

       27
       27
       -
         end

     

       28
       28
       -
         

     

       29
       29
       -
         module Resource = struct

     

       30
       30
       -
           type t = {

     

       31
       31
       -
             uri: string;

     

       32
       32
       -
             name: string;

     

       33
       33
       -
             description: string option;

     

       34
       34
       -
             mime_type: string option;

     

       35
       35
       -
             size: int option;

     

       36
       36
       -
           }

     

       37
       37
       -
           

     

       38
       38
       -
           let yojson_of_t { uri; name; description; mime_type; size } =

     

       39
       39
       -
             let assoc = [

     

       40
       40
       -
               ("uri", `String uri);

     

       41
       41
       -
               ("name", `String name);

     

       42
       42
       -
             ] in

     

       43
       43
       -
             let assoc = match description with

     

       44
       44
       -
               | Some desc -> ("description", `String desc) :: assoc

     

       45
       45
       -
               | None -> assoc

     

       46
       46
       -
             in

     

       47
       47
       -
             let assoc = match mime_type with

     

       48
       48
       -
               | Some mime -> ("mimeType", `String mime) :: assoc

     

       49
       49
       -
               | None -> assoc

     

       50
       50
       -
             in

     

       51
       51
       -
             let assoc = match size with

     

       52
       52
       -
               | Some s -> ("size", `Int s) :: assoc

     

       53
       53
       -
               | None -> assoc

     

       54
       54
       -
             in

     

       55
       55
       -
             `Assoc assoc

     

       56
       56
       -
           

     

       57
       57
       -
           let t_of_yojson = function

     

       58
       58
       -
             | `Assoc fields ->

     

       59
       59
       -
               let uri = match List.assoc_opt "uri" fields with

     

       60
       60
       -
                 | Some (`String s) -> s

     

       61
       61
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'uri' field", `Assoc fields))

     

       62
       62
       -
               in

     

       63
       63
       -
               let name = match List.assoc_opt "name" fields with

     

       64
       64
       -
                 | Some (`String s) -> s

     

       65
       65
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'name' field", `Assoc fields))

     

       66
       66
       -
               in

     

       67
       67
       -
               let description = List.assoc_opt "description" fields |> Option.map (function

     

       68
       68
       -
                 | `String s -> s

     

       69
       69
       -
                 | j -> raise (Json.Of_json ("Expected string for description", j))

     

       70
       70
       -
               ) in

     

       71
       71
       -
               let mime_type = List.assoc_opt "mimeType" fields |> Option.map (function

     

       72
       72
       -
                 | `String s -> s

     

       73
       73
       -
                 | j -> raise (Json.Of_json ("Expected string for mimeType", j))

     

       74
       74
       -
               ) in

     

       75
       75
       -
               let size = List.assoc_opt "size" fields |> Option.map (function

     

       76
       76
       -
                 | `Int i -> i

     

       77
       77
       -
                 | j -> raise (Json.Of_json ("Expected int for size", j))

     

       78
       78
       -
               ) in

     

       79
       79
       -
               { uri; name; description; mime_type; size }

     

       80
       80
       -
             | j -> raise (Json.Of_json ("Expected object for ResourcesList.Resource.t", j))

     

       81
       81
       -
         end

     

       82
       82
       -
         

     

       83
       83
       -
         module Response = struct

     

       84
       84
       -
           type t = {

     

       85
       85
       -
             resources: Resource.t list;

     

       86
       86
       -
             next_cursor: Cursor.t option;

     

       87
       87
       -
           }

     

       88
       88
       -
           

     

       89
       89
       -
           let yojson_of_t { resources; next_cursor } =

     

       90
       90
       -
             let assoc = [

     

       91
       91
       -
               ("resources", `List (List.map Resource.yojson_of_t resources));

     

       92
       92
       -
             ] in

     

       93
       93
       -
             let assoc = match next_cursor with

     

       94
       94
       -
               | Some c -> ("nextCursor", Cursor.yojson_of_t c) :: assoc

     

       95
       95
       -
               | None -> assoc

     

       96
       96
       -
             in

     

       97
       97
       -
             `Assoc assoc

     

       98
       98
       -
           

     

       99
       99
       -
           let t_of_yojson = function

     

       100
       100
       -
             | `Assoc fields ->

     

       101
       101
       -
               let resources = match List.assoc_opt "resources" fields with

     

       102
       102
       -
                 | Some (`List items) -> List.map Resource.t_of_yojson items

     

       103
       103
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'resources' field", `Assoc fields))

     

       104
       104
       -
               in

     

       105
       105
       -
               let next_cursor = List.assoc_opt "nextCursor" fields |> Option.map Cursor.t_of_yojson in

     

       106
       106
       -
               { resources; next_cursor }

     

       107
       107
       -
             | j -> raise (Json.Of_json ("Expected object for ResourcesList.Response.t", j))

     

       108
       108
       -
             

     

       109
       109
       -
         end

     

       110
       110
       -
         

     

       111
       111
       -
         (* Request/response creation helpers *)

     

       112
       112
       -
         let create_request ?cursor ?id () =

     

       113
       113
       -
           let id = match id with

     

       114
       114
       -
             | Some i -> i

     

       115
       115
       -
             | None -> `Int (Random.int 10000)

     

       116
       116
       -
           in

     

       117
       117
       -
           let params = Request.yojson_of_t { cursor } in

     

       118
       118
       -
           JSONRPCMessage.create_request ~id ~method_:Method.resources_list ~params:(Some params) ()

     

       119
       119
       -
         

     

       120
       120
       -
         let create_response ~id ~resources ?next_cursor () =

     

       121
       121
       -
           let result = Response.yojson_of_t { resources; next_cursor } in

     

       122
       122
       -
           JSONRPCMessage.create_response ~id ~result

     

       123
       123
       -
       end

     

       124
       124
       -
       

     

       125
       125
       -
       (* Resources/Read *)

     

       126
       126
       -
       module ResourcesRead = struct

     

       127
       127
       -
         module Request = struct

     

       128
       128
       -
           type t = {

     

       129
       129
       -
             uri: string;

     

       130
       130
       -
           }

     

       131
       131
       -
           

     

       132
       132
       -
           let yojson_of_t { uri } =

     

       133
       133
       -
             `Assoc [

     

       134
       134
       -
               ("uri", `String uri);

     

       135
       135
       -
             ]

     

       136
       136
       -
           

     

       137
       137
       -
           let t_of_yojson = function

     

       138
       138
       -
             | `Assoc fields ->

     

       139
       139
       -
               let uri = match List.assoc_opt "uri" fields with

     

       140
       140
       -
                 | Some (`String s) -> s

     

       141
       141
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'uri' field", `Assoc fields))

     

       142
       142
       -
               in

     

       143
       143
       -
               { uri }

     

       144
       144
       -
             | j -> raise (Json.Of_json ("Expected object for ResourcesRead.Request.t", j))

     

       145
       145
       -
             

     

       146
       146
       -
         end

     

       147
       147
       -
         

     

       148
       148
       -
         module ResourceContent = struct

     

       149
       149
       -
           type t = 

     

       150
       150
       -
             | TextResource of TextResourceContents.t

     

       151
       151
       -
             | BlobResource of BlobResourceContents.t

     

       152
       152
       -
           

     

       153
       153
       -
           let yojson_of_t = function

     

       154
       154
       -
             | TextResource tr -> TextResourceContents.yojson_of_t tr

     

       155
       155
       -
             | BlobResource br -> BlobResourceContents.yojson_of_t br

     

       156
       156
       -
           

     

       157
       157
       -
           let t_of_yojson json =

     

       158
       158
       -
             match json with

     

       159
       159
       -
             | `Assoc fields ->

     

       160
       160
       -
               if List.mem_assoc "text" fields then

     

       161
       161
       -
                 TextResource (TextResourceContents.t_of_yojson json)

     

       162
       162
       -
               else if List.mem_assoc "blob" fields then

     

       163
       163
       -
                 BlobResource (BlobResourceContents.t_of_yojson json)

     

       164
       164
       -
               else

     

       165
       165
       -
                 raise (Json.Of_json ("Invalid resource content", json))

     

       166
       166
       -
             | j -> raise (Json.Of_json ("Expected object for ResourcesRead.ResourceContent.t", j))

     

       167
       167
       -
             

     

       168
       168
       -
         end

     

       169
       169
       -
         

     

       170
       170
       -
         module Response = struct

     

       171
       171
       -
           type t = {

     

       172
       172
       -
             contents: ResourceContent.t list;

     

       173
       173
       -
           }

     

       174
       174
       -
           

     

       175
       175
       -
           let yojson_of_t { contents } =

     

       176
       176
       -
             `Assoc [

     

       177
       177
       -
               ("contents", `List (List.map ResourceContent.yojson_of_t contents));

     

       178
       178
       -
             ]

     

       179
       179
       -
           

     

       180
       180
       -
           let t_of_yojson = function

     

       181
       181
       -
             | `Assoc fields ->

     

       182
       182
       -
               let contents = match List.assoc_opt "contents" fields with

     

       183
       183
       -
                 | Some (`List items) -> List.map ResourceContent.t_of_yojson items

     

       184
       184
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'contents' field", `Assoc fields))

     

       185
       185
       -
               in

     

       186
       186
       -
               { contents }

     

       187
       187
       -
             | j -> raise (Json.Of_json ("Expected object for ResourcesRead.Response.t", j))

     

       188
       188
       -
             

     

       189
       189
       -
         end

     

       190
       190
       -
         

     

       191
       191
       -
         (* Request/response creation helpers *)

     

       192
       192
       -
         let create_request ~uri ?id () =

     

       193
       193
       -
           let id = match id with

     

       194
       194
       -
             | Some i -> i

     

       195
       195
       -
             | None -> `Int (Random.int 10000)

     

       196
       196
       -
           in

     

       197
       197
       -
           let params = Request.yojson_of_t { uri } in

     

       198
       198
       -
           JSONRPCMessage.create_request ~id ~method_:Method.resources_read ~params:(Some params) ()

     

       199
       199
       -
         

     

       200
       200
       -
         let create_response ~id ~contents () =

     

       201
       201
       -
           let result = Response.yojson_of_t { contents } in

     

       202
       202
       -
           JSONRPCMessage.create_response ~id ~result

     

       203
       203
       -
       end

     

       204
       204
       -
       

     

       205
       205
       -
       (* Tools/List *)

     

       206
       206
       -
       module ToolsList = struct

     

       207
       207
       -
         module Request = struct

     

       208
       208
       -
           type t = {

     

       209
       209
       -
             cursor: Cursor.t option;

     

       210
       210
       -
           }

     

       211
       211
       -
           

     

       212
       212
       -
           let yojson_of_t { cursor } =

     

       213
       213
       -
             let assoc = [] in

     

       214
       214
       -
             let assoc = match cursor with

     

       215
       215
       -
               | Some c -> ("cursor", Cursor.yojson_of_t c) :: assoc

     

       216
       216
       -
               | None -> assoc

     

       217
       217
       -
             in

     

       218
       218
       -
             `Assoc assoc

     

       219
       219
       -
           

     

       220
       220
       -
           let t_of_yojson = function

     

       221
       221
       -
             | `Assoc fields ->

     

       222
       222
       -
               let cursor = List.assoc_opt "cursor" fields |> Option.map Cursor.t_of_yojson in

     

       223
       223
       -
               { cursor }

     

       224
       224
       -
             | j -> raise (Json.Of_json ("Expected object for ToolsList.Request.t", j))

     

       225
       225
       -
             

     

       226
       226
       -
         end

     

       227
       227
       -
         

     

       228
       228
       -
         module Tool = struct

     

       229
       229
       -
           type t = {

     

       230
       230
       -
             name: string;

     

       231
       231
       -
             description: string option;

     

       232
       232
       -
             input_schema: Json.t;

     

       233
       233
       -
             annotations: Json.t option;

     

       234
       234
       -
           }

     

       235
       235
       -
           

     

       236
       236
       -
           let yojson_of_t { name; description; input_schema; annotations } =

     

       237
       237
       -
             let assoc = [

     

       238
       238
       -
               ("name", `String name);

     

       239
       239
       -
               ("inputSchema", input_schema);

     

       240
       240
       -
             ] in

     

       241
       241
       -
             let assoc = match description with

     

       242
       242
       -
               | Some desc -> ("description", `String desc) :: assoc

     

       243
       243
       -
               | None -> assoc

     

       244
       244
       -
             in

     

       245
       245
       -
             let assoc = match annotations with

     

       246
       246
       -
               | Some anno -> ("annotations", anno) :: assoc

     

       247
       247
       -
               | None -> assoc

     

       248
       248
       -
             in

     

       249
       249
       -
             `Assoc assoc

     

       250
       250
       -
           

     

       251
       251
       -
           let t_of_yojson = function

     

       252
       252
       -
             | `Assoc fields ->

     

       253
       253
       -
               let name = match List.assoc_opt "name" fields with

     

       254
       254
       -
                 | Some (`String s) -> s

     

       255
       255
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'name' field", `Assoc fields))

     

       256
       256
       -
               in

     

       257
       257
       -
               let description = List.assoc_opt "description" fields |> Option.map (function

     

       258
       258
       -
                 | `String s -> s

     

       259
       259
       -
                 | j -> raise (Json.Of_json ("Expected string for description", j))

     

       260
       260
       -
               ) in

     

       261
       261
       -
               let input_schema = match List.assoc_opt "inputSchema" fields with

     

       262
       262
       -
                 | Some schema -> schema

     

       263
       263
       -
                 | None -> raise (Json.Of_json ("Missing 'inputSchema' field", `Assoc fields))

     

       264
       264
       -
               in

     

       265
       265
       -
               let annotations = List.assoc_opt "annotations" fields in

     

       266
       266
       -
               { name; description; input_schema; annotations }

     

       267
       267
       -
             | j -> raise (Json.Of_json ("Expected object for ToolsList.Tool.t", j))

     

       268
       268
       -
             

     

       269
       269
       -
         end

     

       270
       270
       -
         

     

       271
       271
       -
         module Response = struct

     

       272
       272
       -
           type t = {

     

       273
       273
       -
             tools: Tool.t list;

     

       274
       274
       -
             next_cursor: Cursor.t option;

     

       275
       275
       -
           }

     

       276
       276
       -
           

     

       277
       277
       -
           let yojson_of_t { tools; next_cursor } =

     

       278
       278
       -
             let assoc = [

     

       279
       279
       -
               ("tools", `List (List.map Tool.yojson_of_t tools));

     

       280
       280
       -
             ] in

     

       281
       281
       -
             let assoc = match next_cursor with

     

       282
       282
       -
               | Some c -> ("nextCursor", Cursor.yojson_of_t c) :: assoc

     

       283
       283
       -
               | None -> assoc

     

       284
       284
       -
             in

     

       285
       285
       -
             `Assoc assoc

     

       286
       286
       -
           

     

       287
       287
       -
           let t_of_yojson = function

     

       288
       288
       -
             | `Assoc fields ->

     

       289
       289
       -
               let tools = match List.assoc_opt "tools" fields with

     

       290
       290
       -
                 | Some (`List items) -> List.map Tool.t_of_yojson items

     

       291
       291
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'tools' field", `Assoc fields))

     

       292
       292
       -
               in

     

       293
       293
       -
               let next_cursor = List.assoc_opt "nextCursor" fields |> Option.map Cursor.t_of_yojson in

     

       294
       294
       -
               { tools; next_cursor }

     

       295
       295
       -
             | j -> raise (Json.Of_json ("Expected object for ToolsList.Response.t", j))

     

       296
       296
       -
             

     

       297
       297
       -
         end

     

       298
       298
       -
         

     

       299
       299
       -
         (* Request/response creation helpers *)

     

       300
       300
       -
         let create_request ?cursor ?id () =

     

       301
       301
       -
           let id = match id with

     

       302
       302
       -
             | Some i -> i

     

       303
       303
       -
             | None -> `Int (Random.int 10000)

     

       304
       304
       -
           in

     

       305
       305
       -
           let params = Request.yojson_of_t { cursor } in

     

       306
       306
       -
           JSONRPCMessage.create_request ~id ~method_:Method.tools_list ~params:(Some params) ()

     

       307
       307
       -
         

     

       308
       308
       -
         let create_response ~id ~tools ?next_cursor () =

     

       309
       309
       -
           let result = Response.yojson_of_t { tools; next_cursor } in

     

       310
       310
       -
           JSONRPCMessage.create_response ~id ~result

     

       311
       311
       -
       end

     

       312
       312
       -
       

     

       313
       313
       -
       (* Tools/Call *)

     

       314
       314
       -
       module ToolsCall = struct

     

       315
       315
       -
         module Request = struct

     

       316
       316
       -
           type t = {

     

       317
       317
       -
             name: string;

     

       318
       318
       -
             arguments: Json.t;

     

       319
       319
       -
           }

     

       320
       320
       -
           

     

       321
       321
       -
           let yojson_of_t { name; arguments } =

     

       322
       322
       -
             `Assoc [

     

       323
       323
       -
               ("name", `String name);

     

       324
       324
       -
               ("arguments", arguments);

     

       325
       325
       -
             ]

     

       326
       326
       -
           

     

       327
       327
       -
           let t_of_yojson = function

     

       328
       328
       -
             | `Assoc fields ->

     

       329
       329
       -
               let name = match List.assoc_opt "name" fields with

     

       330
       330
       -
                 | Some (`String s) -> s

     

       331
       331
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'name' field", `Assoc fields))

     

       332
       332
       -
               in

     

       333
       333
       -
               let arguments = match List.assoc_opt "arguments" fields with

     

       334
       334
       -
                 | Some json -> json

     

       335
       335
       -
                 | None -> raise (Json.Of_json ("Missing 'arguments' field", `Assoc fields))

     

       336
       336
       -
               in

     

       337
       337
       -
               { name; arguments }

     

       338
       338
       -
             | j -> raise (Json.Of_json ("Expected object for ToolsCall.Request.t", j))

     

       339
       339
       -
             

     

       340
       340
       -
         end

     

       341
       341
       -
         

     

       342
       342
       -
         module ToolContent = struct

     

       343
       343
       -
           type t = 

     

       344
       344
       -
             | Text of TextContent.t

     

       345
       345
       -
             | Image of ImageContent.t

     

       346
       346
       -
             | Audio of AudioContent.t

     

       347
       347
       -
             | Resource of EmbeddedResource.t

     

       348
       348
       -
           

     

       349
       349
       -
           let yojson_of_t = function

     

       350
       350
       -
             | Text t -> TextContent.yojson_of_t t

     

       351
       351
       -
             | Image i -> ImageContent.yojson_of_t i

     

       352
       352
       -
             | Audio a -> AudioContent.yojson_of_t a

     

       353
       353
       -
             | Resource r -> EmbeddedResource.yojson_of_t r

     

       354
       354
       -
           

     

       355
       355
       -
           let t_of_yojson json =

     

       356
       356
       -
             match json with

     

       357
       357
       -
             | `Assoc fields ->

     

       358
       358
       -
               (match List.assoc_opt "type" fields with

     

       359
       359
       -
                | Some (`String "text") -> Text (TextContent.t_of_yojson json)

     

       360
       360
       -
                | Some (`String "image") -> Image (ImageContent.t_of_yojson json)

     

       361
       361
       -
                | Some (`String "audio") -> Audio (AudioContent.t_of_yojson json)

     

       362
       362
       -
                | Some (`String "resource") -> Resource (EmbeddedResource.t_of_yojson json)

     

       363
       363
       -
                | _ -> raise (Json.Of_json ("Invalid or missing content type", json)))

     

       364
       364
       -
             | j -> raise (Json.Of_json ("Expected object for ToolsCall.ToolContent.t", j))

     

       365
       365
       -
             

     

       366
       366
       -
         end

     

       367
       367
       -
         

     

       368
       368
       -
         module Response = struct

     

       369
       369
       -
           type t = {

     

       370
       370
       -
             content: ToolContent.t list;

     

       371
       371
       -
             is_error: bool;

     

       372
       372
       -
           }

     

       373
       373
       -
           

     

       374
       374
       -
           let yojson_of_t { content; is_error } =

     

       375
       375
       -
             `Assoc [

     

       376
       376
       -
               ("content", `List (List.map ToolContent.yojson_of_t content));

     

       377
       377
       -
               ("isError", `Bool is_error);

     

       378
       378
       -
             ]

     

       379
       379
       -
           

     

       380
       380
       -
           let t_of_yojson = function

     

       381
       381
       -
             | `Assoc fields ->

     

       382
       382
       -
               let content = match List.assoc_opt "content" fields with

     

       383
       383
       -
                 | Some (`List items) -> List.map ToolContent.t_of_yojson items

     

       384
       384
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'content' field", `Assoc fields))

     

       385
       385
       -
               in

     

       386
       386
       -
               let is_error = match List.assoc_opt "isError" fields with

     

       387
       387
       -
                 | Some (`Bool b) -> b

     

       388
       388
       -
                 | _ -> false

     

       389
       389
       -
               in

     

       390
       390
       -
               { content; is_error }

     

       391
       391
       -
             | j -> raise (Json.Of_json ("Expected object for ToolsCall.Response.t", j))

     

       392
       392
       -
             

     

       393
       393
       -
         end

     

       394
       394
       -
         

     

       395
       395
       -
         (* Request/response creation helpers *)

     

       396
       396
       -
         let create_request ~name ~arguments ?id () =

     

       397
       397
       -
           let id = match id with

     

       398
       398
       -
             | Some i -> i

     

       399
       399
       -
             | None -> `Int (Random.int 10000)

     

       400
       400
       -
           in

     

       401
       401
       -
           let params = Request.yojson_of_t { name; arguments } in

     

       402
       402
       -
           JSONRPCMessage.create_request ~id ~method_:Method.tools_call ~params:(Some params) ()

     

       403
       403
       -
         

     

       404
       404
       -
         let create_response ~id ~content ~is_error () =

     

       405
       405
       -
           let result = Response.yojson_of_t { content; is_error } in

     

       406
       406
       -
           JSONRPCMessage.create_response ~id ~result

     

       407
       407
       -
       end

     

       408
       408
       -
       

     

       409
       409
       -
       (* Prompts/List *)

     

       410
       410
       -
       module PromptsList = struct

     

       411
       411
       -
         module PromptArgument = struct

     

       412
       412
       -
           type t = {

     

       413
       413
       -
             name: string;

     

       414
       414
       -
             description: string option;

     

       415
       415
       -
             required: bool;

     

       416
       416
       -
           }

     

       417
       417
       -
           

     

       418
       418
       -
           let yojson_of_t { name; description; required } =

     

       419
       419
       -
             let assoc = [

     

       420
       420
       -
               ("name", `String name);

     

       421
       421
       -
             ] in

     

       422
       422
       -
             let assoc = match description with

     

       423
       423
       -
               | Some desc -> ("description", `String desc) :: assoc

     

       424
       424
       -
               | None -> assoc

     

       425
       425
       -
             in

     

       426
       426
       -
             let assoc = if required then

     

       427
       427
       -
               ("required", `Bool true) :: assoc

     

       428
       428
       -
             else

     

       429
       429
       -
               assoc

     

       430
       430
       -
             in

     

       431
       431
       -
             `Assoc assoc

     

       432
       432
       -
           

     

       433
       433
       -
           let t_of_yojson = function

     

       434
       434
       -
             | `Assoc fields ->

     

       435
       435
       -
               let name = match List.assoc_opt "name" fields with

     

       436
       436
       -
                 | Some (`String s) -> s

     

       437
       437
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'name' field", `Assoc fields))

     

       438
       438
       -
               in

     

       439
       439
       -
               let description = List.assoc_opt "description" fields |> Option.map (function

     

       440
       440
       -
                 | `String s -> s

     

       441
       441
       -
                 | j -> raise (Json.Of_json ("Expected string for description", j))

     

       442
       442
       -
               ) in

     

       443
       443
       -
               let required = match List.assoc_opt "required" fields with

     

       444
       444
       -
                 | Some (`Bool b) -> b

     

       445
       445
       -
                 | _ -> false

     

       446
       446
       -
               in

     

       447
       447
       -
               { name; description; required }

     

       448
       448
       -
             | j -> raise (Json.Of_json ("Expected object for PromptsList.PromptArgument.t", j))

     

       449
       449
       -
             

     

       450
       450
       -
         end

     

       451
       451
       -
         

     

       452
       452
       -
         module Prompt = struct

     

       453
       453
       -
           type t = {

     

       454
       454
       -
             name: string;

     

       455
       455
       -
             description: string option;

     

       456
       456
       -
             arguments: PromptArgument.t list;

     

       457
       457
       -
           }

     

       458
       458
       -
           

     

       459
       459
       -
           let yojson_of_t { name; description; arguments } =

     

       460
       460
       -
             let assoc = [

     

       461
       461
       -
               ("name", `String name);

     

       462
       462
       -
             ] in

     

       463
       463
       -
             let assoc = match description with

     

       464
       464
       -
               | Some desc -> ("description", `String desc) :: assoc

     

       465
       465
       -
               | None -> assoc

     

       466
       466
       -
             in

     

       467
       467
       -
             let assoc = if arguments <> [] then

     

       468
       468
       -
               ("arguments", `List (List.map PromptArgument.yojson_of_t arguments)) :: assoc

     

       469
       469
       -
             else

     

       470
       470
       -
               assoc

     

       471
       471
       -
             in

     

       472
       472
       -
             `Assoc assoc

     

       473
       473
       -
           

     

       474
       474
       -
           let t_of_yojson = function

     

       475
       475
       -
             | `Assoc fields ->

     

       476
       476
       -
               let name = match List.assoc_opt "name" fields with

     

       477
       477
       -
                 | Some (`String s) -> s

     

       478
       478
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'name' field", `Assoc fields))

     

       479
       479
       -
               in

     

       480
       480
       -
               let description = List.assoc_opt "description" fields |> Option.map (function

     

       481
       481
       -
                 | `String s -> s

     

       482
       482
       -
                 | j -> raise (Json.Of_json ("Expected string for description", j))

     

       483
       483
       -
               ) in

     

       484
       484
       -
               let arguments = match List.assoc_opt "arguments" fields with

     

       485
       485
       -
                 | Some (`List items) -> List.map PromptArgument.t_of_yojson items

     

       486
       486
       -
                 | _ -> []

     

       487
       487
       -
               in

     

       488
       488
       -
               { name; description; arguments }

     

       489
       489
       -
             | j -> raise (Json.Of_json ("Expected object for PromptsList.Prompt.t", j))

     

       490
       490
       -
             

     

       491
       491
       -
         end

     

       492
       492
       -
         

     

       493
       493
       -
         module Request = struct

     

       494
       494
       -
           type t = {

     

       495
       495
       -
             cursor: Cursor.t option;

     

       496
       496
       -
           }

     

       497
       497
       -
           

     

       498
       498
       -
           let yojson_of_t { cursor } =

     

       499
       499
       -
             let assoc = [] in

     

       500
       500
       -
             let assoc = match cursor with

     

       501
       501
       -
               | Some c -> ("cursor", Cursor.yojson_of_t c) :: assoc

     

       502
       502
       -
               | None -> assoc

     

       503
       503
       -
             in

     

       504
       504
       -
             `Assoc assoc

     

       505
       505
       -
           

     

       506
       506
       -
           let t_of_yojson = function

     

       507
       507
       -
             | `Assoc fields ->

     

       508
       508
       -
               let cursor = List.assoc_opt "cursor" fields |> Option.map Cursor.t_of_yojson in

     

       509
       509
       -
               { cursor }

     

       510
       510
       -
             | j -> raise (Json.Of_json ("Expected object for PromptsList.Request.t", j))

     

       511
       511
       -
             

     

       512
       512
       -
         end

     

       513
       513
       -
         

     

       514
       514
       -
         module Response = struct

     

       515
       515
       -
           type t = {

     

       516
       516
       -
             prompts: Prompt.t list;

     

       517
       517
       -
             next_cursor: Cursor.t option;

     

       518
       518
       -
           }

     

       519
       519
       -
           

     

       520
       520
       -
           let yojson_of_t { prompts; next_cursor } =

     

       521
       521
       -
             let assoc = [

     

       522
       522
       -
               ("prompts", `List (List.map Prompt.yojson_of_t prompts));

     

       523
       523
       -
             ] in

     

       524
       524
       -
             let assoc = match next_cursor with

     

       525
       525
       -
               | Some c -> ("nextCursor", Cursor.yojson_of_t c) :: assoc

     

       526
       526
       -
               | None -> assoc

     

       527
       527
       -
             in

     

       528
       528
       -
             `Assoc assoc

     

       529
       529
       -
           

     

       530
       530
       -
           let t_of_yojson = function

     

       531
       531
       -
             | `Assoc fields ->

     

       532
       532
       -
               let prompts = match List.assoc_opt "prompts" fields with

     

       533
       533
       -
                 | Some (`List items) -> List.map Prompt.t_of_yojson items

     

       534
       534
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'prompts' field", `Assoc fields))

     

       535
       535
       -
               in

     

       536
       536
       -
               let next_cursor = List.assoc_opt "nextCursor" fields |> Option.map Cursor.t_of_yojson in

     

       537
       537
       -
               { prompts; next_cursor }

     

       538
       538
       -
             | j -> raise (Json.Of_json ("Expected object for PromptsList.Response.t", j))

     

       539
       539
       -
             

     

       540
       540
       -
         end

     

       541
       541
       -
         

     

       542
       542
       -
         (* Request/response creation helpers *)

     

       543
       543
       -
         let create_request ?cursor ?id () =

     

       544
       544
       -
           let id = match id with

     

       545
       545
       -
             | Some i -> i

     

       546
       546
       -
             | None -> `Int (Random.int 10000)

     

       547
       547
       -
           in

     

       548
       548
       -
           let params = Request.yojson_of_t { cursor } in

     

       549
       549
       -
           JSONRPCMessage.create_request ~id ~method_:Method.prompts_list ~params:(Some params) ()

     

       550
       550
       -
         

     

       551
       551
       -
         let create_response ~id ~prompts ?next_cursor () =

     

       552
       552
       -
           let result = Response.yojson_of_t { prompts; next_cursor } in

     

       553
       553
       -
           JSONRPCMessage.create_response ~id ~result

     

       554
       554
       -
       end

     

       555
       555
       -
       

     

       556
       556
       -
       (* Prompts/Get *)

     

       557
       557
       -
       module PromptsGet = struct

     

       558
       558
       -
         module Request = struct

     

       559
       559
       -
           type t = {

     

       560
       560
       -
             name: string;

     

       561
       561
       -
             arguments: (string * string) list;

     

       562
       562
       -
           }

     

       563
       563
       -
           

     

       564
       564
       -
           let yojson_of_t { name; arguments } =

     

       565
       565
       -
             let args_json = `Assoc (List.map (fun (k, v) -> (k, `String v)) arguments) in

     

       566
       566
       -
             `Assoc [

     

       567
       567
       -
               ("name", `String name);

     

       568
       568
       -
               ("arguments", args_json);

     

       569
       569
       -
             ]

     

       570
       570
       -
           

     

       571
       571
       -
           let t_of_yojson = function

     

       572
       572
       -
             | `Assoc fields ->

     

       573
       573
       -
               let name = match List.assoc_opt "name" fields with

     

       574
       574
       -
                 | Some (`String s) -> s

     

       575
       575
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'name' field", `Assoc fields))

     

       576
       576
       -
               in

     

       577
       577
       -
               let arguments = match List.assoc_opt "arguments" fields with

     

       578
       578
       -
                 | Some (`Assoc args) -> 

     

       579
       579
       -
                   List.map (fun (k, v) -> 

     

       580
       580
       -
                     match v with

     

       581
       581
       -
                     | `String s -> (k, s)

     

       582
       582
       -
                     | _ -> raise (Json.Of_json ("Expected string value for argument", v))

     

       583
       583
       -
                   ) args

     

       584
       584
       -
                 | _ -> []

     

       585
       585
       -
               in

     

       586
       586
       -
               { name; arguments }

     

       587
       587
       -
             | j -> raise (Json.Of_json ("Expected object for PromptsGet.Request.t", j))

     

       588
       588
       -
             

     

       589
       589
       -
         end

     

       590
       590
       -
         

     

       591
       591
       -
         module Response = struct

     

       592
       592
       -
           type t = {

     

       593
       593
       -
             description: string option;

     

       594
       594
       -
             messages: PromptMessage.t list;

     

       595
       595
       -
           }

     

       596
       596
       -
           

     

       597
       597
       -
           let yojson_of_t { description; messages } =

     

       598
       598
       -
             let assoc = [

     

       599
       599
       -
               ("messages", `List (List.map PromptMessage.yojson_of_t messages));

     

       600
       600
       -
             ] in

     

       601
       601
       -
             let assoc = match description with

     

       602
       602
       -
               | Some desc -> ("description", `String desc) :: assoc

     

       603
       603
       -
               | None -> assoc

     

       604
       604
       -
             in

     

       605
       605
       -
             `Assoc assoc

     

       606
       606
       -
           

     

       607
       607
       -
           let t_of_yojson = function

     

       608
       608
       -
             | `Assoc fields ->

     

       609
       609
       -
               let messages = match List.assoc_opt "messages" fields with

     

       610
       610
       -
                 | Some (`List items) -> List.map PromptMessage.t_of_yojson items

     

       611
       611
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'messages' field", `Assoc fields))

     

       612
       612
       -
               in

     

       613
       613
       -
               let description = List.assoc_opt "description" fields |> Option.map (function

     

       614
       614
       -
                 | `String s -> s

     

       615
       615
       -
                 | j -> raise (Json.Of_json ("Expected string for description", j))

     

       616
       616
       -
               ) in

     

       617
       617
       -
               { description; messages }

     

       618
       618
       -
             | j -> raise (Json.Of_json ("Expected object for PromptsGet.Response.t", j))

     

       619
       619
       -
             

     

       620
       620
       -
         end

     

       621
       621
       -
         

     

       622
       622
       -
         (* Request/response creation helpers *)

     

       623
       623
       -
         let create_request ~name ~arguments ?id () =

     

       624
       624
       -
           let id = match id with

     

       625
       625
       -
             | Some i -> i

     

       626
       626
       -
             | None -> `Int (Random.int 10000)

     

       627
       627
       -
           in

     

       628
       628
       -
           let params = Request.yojson_of_t { name; arguments } in

     

       629
       629
       -
           JSONRPCMessage.create_request ~id ~method_:Method.prompts_get ~params:(Some params) ()

     

       630
       630
       -
         

     

       631
       631
       -
         let create_response ~id ?description ~messages () =

     

       632
       632
       -
           let result = Response.yojson_of_t { description; messages } in

     

       633
       633
       -
           JSONRPCMessage.create_response ~id ~result

     

       634
       634
       -
       end

     

       635
       635
       -
       

     

       636
       636
       -
       (* List Changed Notifications *)

     

       637
       637
       -
       module ListChanged = struct

     

       638
       638
       -
         (* No parameters for these notifications *)

     

       639
       639
       -
         

     

       640
       640
       -
         let create_resources_notification () =

     

       641
       641
       -
           JSONRPCMessage.create_notification ~method_:Method.resources_list_changed ()

     

       642
       642
       -
         

     

       643
       643
       -
         let create_tools_notification () =

     

       644
       644
       -
           JSONRPCMessage.create_notification ~method_:Method.tools_list_changed ()

     

       645
       645
       -
         

     

       646
       646
       -
         let create_prompts_notification () =

     

       647
       647
       -
           JSONRPCMessage.create_notification ~method_:Method.prompts_list_changed ()

     

       648
       648
       -
       end

     

       649
       649
       -
       

     

       650
       650
       -
       (* Resource Updated Notification *)

     

       651
       651
       -
       module ResourceUpdated = struct

     

       652
       652
       -
         module Notification = struct

     

       653
       653
       -
           type t = {

     

       654
       654
       -
             uri: string;

     

       655
       655
       -
           }

     

       656
       656
       -
           

     

       657
       657
       -
           let yojson_of_t { uri } =

     

       658
       658
       -
             `Assoc [

     

       659
       659
       -
               ("uri", `String uri);

     

       660
       660
       -
             ]

     

       661
       661
       -
           

     

       662
       662
       -
           let t_of_yojson = function

     

       663
       663
       -
             | `Assoc fields ->

     

       664
       664
       -
               let uri = match List.assoc_opt "uri" fields with

     

       665
       665
       -
                 | Some (`String s) -> s

     

       666
       666
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'uri' field", `Assoc fields))

     

       667
       667
       -
               in

     

       668
       668
       -
               { uri }

     

       669
       669
       -
             | j -> raise (Json.Of_json ("Expected object for ResourceUpdated.Notification.t", j))

     

       670
       670
       -
             

     

       671
       671
       -
         end

     

       672
       672
       -
         

     

       673
       673
       -
         let create_notification ~uri () =

     

       674
       674
       -
           let params = Notification.yojson_of_t { uri } in

     

       675
       675
       -
           JSONRPCMessage.create_notification ~method_:Method.resources_updated ~params:(Some params) ()

     

       676
       676
       -
       end

     

       677
       677
       -
       

     

       678
       678
       -
       (* Progress Notification *)

     

       679
       679
       -
       module Progress = struct

     

       680
       680
       -
         module Notification = struct

     

       681
       681
       -
           type t = {

     

       682
       682
       -
             progress: float;

     

       683
       683
       -
             total: float;

     

       684
       684
       -
             progress_token: ProgressToken.t;

     

       685
       685
       -
           }

     

       686
       686
       -
           

     

       687
       687
       -
           let yojson_of_t { progress; total; progress_token } =

     

       688
       688
       -
             `Assoc [

     

       689
       689
       -
               ("progress", `Float progress);

     

       690
       690
       -
               ("total", `Float total);

     

       691
       691
       -
               ("progressToken", ProgressToken.yojson_of_t progress_token);

     

       692
       692
       -
             ]

     

       693
       693
       -
           

     

       694
       694
       -
           let t_of_yojson = function

     

       695
       695
       -
             | `Assoc fields ->

     

       696
       696
       -
               let progress = match List.assoc_opt "progress" fields with

     

       697
       697
       -
                 | Some (`Float f) -> f

     

       698
       698
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'progress' field", `Assoc fields))

     

       699
       699
       -
               in

     

       700
       700
       -
               let total = match List.assoc_opt "total" fields with

     

       701
       701
       -
                 | Some (`Float f) -> f

     

       702
       702
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'total' field", `Assoc fields))

     

       703
       703
       -
               in

     

       704
       704
       -
               let progress_token = match List.assoc_opt "progressToken" fields with

     

       705
       705
       -
                 | Some token -> ProgressToken.t_of_yojson token

     

       706
       706
       -
                 | _ -> raise (Json.Of_json ("Missing or invalid 'progressToken' field", `Assoc fields))

     

       707
       707
       -
               in

     

       708
       708
       -
               { progress; total; progress_token }

     

       709
       709
       -
             | j -> raise (Json.Of_json ("Expected object for Progress.Notification.t", j))

     

       710
       710
       -
             

     

       711
       711
       -
         end

     

       712
       712
       -
         

     

       713
       713
       -
         let create_notification ~progress ~total ~progress_token () =

     

       714
       714
       -
           let params = Notification.yojson_of_t { progress; total; progress_token } in

     

       715
       715
       -
           JSONRPCMessage.create_notification ~method_:Method.progress ~params:(Some params) ()

     

       716
       716
       -
       end

     

       717
       717
       -
       

     

       718
       718
       -
       (* Type aliases for backward compatibility *)

     

       719
       719
       -
       type request = ResourcesList.Request.t

     

       720
       720
       -
       type response = ResourcesList.Response.t 

     

       721
       721
       -
       type resource = ResourcesList.Resource.t

     

       722
       722
       -
       type resource_content = ResourcesRead.ResourceContent.t

     

       723
       723
       -
       type tool = ToolsList.Tool.t

     

       724
       724
       -
       type tool_content = ToolsCall.ToolContent.t

     

       725
       725
       -
       type prompt = PromptsList.Prompt.t

     

       726
       726
       -
       type prompt_argument = PromptsList.PromptArgument.t

-264

lib/mcp_message.mli

···

       1
       1
       -
       (** Mcp_message - High-level RPC message definitions for Model Context Protocol *)

     

       2
       2
       -
       

     

       3
       3
       -
       open Mcp

     

       4
       4
       -
       open Jsonrpc

     

       5
       5
       -
       

     

       6
       6
       -
       (** Resources/List - Request to list available resources *)

     

       7
       7
       -
       module ResourcesList : sig

     

       8
       8
       -
         (** Request parameters *)

     

       9
       9
       -
         module Request : sig

     

       10
       10
       -
           type t = {

     

       11
       11
       -
             cursor: Cursor.t option; (** Optional pagination cursor *)

     

       12
       12
       -
           }

     

       13
       13
       -
           include Json.Jsonable.S with type t := t

     

       14
       14
       -
         end

     

       15
       15
       -
         

     

       16
       16
       -
         (** Resource definition *)

     

       17
       17
       -
         module Resource : sig

     

       18
       18
       -
           type t = {

     

       19
       19
       -
             uri: string; (** Unique identifier for the resource *)

     

       20
       20
       -
             name: string; (** Human-readable name *)

     

       21
       21
       -
             description: string option; (** Optional description *)

     

       22
       22
       -
             mime_type: string option; (** Optional MIME type *)

     

       23
       23
       -
             size: int option; (** Optional size in bytes *)

     

       24
       24
       -
           }

     

       25
       25
       -
           include Json.Jsonable.S with type t := t

     

       26
       26
       -
         end

     

       27
       27
       -
         

     

       28
       28
       -
         (** Response result *)

     

       29
       29
       -
         module Response : sig

     

       30
       30
       -
           type t = {

     

       31
       31
       -
             resources: Resource.t list; (** List of available resources *)

     

       32
       32
       -
             next_cursor: Cursor.t option; (** Optional cursor for the next page *)

     

       33
       33
       -
           }

     

       34
       34
       -
           include Json.Jsonable.S with type t := t

     

       35
       35
       -
         end

     

       36
       36
       -
         

     

       37
       37
       -
         (** Create a resources/list request *)

     

       38
       38
       -
         val create_request : ?cursor:Cursor.t -> ?id:RequestId.t -> unit -> JSONRPCMessage.t

     

       39
       39
       -
         

     

       40
       40
       -
         (** Create a resources/list response *)

     

       41
       41
       -
         val create_response : id:RequestId.t -> resources:Resource.t list -> ?next_cursor:Cursor.t -> unit -> JSONRPCMessage.t

     

       42
       42
       -
       end

     

       43
       43
       -
       

     

       44
       44
       -
       (** Resources/Read - Request to read resource contents *)

     

       45
       45
       -
       module ResourcesRead : sig

     

       46
       46
       -
         (** Request parameters *)

     

       47
       47
       -
         module Request : sig

     

       48
       48
       -
           type t = {

     

       49
       49
       -
             uri: string; (** URI of the resource to read *)

     

       50
       50
       -
           }

     

       51
       51
       -
           include Json.Jsonable.S with type t := t

     

       52
       52
       -
         end

     

       53
       53
       -
         

     

       54
       54
       -
         (** Resource content *)

     

       55
       55
       -
         module ResourceContent : sig

     

       56
       56
       -
           type t = 

     

       57
       57
       -
             | TextResource of TextResourceContents.t (** Text content *)

     

       58
       58
       -
             | BlobResource of BlobResourceContents.t (** Binary content *)

     

       59
       59
       -
           include Json.Jsonable.S with type t := t

     

       60
       60
       -
         end

     

       61
       61
       -
         

     

       62
       62
       -
         (** Response result *)

     

       63
       63
       -
         module Response : sig

     

       64
       64
       -
           type t = {

     

       65
       65
       -
             contents: ResourceContent.t list; (** List of resource contents *)

     

       66
       66
       -
           }

     

       67
       67
       -
           include Json.Jsonable.S with type t := t

     

       68
       68
       -
         end

     

       69
       69
       -
         

     

       70
       70
       -
         (** Create a resources/read request *)

     

       71
       71
       -
         val create_request : uri:string -> ?id:RequestId.t -> unit -> JSONRPCMessage.t

     

       72
       72
       -
         

     

       73
       73
       -
         (** Create a resources/read response *)

     

       74
       74
       -
         val create_response : id:RequestId.t -> contents:ResourceContent.t list -> unit -> JSONRPCMessage.t

     

       75
       75
       -
       end

     

       76
       76
       -
       

     

       77
       77
       -
       (** Tools/List - Request to list available tools *)

     

       78
       78
       -
       module ToolsList : sig

     

       79
       79
       -
         (** Request parameters *)

     

       80
       80
       -
         module Request : sig

     

       81
       81
       -
           type t = {

     

       82
       82
       -
             cursor: Cursor.t option; (** Optional pagination cursor *)

     

       83
       83
       -
           }

     

       84
       84
       -
           include Json.Jsonable.S with type t := t

     

       85
       85
       -
         end

     

       86
       86
       -
         

     

       87
       87
       -
         (** Tool definition *)

     

       88
       88
       -
         module Tool : sig

     

       89
       89
       -
           type t = {

     

       90
       90
       -
             name: string; (** Unique identifier for the tool *)

     

       91
       91
       -
             description: string option; (** Human-readable description *)

     

       92
       92
       -
             input_schema: Json.t; (** JSON Schema defining expected parameters *)

     

       93
       93
       -
             annotations: Json.t option; (** Optional properties describing tool behavior *)

     

       94
       94
       -
           }

     

       95
       95
       -
           include Json.Jsonable.S with type t := t

     

       96
       96
       -
         end

     

       97
       97
       -
         

     

       98
       98
       -
         (** Response result *)

     

       99
       99
       -
         module Response : sig

     

       100
       100
       -
           type t = {

     

       101
       101
       -
             tools: Tool.t list; (** List of available tools *)

     

       102
       102
       -
             next_cursor: Cursor.t option; (** Optional cursor for the next page *)

     

       103
       103
       -
           }

     

       104
       104
       -
           include Json.Jsonable.S with type t := t

     

       105
       105
       -
         end

     

       106
       106
       -
         

     

       107
       107
       -
         (** Create a tools/list request *)

     

       108
       108
       -
         val create_request : ?cursor:Cursor.t -> ?id:RequestId.t -> unit -> JSONRPCMessage.t

     

       109
       109
       -
         

     

       110
       110
       -
         (** Create a tools/list response *)

     

       111
       111
       -
         val create_response : id:RequestId.t -> tools:Tool.t list -> ?next_cursor:Cursor.t -> unit -> JSONRPCMessage.t

     

       112
       112
       -
       end

     

       113
       113
       -
       

     

       114
       114
       -
       (** Tools/Call - Request to invoke a tool *)

     

       115
       115
       -
       module ToolsCall : sig

     

       116
       116
       -
         (** Request parameters *)

     

       117
       117
       -
         module Request : sig

     

       118
       118
       -
           type t = {

     

       119
       119
       -
             name: string; (** Name of the tool to call *)

     

       120
       120
       -
             arguments: Json.t; (** Arguments for the tool invocation *)

     

       121
       121
       -
           }

     

       122
       122
       -
           include Json.Jsonable.S with type t := t

     

       123
       123
       -
         end

     

       124
       124
       -
         

     

       125
       125
       -
         (** Tool content *)

     

       126
       126
       -
         module ToolContent : sig

     

       127
       127
       -
           type t = 

     

       128
       128
       -
             | Text of TextContent.t (** Text content *)

     

       129
       129
       -
             | Image of ImageContent.t (** Image content *)

     

       130
       130
       -
             | Audio of AudioContent.t (** Audio content *)

     

       131
       131
       -
             | Resource of EmbeddedResource.t (** Resource content *)

     

       132
       132
       -
           include Json.Jsonable.S with type t := t

     

       133
       133
       -
         end

     

       134
       134
       -
         

     

       135
       135
       -
         (** Response result *)

     

       136
       136
       -
         module Response : sig

     

       137
       137
       -
           type t = {

     

       138
       138
       -
             content: ToolContent.t list; (** List of content items returned by the tool *)

     

       139
       139
       -
             is_error: bool; (** Whether the result represents an error *)

     

       140
       140
       -
           }

     

       141
       141
       -
           include Json.Jsonable.S with type t := t

     

       142
       142
       -
         end

     

       143
       143
       -
         

     

       144
       144
       -
         (** Create a tools/call request *)

     

       145
       145
       -
         val create_request : name:string -> arguments:Json.t -> ?id:RequestId.t -> unit -> JSONRPCMessage.t

     

       146
       146
       -
         

     

       147
       147
       -
         (** Create a tools/call response *)

     

       148
       148
       -
         val create_response : id:RequestId.t -> content:ToolContent.t list -> is_error:bool -> unit -> JSONRPCMessage.t

     

       149
       149
       -
       end

     

       150
       150
       -
       

     

       151
       151
       -
       (** Prompts/List - Request to list available prompts *)

     

       152
       152
       -
       module PromptsList : sig

     

       153
       153
       -
         (** Prompt argument *)

     

       154
       154
       -
         module PromptArgument : sig

     

       155
       155
       -
           type t = {

     

       156
       156
       -
             name: string; (** Name of the argument *)

     

       157
       157
       -
             description: string option; (** Description of the argument *)

     

       158
       158
       -
             required: bool; (** Whether the argument is required *)

     

       159
       159
       -
           }

     

       160
       160
       -
           include Json.Jsonable.S with type t := t

     

       161
       161
       -
         end

     

       162
       162
       -
         

     

       163
       163
       -
         (** Prompt definition *)

     

       164
       164
       -
         module Prompt : sig

     

       165
       165
       -
           type t = {

     

       166
       166
       -
             name: string; (** Unique identifier for the prompt *)

     

       167
       167
       -
             description: string option; (** Human-readable description *)

     

       168
       168
       -
             arguments: PromptArgument.t list; (** Arguments for customization *)

     

       169
       169
       -
           }

     

       170
       170
       -
           include Json.Jsonable.S with type t := t

     

       171
       171
       -
         end

     

       172
       172
       -
         

     

       173
       173
       -
         (** Request parameters *)

     

       174
       174
       -
         module Request : sig

     

       175
       175
       -
           type t = {

     

       176
       176
       -
             cursor: Cursor.t option; (** Optional pagination cursor *)

     

       177
       177
       -
           }

     

       178
       178
       -
           include Json.Jsonable.S with type t := t

     

       179
       179
       -
         end

     

       180
       180
       -
         

     

       181
       181
       -
         (** Response result *)

     

       182
       182
       -
         module Response : sig

     

       183
       183
       -
           type t = {

     

       184
       184
       -
             prompts: Prompt.t list; (** List of available prompts *)

     

       185
       185
       -
             next_cursor: Cursor.t option; (** Optional cursor for the next page *)

     

       186
       186
       -
           }

     

       187
       187
       -
           include Json.Jsonable.S with type t := t

     

       188
       188
       -
         end

     

       189
       189
       -
         

     

       190
       190
       -
         (** Create a prompts/list request *)

     

       191
       191
       -
         val create_request : ?cursor:Cursor.t -> ?id:RequestId.t -> unit -> JSONRPCMessage.t

     

       192
       192
       -
         

     

       193
       193
       -
         (** Create a prompts/list response *)

     

       194
       194
       -
         val create_response : id:RequestId.t -> prompts:Prompt.t list -> ?next_cursor:Cursor.t -> unit -> JSONRPCMessage.t

     

       195
       195
       -
       end

     

       196
       196
       -
       

     

       197
       197
       -
       (** Prompts/Get - Request to get a prompt with arguments *)

     

       198
       198
       -
       module PromptsGet : sig

     

       199
       199
       -
         (** Request parameters *)

     

       200
       200
       -
         module Request : sig

     

       201
       201
       -
           type t = {

     

       202
       202
       -
             name: string; (** Name of the prompt to get *)

     

       203
       203
       -
             arguments: (string * string) list; (** Arguments for the prompt *)

     

       204
       204
       -
           }

     

       205
       205
       -
           include Json.Jsonable.S with type t := t

     

       206
       206
       -
         end

     

       207
       207
       -
         

     

       208
       208
       -
         (** Response result *)

     

       209
       209
       -
         module Response : sig

     

       210
       210
       -
           type t = {

     

       211
       211
       -
             description: string option; (** Description of the prompt *)

     

       212
       212
       -
             messages: PromptMessage.t list; (** List of messages in the prompt *)

     

       213
       213
       -
           }

     

       214
       214
       -
           include Json.Jsonable.S with type t := t

     

       215
       215
       -
         end

     

       216
       216
       -
         

     

       217
       217
       -
         (** Create a prompts/get request *)

     

       218
       218
       -
         val create_request : name:string -> arguments:(string * string) list -> ?id:RequestId.t -> unit -> JSONRPCMessage.t

     

       219
       219
       -
         

     

       220
       220
       -
         (** Create a prompts/get response *)

     

       221
       221
       -
         val create_response : id:RequestId.t -> ?description:string -> messages:PromptMessage.t list -> unit -> JSONRPCMessage.t

     

       222
       222
       -
       end

     

       223
       223
       -
       

     

       224
       224
       -
       (** List Changed Notifications *)

     

       225
       225
       -
       module ListChanged : sig

     

       226
       226
       -
         (** Create a resources/list_changed notification *)

     

       227
       227
       -
         val create_resources_notification : unit -> JSONRPCMessage.t

     

       228
       228
       -
         

     

       229
       229
       -
         (** Create a tools/list_changed notification *)

     

       230
       230
       -
         val create_tools_notification : unit -> JSONRPCMessage.t

     

       231
       231
       -
         

     

       232
       232
       -
         (** Create a prompts/list_changed notification *)

     

       233
       233
       -
         val create_prompts_notification : unit -> JSONRPCMessage.t

     

       234
       234
       -
       end

     

       235
       235
       -
       

     

       236
       236
       -
       (** Resource Updated Notification *)

     

       237
       237
       -
       module ResourceUpdated : sig

     

       238
       238
       -
         (** Notification parameters *)

     

       239
       239
       -
         module Notification : sig

     

       240
       240
       -
           type t = {

     

       241
       241
       -
             uri: string; (** URI of the updated resource *)

     

       242
       242
       -
           }

     

       243
       243
       -
           include Json.Jsonable.S with type t := t

     

       244
       244
       -
         end

     

       245
       245
       -
         

     

       246
       246
       -
         (** Create a resources/updated notification *)

     

       247
       247
       -
         val create_notification : uri:string -> unit -> JSONRPCMessage.t

     

       248
       248
       -
       end

     

       249
       249
       -
       

     

       250
       250
       -
       (** Progress Notification *)

     

       251
       251
       -
       module Progress : sig

     

       252
       252
       -
         (** Notification parameters *)

     

       253
       253
       -
         module Notification : sig

     

       254
       254
       -
           type t = {

     

       255
       255
       -
             progress: float; (** Current progress value *)

     

       256
       256
       -
             total: float; (** Total progress value *)

     

       257
       257
       -
             progress_token: ProgressToken.t; (** Token identifying the operation *)

     

       258
       258
       -
           }

     

       259
       259
       -
           include Json.Jsonable.S with type t := t

     

       260
       260
       -
         end

     

       261
       261
       -
         

     

       262
       262
       -
         (** Create a progress notification *)

     

       263
       263
       -
         val create_notification : progress:float -> total:float -> progress_token:ProgressToken.t -> unit -> JSONRPCMessage.t

     

       264
       264
       -
       end

+109 -70

lib/mcp_sdk.ml

···

       29
       29
        
         type t = {

     

       30
       30
        
           request_id: RequestId.t option;

     

       31
       31
        
           lifespan_context: (string * Json.t) list;

     

       32
       32
       -
           progress_token: ProgressToken.t option;

     

       32
       32
       +
           mutable progress_token: ProgressToken.t option;

     

       33
       33
        
         }

     

       34
       34
        
       

     

       35
       35
       -
         let create ?request_id ?progress_token ?(lifespan_context=[]) () =

     

       36
       36
       -
           { request_id; lifespan_context; progress_token }

     

       35
       35
       +
         let create ?request_id ?(lifespan_context=[]) () =

     

       36
       36
       +
           { request_id; lifespan_context; progress_token = None }

     

       37
       37
        
       

     

       38
       38
        
         let get_context_value ctx key =

     

       39
       39
        
           List.assoc_opt key ctx.lifespan_context

     
···

       133
       133
        
         let create_argument ~name ?description ?(required=false) () =

     

       134
       134
        
           { name; description; required }

     

       135
       135
        
       

     

       136
       136
       +
         let yojson_of_message { role; content } =

     

       137
       137
       +
           `Assoc [

     

       138
       138
       +
             ("role", Role.yojson_of_t role);

     

       139
       139
       +
             ("content", yojson_of_content content);

     

       140
       140
       +
           ]

     

       141
       141
       +
       

     

       142
       142
       +
         (* This function must match the structure expected by the PromptMessage module in mcp.ml *)

     

       143
       143
       +
         let message_of_yojson json =

     

       144
       144
       +
           match json with

     

       145
       145
       +
           | `Assoc fields -> begin

     

       146
       146
       +
               let role = match List.assoc_opt "role" fields with

     

       147
       147
       +
                 | Some json -> begin

     

       148
       148
       +
                     Role.t_of_yojson json

     

       149
       149
       +
                   end

     

       150
       150
       +
                 | None -> begin

     

       151
       151
       +
                     raise (Json.Of_json ("Missing role field", `Assoc fields))

     

       152
       152
       +
                   end

     

       153
       153
       +
               in

     

       154
       154
       +
               let content = match List.assoc_opt "content" fields with

     

       155
       155
       +
                 | Some json -> begin

     

       156
       156
       +
                     content_of_yojson json

     

       157
       157
       +
                   end

     

       158
       158
       +
                 | None -> begin

     

       159
       159
       +
                     raise (Json.Of_json ("Missing content field", `Assoc fields))

     

       160
       160
       +
                   end

     

       161
       161
       +
               in

     

       162
       162
       +
               { role; content }

     

       163
       163
       +
             end

     

       164
       164
       +
           | j -> begin

     

       165
       165
       +
               raise (Json.Of_json ("Expected object for PromptMessage", j))

     

       166
       166
       +
             end

     

       167
       167
       +
       

     

       136
       168
        
         let to_json prompt =

     

       137
       169
        
           let assoc = [

     

       138
       170
        
             ("name", `String prompt.name);

     
···

       165
       197
        
           `Assoc assoc

     

       166
       198
        
       end

     

       167
       199
        
       

     

       168
       168
       -
       (* Content type constructors have been moved to the Mcp module *)

     

       200
       200
       +
       (* Helper functions for creating common objects *)

     

       201
       201
       +
       let make_text_content text =

     

       202
       202
       +
         Text (TextContent.{ text; annotations = None })

     

       169
       203
        
       

     

       170
       170
       -
       (* Tool result handling using Mcp_message.ToolsCall.ToolContent *)

     

       204
       204
       +
       let make_text_content_with_annotations text annotations =

     

       205
       205
       +
         Text (TextContent.{ text; annotations = Some annotations })

     

       171
       206
        
       

     

       172
       172
       -
       let create_tool_result contents ~is_error =

     

       173
       173
       -
         (* Use the original Mcp.content values as is *)

     

       174
       174
       -
         let content = List.map (fun content ->

     

       175
       175
       -
           match content with

     

       176
       176
       -
           | Text text_content -> 

     

       177
       177
       -
               Mcp_message.ToolsCall.ToolContent.Text text_content

     

       178
       178
       -
           | Image image_content -> 

     

       179
       179
       -
               Mcp_message.ToolsCall.ToolContent.Image image_content

     

       180
       180
       -
           | Audio audio_content -> 

     

       181
       181
       -
               Mcp_message.ToolsCall.ToolContent.Audio audio_content

     

       182
       182
       -
           | Resource resource_content ->

     

       183
       183
       -
               Mcp_message.ToolsCall.ToolContent.Resource resource_content

     

       184
       184
       -
         ) contents in

     

       185
       185
       -
         

     

       186
       186
       -
         (* Use the ToolsCall.Response module's JSON conversion *)

     

       187
       187
       -
         Mcp_message.ToolsCall.Response.yojson_of_t { content; is_error }

     

       207
       207
       +
       let make_image_content data mime_type =

     

       208
       208
       +
         Image (ImageContent.{ data; mime_type; annotations = None })

     

       209
       209
       +
       

     

       210
       210
       +
       let make_image_content_with_annotations data mime_type annotations =

     

       211
       211
       +
         Image (ImageContent.{ data; mime_type; annotations = Some annotations })

     

       212
       212
       +
       

     

       213
       213
       +
       let make_audio_content data mime_type =

     

       214
       214
       +
         Audio (AudioContent.{ data; mime_type; annotations = None })

     

       215
       215
       +
       

     

       216
       216
       +
       let make_audio_content_with_annotations data mime_type annotations =

     

       217
       217
       +
         Audio (AudioContent.{ data; mime_type; annotations = Some annotations })

     

       218
       218
       +
       

     

       219
       219
       +
       let make_text_resource_content uri text ?mime_type () =

     

       220
       220
       +
         Resource (EmbeddedResource.{

     

       221
       221
       +
           resource = `Text TextResourceContents.{ uri; text; mime_type };

     

       222
       222
       +
           annotations = None

     

       223
       223
       +
         })

     

       188
       224
        
       

     

       189
       189
       -
       (* Using error codes from Mcp.ErrorCode module *)

     

       225
       225
       +
       let make_blob_resource_content uri blob ?mime_type () =

     

       226
       226
       +
         Resource (EmbeddedResource.{

     

       227
       227
       +
           resource = `Blob BlobResourceContents.{ uri; blob; mime_type };

     

       228
       228
       +
           annotations = None

     

       229
       229
       +
         })

     

       190
       230
        
       

     

       191
       231
        
       let make_tool_schema properties required =

     

       192
       232
        
         let props = List.map (fun (name, schema_type, description) ->

     
···

       207
       247
        
         name: string;

     

       208
       248
        
         version: string;

     

       209
       249
        
         protocol_version: string;

     

       210
       210
       -
         lifespan_context: (string * Json.t) list;

     

       211
       250
        
         mutable capabilities: Json.t;

     

       212
       251
        
         mutable tools: Tool.t list;

     

       213
       252
        
         mutable resources: Resource.t list;

     

       214
       253
        
         mutable prompts: Prompt.t list;

     

       215
       215
       -
       } 

     

       216
       216
       -
       

     

       217
       217
       -
       let name { name; _ } = name

     

       218
       218
       -
       let version { version; _ } = version

     

       219
       219
       -
       let capabilities { capabilities; _ } = capabilities

     

       220
       220
       -
       let lifespan_context { lifespan_context; _ } = lifespan_context

     

       221
       221
       -
       let protocol_version { protocol_version; _ } = protocol_version

     

       222
       222
       -
       let tools { tools; _ } = tools

     

       223
       223
       -
       let resources { resources; _ } = resources

     

       224
       224
       -
       let prompts { prompts; _ } = prompts

     

       254
       254
       +
         mutable lifespan_context: (string * Json.t) list;

     

       255
       255
       +
         mutable startup_hook: (unit -> unit) option;

     

       256
       256
       +
         mutable shutdown_hook: (unit -> unit) option;

     

       257
       257
       +
       }

     

       225
       258
        
       

     

       226
       259
        
       (* Create a new server *)

     

       227
       260
        
       let create_server ~name ?(version="0.1.0") ?(protocol_version="2024-11-05") () =

     
···

       234
       267
        
           resources = [];

     

       235
       268
        
           prompts = [];

     

       236
       269
        
           lifespan_context = [];

     

       270
       270
       +
           startup_hook = None;

     

       271
       271
       +
           shutdown_hook = None;

     

       237
       272
        
         }

     

       238
       273
        
       

     

       239
       274
        
       (* Default capabilities for the server *)

     
···

       280
       315
        
         server.tools <- tool :: server.tools;

     

       281
       316
        
         tool

     

       282
       317
        
       

     

       283
       283
       -
       (* Create a rich tool result with multiple content types *)

     

       284
       284
       -
       let create_rich_tool_result ?(text=None) ?(image=None) ?(audio=None) ?(resource=None) ~is_error () =

     

       285
       285
       -
         let contents = [] in

     

       286
       286
       -
         

     

       287
       287
       -
         (* Add text content if provided *)

     

       288
       288
       -
         let contents = match text with

     

       289
       289
       -
           | Some text -> (Mcp.make_text_content text) :: contents

     

       290
       290
       -
           | None -> contents

     

       291
       291
       -
         in

     

       292
       292
       -
         

     

       293
       293
       -
         (* Add image content if provided *)

     

       294
       294
       -
         let contents = match image with

     

       295
       295
       -
           | Some (data, mime_type) -> (Mcp.make_image_content data mime_type) :: contents

     

       296
       296
       -
           | None -> contents

     

       297
       297
       -
         in

     

       298
       298
       -
         

     

       299
       299
       -
         (* Add audio content if provided *)

     

       300
       300
       -
         let contents = match audio with

     

       301
       301
       -
           | Some (data, mime_type) -> (Mcp.make_audio_content data mime_type) :: contents

     

       302
       302
       -
           | None -> contents

     

       303
       303
       -
         in

     

       304
       304
       -
         

     

       305
       305
       -
         (* Add resource content if provided *)

     

       306
       306
       -
         let contents = match resource with

     

       307
       307
       -
           | Some (uri, data, is_blob, mime_type) -> 

     

       308
       308
       -
               (if is_blob then 

     

       309
       309
       -
                  Mcp.make_resource_blob_content uri data mime_type

     

       310
       310
       -
                else 

     

       311
       311
       -
                  Mcp.make_resource_text_content uri data mime_type) :: contents

     

       312
       312
       -
           | None -> contents

     

       313
       313
       -
         in

     

       314
       314
       -
         

     

       315
       315
       -
         (* Create the final tool result *)

     

       316
       316
       -
         create_tool_result (List.rev contents) ~is_error

     

       317
       317
       -
       

     

       318
       318
        
       (* Create and register a tool in one step *)

     

       319
       319
        
       let add_tool server ~name ?description ?(schema_properties=[]) ?(schema_required=[]) handler =

     

       320
       320
        
         let input_schema = make_tool_schema schema_properties schema_required in

     
···

       402
       402
        
         set_capabilities server capabilities;

     

       403
       403
        
         server

     

       404
       404
        
       

     

       405
       405
       -
       (* The MCP message helpers have been moved to Mcp_message module. 

     

       406
       406
       -
          This module now reexports them through open statements. *)

     

       405
       405
       +
       (* Set startup and shutdown hooks *)

     

       406
       406
       +
       let set_startup_hook server hook =

     

       407
       407
       +
         server.startup_hook <- Some hook

     

       408
       408
       +
       

     

       409
       409
       +
       let set_shutdown_hook server hook =

     

       410
       410
       +
         server.shutdown_hook <- Some hook

     

       411
       411
       +
       

     

       412
       412
       +
       (* Transport type for server *)

     

       413
       413
       +
       type transport_type = 

     

       414
       414
       +
         | Stdio  (* Read/write to stdin/stdout *)

     

       415
       415
       +
         | Http   (* HTTP server - to be implemented *)

     

       416
       416
       +
       

     

       417
       417
       +
       (* Run server with stdio transport *)

     

       418
       418
       +
       let run_server server =

     

       419
       419
       +
         (* Setup *)

     

       420
       420
       +
         Printexc.record_backtrace true;

     

       421
       421
       +
         

     

       422
       422
       +
         Log.info (Printf.sprintf "%s server starting" server.name);

     

       423
       423
       +
         Log.debug (Printf.sprintf "Protocol version: %s" server.protocol_version);

     

       424
       424
       +
         Log.debug (Printf.sprintf "Server info: %s v%s" server.name server.version);

     

       425
       425
       +
         

     

       426
       426
       +
         (* Initialize capabilities if not already set *)

     

       427
       427
       +
         if server.capabilities = `Assoc [] then

     

       428
       428
       +
           ignore (configure_server server ());

     

       429
       429
       +
         

     

       430
       430
       +
         (* Run startup hook if provided *)

     

       431
       431
       +
         (match server.startup_hook with

     

       432
       432
       +
          | Some hook -> hook ()

     

       433
       433
       +
          | None -> ());

     

       434
       434
       +
         

     

       435
       435
       +
         (* This function will be replaced by a full implementation in the mcp_server module *)

     

       436
       436
       +
         Log.info "Server initialized and ready."

     

       437
       437
       +
       

     

       438
       438
       +
       (* Placeholder for running server with different transports *)

     

       439
       439
       +
       let run_server_with_transport server transport =

     

       440
       440
       +
         match transport with

     

       441
       441
       +
         | Http ->

     

       442
       442
       +
             Log.info "HTTP server not implemented in this version, using stdio instead";

     

       443
       443
       +
             run_server server

     

       444
       444
       +
         | Stdio ->

     

       445
       445
       +
             run_server server

+57 -21

lib/mcp_sdk.mli

···

       21
       21
        
       

     

       22
       22
        
       (** Context for tools and resources *)

     

       23
       23
        
       module Context : sig

     

       24
       24
       -
         type t

     

       24
       24
       +
         type t = {

     

       25
       25
       +
           request_id: RequestId.t option;

     

       26
       26
       +
           lifespan_context: (string * Json.t) list;

     

       27
       27
       +
           mutable progress_token: ProgressToken.t option;

     

       28
       28
       +
         }

     

       25
       29
        
       

     

       26
       26
       -
         val create : ?request_id:RequestId.t -> ?progress_token:ProgressToken.t -> ?lifespan_context:(string * Json.t) list -> unit -> t

     

       30
       30
       +
         val create : ?request_id:RequestId.t -> ?lifespan_context:(string * Json.t) list -> unit -> t

     

       27
       31
        
         val get_context_value : t -> string -> Json.t option

     

       28
       32
        
         val report_progress : t -> float -> float -> JSONRPCMessage.t option

     

       29
       33
        
       end

     
···

       82
       86
        
       

     

       83
       87
        
         val create : name:string -> ?description:string -> ?arguments:argument list -> handler:handler -> unit -> t

     

       84
       88
        
         val create_argument : name:string -> ?description:string -> ?required:bool -> unit -> argument

     

       89
       89
       +
         val yojson_of_message : message -> Json.t

     

       90
       90
       +
         val message_of_yojson : Json.t -> message

     

       85
       91
        
         val to_json : t -> Json.t

     

       86
       92
        
       end

     

       87
       93
        
       

     

       88
       94
        
       (** Main server type *)

     

       89
       89
       -
       type server

     

       90
       90
       -
       

     

       91
       91
       -
       val name : server -> string

     

       92
       92
       -
       val version : server -> string

     

       93
       93
       -
       val protocol_version : server -> string

     

       94
       94
       -
       val capabilities : server -> Json.t

     

       95
       95
       -
       val tools : server -> Tool.t list

     

       96
       96
       -
       val resources : server -> Resource.t list

     

       97
       97
       -
       val prompts : server -> Prompt.t list

     

       95
       95
       +
       type server = {

     

       96
       96
       +
         name: string;

     

       97
       97
       +
         version: string;

     

       98
       98
       +
         protocol_version: string;

     

       99
       99
       +
         mutable capabilities: Json.t;

     

       100
       100
       +
         mutable tools: Tool.t list;

     

       101
       101
       +
         mutable resources: Resource.t list;

     

       102
       102
       +
         mutable prompts: Prompt.t list;

     

       103
       103
       +
         mutable lifespan_context: (string * Json.t) list;

     

       104
       104
       +
         mutable startup_hook: (unit -> unit) option;

     

       105
       105
       +
         mutable shutdown_hook: (unit -> unit) option;

     

       106
       106
       +
       }

     

       98
       107
        
       

     

       99
       108
        
       (** Create a new server *)

     

       100
       109
        
       val create_server : name:string -> ?version:string -> ?protocol_version:string -> unit -> server

     
···

       102
       111
        
       (** Default capabilities for the server *)

     

       103
       112
        
       val default_capabilities : ?with_tools:bool -> ?with_resources:bool -> ?with_prompts:bool -> unit -> Json.t

     

       104
       113
        
       

     

       114
       114
       +
       (** Register a tool with the server *)

     

       115
       115
       +
       val register_tool : server -> Tool.t -> Tool.t

     

       116
       116
       +
       

     

       105
       117
        
       (** Create and register a tool in one step *)

     

       106
       118
        
       val add_tool : server -> name:string -> ?description:string -> ?schema_properties:(string * string * string) list -> ?schema_required:string list -> (Json.t -> Json.t) -> Tool.t

     

       107
       119
        
       

     

       120
       120
       +
       (** Register a resource with the server *)

     

       121
       121
       +
       val register_resource : server -> Resource.t -> Resource.t

     

       122
       122
       +
       

     

       108
       123
        
       (** Create and register a resource in one step *)

     

       109
       124
        
       val add_resource : server -> uri_template:string -> ?description:string -> ?mime_type:string -> (string list -> string) -> Resource.t

     

       110
       125
        
       

     

       126
       126
       +
       (** Register a prompt with the server *)

     

       127
       127
       +
       val register_prompt : server -> Prompt.t -> Prompt.t

     

       128
       128
       +
       

     

       111
       129
        
       (** Create and register a prompt in one step *)

     

       112
       130
        
       val add_prompt : server -> name:string -> ?description:string -> ?arguments:(string * string option * bool) list -> ((string * string) list -> Prompt.message list) -> Prompt.t

     

       113
       131
        
       

     

       132
       132
       +
       (** Set server capabilities *)

     

       133
       133
       +
       val set_capabilities : server -> Json.t -> unit

     

       134
       134
       +
       

     

       114
       135
        
       (** Configure server with default capabilities based on registered components *)

     

       115
       136
        
       val configure_server : server -> ?with_tools:bool -> ?with_resources:bool -> ?with_prompts:bool -> unit -> server

     

       116
       137
        
       

     

       117
       117
       -
       val create_tool_result : content list -> is_error:bool -> Json.t

     

       138
       138
       +
       (** Set startup hook *)

     

       139
       139
       +
       val set_startup_hook : server -> (unit -> unit) -> unit

     

       140
       140
       +
       

     

       141
       141
       +
       (** Set shutdown hook *)

     

       142
       142
       +
       val set_shutdown_hook : server -> (unit -> unit) -> unit

     

       118
       143
        
       

     

       119
       119
       -
       (** Create a rich tool result with multiple content types *)

     

       120
       120
       -
       val create_rich_tool_result : 

     

       121
       121
       -
         ?text:string option -> 

     

       122
       122
       -
         ?image:(string * string) option -> 

     

       123
       123
       -
         ?audio:(string * string) option ->

     

       124
       124
       -
         ?resource:(string * string * bool * string option) option -> 

     

       125
       125
       -
         is_error:bool -> 

     

       126
       126
       -
         unit -> Json.t

     

       144
       144
       +
       (** Run the server using stdio transport (legacy method) *)

     

       145
       145
       +
       val run_server : server -> unit

     

       146
       146
       +
       

     

       147
       147
       +
       (** Transport type for the server *)

     

       148
       148
       +
       type transport_type = 

     

       149
       149
       +
         | Stdio  (** Read/write to stdin/stdout *)

     

       150
       150
       +
         | Http   (** HTTP server - to be implemented *)

     

       151
       151
       +
       

     

       152
       152
       +
       (** Create and start a server with the specified transport *)

     

       153
       153
       +
       val run_server_with_transport : server -> transport_type -> unit

     

       127
       154
        
       

     

       128
       128
       -
       val make_tool_schema : (string * string * string) list -> string list -> Json.t

     

       155
       155
       +
       (** Helper functions for creating common objects *)

     

       156
       156
       +
       val make_text_content : string -> content

     

       157
       157
       +
       val make_text_content_with_annotations : string -> Annotated.annotation -> content

     

       158
       158
       +
       val make_image_content : string -> string -> content

     

       159
       159
       +
       val make_image_content_with_annotations : string -> string -> Annotated.annotation -> content

     

       160
       160
       +
       val make_audio_content : string -> string -> content

     

       161
       161
       +
       val make_audio_content_with_annotations : string -> string -> Annotated.annotation -> content

     

       162
       162
       +
       val make_text_resource_content : string -> string -> ?mime_type:string -> unit -> content

     

       163
       163
       +
       val make_blob_resource_content : string -> string -> ?mime_type:string -> unit -> content

     

       164
       164
       +
       val make_tool_schema : (string * string * string) list -> string list -> Json.t

+512 -259

lib/mcp_server.ml

···

       1
       1
        
       open Mcp

     

       2
       2
       -
       open Jsonrpc

     

       3
       2
        
       open Mcp_sdk

     

       4
       3
        
       

     

       5
       5
       -
       (* Process initialize request *)

     

       6
       6
       -
       let handle_initialize server req =

     

       7
       7
       -
         Log.debug "Processing initialize request";

     

       8
       8
       -
         let result = match req.JSONRPCMessage.params with

     

       9
       9
       -
           | Some params -> 

     

       10
       10
       -
               let req_data = Initialize.Request.t_of_yojson params in

     

       11
       11
       -
               Log.debug (Printf.sprintf "Client info: %s v%s" 

     

       12
       12
       -
                 req_data.client_info.name req_data.client_info.version);

     

       13
       13
       -
               Log.debug (Printf.sprintf "Client protocol version: %s" req_data.protocol_version);

     

       14
       14
       -
               

     

       15
       15
       -
               (* Create initialize response *)

     

       16
       16
       -
               let result = Initialize.Result.create

     

       17
       17
       -
                 ~capabilities:(capabilities server)

     

       18
       18
       -
                 ~server_info:Implementation.{ 

     

       19
       19
       -
                   name = name server; 

     

       20
       20
       -
                   version = version server 

     

       21
       21
       -
                 }

     

       22
       22
       -
                 ~protocol_version:(protocol_version server)

     

       23
       23
       -
                 ~instructions:(Printf.sprintf "This server provides tools for %s." (name server))

     

       24
       24
       -
                 ()

     

       25
       25
       -
               in

     

       26
       26
       -
               Initialize.Result.yojson_of_t result

     

       27
       27
       -
           | None -> 

     

       28
       28
       -
               Log.error "Missing params for initialize request";

     

       29
       29
       -
               `Assoc [("error", `String "Missing params for initialize request")]

     

       30
       30
       -
         in

     

       31
       31
       -
         Some (create_response ~id:req.id ~result)

     

       4
       4
       +
       (* MCP Server module for handling JSON-RPC communication *)

     

       32
       5
        
       

     

       33
       33
       -
       (* Process tools/list request *)

     

       34
       34
       -
       let handle_tools_list server (req:JSONRPCMessage.request) =

     

       35
       35
       -
         Log.debug "Processing tools/list request";

     

       36
       36
       -
         let tool_list = List.map Tool.to_json (tools server) in

     

       37
       37
       -
         let result = `Assoc [("tools", `List tool_list)] in

     

       38
       38
       -
         Some (create_response ~id:req.id ~result)

     

       6
       6
       +
       (** Server types *)

     

       7
       7
       +
       type transport_type = 

     

       8
       8
       +
         | Stdio  (* Read/write to stdin/stdout *)

     

       9
       9
       +
         | Http   (* HTTP server - to be implemented *)

     

       39
       10
        
       

     

       40
       40
       -
       (* Process prompts/list request *)

     

       41
       41
       -
       let handle_prompts_list server (req:JSONRPCMessage.request) =

     

       42
       42
       -
         Log.debug "Processing prompts/list request";

     

       43
       43
       -
         let prompt_list = List.map Prompt.to_json (prompts server) in

     

       44
       44
       -
         let result = `Assoc [("prompts", `List prompt_list)] in

     

       45
       45
       -
         Some (create_response ~id:req.id ~result)

     

       11
       11
       +
       type t = {

     

       12
       12
       +
         server: Mcp_sdk.server;

     

       13
       13
       +
         transport: transport_type;

     

       14
       14
       +
         mutable running: bool;

     

       15
       15
       +
       }

     

       46
       16
        
       

     

       47
       47
       -
       (* Process resources/list request *)

     

       48
       48
       -
       let handle_resources_list server (req:JSONRPCMessage.request) =

     

       49
       49
       -
         Log.debug "Processing resources/list request";

     

       50
       50
       -
         let resource_list = List.map Resource.to_json (resources server) in

     

       51
       51
       -
         let result = `Assoc [("resources", `List resource_list)] in

     

       52
       52
       -
         Some (create_response ~id:req.id ~result)

     

       53
       53
       -
       

     

       54
       54
       -
       (* Extract the tool name from params *)

     

       55
       55
       -
       let extract_tool_name params =

     

       56
       56
       -
         match List.assoc_opt "name" params with

     

       57
       57
       -
           | Some (`String name) -> 

     

       58
       58
       -
               Log.debug (Printf.sprintf "Tool name: %s" name);

     

       59
       59
       -
               Some name

     

       60
       60
       -
           | _ -> 

     

       61
       61
       -
               Log.error "Missing or invalid 'name' parameter in tool call";

     

       62
       62
       -
               None

     

       63
       63
       -
       

     

       64
       64
       -
       (* Extract the tool arguments from params *)

     

       65
       65
       -
       let extract_tool_arguments params =

     

       66
       66
       -
         match List.assoc_opt "arguments" params with

     

       67
       67
       -
           | Some (args) -> 

     

       68
       68
       -
               Log.debug (Printf.sprintf "Tool arguments: %s" (Yojson.Safe.to_string args));

     

       69
       69
       -
               args

     

       70
       70
       -
           | _ -> 

     

       71
       71
       -
               Log.debug "No arguments provided for tool call, using empty object";

     

       72
       72
       -
               `Assoc [] (* Empty arguments is valid *)

     

       73
       73
       -
       

     

       74
       74
       -
       (* Create a proper JSONRPC error with code and data *)

     

       75
       75
       -
       let create_jsonrpc_error id code message ?data () =

     

       76
       76
       -
         let error_code = ErrorCode.to_int code in

     

       77
       77
       -
         let error_data = match data with

     

       78
       78
       -
           | Some d -> d

     

       79
       79
       -
           | None -> `Null

     

       80
       80
       -
         in

     

       81
       81
       -
         create_error ~id ~code:error_code ~message ~data:(Some error_data) ()

     

       82
       82
       -
       

     

       83
       83
       -
       (* Create a tool error result with structured content *)

     

       84
       84
       -
       let create_tool_error_result error =

     

       85
       85
       -
         create_tool_result [make_text_content error] ~is_error:true

     

       86
       86
       -
       

     

       87
       87
       -
       (* Handle tool execution errors *)

     

       88
       88
       -
       let handle_tool_execution_error err =

     

       89
       89
       -
         Log.error (Printf.sprintf "Tool execution failed: %s" err);

     

       90
       90
       -
         create_tool_error_result (Printf.sprintf "Error executing tool: %s" err)

     

       91
       91
       -
       

     

       92
       92
       -
       (* Handle unknown tool error *)

     

       93
       93
       -
       let handle_unknown_tool_error name =

     

       94
       94
       -
         Log.error (Printf.sprintf "Unknown tool: %s" name);

     

       95
       95
       -
         create_tool_error_result (Printf.sprintf "Unknown tool: %s" name)

     

       96
       96
       -
       

     

       97
       97
       -
       (* Handle general tool execution exception *)

     

       98
       98
       -
       let handle_tool_execution_exception exn =

     

       99
       99
       -
         Log.error (Printf.sprintf "Exception executing tool: %s" (Printexc.to_string exn));

     

       100
       100
       -
         create_tool_error_result (Printf.sprintf "Internal error: %s" (Printexc.to_string exn))

     

       101
       101
       -
       

     

       102
       102
       -
       (* Execute a tool *)

     

       103
       103
       -
       let execute_tool server ctx name args =

     

       104
       104
       -
         try

     

       105
       105
       -
           let tool = List.find (fun t -> t.Tool.name = name) (tools server) in

     

       106
       106
       -
           Log.debug (Printf.sprintf "Found tool: %s" name);

     

       107
       107
       -
           

     

       108
       108
       -
           (* Call the tool handler *)

     

       109
       109
       -
           match tool.handler ctx args with

     

       110
       110
       -
           | Ok result -> 

     

       111
       111
       -
               Log.debug "Tool execution succeeded";

     

       112
       112
       -
               result

     

       113
       113
       -
           | Error err -> handle_tool_execution_error err

     

       114
       114
       -
         with

     

       115
       115
       -
         | Not_found -> handle_unknown_tool_error name

     

       116
       116
       -
         | exn -> handle_tool_execution_exception exn

     

       117
       117
       -
       

     

       118
       118
       -
       (* Process tools/call request *)

     

       119
       119
       -
       let handle_tools_call server req =

     

       120
       120
       -
         Log.debug "Processing tools/call request";

     

       121
       121
       -
         match req.JSONRPCMessage.params with

     

       122
       122
       -
         | Some (`Assoc params) ->

     

       123
       123
       -
           (match extract_tool_name params with

     

       124
       124
       -
           | Some name ->

     

       125
       125
       -
               let args = extract_tool_arguments params in

     

       126
       126
       -
               

     

       127
       127
       -
               (* Create context for this request *)

     

       128
       128
       -
               let ctx = Context.create 

     

       129
       129
       -
                 ?request_id:(Some req.id)

     

       130
       130
       -
                 ?progress_token:req.progress_token

     

       131
       131
       -
                 ~lifespan_context:[("tools/call", `Assoc params)] 

     

       132
       132
       -
                 () 

     

       133
       133
       -
               in

     

       134
       134
       -
                       

     

       135
       135
       -
               (* Execute the tool *)

     

       136
       136
       -
               let result = execute_tool server ctx name args in

     

       137
       137
       -
               

     

       138
       138
       -
               Some (create_response ~id:req.id ~result)

     

       139
       139
       -
           | None ->

     

       140
       140
       -
               Some (create_jsonrpc_error req.id InvalidParams "Missing tool name parameter" ()))

     

       141
       141
       -
         | _ ->

     

       142
       142
       -
           Log.error "Invalid params format for tools/call";

     

       143
       143
       -
           Some (create_jsonrpc_error req.id InvalidParams "Invalid params format for tools/call" ())

     

       144
       144
       -
       

     

       145
       145
       -
       (* Process ping request *)

     

       146
       146
       -
       let handle_ping (req:JSONRPCMessage.request) =

     

       147
       147
       -
         Log.debug "Processing ping request";

     

       148
       148
       -
         Some (create_response ~id:req.JSONRPCMessage.id ~result:(`Assoc []))

     

       149
       149
       -
       

     

       150
       150
       -
       (* Handle notifications/initialized *)

     

       151
       151
       -
       let handle_initialized (notif:JSONRPCMessage.notification) =

     

       152
       152
       -
         Log.debug "Client initialization complete - Server is now ready to receive requests";

     

       153
       153
       -
         Log.debug (Printf.sprintf "Notification params: %s" 

     

       154
       154
       -
           (match notif.JSONRPCMessage.params with

     

       155
       155
       -
             | Some p -> Yojson.Safe.to_string p

     

       156
       156
       -
             | None -> "null"));

     

       157
       157
       -
         None

     

       158
       158
       -
       

     

       159
       159
       -
       (* Process a single message using the MCP SDK *)

     

       17
       17
       +
       (** Process a single message *)

     

       160
       18
        
       let process_message server message =

     

       161
       19
        
         try

     

       162
       162
       -
           Log.debug (Printf.sprintf "Processing message: %s" (Yojson.Safe.to_string message));

     

       20
       20
       +
           Log.debug "Parsing message as JSONRPC message...";

     

       163
       21
        
           match JSONRPCMessage.t_of_yojson message with

     

       164
       164
       -
           | JSONRPCMessage.Request req ->

     

       165
       165
       -
             Log.debug (Printf.sprintf "Received request with method: %s" req.method_);

     

       166
       166
       -
             (match req.method_ with

     

       167
       167
       -
              | "initialize" -> handle_initialize server req

     

       168
       168
       -
              | "tools/list" -> handle_tools_list server req

     

       169
       169
       -
              | "tools/call" -> handle_tools_call server req

     

       170
       170
       -
              | "prompts/list" -> handle_prompts_list server req

     

       171
       171
       -
              | "resources/list" -> handle_resources_list server req

     

       172
       172
       -
              | "ping" -> handle_ping req

     

       173
       173
       -
              | _ -> 

     

       174
       174
       -
                 Log.error (Printf.sprintf "Unknown method received: %s" req.method_);

     

       175
       175
       -
                 Some (create_jsonrpc_error req.id MethodNotFound ("Method not found: " ^ req.method_) ()))

     

       176
       176
       -
           | JSONRPCMessage.Notification notif ->

     

       177
       177
       -
             Log.debug (Printf.sprintf "Received notification with method: %s" notif.method_);

     

       178
       178
       -
             (match notif.method_ with

     

       179
       179
       -
              | "notifications/initialized" -> handle_initialized notif

     

       180
       180
       -
              | _ ->

     

       181
       181
       -
                 Log.debug (Printf.sprintf "Ignoring notification: %s" notif.method_);

     

       182
       182
       -
                 None)

     

       183
       183
       -
           | JSONRPCMessage.Response _ ->

     

       184
       184
       -
             Log.error "Unexpected response message received";

     

       22
       22
       +
           | JSONRPCMessage.Request req -> begin

     

       23
       23
       +
               Log.debug (Printf.sprintf "Received request with method: %s" req.method_);

     

       24
       24
       +
               match req.method_ with

     

       25
       25
       +
               | "initialize" -> begin

     

       26
       26
       +
                   Log.debug "Processing initialize request";

     

       27
       27
       +
                   let result = match req.params with

     

       28
       28
       +
                   | Some params -> begin

     

       29
       29
       +
                       Log.debug "Parsing initialize request params...";

     

       30
       30
       +
                       let req_params = Initialize.Request.t_of_yojson params in

     

       31
       31
       +
                       Log.debug (Printf.sprintf "Client info: %s v%s" 

     

       32
       32
       +
                                    req_params.client_info.name 

     

       33
       33
       +
                                    req_params.client_info.version);

     

       34
       34
       +
                       Log.debug (Printf.sprintf "Client protocol version: %s" req_params.protocol_version);

     

       35
       35
       +
                       

     

       36
       36
       +
                       (* Check protocol version compatibility *)

     

       37
       37
       +
                       if req_params.protocol_version <> server.protocol_version then begin

     

       38
       38
       +
                         Log.debug (Printf.sprintf "Protocol version mismatch: client=%s server=%s" 

     

       39
       39
       +
                                     req_params.protocol_version server.protocol_version);

     

       40
       40
       +
                       end;

     

       41
       41
       +
                       

     

       42
       42
       +
                       Initialize.Result.create

     

       43
       43
       +
                         ~capabilities:server.capabilities

     

       44
       44
       +
                         ~server_info:Implementation.{ name = server.name; version = server.version }

     

       45
       45
       +
                         ~protocol_version:server.protocol_version

     

       46
       46
       +
                         ?instructions:(Some "MCP Server") (* TODO: Allow customization *)

     

       47
       47
       +
                         ()

     

       48
       48
       +
                     end

     

       49
       49
       +
                   | None -> begin

     

       50
       50
       +
                       Log.error "Missing params for initialize request";

     

       51
       51
       +
                       Initialize.Result.create

     

       52
       52
       +
                         ~capabilities:server.capabilities

     

       53
       53
       +
                         ~server_info:Implementation.{ name = server.name; version = server.version }

     

       54
       54
       +
                         ~protocol_version:server.protocol_version

     

       55
       55
       +
                         ()

     

       56
       56
       +
                     end

     

       57
       57
       +
                   in

     

       58
       58
       +
                   Some (create_response ~id:req.id ~result:(Initialize.Result.yojson_of_t result))

     

       59
       59
       +
                 end

     

       60
       60
       +
                

     

       61
       61
       +
               | "tools/list" -> begin

     

       62
       62
       +
                   Log.debug "Processing tools/list request";

     

       63
       63
       +
                   let tools_json = List.map Mcp_sdk.Tool.to_json server.tools in

     

       64
       64
       +
                   let result = `Assoc [("tools", `List tools_json)] in

     

       65
       65
       +
                   Some (create_response ~id:req.id ~result)

     

       66
       66
       +
                 end

     

       67
       67
       +
                

     

       68
       68
       +
               | "tools/call" -> begin

     

       69
       69
       +
                   Log.debug "Processing tools/call request";

     

       70
       70
       +
                   match req.params with

     

       71
       71
       +
                   | Some (`Assoc params) -> begin

     

       72
       72
       +
                       let name = match List.assoc_opt "name" params with

     

       73
       73
       +
                       | Some (`String name) -> begin

     

       74
       74
       +
                           Log.debug (Printf.sprintf "Tool name: %s" name);

     

       75
       75
       +
                           name

     

       76
       76
       +
                         end

     

       77
       77
       +
                       | _ -> begin

     

       78
       78
       +
                           Log.error "Missing or invalid 'name' parameter in tool call";

     

       79
       79
       +
                           failwith "Missing or invalid 'name' parameter"

     

       80
       80
       +
                         end

     

       81
       81
       +
                       in

     

       82
       82
       +
                       let args = match List.assoc_opt "arguments" params with

     

       83
       83
       +
                       | Some args -> begin

     

       84
       84
       +
                           Log.debug (Printf.sprintf "Tool arguments: %s" (Yojson.Safe.to_string args));

     

       85
       85
       +
                           args

     

       86
       86
       +
                         end

     

       87
       87
       +
                       | _ -> begin

     

       88
       88
       +
                           Log.debug "No arguments provided for tool call, using empty object";

     

       89
       89
       +
                           `Assoc [] (* Empty arguments is valid *)

     

       90
       90
       +
                         end

     

       91
       91
       +
                       in

     

       92
       92
       +
                       let progress_token = req.progress_token in

     

       93
       93
       +
                       

     

       94
       94
       +
                       (* Find the tool *)

     

       95
       95
       +
                       let tool_opt = List.find_opt (fun t -> t.Mcp_sdk.Tool.name = name) server.tools in

     

       96
       96
       +
                       match tool_opt with

     

       97
       97
       +
                       | Some tool -> begin

     

       98
       98
       +
                           Log.debug (Printf.sprintf "Found tool: %s" name);

     

       99
       99
       +
                           let ctx = Mcp_sdk.Context.create 

     

       100
       100
       +
                               ?request_id:(Some req.id) 

     

       101
       101
       +
                               ~lifespan_context:server.lifespan_context 

     

       102
       102
       +
                               () 

     

       103
       103
       +
                           in

     

       104
       104
       +
                           ctx.progress_token <- progress_token;

     

       105
       105
       +
                           

     

       106
       106
       +
                           (* Call the handler *)

     

       107
       107
       +
                           let result = match tool.handler ctx args with

     

       108
       108
       +
                           | Ok json -> begin

     

       109
       109
       +
                               `Assoc [

     

       110
       110
       +
                                 ("content", `List [Mcp.yojson_of_content (Text (TextContent.{ 

     

       111
       111
       +
                                   text = Yojson.Safe.to_string json;

     

       112
       112
       +
                                   annotations = None 

     

       113
       113
       +
                                 }))]);

     

       114
       114
       +
                                 ("isError", `Bool false)

     

       115
       115
       +
                               ]

     

       116
       116
       +
                             end

     

       117
       117
       +
                           | Error err -> begin

     

       118
       118
       +
                               `Assoc [

     

       119
       119
       +
                                 ("content", `List [Mcp.yojson_of_content (Text (TextContent.{ 

     

       120
       120
       +
                                   text = err;

     

       121
       121
       +
                                   annotations = None 

     

       122
       122
       +
                                 }))]);

     

       123
       123
       +
                                 ("isError", `Bool true)

     

       124
       124
       +
                               ]

     

       125
       125
       +
                             end

     

       126
       126
       +
                           in

     

       127
       127
       +
                           Some (create_response ~id:req.id ~result)

     

       128
       128
       +
                         end

     

       129
       129
       +
                       | None -> begin

     

       130
       130
       +
                           Log.error (Printf.sprintf "Tool not found: %s" name);

     

       131
       131
       +
                           let error_content = TextContent.{

     

       132
       132
       +
                             text = Printf.sprintf "Unknown tool: %s" name;

     

       133
       133
       +
                             annotations = None

     

       134
       134
       +
                           } in

     

       135
       135
       +
                           let result = `Assoc [

     

       136
       136
       +
                             ("content", `List [Mcp.yojson_of_content (Text error_content)]);

     

       137
       137
       +
                             ("isError", `Bool true)

     

       138
       138
       +
                           ] in

     

       139
       139
       +
                           Some (create_response ~id:req.id ~result)

     

       140
       140
       +
                         end

     

       141
       141
       +
                     end

     

       142
       142
       +
                   | _ -> begin

     

       143
       143
       +
                       Log.error "Invalid params format for tools/call";

     

       144
       144
       +
                       Some (create_error ~id:req.id ~code:ErrorCode.invalid_params ~message:"Invalid params for tools/call" ())

     

       145
       145
       +
                     end

     

       146
       146
       +
                 end

     

       147
       147
       +
                   

     

       148
       148
       +
               | "resources/list" -> begin

     

       149
       149
       +
                   Log.debug "Processing resources/list request";

     

       150
       150
       +
                   if server.resources <> [] then begin

     

       151
       151
       +
                     let resources_json = List.map Mcp_sdk.Resource.to_json server.resources in

     

       152
       152
       +
                     let result = `Assoc [("resources", `List resources_json)] in

     

       153
       153
       +
                     Some (create_response ~id:req.id ~result)

     

       154
       154
       +
                   end else begin

     

       155
       155
       +
                     Some (create_error ~id:req.id ~code:ErrorCode.method_not_found ~message:"Resources not supported" ())

     

       156
       156
       +
                   end

     

       157
       157
       +
                 end

     

       158
       158
       +
                  

     

       159
       159
       +
               | "prompts/list" -> begin

     

       160
       160
       +
                   Log.debug "Processing prompts/list request";

     

       161
       161
       +
                   if server.prompts <> [] then begin

     

       162
       162
       +
                     let prompts_json = List.map Mcp_sdk.Prompt.to_json server.prompts in

     

       163
       163
       +
                     let result = `Assoc [("prompts", `List prompts_json)] in

     

       164
       164
       +
                     Some (create_response ~id:req.id ~result)

     

       165
       165
       +
                   end else begin

     

       166
       166
       +
                     Some (create_error ~id:req.id ~code:ErrorCode.method_not_found ~message:"Prompts not supported" ())

     

       167
       167
       +
                   end

     

       168
       168
       +
                 end

     

       169
       169
       +
                  

     

       170
       170
       +
               | "prompts/get" -> begin

     

       171
       171
       +
                   Log.debug "Processing prompts/get request";

     

       172
       172
       +
                   if server.prompts <> [] then begin

     

       173
       173
       +
                     match req.params with

     

       174
       174
       +
                     | Some (`Assoc params) -> begin

     

       175
       175
       +
                         (* Extract prompt name *)

     

       176
       176
       +
                         let name = match List.assoc_opt "name" params with

     

       177
       177
       +
                         | Some (`String name) -> begin 

     

       178
       178
       +
                             Log.debug (Printf.sprintf "Prompt name: %s" name);

     

       179
       179
       +
                             name

     

       180
       180
       +
                           end

     

       181
       181
       +
                         | _ -> begin

     

       182
       182
       +
                             Log.error "Missing or invalid 'name' parameter in prompt request";

     

       183
       183
       +
                             failwith "Missing or invalid 'name' parameter"

     

       184
       184
       +
                           end

     

       185
       185
       +
                         in

     

       186
       186
       +
                         

     

       187
       187
       +
                         (* Extract arguments if any *)

     

       188
       188
       +
                         let arguments = match List.assoc_opt "arguments" params with

     

       189
       189
       +
                         | Some (`Assoc args) -> begin

     

       190
       190
       +
                             Log.debug (Printf.sprintf "Prompt arguments: %s" (Yojson.Safe.to_string (`Assoc args)));

     

       191
       191
       +
                             List.map (fun (k, v) -> 

     

       192
       192
       +
                               match v with 

     

       193
       193
       +
                               | `String s -> begin (k, s) end

     

       194
       194
       +
                               | _ -> begin (k, Yojson.Safe.to_string v) end

     

       195
       195
       +
                             ) args

     

       196
       196
       +
                           end

     

       197
       197
       +
                         | _ -> begin

     

       198
       198
       +
                             []

     

       199
       199
       +
                           end

     

       200
       200
       +
                         in

     

       201
       201
       +
                         

     

       202
       202
       +
                         (* Find the prompt *)

     

       203
       203
       +
                         let prompt_opt = List.find_opt (fun p -> p.Mcp_sdk.Prompt.name = name) server.prompts in

     

       204
       204
       +
                         match prompt_opt with

     

       205
       205
       +
                         | Some prompt -> begin

     

       206
       206
       +
                             Log.debug (Printf.sprintf "Found prompt: %s" name);

     

       207
       207
       +
                             let ctx = Mcp_sdk.Context.create 

     

       208
       208
       +
                                 ?request_id:(Some req.id) 

     

       209
       209
       +
                                 ~lifespan_context:server.lifespan_context 

     

       210
       210
       +
                                 () 

     

       211
       211
       +
                             in

     

       212
       212
       +
                             

     

       213
       213
       +
                             (* Call the prompt handler *)

     

       214
       214
       +
                             match prompt.handler ctx arguments with

     

       215
       215
       +
                             | Ok messages -> begin

     

       216
       216
       +
                                 Log.debug (Printf.sprintf "Prompt handler returned %d messages" (List.length messages));

     

       217
       217
       +
                                 

     

       218
       218
       +
                                 (* Important: We need to directly use yojson_of_message which preserves MIME types *)

     

       219
       219
       +
                                 let messages_json = List.map Prompt.yojson_of_message messages in

     

       220
       220
       +
                                 

     

       221
       221
       +
                                 (* Debug output *)

     

       222
       222
       +
                                 Log.debug (Printf.sprintf "Messages JSON: %s" (Yojson.Safe.to_string (`List messages_json)));

     

       223
       223
       +
                                 

     

       224
       224
       +
                                 (* Verify one message if available to check structure *)

     

       225
       225
       +
                                 if List.length messages > 0 then begin

     

       226
       226
       +
                                   let first_msg = List.hd messages in

     

       227
       227
       +
                                   let content_debug = match first_msg.content with

     

       228
       228
       +
                                   | Text t -> begin

     

       229
       229
       +
                                       Printf.sprintf "Text content: %s" t.text

     

       230
       230
       +
                                     end

     

       231
       231
       +
                                   | Image i -> begin

     

       232
       232
       +
                                       Printf.sprintf "Image content (mime: %s)" i.mime_type

     

       233
       233
       +
                                     end

     

       234
       234
       +
                                   | Audio a -> begin

     

       235
       235
       +
                                       Printf.sprintf "Audio content (mime: %s)" a.mime_type

     

       236
       236
       +
                                     end

     

       237
       237
       +
                                   | Resource r -> begin

     

       238
       238
       +
                                       "Resource content"

     

       239
       239
       +
                                     end

     

       240
       240
       +
                                   in

     

       241
       241
       +
                                   Log.debug (Printf.sprintf "First message content type: %s" content_debug);

     

       242
       242
       +
                                 end;

     

       243
       243
       +
                                 

     

       244
       244
       +
                                 let result = `Assoc [

     

       245
       245
       +
                                   ("messages", `List messages_json);

     

       246
       246
       +
                                   ("description", match prompt.description with 

     

       247
       247
       +
                                     | Some d -> begin `String d end 

     

       248
       248
       +
                                     | None -> begin `Null end)

     

       249
       249
       +
                                 ] in

     

       250
       250
       +
                                 Some (create_response ~id:req.id ~result)

     

       251
       251
       +
                               end

     

       252
       252
       +
                             | Error err -> begin

     

       253
       253
       +
                                 Log.error (Printf.sprintf "Error processing prompt: %s" err);

     

       254
       254
       +
                                 Some (create_error ~id:req.id ~code:ErrorCode.internal_error ~message:err ())

     

       255
       255
       +
                               end

     

       256
       256
       +
                           end

     

       257
       257
       +
                         | None -> begin

     

       258
       258
       +
                             Log.error (Printf.sprintf "Prompt not found: %s" name);

     

       259
       259
       +
                             Some (create_error ~id:req.id ~code:ErrorCode.invalid_params ~message:(Printf.sprintf "Prompt not found: %s" name) ())

     

       260
       260
       +
                           end

     

       261
       261
       +
                       end

     

       262
       262
       +
                     | _ -> begin

     

       263
       263
       +
                         Log.error "Invalid params format for prompts/get";

     

       264
       264
       +
                         Some (create_error ~id:req.id ~code:ErrorCode.invalid_params ~message:"Invalid params format" ())

     

       265
       265
       +
                       end

     

       266
       266
       +
                   end else begin

     

       267
       267
       +
                     Some (create_error ~id:req.id ~code:ErrorCode.method_not_found ~message:"Prompts not supported" ())

     

       268
       268
       +
                   end

     

       269
       269
       +
                 end

     

       270
       270
       +
                  

     

       271
       271
       +
               | "ping" -> begin

     

       272
       272
       +
                   Log.debug "Processing ping request";

     

       273
       273
       +
                   Some (create_response ~id:req.id ~result:(`Assoc []))

     

       274
       274
       +
                 end

     

       275
       275
       +
                

     

       276
       276
       +
               | _ -> begin

     

       277
       277
       +
                   Log.error (Printf.sprintf "Unknown method received: %s" req.method_);

     

       278
       278
       +
                   Some (create_error ~id:req.id ~code:ErrorCode.method_not_found ~message:("Method not found: " ^ req.method_) ())

     

       279
       279
       +
                 end

     

       280
       280
       +
             end

     

       281
       281
       +
                

     

       282
       282
       +
           | JSONRPCMessage.Notification notif -> begin

     

       283
       283
       +
               Log.debug (Printf.sprintf "Received notification with method: %s" notif.method_);

     

       284
       284
       +
               match notif.method_ with

     

       285
       285
       +
               | "notifications/initialized" -> begin

     

       286
       286
       +
                   Log.debug "Client initialization complete - Server is now ready to receive requests";

     

       287
       287
       +
                   None

     

       288
       288
       +
                 end

     

       289
       289
       +
               | _ -> begin

     

       290
       290
       +
                   Log.debug (Printf.sprintf "Ignoring notification: %s" notif.method_);

     

       291
       291
       +
                   None

     

       292
       292
       +
                 end

     

       293
       293
       +
             end

     

       294
       294
       +
                

     

       295
       295
       +
           | JSONRPCMessage.Response _ -> begin

     

       296
       296
       +
               Log.error "Unexpected response message received";

     

       297
       297
       +
               None

     

       298
       298
       +
             end

     

       299
       299
       +
             

     

       300
       300
       +
           | JSONRPCMessage.Error _ -> begin

     

       301
       301
       +
               Log.error "Unexpected error message received";

     

       302
       302
       +
               None

     

       303
       303
       +
             end

     

       304
       304
       +
         with

     

       305
       305
       +
         | Failure msg -> begin

     

       306
       306
       +
             Log.error (Printf.sprintf "JSON error in message processing: %s" msg);

     

       185
       307
        
             None

     

       186
       186
       -
           | JSONRPCMessage.Error _ ->

     

       187
       187
       -
             Log.error "Unexpected error message received";

     

       308
       308
       +
           end

     

       309
       309
       +
         | exc -> begin

     

       310
       310
       +
             Log.error (Printf.sprintf "Exception during message processing: %s" (Printexc.to_string exc));

     

       311
       311
       +
             Log.error (Printf.sprintf "Backtrace: %s" (Printexc.get_backtrace()));

     

       188
       312
        
             None

     

       189
       189
       -
         with

     

       190
       190
       -
         | Json.Of_json (msg, _) ->

     

       191
       191
       -
           Log.error (Printf.sprintf "JSON error: %s" msg);

     

       192
       192
       -
           (* Can't respond with error because we don't have a request ID *)

     

       193
       193
       -
           None

     

       194
       194
       -
         | Yojson.Json_error msg -> 

     

       195
       195
       -
           Log.error (Printf.sprintf "JSON parse error: %s" msg);

     

       196
       196
       -
           (* Can't respond with error because we don't have a request ID *)

     

       197
       197
       -
           None

     

       198
       198
       -
         | exc ->

     

       199
       199
       -
           Log.error (Printf.sprintf "Exception during message processing: %s" (Printexc.to_string exc));

     

       200
       200
       -
           Log.error (Printf.sprintf "Backtrace: %s" (Printexc.get_backtrace()));

     

       201
       201
       -
           Log.error (Printf.sprintf "Message was: %s" (Yojson.Safe.to_string message));

     

       202
       202
       -
           None

     

       313
       313
       +
           end

     

       203
       314
        
       

     

       204
       204
       -
       (* Extract a request ID from a potentially malformed message *)

     

       205
       205
       -
       let extract_request_id json =

     

       315
       315
       +
       (** Read a single message from stdin *)

     

       316
       316
       +
       let read_stdio_message () =

     

       206
       317
        
         try

     

       207
       207
       -
           match json with

     

       208
       208
       -
           | `Assoc fields ->

     

       209
       209
       -
             (match List.assoc_opt "id" fields with

     

       210
       210
       -
              | Some (`Int id) -> Some (`Int id)

     

       211
       211
       -
              | Some (`String id) -> Some (`String id)

     

       212
       212
       -
              | _ -> None)

     

       213
       213
       -
           | _ -> None

     

       214
       214
       -
         with _ -> None

     

       318
       318
       +
           Log.debug "Reading line from stdin...";

     

       319
       319
       +
           let line = read_line () in

     

       320
       320
       +
           if line = "" then begin

     

       321
       321
       +
             Log.debug "Empty line received, ignoring";

     

       322
       322
       +
             None

     

       323
       323
       +
           end else begin

     

       324
       324
       +
             Log.debug (Printf.sprintf "Raw input: %s" (String.sub line 0 (min 100 (String.length line))));

     

       325
       325
       +
             try

     

       326
       326
       +
               let json = Yojson.Safe.from_string line in

     

       327
       327
       +
               Log.debug "Successfully parsed JSON";

     

       328
       328
       +
               Some json

     

       329
       329
       +
             with

     

       330
       330
       +
             | Yojson.Json_error msg -> begin

     

       331
       331
       +
                 Log.error (Printf.sprintf "Error parsing JSON: %s" msg);

     

       332
       332
       +
                 Log.error (Printf.sprintf "Input was: %s" (String.sub line 0 (min 100 (String.length line))));

     

       333
       333
       +
                 None

     

       334
       334
       +
               end

     

       335
       335
       +
           end

     

       336
       336
       +
         with

     

       337
       337
       +
         | End_of_file -> begin

     

       338
       338
       +
             Log.debug "End of file received on stdin";

     

       339
       339
       +
             None

     

       340
       340
       +
           end

     

       341
       341
       +
         | Sys_error msg -> begin

     

       342
       342
       +
             Log.error (Printf.sprintf "System error while reading: %s" msg);

     

       343
       343
       +
             None

     

       344
       344
       +
           end

     

       345
       345
       +
         | exc -> begin

     

       346
       346
       +
             Log.error (Printf.sprintf "Exception while reading: %s" (Printexc.to_string exc));

     

       347
       347
       +
             None

     

       348
       348
       +
           end

     

       215
       349
        
       

     

       216
       216
       -
       (* Handle processing for an input line *)

     

       217
       217
       -
       let process_input_line server line =

     

       218
       218
       -
         if line = "" then (

     

       219
       219
       -
           Log.debug "Empty line received, ignoring";

     

       220
       220
       -
           None

     

       221
       221
       -
         ) else (

     

       222
       222
       -
           Log.debug (Printf.sprintf "Raw input: %s" line);

     

       223
       223
       -
           try

     

       224
       224
       -
             let json = Yojson.Safe.from_string line in

     

       225
       225
       -
             Log.debug "Successfully parsed JSON";

     

       226
       226
       -
             

     

       227
       227
       -
             (* Process the message *)

     

       228
       228
       -
             process_message server json

     

       229
       229
       -
           with

     

       230
       230
       -
           | Yojson.Json_error msg -> begin

     

       231
       231
       -
               Log.error (Printf.sprintf "Error parsing JSON: %s" msg);

     

       232
       232
       -
               Log.error (Printf.sprintf "Input was: %s" line);

     

       233
       233
       -
               None

     

       350
       350
       +
       (** Run stdio server with enhanced error handling *)

     

       351
       351
       +
       let rec run_stdio_server mcp_server =

     

       352
       352
       +
         try begin

     

       353
       353
       +
           if not mcp_server.running then begin

     

       354
       354
       +
             Log.debug "Server stopped";

     

       355
       355
       +
             ()

     

       356
       356
       +
           end else begin

     

       357
       357
       +
             match read_stdio_message () with

     

       358
       358
       +
             | Some json -> begin

     

       359
       359
       +
                 Log.debug "Processing message...";

     

       360
       360
       +
                 try begin

     

       361
       361
       +
                   match process_message mcp_server.server json with

     

       362
       362
       +
                   | Some response -> begin

     

       363
       363
       +
                       let response_json = JSONRPCMessage.yojson_of_t response in

     

       364
       364
       +
                       let response_str = Yojson.Safe.to_string response_json in

     

       365
       365
       +
                       Log.debug (Printf.sprintf "Sending response: %s" 

     

       366
       366
       +
                                   (String.sub response_str 0 (min 100 (String.length response_str))));

     

       367
       367
       +
                       Printf.printf "%s\n" response_str;

     

       368
       368
       +
                       flush stdout;

     

       369
       369
       +
                       (* Give client time to process *)

     

       370
       370
       +
                       Unix.sleepf 0.01;

     

       371
       371
       +
                     end

     

       372
       372
       +
                   | None -> begin

     

       373
       373
       +
                       Log.debug "No response needed"

     

       374
       374
       +
                     end

     

       375
       375
       +
                   end with

     

       376
       376
       +
                   | exc -> begin

     

       377
       377
       +
                       Log.error (Printf.sprintf "ERROR in message processing: %s" (Printexc.to_string exc));

     

       378
       378
       +
                       Log.error (Printf.sprintf "Backtrace: %s" (Printexc.get_backtrace()));

     

       379
       379
       +
                       (* Try to extract ID and send an error response *)

     

       380
       380
       +
                       try begin

     

       381
       381
       +
                         let id_opt = match Yojson.Safe.Util.member "id" json with

     

       382
       382
       +
                           | `Int i -> Some (`Int i)

     

       383
       383
       +
                           | `String s -> Some (`String s)

     

       384
       384
       +
                           | _ -> None

     

       385
       385
       +
                         in

     

       386
       386
       +
                         match id_opt with

     

       387
       387
       +
                         | Some id -> begin

     

       388
       388
       +
                             let error_resp = create_error ~id ~code:ErrorCode.internal_error ~message:(Printexc.to_string exc) () in

     

       389
       389
       +
                             let error_json = JSONRPCMessage.yojson_of_t error_resp in

     

       390
       390
       +
                             let error_str = Yojson.Safe.to_string error_json in

     

       391
       391
       +
                             Printf.printf "%s\n" error_str;

     

       392
       392
       +
                             flush stdout;

     

       393
       393
       +
                           end

     

       394
       394
       +
                         | None -> begin

     

       395
       395
       +
                             Log.error "Could not extract request ID to send error response"

     

       396
       396
       +
                           end

     

       397
       397
       +
                         end with

     

       398
       398
       +
                         | e -> begin

     

       399
       399
       +
                             Log.error (Printf.sprintf "Failed to send error response: %s" (Printexc.to_string e))

     

       400
       400
       +
                           end

     

       401
       401
       +
                     end;

     

       402
       402
       +
                 run_stdio_server mcp_server

     

       403
       403
       +
               end

     

       404
       404
       +
             | None -> begin

     

       405
       405
       +
                 if mcp_server.running then begin

     

       406
       406
       +
                   (* No message received, but server is still running *)

     

       407
       407
       +
                   Unix.sleepf 0.1;  (* Small sleep to prevent CPU spinning *)

     

       408
       408
       +
                   run_stdio_server mcp_server

     

       409
       409
       +
                 end else begin

     

       410
       410
       +
                   Log.debug "Server stopped during message processing"

     

       411
       411
       +
                 end

     

       412
       412
       +
               end

     

       234
       413
        
           end

     

       235
       235
       -
         )

     

       236
       236
       -
       

     

       237
       237
       -
       (* Send a response to the client *)

     

       238
       238
       -
       let send_response stdout response =

     

       239
       239
       -
         let response_json = JSONRPCMessage.yojson_of_t response in

     

       240
       240
       -
         let response_str = Yojson.Safe.to_string response_json in

     

       241
       241
       -
         Log.debug (Printf.sprintf "Sending response: %s" response_str);

     

       242
       242
       -
         

     

       243
       243
       -
         (* Write the response followed by a newline *)

     

       244
       244
       -
         Eio.Flow.copy_string response_str stdout;

     

       245
       245
       -
         Eio.Flow.copy_string "\n" stdout

     

       414
       414
       +
         end with

     

       415
       415
       +
         | exc -> begin

     

       416
       416
       +
             Log.error (Printf.sprintf "FATAL ERROR in server main loop: %s" (Printexc.to_string exc));

     

       417
       417
       +
             Log.error (Printf.sprintf "Backtrace: %s" (Printexc.get_backtrace()));

     

       418
       418
       +
             (* Try to continue anyway *)

     

       419
       419
       +
             if mcp_server.running then begin

     

       420
       420
       +
               Unix.sleepf 0.1;

     

       421
       421
       +
               run_stdio_server mcp_server

     

       422
       422
       +
             end

     

       423
       423
       +
           end

     

       246
       424
        
       

     

       247
       247
       -
       (* Run the MCP server with the given server configuration *)

     

       248
       248
       -
       let run_server env server =

     

       249
       249
       -
         let stdin = Eio.Stdenv.stdin env in

     

       250
       250
       -
         let stdout = Eio.Stdenv.stdout env in

     

       425
       425
       +
       (** Create an MCP server *)

     

       426
       426
       +
       let create ~server ~transport () =

     

       427
       427
       +
         { server; transport; running = false }

     

       251
       428
        
       

     

       252
       252
       -
         Log.debug (Printf.sprintf "Starting MCP server: %s v%s" (name server) (version server));

     

       253
       253
       -
         Log.debug (Printf.sprintf "Protocol version: %s" (protocol_version server));

     

       429
       429
       +
       (** HTTP server placeholder (to be fully implemented) *)

     

       430
       430
       +
       let run_http_server mcp_server port =

     

       431
       431
       +
         Log.info (Printf.sprintf "%s HTTP server starting on port %d" mcp_server.server.name port);

     

       432
       432
       +
         Log.info "HTTP transport is a placeholder and not fully implemented yet";

     

       433
       433
       +
         

     

       434
       434
       +
         (* This would be where we'd set up cohttp server *)

     

       435
       435
       +
         (*

     

       436
       436
       +
         let callback _conn req body =

     

       437
       437
       +
           let uri = req |> Cohttp.Request.uri in

     

       438
       438
       +
           let meth = req |> Cohttp.Request.meth |> Cohttp.Code.string_of_method in

     

       439
       439
       +
           

     

       440
       440
       +
           (* Handle only POST /jsonrpc endpoint *)

     

       441
       441
       +
           match (meth, Uri.path uri) with

     

       442
       442
       +
           | "POST", "/jsonrpc" ->

     

       443
       443
       +
             (* Read the body *)

     

       444
       444
       +
             Cohttp_lwt.Body.to_string body >>= fun body_str ->

     

       445
       445
       +
             

     

       446
       446
       +
             (* Parse JSON *)

     

       447
       447
       +
             let json = try Some (Yojson.Safe.from_string body_str) with _ -> None in

     

       448
       448
       +
             match json with

     

       449
       449
       +
             | Some json_msg ->

     

       450
       450
       +
               (* Process the message *)

     

       451
       451
       +
               let response_opt = process_message mcp_server.server json_msg in

     

       452
       452
       +
               (match response_opt with

     

       453
       453
       +
               | Some response ->

     

       454
       454
       +
                 let response_json = JSONRPCMessage.yojson_of_t response in

     

       455
       455
       +
                 let response_str = Yojson.Safe.to_string response_json in

     

       456
       456
       +
                 Cohttp_lwt_unix.Server.respond_string

     

       457
       457
       +
                   ~status:`OK

     

       458
       458
       +
                   ~body:response_str

     

       459
       459
       +
                   ~headers:(Cohttp.Header.init_with "Content-Type" "application/json")

     

       460
       460
       +
                   ()

     

       461
       461
       +
               | None ->

     

       462
       462
       +
                 Cohttp_lwt_unix.Server.respond_string

     

       463
       463
       +
                   ~status:`OK

     

       464
       464
       +
                   ~body:"{}"

     

       465
       465
       +
                   ~headers:(Cohttp.Header.init_with "Content-Type" "application/json")

     

       466
       466
       +
                   ())

     

       467
       467
       +
             | None ->

     

       468
       468
       +
               Cohttp_lwt_unix.Server.respond_string

     

       469
       469
       +
                 ~status:`Bad_request

     

       470
       470
       +
                 ~body:"{\"error\":\"Invalid JSON\"}"

     

       471
       471
       +
                 ~headers:(Cohttp.Header.init_with "Content-Type" "application/json")

     

       472
       472
       +
                 ()

     

       473
       473
       +
           | _ ->

     

       474
       474
       +
             (* Return 404 for any other routes *)

     

       475
       475
       +
             Cohttp_lwt_unix.Server.respond_string

     

       476
       476
       +
               ~status:`Not_found

     

       477
       477
       +
               ~body:"Not found"

     

       478
       478
       +
               ()

     

       479
       479
       +
         in

     

       480
       480
       +
         

     

       481
       481
       +
         (* Create and start the server *)

     

       482
       482
       +
         let server = Cohttp_lwt_unix.Server.create

     

       483
       483
       +
           ~mode:(`TCP (`Port port))

     

       484
       484
       +
           (Cohttp_lwt_unix.Server.make ~callback ())

     

       485
       485
       +
         in

     

       486
       486
       +
         

     

       487
       487
       +
         (* Run the server *)

     

       488
       488
       +
         Lwt_main.run server

     

       489
       489
       +
         *)

     

       490
       490
       +
         

     

       491
       491
       +
         (* For now, just wait until the server is stopped *)

     

       492
       492
       +
         while mcp_server.running do

     

       493
       493
       +
           Unix.sleep 1

     

       494
       494
       +
         done

     

       254
       495
        
       

     

       255
       255
       -
         (* Enable exception backtraces *)

     

       256
       256
       -
         Printexc.record_backtrace true;

     

       496
       496
       +
       (** Start the server based on transport type *)

     

       497
       497
       +
       let start server =

     

       498
       498
       +
         server.running <- true;

     

       257
       499
        
         

     

       258
       258
       -
         let buf = Eio.Buf_read.of_flow stdin ~initial_size:100 ~max_size:1_000_000 in

     

       500
       500
       +
         (* Run startup hook if provided *)

     

       501
       501
       +
         (match server.server.startup_hook with

     

       502
       502
       +
         | Some hook -> begin hook () end

     

       503
       503
       +
         | None -> begin () end);

     

       259
       504
        
         

     

       260
       260
       -
         (* Main processing loop *)

     

       261
       261
       -
         try

     

       262
       262
       -
           while true do

     

       263
       263
       -
             Log.debug "Waiting for message...";

     

       264
       264
       -
             let line = Eio.Buf_read.line buf in

     

       505
       505
       +
         (* Install signal handler *)

     

       506
       506
       +
         Sys.(set_signal sigint (Signal_handle (fun _ -> 

     

       507
       507
       +
           Log.debug "Received interrupt signal, stopping server...";

     

       508
       508
       +
           server.running <- false

     

       509
       509
       +
         )));

     

       510
       510
       +
         

     

       511
       511
       +
         match server.transport with

     

       512
       512
       +
         | Stdio -> begin

     

       513
       513
       +
             (* Setup stdout and stderr *)

     

       514
       514
       +
             set_binary_mode_out stdout false;

     

       515
       515
       +
             Log.info (Printf.sprintf "%s server started with stdio transport" server.server.name);

     

       265
       516
        
             

     

       266
       266
       -
             (* Process the input and send response if needed *)

     

       267
       267
       -
             match process_input_line server line with

     

       268
       268
       -
             | Some response -> send_response stdout response

     

       269
       269
       -
             | None -> Log.debug "No response needed for this message"

     

       270
       270
       -
           done

     

       271
       271
       -
         with

     

       272
       272
       -
         | End_of_file -> 

     

       273
       273
       -
             Log.debug "End of file received on stdin";

     

       274
       274
       -
             ()

     

       275
       275
       -
         | Eio.Exn.Io _ as exn ->

     

       276
       276
       -
             Log.error (Printf.sprintf "I/O error while reading: %s" (Printexc.to_string exn));

     

       277
       277
       -
             ()

     

       278
       278
       -
         | exn ->

     

       279
       279
       -
             Log.error (Printf.sprintf "Exception while reading: %s" (Printexc.to_string exn));

     

       280
       280
       -
             ()

     

       517
       517
       +
             (* Run the server loop *)

     

       518
       518
       +
             run_stdio_server server

     

       519
       519
       +
           end

     

       520
       520
       +
         | Http -> begin

     

       521
       521
       +
             (* HTTP server placeholder *)

     

       522
       522
       +
             run_http_server server 8080

     

       523
       523
       +
           end

     

       524
       524
       +
       

     

       525
       525
       +
       (** Stop the server *)

     

       526
       526
       +
       let stop server =

     

       527
       527
       +
         Log.info "Stopping server...";

     

       528
       528
       +
         server.running <- false;

     

       529
       529
       +
         

     

       530
       530
       +
         (* Run shutdown hook if provided *)

     

       531
       531
       +
         match server.server.shutdown_hook with

     

       532
       532
       +
         | Some hook -> begin hook () end

     

       533
       533
       +
         | None -> begin () end

+54

lib/mcp_server.mli

···

       1
       1
       +
       (** MCP Server module - full implementation *)

     

       2
       2
       +
       

     

       3
       3
       +
       (** Transport type for server *)

     

       4
       4
       +
       type transport_type = 

     

       5
       5
       +
         | Stdio  (** Read/write to stdin/stdout *)

     

       6
       6
       +
         | Http   (** HTTP server - to be implemented *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** Server type *)

     

       9
       9
       +
       type t = {

     

       10
       10
       +
         server: Mcp_sdk.server;

     

       11
       11
       +
         transport: transport_type;

     

       12
       12
       +
         mutable running: bool;

     

       13
       13
       +
       }

     

       14
       14
       +
       

     

       15
       15
       +
       (** Create an MCP server 

     

       16
       16
       +
           @param server The Mcp_sdk server to use

     

       17
       17
       +
           @param transport The transport type to use

     

       18
       18
       +
       *)

     

       19
       19
       +
       val create : server:Mcp_sdk.server -> transport:transport_type -> unit -> t

     

       20
       20
       +
       

     

       21
       21
       +
       (** Start the server

     

       22
       22
       +
           This function will block until the server is stopped.

     

       23
       23
       +
           @param server The server to start

     

       24
       24
       +
       *)

     

       25
       25
       +
       val start : t -> unit

     

       26
       26
       +
       

     

       27
       27
       +
       (** Stop the server

     

       28
       28
       +
           This will set the running flag to false and invoke the shutdown hook.

     

       29
       29
       +
           @param server The server to stop

     

       30
       30
       +
       *)

     

       31
       31
       +
       val stop : t -> unit

     

       32
       32
       +
       

     

       33
       33
       +
       (** Process a single message 

     

       34
       34
       +
           @param server The Mcp_sdk server to use

     

       35
       35
       +
           @param message The JSON message to process

     

       36
       36
       +
           @return An optional response message

     

       37
       37
       +
       *)

     

       38
       38
       +
       val process_message : Mcp_sdk.server -> Yojson.Safe.t -> Mcp.JSONRPCMessage.t option

     

       39
       39
       +
       

     

       40
       40
       +
       (** Run stdio server implementation 

     

       41
       41
       +
           @param mcp_server The mcp_server to run

     

       42
       42
       +
       *)

     

       43
       43
       +
       val run_stdio_server : t -> unit

     

       44
       44
       +
       

     

       45
       45
       +
       (** Read a message from stdio

     

       46
       46
       +
           @return An optional JSON message

     

       47
       47
       +
       *)

     

       48
       48
       +
       val read_stdio_message : unit -> Yojson.Safe.t option

     

       49
       49
       +
       

     

       50
       50
       +
       (** Run HTTP server implementation (placeholder)

     

       51
       51
       +
           @param mcp_server The mcp_server to run

     

       52
       52
       +
           @param port The port to listen on

     

       53
       53
       +
       *)

     

       54
       54
       +
       val run_http_server : t -> int -> unit

-29

mcp.opam

···

       1
       1
       -
       # This file is generated by dune, edit dune-project instead

     

       2
       2
       -
       opam-version: "2.0"

     

       3
       3
       -
       synopsis: "Model Context Protocol for LLMs"

     

       4
       4
       -
       description: "This is all still a work in progress"

     

       5
       5
       -
       maintainer: ["anil@recoil.org"]

     

       6
       6
       -
       authors: ["Anil Madhavapeddy"]

     

       7
       7
       -
       license: "ISC"

     

       8
       8
       -
       depends: [

     

       9
       9
       -
         "dune" {>= "3.17"}

     

       10
       10
       -
         "ocaml" {>= "5.2.0"}

     

       11
       11
       -
         "jsonrpc"

     

       12
       12
       -
         "eio_main"

     

       13
       13
       -
         "eio"

     

       14
       14
       -
         "odoc" {with-doc}

     

       15
       15
       -
       ]

     

       16
       16
       -
       build: [

     

       17
       17
       -
         ["dune" "subst"] {dev}

     

       18
       18
       -
         [

     

       19
       19
       -
           "dune"

     

       20
       20
       -
           "build"

     

       21
       21
       -
           "-p"

     

       22
       22
       -
           name

     

       23
       23
       -
           "-j"

     

       24
       24
       -
           jobs

     

       25
       25
       -
           "@install"

     

       26
       26
       -
           "@runtest" {with-test}

     

       27
       27
       -
           "@doc" {with-doc}

     

       28
       28
       -
         ]

     

       29
       29
       -
       ]

+178

spec/00-arch.md

···

       1
       1
       +
       ---

     

       2
       2
       +
       title: Architecture

     

       3
       3
       +
       cascade:

     

       4
       4
       +
         type: docs

     

       5
       5
       +
       weight: 10

     

       6
       6
       +
       ---

     

       7
       7
       +
       

     

       8
       8
       +
       The Model Context Protocol (MCP) follows a client-host-server architecture where each

     

       9
       9
       +
       host can run multiple client instances. This architecture enables users to integrate AI

     

       10
       10
       +
       capabilities across applications while maintaining clear security boundaries and

     

       11
       11
       +
       isolating concerns. Built on JSON-RPC, MCP provides a stateful session protocol focused

     

       12
       12
       +
       on context exchange and sampling coordination between clients and servers.

     

       13
       13
       +
       

     

       14
       14
       +
       ## Core Components

     

       15
       15
       +
       

     

       16
       16
       +
       ```mermaid

     

       17
       17
       +
       graph LR

     

       18
       18
       +
           subgraph "Application Host Process"

     

       19
       19
       +
               H[Host]

     

       20
       20
       +
               C1[Client 1]

     

       21
       21
       +
               C2[Client 2]

     

       22
       22
       +
               C3[Client 3]

     

       23
       23
       +
               H --> C1

     

       24
       24
       +
               H --> C2

     

       25
       25
       +
               H --> C3

     

       26
       26
       +
           end

     

       27
       27
       +
       

     

       28
       28
       +
           subgraph "Local machine"

     

       29
       29
       +
               S1[Server 1<br>Files & Git]

     

       30
       30
       +
               S2[Server 2<br>Database]

     

       31
       31
       +
               R1[("Local<br>Resource A")]

     

       32
       32
       +
               R2[("Local<br>Resource B")]

     

       33
       33
       +
       

     

       34
       34
       +
               C1 --> S1

     

       35
       35
       +
               C2 --> S2

     

       36
       36
       +
               S1 <--> R1

     

       37
       37
       +
               S2 <--> R2

     

       38
       38
       +
           end

     

       39
       39
       +
       

     

       40
       40
       +
           subgraph "Internet"

     

       41
       41
       +
               S3[Server 3<br>External APIs]

     

       42
       42
       +
               R3[("Remote<br>Resource C")]

     

       43
       43
       +
       

     

       44
       44
       +
               C3 --> S3

     

       45
       45
       +
               S3 <--> R3

     

       46
       46
       +
           end

     

       47
       47
       +
       ```

     

       48
       48
       +
       

     

       49
       49
       +
       ### Host

     

       50
       50
       +
       

     

       51
       51
       +
       The host process acts as the container and coordinator:

     

       52
       52
       +
       

     

       53
       53
       +
       - Creates and manages multiple client instances

     

       54
       54
       +
       - Controls client connection permissions and lifecycle

     

       55
       55
       +
       - Enforces security policies and consent requirements

     

       56
       56
       +
       - Handles user authorization decisions

     

       57
       57
       +
       - Coordinates AI/LLM integration and sampling

     

       58
       58
       +
       - Manages context aggregation across clients

     

       59
       59
       +
       

     

       60
       60
       +
       ### Clients

     

       61
       61
       +
       

     

       62
       62
       +
       Each client is created by the host and maintains an isolated server connection:

     

       63
       63
       +
       

     

       64
       64
       +
       - Establishes one stateful session per server

     

       65
       65
       +
       - Handles protocol negotiation and capability exchange

     

       66
       66
       +
       - Routes protocol messages bidirectionally

     

       67
       67
       +
       - Manages subscriptions and notifications

     

       68
       68
       +
       - Maintains security boundaries between servers

     

       69
       69
       +
       

     

       70
       70
       +
       A host application creates and manages multiple clients, with each client having a 1:1

     

       71
       71
       +
       relationship with a particular server.

     

       72
       72
       +
       

     

       73
       73
       +
       ### Servers

     

       74
       74
       +
       

     

       75
       75
       +
       Servers provide specialized context and capabilities:

     

       76
       76
       +
       

     

       77
       77
       +
       - Expose resources, tools and prompts via MCP primitives

     

       78
       78
       +
       - Operate independently with focused responsibilities

     

       79
       79
       +
       - Request sampling through client interfaces

     

       80
       80
       +
       - Must respect security constraints

     

       81
       81
       +
       - Can be local processes or remote services

     

       82
       82
       +
       

     

       83
       83
       +
       ## Design Principles

     

       84
       84
       +
       

     

       85
       85
       +
       MCP is built on several key design principles that inform its architecture and

     

       86
       86
       +
       implementation:

     

       87
       87
       +
       

     

       88
       88
       +
       1. **Servers should be extremely easy to build**

     

       89
       89
       +
       

     

       90
       90
       +
          - Host applications handle complex orchestration responsibilities

     

       91
       91
       +
          - Servers focus on specific, well-defined capabilities

     

       92
       92
       +
          - Simple interfaces minimize implementation overhead

     

       93
       93
       +
          - Clear separation enables maintainable code

     

       94
       94
       +
       

     

       95
       95
       +
       2. **Servers should be highly composable**

     

       96
       96
       +
       

     

       97
       97
       +
          - Each server provides focused functionality in isolation

     

       98
       98
       +
          - Multiple servers can be combined seamlessly

     

       99
       99
       +
          - Shared protocol enables interoperability

     

       100
       100
       +
          - Modular design supports extensibility

     

       101
       101
       +
       

     

       102
       102
       +
       3. **Servers should not be able to read the whole conversation, nor "see into" other

     

       103
       103
       +
          servers**

     

       104
       104
       +
       

     

       105
       105
       +
          - Servers receive only necessary contextual information

     

       106
       106
       +
          - Full conversation history stays with the host

     

       107
       107
       +
          - Each server connection maintains isolation

     

       108
       108
       +
          - Cross-server interactions are controlled by the host

     

       109
       109
       +
          - Host process enforces security boundaries

     

       110
       110
       +
       

     

       111
       111
       +
       4. **Features can be added to servers and clients progressively**

     

       112
       112
       +
          - Core protocol provides minimal required functionality

     

       113
       113
       +
          - Additional capabilities can be negotiated as needed

     

       114
       114
       +
          - Servers and clients evolve independently

     

       115
       115
       +
          - Protocol designed for future extensibility

     

       116
       116
       +
          - Backwards compatibility is maintained

     

       117
       117
       +
       

     

       118
       118
       +
       ## Capability Negotiation

     

       119
       119
       +
       

     

       120
       120
       +
       The Model Context Protocol uses a capability-based negotiation system where clients and

     

       121
       121
       +
       servers explicitly declare their supported features during initialization. Capabilities

     

       122
       122
       +
       determine which protocol features and primitives are available during a session.

     

       123
       123
       +
       

     

       124
       124
       +
       - Servers declare capabilities like resource subscriptions, tool support, and prompt

     

       125
       125
       +
         templates

     

       126
       126
       +
       - Clients declare capabilities like sampling support and notification handling

     

       127
       127
       +
       - Both parties must respect declared capabilities throughout the session

     

       128
       128
       +
       - Additional capabilities can be negotiated through extensions to the protocol

     

       129
       129
       +
       

     

       130
       130
       +
       ```mermaid

     

       131
       131
       +
       sequenceDiagram

     

       132
       132
       +
           participant Host

     

       133
       133
       +
           participant Client

     

       134
       134
       +
           participant Server

     

       135
       135
       +
       

     

       136
       136
       +
           Host->>+Client: Initialize client

     

       137
       137
       +
           Client->>+Server: Initialize session with capabilities

     

       138
       138
       +
           Server-->>Client: Respond with supported capabilities

     

       139
       139
       +
       

     

       140
       140
       +
           Note over Host,Server: Active Session with Negotiated Features

     

       141
       141
       +
       

     

       142
       142
       +
           loop Client Requests

     

       143
       143
       +
               Host->>Client: User- or model-initiated action

     

       144
       144
       +
               Client->>Server: Request (tools/resources)

     

       145
       145
       +
               Server-->>Client: Response

     

       146
       146
       +
               Client-->>Host: Update UI or respond to model

     

       147
       147
       +
           end

     

       148
       148
       +
       

     

       149
       149
       +
           loop Server Requests

     

       150
       150
       +
               Server->>Client: Request (sampling)

     

       151
       151
       +
               Client->>Host: Forward to AI

     

       152
       152
       +
               Host-->>Client: AI response

     

       153
       153
       +
               Client-->>Server: Response

     

       154
       154
       +
           end

     

       155
       155
       +
       

     

       156
       156
       +
           loop Notifications

     

       157
       157
       +
               Server--)Client: Resource updates

     

       158
       158
       +
               Client--)Server: Status changes

     

       159
       159
       +
           end

     

       160
       160
       +
       

     

       161
       161
       +
           Host->>Client: Terminate

     

       162
       162
       +
           Client->>-Server: End session

     

       163
       163
       +
           deactivate Server

     

       164
       164
       +
       ```

     

       165
       165
       +
       

     

       166
       166
       +
       Each capability unlocks specific protocol features for use during the session. For

     

       167
       167
       +
       example:

     

       168
       168
       +
       

     

       169
       169
       +
       - Implemented [server features]({{< ref "../server" >}}) must be advertised in the

     

       170
       170
       +
         server's capabilities

     

       171
       171
       +
       - Emitting resource subscription notifications requires the server to declare

     

       172
       172
       +
         subscription support

     

       173
       173
       +
       - Tool invocation requires the server to declare tool capabilities

     

       174
       174
       +
       - [Sampling]({{< ref "../client" >}}) requires the client to declare support in its

     

       175
       175
       +
         capabilities

     

       176
       176
       +
       

     

       177
       177
       +
       This capability negotiation ensures clients and servers have a clear understanding of

     

       178
       178
       +
       supported functionality while maintaining protocol extensibility.

spec/README.md

···

       1
       1
       +
       These specifications are snapshots from

     

       2
       2
       +
       https://github.com/modelcontextprotocol/specification/tree/main/docs/specification/2025-03-26

     

       3
       3
       +
       

     

       4
       4
       +
       to help with the agentic prompting.

+386

spec/authorization.md

···

       1
       1
       +
       ---

     

       2
       2
       +
       title: Authorization

     

       3
       3
       +
       type: docs

     

       4
       4
       +
       weight: 15

     

       5
       5
       +
       ---

     

       6
       6
       +
       

     

       7
       7
       +
       {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}

     

       8
       8
       +
       

     

       9
       9
       +
       ## 1. Introduction

     

       10
       10
       +
       

     

       11
       11
       +
       ### 1.1 Purpose and Scope

     

       12
       12
       +
       

     

       13
       13
       +
       The Model Context Protocol provides authorization capabilities at the transport level,

     

       14
       14
       +
       enabling MCP clients to make requests to restricted MCP servers on behalf of resource

     

       15
       15
       +
       owners. This specification defines the authorization flow for HTTP-based transports.

     

       16
       16
       +
       

     

       17
       17
       +
       ### 1.2 Protocol Requirements

     

       18
       18
       +
       

     

       19
       19
       +
       Authorization is **OPTIONAL** for MCP implementations. When supported:

     

       20
       20
       +
       

     

       21
       21
       +
       - Implementations using an HTTP-based transport **SHOULD** conform to this specification.

     

       22
       22
       +
       - Implementations using an STDIO transport **SHOULD NOT** follow this specification, and

     

       23
       23
       +
         instead retrieve credentials from the environment.

     

       24
       24
       +
       - Implementations using alternative transports **MUST** follow established security best

     

       25
       25
       +
         practices for their protocol.

     

       26
       26
       +
       

     

       27
       27
       +
       ### 1.3 Standards Compliance

     

       28
       28
       +
       

     

       29
       29
       +
       This authorization mechanism is based on established specifications listed below, but

     

       30
       30
       +
       implements a selected subset of their features to ensure security and interoperability

     

       31
       31
       +
       while maintaining simplicity:

     

       32
       32
       +
       

     

       33
       33
       +
       - [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12)

     

       34
       34
       +
       - OAuth 2.0 Authorization Server Metadata

     

       35
       35
       +
         ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414))

     

       36
       36
       +
       - OAuth 2.0 Dynamic Client Registration Protocol

     

       37
       37
       +
         ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591))

     

       38
       38
       +
       

     

       39
       39
       +
       ## 2. Authorization Flow

     

       40
       40
       +
       

     

       41
       41
       +
       ### 2.1 Overview

     

       42
       42
       +
       

     

       43
       43
       +
       1. MCP auth implementations **MUST** implement OAuth 2.1 with appropriate security

     

       44
       44
       +
          measures for both confidential and public clients.

     

       45
       45
       +
       

     

       46
       46
       +
       2. MCP auth implementations **SHOULD** support the OAuth 2.0 Dynamic Client Registration

     

       47
       47
       +
          Protocol ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)).

     

       48
       48
       +
       

     

       49
       49
       +
       3. MCP servers **SHOULD** and MCP clients **MUST** implement OAuth 2.0 Authorization

     

       50
       50
       +
          Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)). Servers

     

       51
       51
       +
          that do not support Authorization Server Metadata **MUST** follow the default URI

     

       52
       52
       +
          schema.

     

       53
       53
       +
       

     

       54
       54
       +
       ### 2.2 Basic OAuth 2.1 Authorization

     

       55
       55
       +
       

     

       56
       56
       +
       When authorization is required and not yet proven by the client, servers **MUST** respond

     

       57
       57
       +
       with _HTTP 401 Unauthorized_.

     

       58
       58
       +
       

     

       59
       59
       +
       Clients initiate the

     

       60
       60
       +
       [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12)

     

       61
       61
       +
       authorization flow after receiving the _HTTP 401 Unauthorized_.

     

       62
       62
       +
       

     

       63
       63
       +
       The following demonstrates the basic OAuth 2.1 for public clients using PKCE.

     

       64
       64
       +
       

     

       65
       65
       +
       ```mermaid

     

       66
       66
       +
       sequenceDiagram

     

       67
       67
       +
           participant B as User-Agent (Browser)

     

       68
       68
       +
           participant C as Client

     

       69
       69
       +
           participant M as MCP Server

     

       70
       70
       +
       

     

       71
       71
       +
           C->>M: MCP Request

     

       72
       72
       +
           M->>C: HTTP 401 Unauthorized

     

       73
       73
       +
           Note over C: Generate code_verifier and code_challenge

     

       74
       74
       +
           C->>B: Open browser with authorization URL + code_challenge

     

       75
       75
       +
           B->>M: GET /authorize

     

       76
       76
       +
           Note over M: User logs in and authorizes

     

       77
       77
       +
           M->>B: Redirect to callback URL with auth code

     

       78
       78
       +
           B->>C: Callback with authorization code

     

       79
       79
       +
           C->>M: Token Request with code + code_verifier

     

       80
       80
       +
           M->>C: Access Token (+ Refresh Token)

     

       81
       81
       +
           C->>M: MCP Request with Access Token

     

       82
       82
       +
           Note over C,M: Begin standard MCP message exchange

     

       83
       83
       +
       ```

     

       84
       84
       +
       

     

       85
       85
       +
       ### 2.3 Server Metadata Discovery

     

       86
       86
       +
       

     

       87
       87
       +
       For server capability discovery:

     

       88
       88
       +
       

     

       89
       89
       +
       - MCP clients _MUST_ follow the OAuth 2.0 Authorization Server Metadata protocol defined

     

       90
       90
       +
         in [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414).

     

       91
       91
       +
       - MCP server _SHOULD_ follow the OAuth 2.0 Authorization Server Metadata protocol.

     

       92
       92
       +
       - MCP servers that do not support the OAuth 2.0 Authorization Server Metadata protocol,

     

       93
       93
       +
         _MUST_ support fallback URLs.

     

       94
       94
       +
       

     

       95
       95
       +
       The discovery flow is illustrated below:

     

       96
       96
       +
       

     

       97
       97
       +
       ```mermaid

     

       98
       98
       +
       sequenceDiagram

     

       99
       99
       +
           participant C as Client

     

       100
       100
       +
           participant S as Server

     

       101
       101
       +
       

     

       102
       102
       +
           C->>S: GET /.well-known/oauth-authorization-server

     

       103
       103
       +
           alt Discovery Success

     

       104
       104
       +
               S->>C: 200 OK + Metadata Document

     

       105
       105
       +
               Note over C: Use endpoints from metadata

     

       106
       106
       +
           else Discovery Failed

     

       107
       107
       +
               S->>C: 404 Not Found

     

       108
       108
       +
               Note over C: Fall back to default endpoints

     

       109
       109
       +
           end

     

       110
       110
       +
           Note over C: Continue with authorization flow

     

       111
       111
       +
       ```

     

       112
       112
       +
       

     

       113
       113
       +
       #### 2.3.1 Server Metadata Discovery Headers

     

       114
       114
       +
       

     

       115
       115
       +
       MCP clients _SHOULD_ include the header `MCP-Protocol-Version: <protocol-version>` during

     

       116
       116
       +
       Server Metadata Discovery to allow the MCP server to respond based on the MCP protocol

     

       117
       117
       +
       version.

     

       118
       118
       +
       

     

       119
       119
       +
       For example: `MCP-Protocol-Version: 2024-11-05`

     

       120
       120
       +
       

     

       121
       121
       +
       #### 2.3.2 Authorization Base URL

     

       122
       122
       +
       

     

       123
       123
       +
       The authorization base URL **MUST** be determined from the MCP server URL by discarding

     

       124
       124
       +
       any existing `path` component. For example:

     

       125
       125
       +
       

     

       126
       126
       +
       If the MCP server URL is `https://api.example.com/v1/mcp`, then:

     

       127
       127
       +
       

     

       128
       128
       +
       - The authorization base URL is `https://api.example.com`

     

       129
       129
       +
       - The metadata endpoint **MUST** be at

     

       130
       130
       +
         `https://api.example.com/.well-known/oauth-authorization-server`

     

       131
       131
       +
       

     

       132
       132
       +
       This ensures authorization endpoints are consistently located at the root level of the

     

       133
       133
       +
       domain hosting the MCP server, regardless of any path components in the MCP server URL.

     

       134
       134
       +
       

     

       135
       135
       +
       #### 2.3.3 Fallbacks for Servers without Metadata Discovery

     

       136
       136
       +
       

     

       137
       137
       +
       For servers that do not implement OAuth 2.0 Authorization Server Metadata, clients

     

       138
       138
       +
       **MUST** use the following default endpoint paths relative to the authorization base URL

     

       139
       139
       +
       (as defined in [Section 2.3.2](#232-authorization-base-url)):

     

       140
       140
       +
       

     

       141
       141
       +
       | Endpoint               | Default Path | Description                          |

     

       142
       142
       +
       | ---------------------- | ------------ | ------------------------------------ |

     

       143
       143
       +
       | Authorization Endpoint | /authorize   | Used for authorization requests      |

     

       144
       144
       +
       | Token Endpoint         | /token       | Used for token exchange & refresh    |

     

       145
       145
       +
       | Registration Endpoint  | /register    | Used for dynamic client registration |

     

       146
       146
       +
       

     

       147
       147
       +
       For example, with an MCP server hosted at `https://api.example.com/v1/mcp`, the default

     

       148
       148
       +
       endpoints would be:

     

       149
       149
       +
       

     

       150
       150
       +
       - `https://api.example.com/authorize`

     

       151
       151
       +
       - `https://api.example.com/token`

     

       152
       152
       +
       - `https://api.example.com/register`

     

       153
       153
       +
       

     

       154
       154
       +
       Clients **MUST** first attempt to discover endpoints via the metadata document before

     

       155
       155
       +
       falling back to default paths. When using default paths, all other protocol requirements

     

       156
       156
       +
       remain unchanged.

     

       157
       157
       +
       

     

       158
       158
       +
       ### 2.3 Dynamic Client Registration

     

       159
       159
       +
       

     

       160
       160
       +
       MCP clients and servers **SHOULD** support the

     

       161
       161
       +
       [OAuth 2.0 Dynamic Client Registration Protocol](https://datatracker.ietf.org/doc/html/rfc7591)

     

       162
       162
       +
       to allow MCP clients to obtain OAuth client IDs without user interaction. This provides a

     

       163
       163
       +
       standardized way for clients to automatically register with new servers, which is crucial

     

       164
       164
       +
       for MCP because:

     

       165
       165
       +
       

     

       166
       166
       +
       - Clients cannot know all possible servers in advance

     

       167
       167
       +
       - Manual registration would create friction for users

     

       168
       168
       +
       - It enables seamless connection to new servers

     

       169
       169
       +
       - Servers can implement their own registration policies

     

       170
       170
       +
       

     

       171
       171
       +
       Any MCP servers that _do not_ support Dynamic Client Registration need to provide

     

       172
       172
       +
       alternative ways to obtain a client ID (and, if applicable, client secret). For one of

     

       173
       173
       +
       these servers, MCP clients will have to either:

     

       174
       174
       +
       

     

       175
       175
       +
       1. Hardcode a client ID (and, if applicable, client secret) specifically for that MCP

     

       176
       176
       +
          server, or

     

       177
       177
       +
       2. Present a UI to users that allows them to enter these details, after registering an

     

       178
       178
       +
          OAuth client themselves (e.g., through a configuration interface hosted by the

     

       179
       179
       +
          server).

     

       180
       180
       +
       

     

       181
       181
       +
       ### 2.4 Authorization Flow Steps

     

       182
       182
       +
       

     

       183
       183
       +
       The complete Authorization flow proceeds as follows:

     

       184
       184
       +
       

     

       185
       185
       +
       ```mermaid

     

       186
       186
       +
       sequenceDiagram

     

       187
       187
       +
           participant B as User-Agent (Browser)

     

       188
       188
       +
           participant C as Client

     

       189
       189
       +
           participant M as MCP Server

     

       190
       190
       +
       

     

       191
       191
       +
           C->>M: GET /.well-known/oauth-authorization-server

     

       192
       192
       +
           alt Server Supports Discovery

     

       193
       193
       +
               M->>C: Authorization Server Metadata

     

       194
       194
       +
           else No Discovery

     

       195
       195
       +
               M->>C: 404 (Use default endpoints)

     

       196
       196
       +
           end

     

       197
       197
       +
       

     

       198
       198
       +
           alt Dynamic Client Registration

     

       199
       199
       +
               C->>M: POST /register

     

       200
       200
       +
               M->>C: Client Credentials

     

       201
       201
       +
           end

     

       202
       202
       +
       

     

       203
       203
       +
           Note over C: Generate PKCE Parameters

     

       204
       204
       +
           C->>B: Open browser with authorization URL + code_challenge

     

       205
       205
       +
           B->>M: Authorization Request

     

       206
       206
       +
           Note over M: User /authorizes

     

       207
       207
       +
           M->>B: Redirect to callback with authorization code

     

       208
       208
       +
           B->>C: Authorization code callback

     

       209
       209
       +
           C->>M: Token Request + code_verifier

     

       210
       210
       +
           M->>C: Access Token (+ Refresh Token)

     

       211
       211
       +
           C->>M: API Requests with Access Token

     

       212
       212
       +
       ```

     

       213
       213
       +
       

     

       214
       214
       +
       #### 2.4.1 Decision Flow Overview

     

       215
       215
       +
       

     

       216
       216
       +
       ```mermaid

     

       217
       217
       +
       flowchart TD

     

       218
       218
       +
           A[Start Auth Flow] --> B{Check Metadata Discovery}

     

       219
       219
       +
           B -->|Available| C[Use Metadata Endpoints]

     

       220
       220
       +
           B -->|Not Available| D[Use Default Endpoints]

     

       221
       221
       +
       

     

       222
       222
       +
           C --> G{Check Registration Endpoint}

     

       223
       223
       +
           D --> G

     

       224
       224
       +
       

     

       225
       225
       +
           G -->|Available| H[Perform Dynamic Registration]

     

       226
       226
       +
           G -->|Not Available| I[Alternative Registration Required]

     

       227
       227
       +
       

     

       228
       228
       +
           H --> J[Start OAuth Flow]

     

       229
       229
       +
           I --> J

     

       230
       230
       +
       

     

       231
       231
       +
           J --> K[Generate PKCE Parameters]

     

       232
       232
       +
           K --> L[Request Authorization]

     

       233
       233
       +
           L --> M[User Authorization]

     

       234
       234
       +
           M --> N[Exchange Code for Tokens]

     

       235
       235
       +
           N --> O[Use Access Token]

     

       236
       236
       +
       ```

     

       237
       237
       +
       

     

       238
       238
       +
       ### 2.5 Access Token Usage

     

       239
       239
       +
       

     

       240
       240
       +
       #### 2.5.1 Token Requirements

     

       241
       241
       +
       

     

       242
       242
       +
       Access token handling **MUST** conform to

     

       243
       243
       +
       [OAuth 2.1 Section 5](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5)

     

       244
       244
       +
       requirements for resource requests. Specifically:

     

       245
       245
       +
       

     

       246
       246
       +
       1. MCP client **MUST** use the Authorization request header field

     

       247
       247
       +
          [Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.1.1):

     

       248
       248
       +
       

     

       249
       249
       +
       ```

     

       250
       250
       +
       Authorization: Bearer <access-token>

     

       251
       251
       +
       ```

     

       252
       252
       +
       

     

       253
       253
       +
       Note that authorization **MUST** be included in every HTTP request from client to server,

     

       254
       254
       +
       even if they are part of the same logical session.

     

       255
       255
       +
       

     

       256
       256
       +
       2. Access tokens **MUST NOT** be included in the URI query string

     

       257
       257
       +
       

     

       258
       258
       +
       Example request:

     

       259
       259
       +
       

     

       260
       260
       +
       ```http

     

       261
       261
       +
       GET /v1/contexts HTTP/1.1

     

       262
       262
       +
       Host: mcp.example.com

     

       263
       263
       +
       Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

     

       264
       264
       +
       ```

     

       265
       265
       +
       

     

       266
       266
       +
       #### 2.5.2 Token Handling

     

       267
       267
       +
       

     

       268
       268
       +
       Resource servers **MUST** validate access tokens as described in

     

       269
       269
       +
       [Section 5.2](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.2).

     

       270
       270
       +
       If validation fails, servers **MUST** respond according to

     

       271
       271
       +
       [Section 5.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.3)

     

       272
       272
       +
       error handling requirements. Invalid or expired tokens **MUST** receive a HTTP 401

     

       273
       273
       +
       response.

     

       274
       274
       +
       

     

       275
       275
       +
       ### 2.6 Security Considerations

     

       276
       276
       +
       

     

       277
       277
       +
       The following security requirements **MUST** be implemented:

     

       278
       278
       +
       

     

       279
       279
       +
       1. Clients **MUST** securely store tokens following OAuth 2.0 best practices

     

       280
       280
       +
       2. Servers **SHOULD** enforce token expiration and rotation

     

       281
       281
       +
       3. All authorization endpoints **MUST** be served over HTTPS

     

       282
       282
       +
       4. Servers **MUST** validate redirect URIs to prevent open redirect vulnerabilities

     

       283
       283
       +
       5. Redirect URIs **MUST** be either localhost URLs or HTTPS URLs

     

       284
       284
       +
       

     

       285
       285
       +
       ### 2.7 Error Handling

     

       286
       286
       +
       

     

       287
       287
       +
       Servers **MUST** return appropriate HTTP status codes for authorization errors:

     

       288
       288
       +
       

     

       289
       289
       +
       | Status Code | Description  | Usage                                      |

     

       290
       290
       +
       | ----------- | ------------ | ------------------------------------------ |

     

       291
       291
       +
       | 401         | Unauthorized | Authorization required or token invalid    |

     

       292
       292
       +
       | 403         | Forbidden    | Invalid scopes or insufficient permissions |

     

       293
       293
       +
       | 400         | Bad Request  | Malformed authorization request            |

     

       294
       294
       +
       

     

       295
       295
       +
       ### 2.8 Implementation Requirements

     

       296
       296
       +
       

     

       297
       297
       +
       1. Implementations **MUST** follow OAuth 2.1 security best practices

     

       298
       298
       +
       2. PKCE is **REQUIRED** for all clients

     

       299
       299
       +
       3. Token rotation **SHOULD** be implemented for enhanced security

     

       300
       300
       +
       4. Token lifetimes **SHOULD** be limited based on security requirements

     

       301
       301
       +
       

     

       302
       302
       +
       ### 2.9 Third-Party Authorization Flow

     

       303
       303
       +
       

     

       304
       304
       +
       #### 2.9.1 Overview

     

       305
       305
       +
       

     

       306
       306
       +
       MCP servers **MAY** support delegated authorization through third-party authorization

     

       307
       307
       +
       servers. In this flow, the MCP server acts as both an OAuth client (to the third-party

     

       308
       308
       +
       auth server) and an OAuth authorization server (to the MCP client).

     

       309
       309
       +
       

     

       310
       310
       +
       #### 2.9.2 Flow Description

     

       311
       311
       +
       

     

       312
       312
       +
       The third-party authorization flow comprises these steps:

     

       313
       313
       +
       

     

       314
       314
       +
       1. MCP client initiates standard OAuth flow with MCP server

     

       315
       315
       +
       2. MCP server redirects user to third-party authorization server

     

       316
       316
       +
       3. User authorizes with third-party server

     

       317
       317
       +
       4. Third-party server redirects back to MCP server with authorization code

     

       318
       318
       +
       5. MCP server exchanges code for third-party access token

     

       319
       319
       +
       6. MCP server generates its own access token bound to the third-party session

     

       320
       320
       +
       7. MCP server completes original OAuth flow with MCP client

     

       321
       321
       +
       

     

       322
       322
       +
       ```mermaid

     

       323
       323
       +
       sequenceDiagram

     

       324
       324
       +
           participant B as User-Agent (Browser)

     

       325
       325
       +
           participant C as MCP Client

     

       326
       326
       +
           participant M as MCP Server

     

       327
       327
       +
           participant T as Third-Party Auth Server

     

       328
       328
       +
       

     

       329
       329
       +
           C->>M: Initial OAuth Request

     

       330
       330
       +
           M->>B: Redirect to Third-Party /authorize

     

       331
       331
       +
           B->>T: Authorization Request

     

       332
       332
       +
           Note over T: User authorizes

     

       333
       333
       +
           T->>B: Redirect to MCP Server callback

     

       334
       334
       +
           B->>M: Authorization code

     

       335
       335
       +
           M->>T: Exchange code for token

     

       336
       336
       +
           T->>M: Third-party access token

     

       337
       337
       +
           Note over M: Generate bound MCP token

     

       338
       338
       +
           M->>B: Redirect to MCP Client callback

     

       339
       339
       +
           B->>C: MCP authorization code

     

       340
       340
       +
           C->>M: Exchange code for token

     

       341
       341
       +
           M->>C: MCP access token

     

       342
       342
       +
       ```

     

       343
       343
       +
       

     

       344
       344
       +
       #### 2.9.3 Session Binding Requirements

     

       345
       345
       +
       

     

       346
       346
       +
       MCP servers implementing third-party authorization **MUST**:

     

       347
       347
       +
       

     

       348
       348
       +
       1. Maintain secure mapping between third-party tokens and issued MCP tokens

     

       349
       349
       +
       2. Validate third-party token status before honoring MCP tokens

     

       350
       350
       +
       3. Implement appropriate token lifecycle management

     

       351
       351
       +
       4. Handle third-party token expiration and renewal

     

       352
       352
       +
       

     

       353
       353
       +
       #### 2.9.4 Security Considerations

     

       354
       354
       +
       

     

       355
       355
       +
       When implementing third-party authorization, servers **MUST**:

     

       356
       356
       +
       

     

       357
       357
       +
       1. Validate all redirect URIs

     

       358
       358
       +
       2. Securely store third-party credentials

     

       359
       359
       +
       3. Implement appropriate session timeout handling

     

       360
       360
       +
       4. Consider security implications of token chaining

     

       361
       361
       +
       5. Implement proper error handling for third-party auth failures

     

       362
       362
       +
       

     

       363
       363
       +
       ## 3. Best Practices

     

       364
       364
       +
       

     

       365
       365
       +
       #### 3.1 Local clients as Public OAuth 2.1 Clients

     

       366
       366
       +
       

     

       367
       367
       +
       We strongly recommend that local clients implement OAuth 2.1 as a public client:

     

       368
       368
       +
       

     

       369
       369
       +
       1. Utilizing code challenges (PKCE) for authorization requests to prevent interception

     

       370
       370
       +
          attacks

     

       371
       371
       +
       2. Implementing secure token storage appropriate for the local system

     

       372
       372
       +
       3. Following token refresh best practices to maintain sessions

     

       373
       373
       +
       4. Properly handling token expiration and renewal

     

       374
       374
       +
       

     

       375
       375
       +
       #### 3.2 Authorization Metadata Discovery

     

       376
       376
       +
       

     

       377
       377
       +
       We strongly recommend that all clients implement metadata discovery. This reduces the

     

       378
       378
       +
       need for users to provide endpoints manually or clients to fallback to the defined

     

       379
       379
       +
       defaults.

     

       380
       380
       +
       

     

       381
       381
       +
       #### 3.3 Dynamic Client Registration

     

       382
       382
       +
       

     

       383
       383
       +
       Since clients do not know the set of MCP servers in advance, we strongly recommend the

     

       384
       384
       +
       implementation of dynamic client registration. This allows applications to automatically

     

       385
       385
       +
       register with the MCP server, and removes the need for users to obtain client ids

     

       386
       386
       +
       manually.

+239

spec/lifecycle.md

···

       1
       1
       +
       ---

     

       2
       2
       +
       title: Lifecycle

     

       3
       3
       +
       type: docs

     

       4
       4
       +
       weight: 30

     

       5
       5
       +
       ---

     

       6
       6
       +
       

     

       7
       7
       +
       {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}

     

       8
       8
       +
       

     

       9
       9
       +
       The Model Context Protocol (MCP) defines a rigorous lifecycle for client-server

     

       10
       10
       +
       connections that ensures proper capability negotiation and state management.

     

       11
       11
       +
       

     

       12
       12
       +
       1. **Initialization**: Capability negotiation and protocol version agreement

     

       13
       13
       +
       2. **Operation**: Normal protocol communication

     

       14
       14
       +
       3. **Shutdown**: Graceful termination of the connection

     

       15
       15
       +
       

     

       16
       16
       +
       ```mermaid

     

       17
       17
       +
       sequenceDiagram

     

       18
       18
       +
           participant Client

     

       19
       19
       +
           participant Server

     

       20
       20
       +
       

     

       21
       21
       +
           Note over Client,Server: Initialization Phase

     

       22
       22
       +
           activate Client

     

       23
       23
       +
           Client->>+Server: initialize request

     

       24
       24
       +
           Server-->>Client: initialize response

     

       25
       25
       +
           Client--)Server: initialized notification

     

       26
       26
       +
       

     

       27
       27
       +
           Note over Client,Server: Operation Phase

     

       28
       28
       +
           rect rgb(200, 220, 250)

     

       29
       29
       +
               note over Client,Server: Normal protocol operations

     

       30
       30
       +
           end

     

       31
       31
       +
       

     

       32
       32
       +
           Note over Client,Server: Shutdown

     

       33
       33
       +
           Client--)-Server: Disconnect

     

       34
       34
       +
           deactivate Server

     

       35
       35
       +
           Note over Client,Server: Connection closed

     

       36
       36
       +
       ```

     

       37
       37
       +
       

     

       38
       38
       +
       ## Lifecycle Phases

     

       39
       39
       +
       

     

       40
       40
       +
       ### Initialization

     

       41
       41
       +
       

     

       42
       42
       +
       The initialization phase **MUST** be the first interaction between client and server.

     

       43
       43
       +
       During this phase, the client and server:

     

       44
       44
       +
       

     

       45
       45
       +
       - Establish protocol version compatibility

     

       46
       46
       +
       - Exchange and negotiate capabilities

     

       47
       47
       +
       - Share implementation details

     

       48
       48
       +
       

     

       49
       49
       +
       The client **MUST** initiate this phase by sending an `initialize` request containing:

     

       50
       50
       +
       

     

       51
       51
       +
       - Protocol version supported

     

       52
       52
       +
       - Client capabilities

     

       53
       53
       +
       - Client implementation information

     

       54
       54
       +
       

     

       55
       55
       +
       ```json

     

       56
       56
       +
       {

     

       57
       57
       +
         "jsonrpc": "2.0",

     

       58
       58
       +
         "id": 1,

     

       59
       59
       +
         "method": "initialize",

     

       60
       60
       +
         "params": {

     

       61
       61
       +
           "protocolVersion": "2024-11-05",

     

       62
       62
       +
           "capabilities": {

     

       63
       63
       +
             "roots": {

     

       64
       64
       +
               "listChanged": true

     

       65
       65
       +
             },

     

       66
       66
       +
             "sampling": {}

     

       67
       67
       +
           },

     

       68
       68
       +
           "clientInfo": {

     

       69
       69
       +
             "name": "ExampleClient",

     

       70
       70
       +
             "version": "1.0.0"

     

       71
       71
       +
           }

     

       72
       72
       +
         }

     

       73
       73
       +
       }

     

       74
       74
       +
       ```

     

       75
       75
       +
       

     

       76
       76
       +
       The initialize request **MUST NOT** be part of a JSON-RPC

     

       77
       77
       +
       [batch](https://www.jsonrpc.org/specification#batch), as other requests and notifications

     

       78
       78
       +
       are not possible until initialization has completed. This also permits backwards

     

       79
       79
       +
       compatibility with prior protocol versions that do not explicitly support JSON-RPC

     

       80
       80
       +
       batches.

     

       81
       81
       +
       

     

       82
       82
       +
       The server **MUST** respond with its own capabilities and information:

     

       83
       83
       +
       

     

       84
       84
       +
       ```json

     

       85
       85
       +
       {

     

       86
       86
       +
         "jsonrpc": "2.0",

     

       87
       87
       +
         "id": 1,

     

       88
       88
       +
         "result": {

     

       89
       89
       +
           "protocolVersion": "2024-11-05",

     

       90
       90
       +
           "capabilities": {

     

       91
       91
       +
             "logging": {},

     

       92
       92
       +
             "prompts": {

     

       93
       93
       +
               "listChanged": true

     

       94
       94
       +
             },

     

       95
       95
       +
             "resources": {

     

       96
       96
       +
               "subscribe": true,

     

       97
       97
       +
               "listChanged": true

     

       98
       98
       +
             },

     

       99
       99
       +
             "tools": {

     

       100
       100
       +
               "listChanged": true

     

       101
       101
       +
             }

     

       102
       102
       +
           },

     

       103
       103
       +
           "serverInfo": {

     

       104
       104
       +
             "name": "ExampleServer",

     

       105
       105
       +
             "version": "1.0.0"

     

       106
       106
       +
           }

     

       107
       107
       +
         }

     

       108
       108
       +
       }

     

       109
       109
       +
       ```

     

       110
       110
       +
       

     

       111
       111
       +
       After successful initialization, the client **MUST** send an `initialized` notification

     

       112
       112
       +
       to indicate it is ready to begin normal operations:

     

       113
       113
       +
       

     

       114
       114
       +
       ```json

     

       115
       115
       +
       {

     

       116
       116
       +
         "jsonrpc": "2.0",

     

       117
       117
       +
         "method": "notifications/initialized"

     

       118
       118
       +
       }

     

       119
       119
       +
       ```

     

       120
       120
       +
       

     

       121
       121
       +
       - The client **SHOULD NOT** send requests other than

     

       122
       122
       +
         [pings]({{< ref "utilities/ping" >}}) before the server has responded to the

     

       123
       123
       +
         `initialize` request.

     

       124
       124
       +
       - The server **SHOULD NOT** send requests other than

     

       125
       125
       +
         [pings]({{< ref "utilities/ping" >}}) and

     

       126
       126
       +
         [logging]({{< ref "../server/utilities/logging" >}}) before receiving the `initialized`

     

       127
       127
       +
         notification.

     

       128
       128
       +
       

     

       129
       129
       +
       #### Version Negotiation

     

       130
       130
       +
       

     

       131
       131
       +
       In the `initialize` request, the client **MUST** send a protocol version it supports.

     

       132
       132
       +
       This **SHOULD** be the _latest_ version supported by the client.

     

       133
       133
       +
       

     

       134
       134
       +
       If the server supports the requested protocol version, it **MUST** respond with the same

     

       135
       135
       +
       version. Otherwise, the server **MUST** respond with another protocol version it

     

       136
       136
       +
       supports. This **SHOULD** be the _latest_ version supported by the server.

     

       137
       137
       +
       

     

       138
       138
       +
       If the client does not support the version in the server's response, it **SHOULD**

     

       139
       139
       +
       disconnect.

     

       140
       140
       +
       

     

       141
       141
       +
       #### Capability Negotiation

     

       142
       142
       +
       

     

       143
       143
       +
       Client and server capabilities establish which optional protocol features will be

     

       144
       144
       +
       available during the session.

     

       145
       145
       +
       

     

       146
       146
       +
       Key capabilities include:

     

       147
       147
       +
       

     

       148
       148
       +
       | Category | Capability     | Description                                                                |

     

       149
       149
       +
       | -------- | -------------- | -------------------------------------------------------------------------- |

     

       150
       150
       +
       | Client   | `roots`        | Ability to provide filesystem [roots]({{< ref "../client/roots" >}})       |

     

       151
       151
       +
       | Client   | `sampling`     | Support for LLM [sampling]({{< ref "../client/sampling" >}}) requests      |

     

       152
       152
       +
       | Client   | `experimental` | Describes support for non-standard experimental features                   |

     

       153
       153
       +
       | Server   | `prompts`      | Offers [prompt templates]({{< ref "../server/prompts" >}})                 |

     

       154
       154
       +
       | Server   | `resources`    | Provides readable [resources]({{< ref "../server/resources" >}})           |

     

       155
       155
       +
       | Server   | `tools`        | Exposes callable [tools]({{< ref "../server/tools" >}})                    |

     

       156
       156
       +
       | Server   | `logging`      | Emits structured [log messages]({{< ref "../server/utilities/logging" >}}) |

     

       157
       157
       +
       | Server   | `experimental` | Describes support for non-standard experimental features                   |

     

       158
       158
       +
       

     

       159
       159
       +
       Capability objects can describe sub-capabilities like:

     

       160
       160
       +
       

     

       161
       161
       +
       - `listChanged`: Support for list change notifications (for prompts, resources, and

     

       162
       162
       +
         tools)

     

       163
       163
       +
       - `subscribe`: Support for subscribing to individual items' changes (resources only)

     

       164
       164
       +
       

     

       165
       165
       +
       ### Operation

     

       166
       166
       +
       

     

       167
       167
       +
       During the operation phase, the client and server exchange messages according to the

     

       168
       168
       +
       negotiated capabilities.

     

       169
       169
       +
       

     

       170
       170
       +
       Both parties **SHOULD**:

     

       171
       171
       +
       

     

       172
       172
       +
       - Respect the negotiated protocol version

     

       173
       173
       +
       - Only use capabilities that were successfully negotiated

     

       174
       174
       +
       

     

       175
       175
       +
       ### Shutdown

     

       176
       176
       +
       

     

       177
       177
       +
       During the shutdown phase, one side (usually the client) cleanly terminates the protocol

     

       178
       178
       +
       connection. No specific shutdown messages are defined—instead, the underlying transport

     

       179
       179
       +
       mechanism should be used to signal connection termination:

     

       180
       180
       +
       

     

       181
       181
       +
       #### stdio

     

       182
       182
       +
       

     

       183
       183
       +
       For the stdio [transport]({{< ref "transports" >}}), the client **SHOULD** initiate

     

       184
       184
       +
       shutdown by:

     

       185
       185
       +
       

     

       186
       186
       +
       1. First, closing the input stream to the child process (the server)

     

       187
       187
       +
       2. Waiting for the server to exit, or sending `SIGTERM` if the server does not exit

     

       188
       188
       +
          within a reasonable time

     

       189
       189
       +
       3. Sending `SIGKILL` if the server does not exit within a reasonable time after `SIGTERM`

     

       190
       190
       +
       

     

       191
       191
       +
       The server **MAY** initiate shutdown by closing its output stream to the client and

     

       192
       192
       +
       exiting.

     

       193
       193
       +
       

     

       194
       194
       +
       #### HTTP

     

       195
       195
       +
       

     

       196
       196
       +
       For HTTP [transports]({{< ref "transports" >}}), shutdown is indicated by closing the

     

       197
       197
       +
       associated HTTP connection(s).

     

       198
       198
       +
       

     

       199
       199
       +
       ## Timeouts

     

       200
       200
       +
       

     

       201
       201
       +
       Implementations **SHOULD** establish timeouts for all sent requests, to prevent hung

     

       202
       202
       +
       connections and resource exhaustion. When the request has not received a success or error

     

       203
       203
       +
       response within the timeout period, the sender **SHOULD** issue a [cancellation

     

       204
       204
       +
       notification]({{< ref "utilities/cancellation" >}}) for that request and stop waiting for

     

       205
       205
       +
       a response.

     

       206
       206
       +
       

     

       207
       207
       +
       SDKs and other middleware **SHOULD** allow these timeouts to be configured on a

     

       208
       208
       +
       per-request basis.

     

       209
       209
       +
       

     

       210
       210
       +
       Implementations **MAY** choose to reset the timeout clock when receiving a [progress

     

       211
       211
       +
       notification]({{< ref "utilities/progress" >}}) corresponding to the request, as this

     

       212
       212
       +
       implies that work is actually happening. However, implementations **SHOULD** always

     

       213
       213
       +
       enforce a maximum timeout, regardless of progress notifications, to limit the impact of a

     

       214
       214
       +
       misbehaving client or server.

     

       215
       215
       +
       

     

       216
       216
       +
       ## Error Handling

     

       217
       217
       +
       

     

       218
       218
       +
       Implementations **SHOULD** be prepared to handle these error cases:

     

       219
       219
       +
       

     

       220
       220
       +
       - Protocol version mismatch

     

       221
       221
       +
       - Failure to negotiate required capabilities

     

       222
       222
       +
       - Request [timeouts](#timeouts)

     

       223
       223
       +
       

     

       224
       224
       +
       Example initialization error:

     

       225
       225
       +
       

     

       226
       226
       +
       ```json

     

       227
       227
       +
       {

     

       228
       228
       +
         "jsonrpc": "2.0",

     

       229
       229
       +
         "id": 1,

     

       230
       230
       +
         "error": {

     

       231
       231
       +
           "code": -32602,

     

       232
       232
       +
           "message": "Unsupported protocol version",

     

       233
       233
       +
           "data": {

     

       234
       234
       +
             "supported": ["2024-11-05"],

     

       235
       235
       +
             "requested": "1.0.0"

     

       236
       236
       +
           }

     

       237
       237
       +
         }

     

       238
       238
       +
       }

     

       239
       239
       +
       ```

+265

spec/prompts.md

···

       1
       1
       +
       ---

     

       2
       2
       +
       title: Prompts

     

       3
       3
       +
       weight: 10

     

       4
       4
       +
       ---

     

       5
       5
       +
       

     

       6
       6
       +
       {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}

     

       7
       7
       +
       

     

       8
       8
       +
       The Model Context Protocol (MCP) provides a standardized way for servers to expose prompt

     

       9
       9
       +
       templates to clients. Prompts allow servers to provide structured messages and

     

       10
       10
       +
       instructions for interacting with language models. Clients can discover available

     

       11
       11
       +
       prompts, retrieve their contents, and provide arguments to customize them.

     

       12
       12
       +
       

     

       13
       13
       +
       ## User Interaction Model

     

       14
       14
       +
       

     

       15
       15
       +
       Prompts are designed to be **user-controlled**, meaning they are exposed from servers to

     

       16
       16
       +
       clients with the intention of the user being able to explicitly select them for use.

     

       17
       17
       +
       

     

       18
       18
       +
       Typically, prompts would be triggered through user-initiated commands in the user

     

       19
       19
       +
       interface, which allows users to naturally discover and invoke available prompts.

     

       20
       20
       +
       

     

       21
       21
       +
       For example, as slash commands:

     

       22
       22
       +
       

     

       23
       23
       +
       ![Example of prompt exposed as slash command](slash-command.png)

     

       24
       24
       +
       

     

       25
       25
       +
       However, implementors are free to expose prompts through any interface pattern that suits

     

       26
       26
       +
       their needs&mdash;the protocol itself does not mandate any specific user interaction

     

       27
       27
       +
       model.

     

       28
       28
       +
       

     

       29
       29
       +
       ## Capabilities

     

       30
       30
       +
       

     

       31
       31
       +
       Servers that support prompts **MUST** declare the `prompts` capability during

     

       32
       32
       +
       [initialization]({{< ref "../basic/lifecycle#initialization" >}}):

     

       33
       33
       +
       

     

       34
       34
       +
       /draft`json { "capabilities": { "prompts": { "listChanged": true } } }

     

       35
       35
       +
       

     

       36
       36
       +
       ````

     

       37
       37
       +
       

     

       38
       38
       +
       `listChanged` indicates whether the server will emit notifications when the list of

     

       39
       39
       +
       available prompts changes.

     

       40
       40
       +
       

     

       41
       41
       +
       ## Protocol Messages

     

       42
       42
       +
       

     

       43
       43
       +
       ### Listing Prompts

     

       44
       44
       +
       

     

       45
       45
       +
       To retrieve available prompts, clients send a `prompts/list` request. This operation

     

       46
       46
       +
       supports [pagination]({{< ref "utilities/pagination" >}}).

     

       47
       47
       +
       

     

       48
       48
       +
       **Request:**

     

       49
       49
       +
       

     

       50
       50
       +
       ```json

     

       51
       51
       +
       {

     

       52
       52
       +
         "jsonrpc": "2.0",

     

       53
       53
       +
         "id": 1,

     

       54
       54
       +
         "method": "prompts/list",

     

       55
       55
       +
         "params": {

     

       56
       56
       +
           "cursor": "optional-cursor-value"

     

       57
       57
       +
         }

     

       58
       58
       +
       }

     

       59
       59
       +
       ````

     

       60
       60
       +
       

     

       61
       61
       +
       **Response:**

     

       62
       62
       +
       

     

       63
       63
       +
       ```json

     

       64
       64
       +
       {

     

       65
       65
       +
         "jsonrpc": "2.0",

     

       66
       66
       +
         "id": 1,

     

       67
       67
       +
         "result": {

     

       68
       68
       +
           "prompts": [

     

       69
       69
       +
             {

     

       70
       70
       +
               "name": "code_review",

     

       71
       71
       +
               "description": "Asks the LLM to analyze code quality and suggest improvements",

     

       72
       72
       +
               "arguments": [

     

       73
       73
       +
                 {

     

       74
       74
       +
                   "name": "code",

     

       75
       75
       +
                   "description": "The code to review",

     

       76
       76
       +
                   "required": true

     

       77
       77
       +
                 }

     

       78
       78
       +
               ]

     

       79
       79
       +
             }

     

       80
       80
       +
           ],

     

       81
       81
       +
           "nextCursor": "next-page-cursor"

     

       82
       82
       +
         }

     

       83
       83
       +
       }

     

       84
       84
       +
       ```

     

       85
       85
       +
       

     

       86
       86
       +
       ### Getting a Prompt

     

       87
       87
       +
       

     

       88
       88
       +
       To retrieve a specific prompt, clients send a `prompts/get` request. Arguments may be

     

       89
       89
       +
       auto-completed through [the completion API]({{< ref "utilities/completion" >}}).

     

       90
       90
       +
       

     

       91
       91
       +
       **Request:**

     

       92
       92
       +
       

     

       93
       93
       +
       ```json

     

       94
       94
       +
       {

     

       95
       95
       +
         "jsonrpc": "2.0",

     

       96
       96
       +
         "id": 2,

     

       97
       97
       +
         "method": "prompts/get",

     

       98
       98
       +
         "params": {

     

       99
       99
       +
           "name": "code_review",

     

       100
       100
       +
           "arguments": {

     

       101
       101
       +
             "code": "def hello():\n    print('world')"

     

       102
       102
       +
           }

     

       103
       103
       +
         }

     

       104
       104
       +
       }

     

       105
       105
       +
       ```

     

       106
       106
       +
       

     

       107
       107
       +
       **Response:**

     

       108
       108
       +
       

     

       109
       109
       +
       ```json

     

       110
       110
       +
       {

     

       111
       111
       +
         "jsonrpc": "2.0",

     

       112
       112
       +
         "id": 2,

     

       113
       113
       +
         "result": {

     

       114
       114
       +
           "description": "Code review prompt",

     

       115
       115
       +
           "messages": [

     

       116
       116
       +
             {

     

       117
       117
       +
               "role": "user",

     

       118
       118
       +
               "content": {

     

       119
       119
       +
                 "type": "text",

     

       120
       120
       +
                 "text": "Please review this Python code:\ndef hello():\n    print('world')"

     

       121
       121
       +
               }

     

       122
       122
       +
             }

     

       123
       123
       +
           ]

     

       124
       124
       +
         }

     

       125
       125
       +
       }

     

       126
       126
       +
       ```

     

       127
       127
       +
       

     

       128
       128
       +
       ### List Changed Notification

     

       129
       129
       +
       

     

       130
       130
       +
       When the list of available prompts changes, servers that declared the `listChanged`

     

       131
       131
       +
       capability **SHOULD** send a notification:

     

       132
       132
       +
       

     

       133
       133
       +
       ```json

     

       134
       134
       +
       {

     

       135
       135
       +
         "jsonrpc": "2.0",

     

       136
       136
       +
         "method": "notifications/prompts/list_changed"

     

       137
       137
       +
       }

     

       138
       138
       +
       ```

     

       139
       139
       +
       

     

       140
       140
       +
       ## Message Flow

     

       141
       141
       +
       

     

       142
       142
       +
       ```mermaid

     

       143
       143
       +
       sequenceDiagram

     

       144
       144
       +
           participant Client

     

       145
       145
       +
           participant Server

     

       146
       146
       +
       

     

       147
       147
       +
           Note over Client,Server: Discovery

     

       148
       148
       +
           Client->>Server: prompts/list

     

       149
       149
       +
           Server-->>Client: List of prompts

     

       150
       150
       +
       

     

       151
       151
       +
           Note over Client,Server: Usage

     

       152
       152
       +
           Client->>Server: prompts/get

     

       153
       153
       +
           Server-->>Client: Prompt content

     

       154
       154
       +
       

     

       155
       155
       +
           opt listChanged

     

       156
       156
       +
             Note over Client,Server: Changes

     

       157
       157
       +
             Server--)Client: prompts/list_changed

     

       158
       158
       +
             Client->>Server: prompts/list

     

       159
       159
       +
             Server-->>Client: Updated prompts

     

       160
       160
       +
           end

     

       161
       161
       +
       ```

     

       162
       162
       +
       

     

       163
       163
       +
       ## Data Types

     

       164
       164
       +
       

     

       165
       165
       +
       ### Prompt

     

       166
       166
       +
       

     

       167
       167
       +
       A prompt definition includes:

     

       168
       168
       +
       

     

       169
       169
       +
       - `name`: Unique identifier for the prompt

     

       170
       170
       +
       - `description`: Optional human-readable description

     

       171
       171
       +
       - `arguments`: Optional list of arguments for customization

     

       172
       172
       +
       

     

       173
       173
       +
       ### PromptMessage

     

       174
       174
       +
       

     

       175
       175
       +
       Messages in a prompt can contain:

     

       176
       176
       +
       

     

       177
       177
       +
       - `role`: Either "user" or "assistant" to indicate the speaker

     

       178
       178
       +
       - `content`: One of the following content types:

     

       179
       179
       +
       

     

       180
       180
       +
       #### Text Content

     

       181
       181
       +
       

     

       182
       182
       +
       Text content represents plain text messages:

     

       183
       183
       +
       

     

       184
       184
       +
       ```json

     

       185
       185
       +
       {

     

       186
       186
       +
         "type": "text",

     

       187
       187
       +
         "text": "The text content of the message"

     

       188
       188
       +
       }

     

       189
       189
       +
       ```

     

       190
       190
       +
       

     

       191
       191
       +
       This is the most common content type used for natural language interactions.

     

       192
       192
       +
       

     

       193
       193
       +
       #### Image Content

     

       194
       194
       +
       

     

       195
       195
       +
       Image content allows including visual information in messages:

     

       196
       196
       +
       

     

       197
       197
       +
       ```json

     

       198
       198
       +
       {

     

       199
       199
       +
         "type": "image",

     

       200
       200
       +
         "data": "base64-encoded-image-data",

     

       201
       201
       +
         "mimeType": "image/png"

     

       202
       202
       +
       }

     

       203
       203
       +
       ```

     

       204
       204
       +
       

     

       205
       205
       +
       The image data **MUST** be base64-encoded and include a valid MIME type. This enables

     

       206
       206
       +
       multi-modal interactions where visual context is important.

     

       207
       207
       +
       

     

       208
       208
       +
       #### Audio Content

     

       209
       209
       +
       

     

       210
       210
       +
       Audio content allows including audio information in messages:

     

       211
       211
       +
       

     

       212
       212
       +
       ```json

     

       213
       213
       +
       {

     

       214
       214
       +
         "type": "audio",

     

       215
       215
       +
         "data": "base64-encoded-audio-data",

     

       216
       216
       +
         "mimeType": "audio/wav"

     

       217
       217
       +
       }

     

       218
       218
       +
       ```

     

       219
       219
       +
       

     

       220
       220
       +
       The audio data MUST be base64-encoded and include a valid MIME type. This enables

     

       221
       221
       +
       multi-modal interactions where audio context is important.

     

       222
       222
       +
       

     

       223
       223
       +
       #### Embedded Resources

     

       224
       224
       +
       

     

       225
       225
       +
       Embedded resources allow referencing server-side resources directly in messages:

     

       226
       226
       +
       

     

       227
       227
       +
       ```json

     

       228
       228
       +
       {

     

       229
       229
       +
         "type": "resource",

     

       230
       230
       +
         "resource": {

     

       231
       231
       +
           "uri": "resource://example",

     

       232
       232
       +
           "mimeType": "text/plain",

     

       233
       233
       +
           "text": "Resource content"

     

       234
       234
       +
         }

     

       235
       235
       +
       }

     

       236
       236
       +
       ```

     

       237
       237
       +
       

     

       238
       238
       +
       Resources can contain either text or binary (blob) data and **MUST** include:

     

       239
       239
       +
       

     

       240
       240
       +
       - A valid resource URI

     

       241
       241
       +
       - The appropriate MIME type

     

       242
       242
       +
       - Either text content or base64-encoded blob data

     

       243
       243
       +
       

     

       244
       244
       +
       Embedded resources enable prompts to seamlessly incorporate server-managed content like

     

       245
       245
       +
       documentation, code samples, or other reference materials directly into the conversation

     

       246
       246
       +
       flow.

     

       247
       247
       +
       

     

       248
       248
       +
       ## Error Handling

     

       249
       249
       +
       

     

       250
       250
       +
       Servers **SHOULD** return standard JSON-RPC errors for common failure cases:

     

       251
       251
       +
       

     

       252
       252
       +
       - Invalid prompt name: `-32602` (Invalid params)

     

       253
       253
       +
       - Missing required arguments: `-32602` (Invalid params)

     

       254
       254
       +
       - Internal errors: `-32603` (Internal error)

     

       255
       255
       +
       

     

       256
       256
       +
       ## Implementation Considerations

     

       257
       257
       +
       

     

       258
       258
       +
       1. Servers **SHOULD** validate prompt arguments before processing

     

       259
       259
       +
       2. Clients **SHOULD** handle pagination for large prompt lists

     

       260
       260
       +
       3. Both parties **SHOULD** respect capability negotiation

     

       261
       261
       +
       

     

       262
       262
       +
       ## Security

     

       263
       263
       +
       

     

       264
       264
       +
       Implementations **MUST** carefully validate all prompt inputs and outputs to prevent

     

       265
       265
       +
       injection attacks or unauthorized access to resources.

+357

spec/resources.md

···

       1
       1
       +
       ---

     

       2
       2
       +
       title: Resources

     

       3
       3
       +
       type: docs

     

       4
       4
       +
       weight: 20

     

       5
       5
       +
       ---

     

       6
       6
       +
       

     

       7
       7
       +
       {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}

     

       8
       8
       +
       

     

       9
       9
       +
       The Model Context Protocol (MCP) provides a standardized way for servers to expose

     

       10
       10
       +
       resources to clients. Resources allow servers to share data that provides context to

     

       11
       11
       +
       language models, such as files, database schemas, or application-specific information.

     

       12
       12
       +
       Each resource is uniquely identified by a

     

       13
       13
       +
       [URI](https://datatracker.ietf.org/doc/html/rfc3986).

     

       14
       14
       +
       

     

       15
       15
       +
       ## User Interaction Model

     

       16
       16
       +
       

     

       17
       17
       +
       Resources in MCP are designed to be **application-driven**, with host applications

     

       18
       18
       +
       determining how to incorporate context based on their needs.

     

       19
       19
       +
       

     

       20
       20
       +
       For example, applications could:

     

       21
       21
       +
       

     

       22
       22
       +
       - Expose resources through UI elements for explicit selection, in a tree or list view

     

       23
       23
       +
       - Allow the user to search through and filter available resources

     

       24
       24
       +
       - Implement automatic context inclusion, based on heuristics or the AI model's selection

     

       25
       25
       +
       

     

       26
       26
       +
       ![Example of resource context picker](resource-picker.png)

     

       27
       27
       +
       

     

       28
       28
       +
       However, implementations are free to expose resources through any interface pattern that

     

       29
       29
       +
       suits their needs&mdash;the protocol itself does not mandate any specific user

     

       30
       30
       +
       interaction model.

     

       31
       31
       +
       

     

       32
       32
       +
       ## Capabilities

     

       33
       33
       +
       

     

       34
       34
       +
       Servers that support resources **MUST** declare the `resources` capability:

     

       35
       35
       +
       

     

       36
       36
       +
       ```json

     

       37
       37
       +
       {

     

       38
       38
       +
         "capabilities": {

     

       39
       39
       +
           "resources": {

     

       40
       40
       +
             "subscribe": true,

     

       41
       41
       +
             "listChanged": true

     

       42
       42
       +
           }

     

       43
       43
       +
         }

     

       44
       44
       +
       }

     

       45
       45
       +
       ```

     

       46
       46
       +
       

     

       47
       47
       +
       The capability supports two optional features:

     

       48
       48
       +
       

     

       49
       49
       +
       - `subscribe`: whether the client can subscribe to be notified of changes to individual

     

       50
       50
       +
         resources.

     

       51
       51
       +
       - `listChanged`: whether the server will emit notifications when the list of available

     

       52
       52
       +
         resources changes.

     

       53
       53
       +
       

     

       54
       54
       +
       Both `subscribe` and `listChanged` are optional&mdash;servers can support neither,

     

       55
       55
       +
       either, or both:

     

       56
       56
       +
       

     

       57
       57
       +
       ```json

     

       58
       58
       +
       {

     

       59
       59
       +
         "capabilities": {

     

       60
       60
       +
           "resources": {} // Neither feature supported

     

       61
       61
       +
         }

     

       62
       62
       +
       }

     

       63
       63
       +
       ```

     

       64
       64
       +
       

     

       65
       65
       +
       ```json

     

       66
       66
       +
       {

     

       67
       67
       +
         "capabilities": {

     

       68
       68
       +
           "resources": {

     

       69
       69
       +
             "subscribe": true // Only subscriptions supported

     

       70
       70
       +
           }

     

       71
       71
       +
         }

     

       72
       72
       +
       }

     

       73
       73
       +
       ```

     

       74
       74
       +
       

     

       75
       75
       +
       ```json

     

       76
       76
       +
       {

     

       77
       77
       +
         "capabilities": {

     

       78
       78
       +
           "resources": {

     

       79
       79
       +
             "listChanged": true // Only list change notifications supported

     

       80
       80
       +
           }

     

       81
       81
       +
         }

     

       82
       82
       +
       }

     

       83
       83
       +
       ```

     

       84
       84
       +
       

     

       85
       85
       +
       ## Protocol Messages

     

       86
       86
       +
       

     

       87
       87
       +
       ### Listing Resources

     

       88
       88
       +
       

     

       89
       89
       +
       To discover available resources, clients send a `resources/list` request. This operation

     

       90
       90
       +
       supports [pagination]({{< ref "utilities/pagination" >}}).

     

       91
       91
       +
       

     

       92
       92
       +
       **Request:**

     

       93
       93
       +
       

     

       94
       94
       +
       ```json

     

       95
       95
       +
       {

     

       96
       96
       +
         "jsonrpc": "2.0",

     

       97
       97
       +
         "id": 1,

     

       98
       98
       +
         "method": "resources/list",

     

       99
       99
       +
         "params": {

     

       100
       100
       +
           "cursor": "optional-cursor-value"

     

       101
       101
       +
         }

     

       102
       102
       +
       }

     

       103
       103
       +
       ```

     

       104
       104
       +
       

     

       105
       105
       +
       **Response:**

     

       106
       106
       +
       

     

       107
       107
       +
       ```json

     

       108
       108
       +
       {

     

       109
       109
       +
         "jsonrpc": "2.0",

     

       110
       110
       +
         "id": 1,

     

       111
       111
       +
         "result": {

     

       112
       112
       +
           "resources": [

     

       113
       113
       +
             {

     

       114
       114
       +
               "uri": "file:///project/src/main.rs",

     

       115
       115
       +
               "name": "main.rs",

     

       116
       116
       +
               "description": "Primary application entry point",

     

       117
       117
       +
               "mimeType": "text/x-rust"

     

       118
       118
       +
             }

     

       119
       119
       +
           ],

     

       120
       120
       +
           "nextCursor": "next-page-cursor"

     

       121
       121
       +
         }

     

       122
       122
       +
       }

     

       123
       123
       +
       ```

     

       124
       124
       +
       

     

       125
       125
       +
       ### Reading Resources

     

       126
       126
       +
       

     

       127
       127
       +
       To retrieve resource contents, clients send a `resources/read` request:

     

       128
       128
       +
       

     

       129
       129
       +
       **Request:**

     

       130
       130
       +
       

     

       131
       131
       +
       ```json

     

       132
       132
       +
       {

     

       133
       133
       +
         "jsonrpc": "2.0",

     

       134
       134
       +
         "id": 2,

     

       135
       135
       +
         "method": "resources/read",

     

       136
       136
       +
         "params": {

     

       137
       137
       +
           "uri": "file:///project/src/main.rs"

     

       138
       138
       +
         }

     

       139
       139
       +
       }

     

       140
       140
       +
       ```

     

       141
       141
       +
       

     

       142
       142
       +
       **Response:**

     

       143
       143
       +
       

     

       144
       144
       +
       ```json

     

       145
       145
       +
       {

     

       146
       146
       +
         "jsonrpc": "2.0",

     

       147
       147
       +
         "id": 2,

     

       148
       148
       +
         "result": {

     

       149
       149
       +
           "contents": [

     

       150
       150
       +
             {

     

       151
       151
       +
               "uri": "file:///project/src/main.rs",

     

       152
       152
       +
               "mimeType": "text/x-rust",

     

       153
       153
       +
               "text": "fn main() {\n    println!(\"Hello world!\");\n}"

     

       154
       154
       +
             }

     

       155
       155
       +
           ]

     

       156
       156
       +
         }

     

       157
       157
       +
       }

     

       158
       158
       +
       ```

     

       159
       159
       +
       

     

       160
       160
       +
       ### Resource Templates

     

       161
       161
       +
       

     

       162
       162
       +
       Resource templates allow servers to expose parameterized resources using

     

       163
       163
       +
       [URI templates](https://datatracker.ietf.org/doc/html/rfc6570). Arguments may be

     

       164
       164
       +
       auto-completed through [the completion API]({{< ref "utilities/completion" >}}).

     

       165
       165
       +
       

     

       166
       166
       +
       **Request:**

     

       167
       167
       +
       

     

       168
       168
       +
       ```json

     

       169
       169
       +
       {

     

       170
       170
       +
         "jsonrpc": "2.0",

     

       171
       171
       +
         "id": 3,

     

       172
       172
       +
         "method": "resources/templates/list"

     

       173
       173
       +
       }

     

       174
       174
       +
       ```

     

       175
       175
       +
       

     

       176
       176
       +
       **Response:**

     

       177
       177
       +
       

     

       178
       178
       +
       ```json

     

       179
       179
       +
       {

     

       180
       180
       +
         "jsonrpc": "2.0",

     

       181
       181
       +
         "id": 3,

     

       182
       182
       +
         "result": {

     

       183
       183
       +
           "resourceTemplates": [

     

       184
       184
       +
             {

     

       185
       185
       +
               "uriTemplate": "file:///{path}",

     

       186
       186
       +
               "name": "Project Files",

     

       187
       187
       +
               "description": "Access files in the project directory",

     

       188
       188
       +
               "mimeType": "application/octet-stream"

     

       189
       189
       +
             }

     

       190
       190
       +
           ]

     

       191
       191
       +
         }

     

       192
       192
       +
       }

     

       193
       193
       +
       ```

     

       194
       194
       +
       

     

       195
       195
       +
       ### List Changed Notification

     

       196
       196
       +
       

     

       197
       197
       +
       When the list of available resources changes, servers that declared the `listChanged`

     

       198
       198
       +
       capability **SHOULD** send a notification:

     

       199
       199
       +
       

     

       200
       200
       +
       ```json

     

       201
       201
       +
       {

     

       202
       202
       +
         "jsonrpc": "2.0",

     

       203
       203
       +
         "method": "notifications/resources/list_changed"

     

       204
       204
       +
       }

     

       205
       205
       +
       ```

     

       206
       206
       +
       

     

       207
       207
       +
       ### Subscriptions

     

       208
       208
       +
       

     

       209
       209
       +
       The protocol supports optional subscriptions to resource changes. Clients can subscribe

     

       210
       210
       +
       to specific resources and receive notifications when they change:

     

       211
       211
       +
       

     

       212
       212
       +
       **Subscribe Request:**

     

       213
       213
       +
       

     

       214
       214
       +
       ```json

     

       215
       215
       +
       {

     

       216
       216
       +
         "jsonrpc": "2.0",

     

       217
       217
       +
         "id": 4,

     

       218
       218
       +
         "method": "resources/subscribe",

     

       219
       219
       +
         "params": {

     

       220
       220
       +
           "uri": "file:///project/src/main.rs"

     

       221
       221
       +
         }

     

       222
       222
       +
       }

     

       223
       223
       +
       ```

     

       224
       224
       +
       

     

       225
       225
       +
       **Update Notification:**

     

       226
       226
       +
       

     

       227
       227
       +
       ```json

     

       228
       228
       +
       {

     

       229
       229
       +
         "jsonrpc": "2.0",

     

       230
       230
       +
         "method": "notifications/resources/updated",

     

       231
       231
       +
         "params": {

     

       232
       232
       +
           "uri": "file:///project/src/main.rs"

     

       233
       233
       +
         }

     

       234
       234
       +
       }

     

       235
       235
       +
       ```

     

       236
       236
       +
       

     

       237
       237
       +
       ## Message Flow

     

       238
       238
       +
       

     

       239
       239
       +
       ```mermaid

     

       240
       240
       +
       sequenceDiagram

     

       241
       241
       +
           participant Client

     

       242
       242
       +
           participant Server

     

       243
       243
       +
       

     

       244
       244
       +
           Note over Client,Server: Resource Discovery

     

       245
       245
       +
           Client->>Server: resources/list

     

       246
       246
       +
           Server-->>Client: List of resources

     

       247
       247
       +
       

     

       248
       248
       +
           Note over Client,Server: Resource Access

     

       249
       249
       +
           Client->>Server: resources/read

     

       250
       250
       +
           Server-->>Client: Resource contents

     

       251
       251
       +
       

     

       252
       252
       +
           Note over Client,Server: Subscriptions

     

       253
       253
       +
           Client->>Server: resources/subscribe

     

       254
       254
       +
           Server-->>Client: Subscription confirmed

     

       255
       255
       +
       

     

       256
       256
       +
           Note over Client,Server: Updates

     

       257
       257
       +
           Server--)Client: notifications/resources/updated

     

       258
       258
       +
           Client->>Server: resources/read

     

       259
       259
       +
           Server-->>Client: Updated contents

     

       260
       260
       +
       ```

     

       261
       261
       +
       

     

       262
       262
       +
       ## Data Types

     

       263
       263
       +
       

     

       264
       264
       +
       ### Resource

     

       265
       265
       +
       

     

       266
       266
       +
       A resource definition includes:

     

       267
       267
       +
       

     

       268
       268
       +
       - `uri`: Unique identifier for the resource

     

       269
       269
       +
       - `name`: Human-readable name

     

       270
       270
       +
       - `description`: Optional description

     

       271
       271
       +
       - `mimeType`: Optional MIME type

     

       272
       272
       +
       - `size`: Optional size in bytes

     

       273
       273
       +
       

     

       274
       274
       +
       ### Resource Contents

     

       275
       275
       +
       

     

       276
       276
       +
       Resources can contain either text or binary data:

     

       277
       277
       +
       

     

       278
       278
       +
       #### Text Content

     

       279
       279
       +
       

     

       280
       280
       +
       ```json

     

       281
       281
       +
       {

     

       282
       282
       +
         "uri": "file:///example.txt",

     

       283
       283
       +
         "mimeType": "text/plain",

     

       284
       284
       +
         "text": "Resource content"

     

       285
       285
       +
       }

     

       286
       286
       +
       ```

     

       287
       287
       +
       

     

       288
       288
       +
       #### Binary Content

     

       289
       289
       +
       

     

       290
       290
       +
       ```json

     

       291
       291
       +
       {

     

       292
       292
       +
         "uri": "file:///example.png",

     

       293
       293
       +
         "mimeType": "image/png",

     

       294
       294
       +
         "blob": "base64-encoded-data"

     

       295
       295
       +
       }

     

       296
       296
       +
       ```

     

       297
       297
       +
       

     

       298
       298
       +
       ## Common URI Schemes

     

       299
       299
       +
       

     

       300
       300
       +
       The protocol defines several standard URI schemes. This list not

     

       301
       301
       +
       exhaustive&mdash;implementations are always free to use additional, custom URI schemes.

     

       302
       302
       +
       

     

       303
       303
       +
       ### https://

     

       304
       304
       +
       

     

       305
       305
       +
       Used to represent a resource available on the web.

     

       306
       306
       +
       

     

       307
       307
       +
       Servers **SHOULD** use this scheme only when the client is able to fetch and load the

     

       308
       308
       +
       resource directly from the web on its own—that is, it doesn’t need to read the resource

     

       309
       309
       +
       via the MCP server.

     

       310
       310
       +
       

     

       311
       311
       +
       For other use cases, servers **SHOULD** prefer to use another URI scheme, or define a

     

       312
       312
       +
       custom one, even if the server will itself be downloading resource contents over the

     

       313
       313
       +
       internet.

     

       314
       314
       +
       

     

       315
       315
       +
       ### file://

     

       316
       316
       +
       

     

       317
       317
       +
       Used to identify resources that behave like a filesystem. However, the resources do not

     

       318
       318
       +
       need to map to an actual physical filesystem.

     

       319
       319
       +
       

     

       320
       320
       +
       MCP servers **MAY** identify file:// resources with an

     

       321
       321
       +
       [XDG MIME type](https://specifications.freedesktop.org/shared-mime-info-spec/0.14/ar01s02.html#id-1.3.14),

     

       322
       322
       +
       like `inode/directory`, to represent non-regular files (such as directories) that don’t

     

       323
       323
       +
       otherwise have a standard MIME type.

     

       324
       324
       +
       

     

       325
       325
       +
       ### git://

     

       326
       326
       +
       

     

       327
       327
       +
       Git version control integration.

     

       328
       328
       +
       

     

       329
       329
       +
       ## Error Handling

     

       330
       330
       +
       

     

       331
       331
       +
       Servers **SHOULD** return standard JSON-RPC errors for common failure cases:

     

       332
       332
       +
       

     

       333
       333
       +
       - Resource not found: `-32002`

     

       334
       334
       +
       - Internal errors: `-32603`

     

       335
       335
       +
       

     

       336
       336
       +
       Example error:

     

       337
       337
       +
       

     

       338
       338
       +
       ```json

     

       339
       339
       +
       {

     

       340
       340
       +
         "jsonrpc": "2.0",

     

       341
       341
       +
         "id": 5,

     

       342
       342
       +
         "error": {

     

       343
       343
       +
           "code": -32002,

     

       344
       344
       +
           "message": "Resource not found",

     

       345
       345
       +
           "data": {

     

       346
       346
       +
             "uri": "file:///nonexistent.txt"

     

       347
       347
       +
           }

     

       348
       348
       +
         }

     

       349
       349
       +
       }

     

       350
       350
       +
       ```

     

       351
       351
       +
       

     

       352
       352
       +
       ## Security Considerations

     

       353
       353
       +
       

     

       354
       354
       +
       1. Servers **MUST** validate all resource URIs

     

       355
       355
       +
       2. Access controls **SHOULD** be implemented for sensitive resources

     

       356
       356
       +
       3. Binary data **MUST** be properly encoded

     

       357
       357
       +
       4. Resource permissions **SHOULD** be checked before operations

spec/slash-command.png

This is a binary file and will not be displayed.

+299

spec/tools.md

···

       1
       1
       +
       ---

     

       2
       2
       +
       title: Tools

     

       3
       3
       +
       type: docs

     

       4
       4
       +
       weight: 40

     

       5
       5
       +
       ---

     

       6
       6
       +
       

     

       7
       7
       +
       {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}

     

       8
       8
       +
       

     

       9
       9
       +
       The Model Context Protocol (MCP) allows servers to expose tools that can be invoked by

     

       10
       10
       +
       language models. Tools enable models to interact with external systems, such as querying

     

       11
       11
       +
       databases, calling APIs, or performing computations. Each tool is uniquely identified by

     

       12
       12
       +
       a name and includes metadata describing its schema.

     

       13
       13
       +
       

     

       14
       14
       +
       ## User Interaction Model

     

       15
       15
       +
       

     

       16
       16
       +
       Tools in MCP are designed to be **model-controlled**, meaning that the language model can

     

       17
       17
       +
       discover and invoke tools automatically based on its contextual understanding and the

     

       18
       18
       +
       user's prompts.

     

       19
       19
       +
       

     

       20
       20
       +
       However, implementations are free to expose tools through any interface pattern that

     

       21
       21
       +
       suits their needs&mdash;the protocol itself does not mandate any specific user

     

       22
       22
       +
       interaction model.

     

       23
       23
       +
       

     

       24
       24
       +
       {{< callout type="warning" >}} For trust & safety and security, there **SHOULD** always

     

       25
       25
       +
       be a human in the loop with the ability to deny tool invocations.

     

       26
       26
       +
       

     

       27
       27
       +
       Applications **SHOULD**:

     

       28
       28
       +
       

     

       29
       29
       +
       - Provide UI that makes clear which tools are being exposed to the AI model

     

       30
       30
       +
       - Insert clear visual indicators when tools are invoked

     

       31
       31
       +
       - Present confirmation prompts to the user for operations, to ensure a human is in the

     

       32
       32
       +
         loop {{< /callout >}}

     

       33
       33
       +
       

     

       34
       34
       +
       ## Capabilities

     

       35
       35
       +
       

     

       36
       36
       +
       Servers that support tools **MUST** declare the `tools` capability:

     

       37
       37
       +
       

     

       38
       38
       +
       ```json

     

       39
       39
       +
       {

     

       40
       40
       +
         "capabilities": {

     

       41
       41
       +
           "tools": {

     

       42
       42
       +
             "listChanged": true

     

       43
       43
       +
           }

     

       44
       44
       +
         }

     

       45
       45
       +
       }

     

       46
       46
       +
       ```

     

       47
       47
       +
       

     

       48
       48
       +
       `listChanged` indicates whether the server will emit notifications when the list of

     

       49
       49
       +
       available tools changes.

     

       50
       50
       +
       

     

       51
       51
       +
       ## Protocol Messages

     

       52
       52
       +
       

     

       53
       53
       +
       ### Listing Tools

     

       54
       54
       +
       

     

       55
       55
       +
       To discover available tools, clients send a `tools/list` request. This operation supports

     

       56
       56
       +
       [pagination]({{< ref "utilities/pagination" >}}).

     

       57
       57
       +
       

     

       58
       58
       +
       **Request:**

     

       59
       59
       +
       

     

       60
       60
       +
       ```json

     

       61
       61
       +
       {

     

       62
       62
       +
         "jsonrpc": "2.0",

     

       63
       63
       +
         "id": 1,

     

       64
       64
       +
         "method": "tools/list",

     

       65
       65
       +
         "params": {

     

       66
       66
       +
           "cursor": "optional-cursor-value"

     

       67
       67
       +
         }

     

       68
       68
       +
       }

     

       69
       69
       +
       ```

     

       70
       70
       +
       

     

       71
       71
       +
       **Response:**

     

       72
       72
       +
       

     

       73
       73
       +
       ```json

     

       74
       74
       +
       {

     

       75
       75
       +
         "jsonrpc": "2.0",

     

       76
       76
       +
         "id": 1,

     

       77
       77
       +
         "result": {

     

       78
       78
       +
           "tools": [

     

       79
       79
       +
             {

     

       80
       80
       +
               "name": "get_weather",

     

       81
       81
       +
               "description": "Get current weather information for a location",

     

       82
       82
       +
               "inputSchema": {

     

       83
       83
       +
                 "type": "object",

     

       84
       84
       +
                 "properties": {

     

       85
       85
       +
                   "location": {

     

       86
       86
       +
                     "type": "string",

     

       87
       87
       +
                     "description": "City name or zip code"

     

       88
       88
       +
                   }

     

       89
       89
       +
                 },

     

       90
       90
       +
                 "required": ["location"]

     

       91
       91
       +
               }

     

       92
       92
       +
             }

     

       93
       93
       +
           ],

     

       94
       94
       +
           "nextCursor": "next-page-cursor"

     

       95
       95
       +
         }

     

       96
       96
       +
       }

     

       97
       97
       +
       ```

     

       98
       98
       +
       

     

       99
       99
       +
       ### Calling Tools

     

       100
       100
       +
       

     

       101
       101
       +
       To invoke a tool, clients send a `tools/call` request:

     

       102
       102
       +
       

     

       103
       103
       +
       **Request:**

     

       104
       104
       +
       

     

       105
       105
       +
       ```json

     

       106
       106
       +
       {

     

       107
       107
       +
         "jsonrpc": "2.0",

     

       108
       108
       +
         "id": 2,

     

       109
       109
       +
         "method": "tools/call",

     

       110
       110
       +
         "params": {

     

       111
       111
       +
           "name": "get_weather",

     

       112
       112
       +
           "arguments": {

     

       113
       113
       +
             "location": "New York"

     

       114
       114
       +
           }

     

       115
       115
       +
         }

     

       116
       116
       +
       }

     

       117
       117
       +
       ```

     

       118
       118
       +
       

     

       119
       119
       +
       **Response:**

     

       120
       120
       +
       

     

       121
       121
       +
       ```json

     

       122
       122
       +
       {

     

       123
       123
       +
         "jsonrpc": "2.0",

     

       124
       124
       +
         "id": 2,

     

       125
       125
       +
         "result": {

     

       126
       126
       +
           "content": [

     

       127
       127
       +
             {

     

       128
       128
       +
               "type": "text",

     

       129
       129
       +
               "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"

     

       130
       130
       +
             }

     

       131
       131
       +
           ],

     

       132
       132
       +
           "isError": false

     

       133
       133
       +
         }

     

       134
       134
       +
       }

     

       135
       135
       +
       ```

     

       136
       136
       +
       

     

       137
       137
       +
       ### List Changed Notification

     

       138
       138
       +
       

     

       139
       139
       +
       When the list of available tools changes, servers that declared the `listChanged`

     

       140
       140
       +
       capability **SHOULD** send a notification:

     

       141
       141
       +
       

     

       142
       142
       +
       ```json

     

       143
       143
       +
       {

     

       144
       144
       +
         "jsonrpc": "2.0",

     

       145
       145
       +
         "method": "notifications/tools/list_changed"

     

       146
       146
       +
       }

     

       147
       147
       +
       ```

     

       148
       148
       +
       

     

       149
       149
       +
       ## Message Flow

     

       150
       150
       +
       

     

       151
       151
       +
       ```mermaid

     

       152
       152
       +
       sequenceDiagram

     

       153
       153
       +
           participant LLM

     

       154
       154
       +
           participant Client

     

       155
       155
       +
           participant Server

     

       156
       156
       +
       

     

       157
       157
       +
           Note over Client,Server: Discovery

     

       158
       158
       +
           Client->>Server: tools/list

     

       159
       159
       +
           Server-->>Client: List of tools

     

       160
       160
       +
       

     

       161
       161
       +
           Note over Client,LLM: Tool Selection

     

       162
       162
       +
           LLM->>Client: Select tool to use

     

       163
       163
       +
       

     

       164
       164
       +
           Note over Client,Server: Invocation

     

       165
       165
       +
           Client->>Server: tools/call

     

       166
       166
       +
           Server-->>Client: Tool result

     

       167
       167
       +
           Client->>LLM: Process result

     

       168
       168
       +
       

     

       169
       169
       +
           Note over Client,Server: Updates

     

       170
       170
       +
           Server--)Client: tools/list_changed

     

       171
       171
       +
           Client->>Server: tools/list

     

       172
       172
       +
           Server-->>Client: Updated tools

     

       173
       173
       +
       ```

     

       174
       174
       +
       

     

       175
       175
       +
       ## Data Types

     

       176
       176
       +
       

     

       177
       177
       +
       ### Tool

     

       178
       178
       +
       

     

       179
       179
       +
       A tool definition includes:

     

       180
       180
       +
       

     

       181
       181
       +
       - `name`: Unique identifier for the tool

     

       182
       182
       +
       - `description`: Human-readable description of functionality

     

       183
       183
       +
       - `inputSchema`: JSON Schema defining expected parameters

     

       184
       184
       +
       - `annotations`: optional properties describing tool behavior

     

       185
       185
       +
       

     

       186
       186
       +
       {{< callout type="warning" >}} For trust & safety and security, clients **MUST** consider

     

       187
       187
       +
       tool annotations to be untrusted unless they come from trusted servers. {{< /callout >}}

     

       188
       188
       +
       

     

       189
       189
       +
       ### Tool Result

     

       190
       190
       +
       

     

       191
       191
       +
       Tool results can contain multiple content items of different types:

     

       192
       192
       +
       

     

       193
       193
       +
       #### Text Content

     

       194
       194
       +
       

     

       195
       195
       +
       ```json

     

       196
       196
       +
       {

     

       197
       197
       +
         "type": "text",

     

       198
       198
       +
         "text": "Tool result text"

     

       199
       199
       +
       }

     

       200
       200
       +
       ```

     

       201
       201
       +
       

     

       202
       202
       +
       #### Image Content

     

       203
       203
       +
       

     

       204
       204
       +
       ```json

     

       205
       205
       +
       {

     

       206
       206
       +
         "type": "image",

     

       207
       207
       +
         "data": "base64-encoded-data",

     

       208
       208
       +
         "mimeType": "image/png"

     

       209
       209
       +
       }

     

       210
       210
       +
       ```

     

       211
       211
       +
       

     

       212
       212
       +
       #### Audio Content

     

       213
       213
       +
       

     

       214
       214
       +
       ```json

     

       215
       215
       +
       {

     

       216
       216
       +
         "type": "audio",

     

       217
       217
       +
         "data": "base64-encoded-audio-data",

     

       218
       218
       +
         "mimeType": "audio/wav"

     

       219
       219
       +
       }

     

       220
       220
       +
       ```

     

       221
       221
       +
       

     

       222
       222
       +
       #### Embedded Resources

     

       223
       223
       +
       

     

       224
       224
       +
       [Resources]({{< ref "resources" >}}) **MAY** be embedded, to provide additional context

     

       225
       225
       +
       or data, behind a URI that can be subscribed to or fetched again by the client later:

     

       226
       226
       +
       

     

       227
       227
       +
       ```json

     

       228
       228
       +
       {

     

       229
       229
       +
         "type": "resource",

     

       230
       230
       +
         "resource": {

     

       231
       231
       +
           "uri": "resource://example",

     

       232
       232
       +
           "mimeType": "text/plain",

     

       233
       233
       +
           "text": "Resource content"

     

       234
       234
       +
         }

     

       235
       235
       +
       }

     

       236
       236
       +
       ```

     

       237
       237
       +
       

     

       238
       238
       +
       ## Error Handling

     

       239
       239
       +
       

     

       240
       240
       +
       Tools use two error reporting mechanisms:

     

       241
       241
       +
       

     

       242
       242
       +
       1. **Protocol Errors**: Standard JSON-RPC errors for issues like:

     

       243
       243
       +
       

     

       244
       244
       +
          - Unknown tools

     

       245
       245
       +
          - Invalid arguments

     

       246
       246
       +
          - Server errors

     

       247
       247
       +
       

     

       248
       248
       +
       2. **Tool Execution Errors**: Reported in tool results with `isError: true`:

     

       249
       249
       +
          - API failures

     

       250
       250
       +
          - Invalid input data

     

       251
       251
       +
          - Business logic errors

     

       252
       252
       +
       

     

       253
       253
       +
       Example protocol error:

     

       254
       254
       +
       

     

       255
       255
       +
       ```json

     

       256
       256
       +
       {

     

       257
       257
       +
         "jsonrpc": "2.0",

     

       258
       258
       +
         "id": 3,

     

       259
       259
       +
         "error": {

     

       260
       260
       +
           "code": -32602,

     

       261
       261
       +
           "message": "Unknown tool: invalid_tool_name"

     

       262
       262
       +
         }

     

       263
       263
       +
       }

     

       264
       264
       +
       ```

     

       265
       265
       +
       

     

       266
       266
       +
       Example tool execution error:

     

       267
       267
       +
       

     

       268
       268
       +
       ```json

     

       269
       269
       +
       {

     

       270
       270
       +
         "jsonrpc": "2.0",

     

       271
       271
       +
         "id": 4,

     

       272
       272
       +
         "result": {

     

       273
       273
       +
           "content": [

     

       274
       274
       +
             {

     

       275
       275
       +
               "type": "text",

     

       276
       276
       +
               "text": "Failed to fetch weather data: API rate limit exceeded"

     

       277
       277
       +
             }

     

       278
       278
       +
           ],

     

       279
       279
       +
           "isError": true

     

       280
       280
       +
         }

     

       281
       281
       +
       }

     

       282
       282
       +
       ```

     

       283
       283
       +
       

     

       284
       284
       +
       ## Security Considerations

     

       285
       285
       +
       

     

       286
       286
       +
       1. Servers **MUST**:

     

       287
       287
       +
       

     

       288
       288
       +
          - Validate all tool inputs

     

       289
       289
       +
          - Implement proper access controls

     

       290
       290
       +
          - Rate limit tool invocations

     

       291
       291
       +
          - Sanitize tool outputs

     

       292
       292
       +
       

     

       293
       293
       +
       2. Clients **SHOULD**:

     

       294
       294
       +
          - Prompt for user confirmation on sensitive operations

     

       295
       295
       +
          - Show tool inputs to the user before calling the server, to avoid malicious or

     

       296
       296
       +
            accidental data exfiltration

     

       297
       297
       +
          - Validate tool results before passing to LLM

     

       298
       298
       +
          - Implement timeouts for tool calls

     

       299
       299
       +
          - Log tool usage for audit purposes

+278

spec/transports.md

···

       1
       1
       +
       ---

     

       2
       2
       +
       title: Transports

     

       3
       3
       +
       type: docs

     

       4
       4
       +
       weight: 10

     

       5
       5
       +
       ---

     

       6
       6
       +
       

     

       7
       7
       +
       {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}

     

       8
       8
       +
       

     

       9
       9
       +
       MCP uses JSON-RPC to encode messages. JSON-RPC messages **MUST** be UTF-8 encoded.

     

       10
       10
       +
       

     

       11
       11
       +
       The protocol currently defines two standard transport mechanisms for client-server

     

       12
       12
       +
       communication:

     

       13
       13
       +
       

     

       14
       14
       +
       1. [stdio](#stdio), communication over standard in and standard out

     

       15
       15
       +
       2. [Streamable HTTP](#streamable-http)

     

       16
       16
       +
       

     

       17
       17
       +
       Clients **SHOULD** support stdio whenever possible.

     

       18
       18
       +
       

     

       19
       19
       +
       It is also possible for clients and servers to implement

     

       20
       20
       +
       [custom transports](#custom-transports) in a pluggable fashion.

     

       21
       21
       +
       

     

       22
       22
       +
       ## stdio

     

       23
       23
       +
       

     

       24
       24
       +
       In the **stdio** transport:

     

       25
       25
       +
       

     

       26
       26
       +
       - The client launches the MCP server as a subprocess.

     

       27
       27
       +
       - The server reads JSON-RPC messages from its standard input (`stdin`) and sends messages

     

       28
       28
       +
         to its standard output (`stdout`).

     

       29
       29
       +
       - Messages may be JSON-RPC requests, notifications, responses—or a JSON-RPC

     

       30
       30
       +
         [batch](https://www.jsonrpc.org/specification#batch) containing one or more requests

     

       31
       31
       +
         and/or notifications.

     

       32
       32
       +
       - Messages are delimited by newlines, and **MUST NOT** contain embedded newlines.

     

       33
       33
       +
       - The server **MAY** write UTF-8 strings to its standard error (`stderr`) for logging

     

       34
       34
       +
         purposes. Clients **MAY** capture, forward, or ignore this logging.

     

       35
       35
       +
       - The server **MUST NOT** write anything to its `stdout` that is not a valid MCP message.

     

       36
       36
       +
       - The client **MUST NOT** write anything to the server's `stdin` that is not a valid MCP

     

       37
       37
       +
         message.

     

       38
       38
       +
       

     

       39
       39
       +
       ```mermaid

     

       40
       40
       +
       sequenceDiagram

     

       41
       41
       +
           participant Client

     

       42
       42
       +
           participant Server Process

     

       43
       43
       +
       

     

       44
       44
       +
           Client->>+Server Process: Launch subprocess

     

       45
       45
       +
           loop Message Exchange

     

       46
       46
       +
               Client->>Server Process: Write to stdin

     

       47
       47
       +
               Server Process->>Client: Write to stdout

     

       48
       48
       +
               Server Process--)Client: Optional logs on stderr

     

       49
       49
       +
           end

     

       50
       50
       +
           Client->>Server Process: Close stdin, terminate subprocess

     

       51
       51
       +
           deactivate Server Process

     

       52
       52
       +
       ```

     

       53
       53
       +
       

     

       54
       54
       +
       ## Streamable HTTP

     

       55
       55
       +
       

     

       56
       56
       +
       {{< callout type="info" >}} This replaces the [HTTP+SSE

     

       57
       57
       +
       transport]({{< ref "/specification/2024-11-05/basic/transports#http-with-sse" >}}) from

     

       58
       58
       +
       protocol version 2024-11-05. See the [backwards compatibility](#backwards-compatibility)

     

       59
       59
       +
       guide below. {{< /callout >}}

     

       60
       60
       +
       

     

       61
       61
       +
       In the **Streamable HTTP** transport, the server operates as an independent process that

     

       62
       62
       +
       can handle multiple client connections. This transport uses HTTP POST and GET requests.

     

       63
       63
       +
       Server can optionally make use of

     

       64
       64
       +
       [Server-Sent Events](https://en.wikipedia.org/wiki/Server-sent_events) (SSE) to stream

     

       65
       65
       +
       multiple server messages. This permits basic MCP servers, as well as more feature-rich

     

       66
       66
       +
       servers supporting streaming and server-to-client notifications and requests.

     

       67
       67
       +
       

     

       68
       68
       +
       The server **MUST** provide a single HTTP endpoint path (hereafter referred to as the

     

       69
       69
       +
       **MCP endpoint**) that supports both POST and GET methods. For example, this could be a

     

       70
       70
       +
       URL like `https://example.com/mcp`.

     

       71
       71
       +
       

     

       72
       72
       +
       ### Sending Messages to the Server

     

       73
       73
       +
       

     

       74
       74
       +
       Every JSON-RPC message sent from the client **MUST** be a new HTTP POST request to the

     

       75
       75
       +
       MCP endpoint.

     

       76
       76
       +
       

     

       77
       77
       +
       1. The client **MUST** use HTTP POST to send JSON-RPC messages to the MCP endpoint.

     

       78
       78
       +
       2. The client **MUST** include an `Accept` header, listing both `application/json` and

     

       79
       79
       +
          `text/event-stream` as supported content types.

     

       80
       80
       +
       3. The body of the POST request **MUST** be one of the following:

     

       81
       81
       +
          - A single JSON-RPC _request_, _notification_, or _response_

     

       82
       82
       +
          - An array [batching](https://www.jsonrpc.org/specification#batch) one or more

     

       83
       83
       +
            _requests and/or notifications_

     

       84
       84
       +
          - An array [batching](https://www.jsonrpc.org/specification#batch) one or more

     

       85
       85
       +
            _responses_

     

       86
       86
       +
       4. If the input consists solely of (any number of) JSON-RPC _responses_ or

     

       87
       87
       +
          _notifications_:

     

       88
       88
       +
          - If the server accepts the input, the server **MUST** return HTTP status code 202

     

       89
       89
       +
            Accepted with no body.

     

       90
       90
       +
          - If the server cannot accept the input, it **MUST** return an HTTP error status code

     

       91
       91
       +
            (e.g., 400 Bad Request). The HTTP response body **MAY** comprise a JSON-RPC _error

     

       92
       92
       +
            response_ that has no `id`.

     

       93
       93
       +
       5. If the input contains any number of JSON-RPC _requests_, the server **MUST** either

     

       94
       94
       +
          return `Content-Type: text/event-stream`, to initiate an SSE stream, or

     

       95
       95
       +
          `Content-Type: application/json`, to return one JSON object. The client **MUST**

     

       96
       96
       +
          support both these cases.

     

       97
       97
       +
       6. If the server initiates an SSE stream:

     

       98
       98
       +
          - The SSE stream **SHOULD** eventually include one JSON-RPC _response_ per each

     

       99
       99
       +
            JSON-RPC _request_ sent in the POST body. These _responses_ **MAY** be

     

       100
       100
       +
            [batched](https://www.jsonrpc.org/specification#batch).

     

       101
       101
       +
          - The server **MAY** send JSON-RPC _requests_ and _notifications_ before sending a

     

       102
       102
       +
            JSON-RPC _response_. These messages **SHOULD** relate to the originating client

     

       103
       103
       +
            _request_. These _requests_ and _notifications_ **MAY** be

     

       104
       104
       +
            [batched](https://www.jsonrpc.org/specification#batch).

     

       105
       105
       +
          - The server **SHOULD NOT** close the SSE stream before sending a JSON-RPC _response_

     

       106
       106
       +
            per each received JSON-RPC _request_, unless the [session](#session-management)

     

       107
       107
       +
            expires.

     

       108
       108
       +
          - After all JSON-RPC _responses_ have been sent, the server **SHOULD** close the SSE

     

       109
       109
       +
            stream.

     

       110
       110
       +
          - Disconnection **MAY** occur at any time (e.g., due to network conditions).

     

       111
       111
       +
            Therefore:

     

       112
       112
       +
            - Disconnection **SHOULD NOT** be interpreted as the client cancelling its request.

     

       113
       113
       +
            - To cancel, the client **SHOULD** explicitly send an MCP `CancelledNotification`.

     

       114
       114
       +
            - To avoid message loss due to disconnection, the server **MAY** make the stream

     

       115
       115
       +
              [resumable](#resumability-and-redelivery).

     

       116
       116
       +
       

     

       117
       117
       +
       ### Listening for Messages from the Server

     

       118
       118
       +
       

     

       119
       119
       +
       1. The client **MAY** issue an HTTP GET to the MCP endpoint. This can be used to open an

     

       120
       120
       +
          SSE stream, allowing the server to communicate to the client, without the client first

     

       121
       121
       +
          sending data via HTTP POST.

     

       122
       122
       +
       2. The client **MUST** include an `Accept` header, listing `text/event-stream` as a

     

       123
       123
       +
          supported content type.

     

       124
       124
       +
       3. The server **MUST** either return `Content-Type: text/event-stream` in response to

     

       125
       125
       +
          this HTTP GET, or else return HTTP 405 Method Not Allowed, indicating that the server

     

       126
       126
       +
          does not offer an SSE stream at this endpoint.

     

       127
       127
       +
       4. If the server initiates an SSE stream:

     

       128
       128
       +
          - The server **MAY** send JSON-RPC _requests_ and _notifications_ on the stream. These

     

       129
       129
       +
            _requests_ and _notifications_ **MAY** be

     

       130
       130
       +
            [batched](https://www.jsonrpc.org/specification#batch).

     

       131
       131
       +
          - These messages **SHOULD** be unrelated to any concurrently-running JSON-RPC

     

       132
       132
       +
            _request_ from the client.

     

       133
       133
       +
          - The server **MUST NOT** send a JSON-RPC _response_ on the stream **unless**

     

       134
       134
       +
            [resuming](#resumability-and-redelivery) a stream associated with a previous client

     

       135
       135
       +
            request.

     

       136
       136
       +
          - The server **MAY** close the SSE stream at any time.

     

       137
       137
       +
          - The client **MAY** close the SSE stream at any time.

     

       138
       138
       +
       

     

       139
       139
       +
       ### Multiple Connections

     

       140
       140
       +
       

     

       141
       141
       +
       1. The client **MAY** remain connected to multiple SSE streams simultaneously.

     

       142
       142
       +
       2. The server **MUST** send each of its JSON-RPC messages on only one of the connected

     

       143
       143
       +
          streams; that is, it **MUST NOT** broadcast the same message across multiple streams.

     

       144
       144
       +
          - The risk of message loss **MAY** be mitigated by making the stream

     

       145
       145
       +
            [resumable](#resumability-and-redelivery).

     

       146
       146
       +
       

     

       147
       147
       +
       ### Resumability and Redelivery

     

       148
       148
       +
       

     

       149
       149
       +
       To support resuming broken connections, and redelivering messages that might otherwise be

     

       150
       150
       +
       lost:

     

       151
       151
       +
       

     

       152
       152
       +
       1. Servers **MAY** attach an `id` field to their SSE events, as described in the

     

       153
       153
       +
          [SSE standard](https://html.spec.whatwg.org/multipage/server-sent-events.html#event-stream-interpretation).

     

       154
       154
       +
          - If present, the ID **MUST** be globally unique across all streams within that

     

       155
       155
       +
            [session](#session-management)—or all streams with that specific client, if session

     

       156
       156
       +
            management is not in use.

     

       157
       157
       +
       2. If the client wishes to resume after a broken connection, it **SHOULD** issue an HTTP

     

       158
       158
       +
          GET to the MCP endpoint, and include the

     

       159
       159
       +
          [`Last-Event-ID`](https://html.spec.whatwg.org/multipage/server-sent-events.html#the-last-event-id-header)

     

       160
       160
       +
          header to indicate the last event ID it received.

     

       161
       161
       +
          - The server **MAY** use this header to replay messages that would have been sent

     

       162
       162
       +
            after the last event ID, _on the stream that was disconnected_, and to resume the

     

       163
       163
       +
            stream from that point.

     

       164
       164
       +
          - The server **MUST NOT** replay messages that would have been delivered on a

     

       165
       165
       +
            different stream.

     

       166
       166
       +
       

     

       167
       167
       +
       In other words, these event IDs should be assigned by servers on a _per-stream_ basis, to

     

       168
       168
       +
       act as a cursor within that particular stream.

     

       169
       169
       +
       

     

       170
       170
       +
       ### Session Management

     

       171
       171
       +
       

     

       172
       172
       +
       An MCP "session" consists of logically related interactions between a client and a

     

       173
       173
       +
       server, beginning with the [initialization phase]({{< ref "lifecycle" >}}). To support

     

       174
       174
       +
       servers which want to establish stateful sessions:

     

       175
       175
       +
       

     

       176
       176
       +
       1. A server using the Streamable HTTP transport **MAY** assign a session ID at

     

       177
       177
       +
          initialization time, by including it in an `Mcp-Session-Id` header on the HTTP

     

       178
       178
       +
          response containing the `InitializeResult`.

     

       179
       179
       +
          - The session ID **SHOULD** be globally unique and cryptographically secure (e.g., a

     

       180
       180
       +
            securely generated UUID, a JWT, or a cryptographic hash).

     

       181
       181
       +
          - The session ID **MUST** only contain visible ASCII characters (ranging from 0x21 to

     

       182
       182
       +
            0x7E).

     

       183
       183
       +
       2. If an `Mcp-Session-Id` is returned by the server during initialization, clients using

     

       184
       184
       +
          the Streamable HTTP transport **MUST** include it in the `Mcp-Session-Id` header on

     

       185
       185
       +
          all of their subsequent HTTP requests.

     

       186
       186
       +
          - Servers that require a session ID **SHOULD** respond to requests without an

     

       187
       187
       +
            `Mcp-Session-Id` header (other than initialization) with HTTP 400 Bad Request.

     

       188
       188
       +
       3. The server **MAY** terminate the session at any time, after which it **MUST** respond

     

       189
       189
       +
          to requests containing that session ID with HTTP 404 Not Found.

     

       190
       190
       +
       4. When a client receives HTTP 404 in response to a request containing an

     

       191
       191
       +
          `Mcp-Session-Id`, it **MUST** start a new session by sending a new `InitializeRequest`

     

       192
       192
       +
          without a session ID attached.

     

       193
       193
       +
       5. Clients that no longer need a particular session (e.g., because the user is leaving

     

       194
       194
       +
          the client application) **SHOULD** send an HTTP DELETE to the MCP endpoint with the

     

       195
       195
       +
          `Mcp-Session-Id` header, to explicitly terminate the session.

     

       196
       196
       +
          - The server **MAY** respond to this request with HTTP 405 Method Not Allowed,

     

       197
       197
       +
            indicating that the server does not allow clients to terminate sessions.

     

       198
       198
       +
       

     

       199
       199
       +
       ### Sequence Diagram

     

       200
       200
       +
       

     

       201
       201
       +
       ```mermaid

     

       202
       202
       +
       sequenceDiagram

     

       203
       203
       +
           participant Client

     

       204
       204
       +
           participant Server

     

       205
       205
       +
       

     

       206
       206
       +
           note over Client, Server: initialization

     

       207
       207
       +
       

     

       208
       208
       +
           Client->>+Server: POST InitializeRequest

     

       209
       209
       +
           Server->>-Client: InitializeResponse<br>Mcp-Session-Id: 1868a90c...

     

       210
       210
       +
       

     

       211
       211
       +
           Client->>+Server: POST InitializedNotification<br>Mcp-Session-Id: 1868a90c...

     

       212
       212
       +
           Server->>-Client: 202 Accepted

     

       213
       213
       +
       

     

       214
       214
       +
           note over Client, Server: client requests

     

       215
       215
       +
           Client->>+Server: POST ... request ...<br>Mcp-Session-Id: 1868a90c...

     

       216
       216
       +
       

     

       217
       217
       +
           alt single HTTP response

     

       218
       218
       +
             Server->>Client: ... response ...

     

       219
       219
       +
           else server opens SSE stream

     

       220
       220
       +
             loop while connection remains open

     

       221
       221
       +
                 Server-)Client: ... SSE messages from server ...

     

       222
       222
       +
             end

     

       223
       223
       +
             Server-)Client: SSE event: ... response ...

     

       224
       224
       +
           end

     

       225
       225
       +
           deactivate Server

     

       226
       226
       +
       

     

       227
       227
       +
           note over Client, Server: client notifications/responses

     

       228
       228
       +
           Client->>+Server: POST ... notification/response ...<br>Mcp-Session-Id: 1868a90c...

     

       229
       229
       +
           Server->>-Client: 202 Accepted

     

       230
       230
       +
       

     

       231
       231
       +
           note over Client, Server: server requests

     

       232
       232
       +
           Client->>+Server: GET<br>Mcp-Session-Id: 1868a90c...

     

       233
       233
       +
           loop while connection remains open

     

       234
       234
       +
               Server-)Client: ... SSE messages from server ...

     

       235
       235
       +
           end

     

       236
       236
       +
           deactivate Server

     

       237
       237
       +
       

     

       238
       238
       +
       ```

     

       239
       239
       +
       

     

       240
       240
       +
       ### Backwards Compatibility

     

       241
       241
       +
       

     

       242
       242
       +
       Clients and servers can maintain backwards compatibility with the deprecated [HTTP+SSE

     

       243
       243
       +
       transport]({{< ref "/specification/2024-11-05/basic/transports#http-with-sse" >}}) (from

     

       244
       244
       +
       protocol version 2024-11-05) as follows:

     

       245
       245
       +
       

     

       246
       246
       +
       **Servers** wanting to support older clients should:

     

       247
       247
       +
       

     

       248
       248
       +
       - Continue to host both the SSE and POST endpoints of the old transport, alongside the

     

       249
       249
       +
         new "MCP endpoint" defined for the Streamable HTTP transport.

     

       250
       250
       +
         - It is also possible to combine the old POST endpoint and the new MCP endpoint, but

     

       251
       251
       +
           this may introduce unneeded complexity.

     

       252
       252
       +
       

     

       253
       253
       +
       **Clients** wanting to support older servers should:

     

       254
       254
       +
       

     

       255
       255
       +
       1. Accept an MCP server URL from the user, which may point to either a server using the

     

       256
       256
       +
          old transport or the new transport.

     

       257
       257
       +
       2. Attempt to POST an `InitializeRequest` to the server URL, with an `Accept` header as

     

       258
       258
       +
          defined above:

     

       259
       259
       +
          - If it succeeds, the client can assume this is a server supporting the new Streamable

     

       260
       260
       +
            HTTP transport.

     

       261
       261
       +
          - If it fails with an HTTP 4xx status code (e.g., 405 Method Not Allowed or 404 Not

     

       262
       262
       +
            Found):

     

       263
       263
       +
            - Issue a GET request to the server URL, expecting that this will open an SSE stream

     

       264
       264
       +
              and return an `endpoint` event as the first event.

     

       265
       265
       +
            - When the `endpoint` event arrives, the client can assume this is a server running

     

       266
       266
       +
              the old HTTP+SSE transport, and should use that transport for all subsequent

     

       267
       267
       +
              communication.

     

       268
       268
       +
       

     

       269
       269
       +
       ## Custom Transports

     

       270
       270
       +
       

     

       271
       271
       +
       Clients and servers **MAY** implement additional custom transport mechanisms to suit

     

       272
       272
       +
       their specific needs. The protocol is transport-agnostic and can be implemented over any

     

       273
       273
       +
       communication channel that supports bidirectional message exchange.

     

       274
       274
       +
       

     

       275
       275
       +
       Implementers who choose to support custom transports **MUST** ensure they preserve the

     

       276
       276
       +
       JSON-RPC message format and lifecycle requirements defined by MCP. Custom transports

     

       277
       277
       +
       **SHOULD** document their specific connection establishment and message exchange patterns

     

       278
       278
       +
       to aid interoperability.

Compare changes