comparing 3d958b958219717ad949ba817fb4935591b346a4 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

+52 -41

bin/capitalize_sdk.ml

···

       1
       1
        
       open Mcp

     

       2
       2
        
       open Mcp_sdk

     

       3
       3
       -
       

     

       4
       4
       -
       (* Create the server module *)

     

       5
       5
       -
       module CapitalizeServer = MakeServer(struct

     

       6
       6
       -
         let name = "OCaml MCP Capitalizer"

     

       7
       7
       -
         let version = Some "0.1.0"

     

       8
       8
       -
       end)

     

       3
       3
       +
       open Mcp_server

     

       9
       4
        
       

     

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

     

       11
       6
        
       let get_string_param json name =

     
···

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

     

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

     

       18
       13
        
       

     

       19
       19
       -
       (* Define a capitalize tool *)

     

       20
       20
       -
       let _ = CapitalizeServer.tool

     

       21
       21
       -
         ~name:(Some "capitalize")

     

       14
       14
       +
       (* Create a server *)

     

       15
       15
       +
       let server = create_server 

     

       16
       16
       +
         ~name:"OCaml MCP Capitalizer" 

     

       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 "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

     

       37
       37
       +
       

     

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

     

       39
       39
       +
       let _ = add_tool server

     

       40
       40
       +
         ~name:"capitalize"

     

       22
       41
        
         ~description:"Capitalizes the provided text"

     

       23
       42
        
         ~schema_properties:[

     

       24
       43
        
           ("text", "string", "The text to capitalize")

     
···

       41
       60
        
             }

     

       42
       61
        
         )

     

       43
       62
        
       

     

       44
       44
       -
       (* Define a resource example *)

     

       45
       45
       -
       let _ = CapitalizeServer.resource

     

       46
       46
       -
         ~uri_template:(Some "greeting://{name}")

     

       63
       63
       +
       (* Define and register a resource example *)

     

       64
       64
       +
       let _ = add_resource server

     

       65
       65
       +
         ~uri_template:"greeting://{name}"

     

       47
       66
        
         ~description:"Get a greeting for a name"

     

       48
       67
        
         ~mime_type:"text/plain"

     

       49
       68
        
         (fun params ->

     
···

       52
       71
        
           | _ -> "Hello, world! Welcome to the OCaml MCP server."

     

       53
       72
        
         )

     

       54
       73
        
       

     

       55
       55
       -
       (* Define a prompt example *)

     

       56
       56
       -
       let _ = CapitalizeServer.prompt

     

       57
       57
       -
         ~name:(Some "capitalize-prompt")

     

       74
       74
       +
       (* Define and register a prompt example *)

     

       75
       75
       +
       let _ = add_prompt server

     

       76
       76
       +
         ~name:"capitalize-prompt"

     

       58
       77
        
         ~description:"A prompt to help with text capitalization"

     

       59
       78
        
         ~arguments:[

     

       60
       79
        
           ("text", Some "The text to be capitalized", true)

     
···

       86
       105
        
           ]

     

       87
       106
        
         )

     

       88
       107
        
       

     

       89
       89
       -
       (* Define startup and shutdown hooks *)

     

       90
       90
       -
       let startup () =

     

       91
       91
       -
         Printf.printf "CapitalizeServer is starting up!\n";

     

       92
       92
       -
         flush stdout;

     

       93
       93
       -
         Log.info "CapitalizeServer is starting up!"

     

       94
       94
       -
       

     

       95
       95
       -
       let shutdown () =

     

       96
       96
       -
         Printf.printf "CapitalizeServer is shutting down. Goodbye!\n";

     

       97
       97
       -
         flush stdout;

     

       98
       98
       -
         Log.info "CapitalizeServer is shutting down. Goodbye!"

     

       99
       99
       -
       

     

       100
       108
        
       (* Main function *)

     

       101
       109
        
       let () =

     

       102
       102
       -
         (* Print directly to ensure we see output *)

     

       103
       103
       -
         Printf.printf "Starting CapitalizeServer...\n";

     

       104
       104
       -
         flush stdout;

     

       105
       105
       -
         

     

       106
       106
       -
         (* Run the server with all our registered capabilities *)

     

       107
       107
       -
         let server_with_hooks = { CapitalizeServer.server with 

     

       108
       108
       -
           Server.startup_hook = Some startup;

     

       109
       109
       -
           Server.shutdown_hook = Some shutdown;

     

       110
       110
       -
         } in

     

       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...";

     

       111
       123
        
         

     

       112
       112
       -
         (* Run the startup hook directly *)

     

       113
       113
       -
         (match server_with_hooks.Server.startup_hook with

     

       114
       114
       -
          | Some hook -> hook()

     

       115
       115
       -
          | None -> ());

     

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

     

       125
       125
       +
         ignore (configure_server server ());

     

       116
       126
        
         

     

       117
       117
       -
         (* Now run the server *)

     

       118
       118
       -
         Server.run server_with_hooks
     

       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

+36 -2

bin/dune

···

       1
       1
        
       (executable

     

       2
       2
        
        (name server)

     

       3
       3
       -
        (libraries mcp yojson unix))

     

       3
       3
       +
        (libraries mcp yojson unix)

     

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

     

       4
       5
        
       

     

       5
       6
        
       (executable

     

       6
       7
        
        (name capitalize_sdk)

     

       7
       8
        
        (modules capitalize_sdk)

     

       8
       8
       -
        (libraries mcp mcp_sdk yojson unix))
     

       9
       9
       +
        (libraries mcp mcp_sdk mcp_server yojson unix)

     

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

     

       11
       11
       +
       

     

       12
       12
       +
       (executable

     

       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)))

     

       17
       17
       +
       

     

       18
       18
       +
       (executable

     

       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;

+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

lib/dune

···

       8
       8
        
         (libraries mcp jsonrpc unix yojson)

     

       9
       9
        
         (modules mcp_sdk)

     

       10
       10
        
         (flags (:standard -w -67 -w -27 -w -32)))

     

       11
       11
       +
       

     

       12
       12
       +
       (library

     

       13
       13
       +
         (name mcp_server)

     

       14
       14
       +
         (libraries mcp mcp_sdk jsonrpc unix yojson)

     

       15
       15
       +
         (modules mcp_server)

     

       16
       16
       +
         (flags (:standard -w -67 -w -27 -w -32 -w -8 -w -11 -w -33)))

+460 -1

lib/mcp.ml

···

       1
       1
        
       open Jsonrpc

     

       2
       2
        
       

     

       3
       3
       +
       (* Standard error codes *)

     

       4
       4
       +
       module ErrorCode = struct

     

       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

     

       13
       13
       +
       end

     

       14
       14
       +
       

     

       3
       15
        
       (* Common types *)

     

       4
       16
        
       

     

       5
       17
        
       module Role = struct

     
···

       157
       169
        
           | j -> raise (Json.Of_json ("Expected object for ImageContent", j))

     

       158
       170
        
       end

     

       159
       171
        
       

     

       172
       172
       +
       module AudioContent = struct

     

       173
       173
       +
         type t = {

     

       174
       174
       +
           data: string;

     

       175
       175
       +
           mime_type: string;

     

       176
       176
       +
           annotations: Annotated.annotation option;

     

       177
       177
       +
         }

     

       178
       178
       +
       

     

       179
       179
       +
         let yojson_of_t { data; mime_type; annotations } =

     

       180
       180
       +
           let assoc = [

     

       181
       181
       +
             ("data", `String data);

     

       182
       182
       +
             ("mimeType", `String mime_type);

     

       183
       183
       +
             ("type", `String "audio");

     

       184
       184
       +
           ] in

     

       185
       185
       +
           let assoc = match annotations with

     

       186
       186
       +
             | Some annotations -> ("annotations", Annotated.yojson_of_annotation annotations) :: assoc

     

       187
       187
       +
             | None -> assoc

     

       188
       188
       +
           in

     

       189
       189
       +
           `Assoc assoc

     

       190
       190
       +
       

     

       191
       191
       +
         let t_of_yojson = function

     

       192
       192
       +
           | `Assoc fields ->

     

       193
       193
       +
             let data = match List.assoc_opt "data" fields with

     

       194
       194
       +
               | Some (`String s) -> s

     

       195
       195
       +
               | _ -> raise (Json.Of_json ("Missing or invalid 'data' field", `Assoc fields))

     

       196
       196
       +
             in

     

       197
       197
       +
             let mime_type = match List.assoc_opt "mimeType" fields with

     

       198
       198
       +
               | Some (`String s) -> s

     

       199
       199
       +
               | _ -> raise (Json.Of_json ("Missing or invalid 'mimeType' field", `Assoc fields))

     

       200
       200
       +
             in

     

       201
       201
       +
             let _ = match List.assoc_opt "type" fields with

     

       202
       202
       +
               | Some (`String "audio") -> ()

     

       203
       203
       +
               | _ -> raise (Json.Of_json ("Missing or invalid 'type' field", `Assoc fields))

     

       204
       204
       +
             in

     

       205
       205
       +
             let annotations = List.assoc_opt "annotations" fields |> Option.map Annotated.annotation_of_yojson in

     

       206
       206
       +
             { data; mime_type; annotations }

     

       207
       207
       +
           | j -> raise (Json.Of_json ("Expected object for AudioContent", j))

     

       208
       208
       +
       end

     

       209
       209
       +
       

     

       160
       210
        
       module ResourceContents = struct

     

       161
       211
        
         type t = {

     

       162
       212
        
           uri: string;

     
···

       301
       351
        
           | j -> raise (Json.Of_json ("Expected object for EmbeddedResource", j))

     

       302
       352
        
       end

     

       303
       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
       +
       

     

       304
       391
        
       type content = 

     

       305
       392
        
         | Text of TextContent.t

     

       306
       393
        
         | Image of ImageContent.t

     

       394
       394
       +
         | Audio of AudioContent.t

     

       307
       395
        
         | Resource of EmbeddedResource.t

     

       308
       396
        
       

     

       309
       397
        
       let yojson_of_content = function

     

       310
       398
        
         | Text t -> TextContent.yojson_of_t t

     

       311
       399
        
         | Image i -> ImageContent.yojson_of_t i

     

       400
       400
       +
         | Audio a -> AudioContent.yojson_of_t a

     

       312
       401
        
         | Resource r -> EmbeddedResource.yojson_of_t r

     

       313
       402
        
       

     

       314
       403
        
       let content_of_yojson = function

     
···

       316
       405
        
           (match List.assoc_opt "type" fields with

     

       317
       406
        
            | Some (`String "text") -> Text (TextContent.t_of_yojson (`Assoc fields))

     

       318
       407
        
            | Some (`String "image") -> Image (ImageContent.t_of_yojson (`Assoc fields))

     

       408
       408
       +
            | Some (`String "audio") -> Audio (AudioContent.t_of_yojson (`Assoc fields))

     

       319
       409
        
            | Some (`String "resource") -> Resource (EmbeddedResource.t_of_yojson (`Assoc fields))

     

       320
       410
        
            | _ -> raise (Json.Of_json ("Invalid or missing content type", `Assoc fields)))

     

       321
       411
        
         | j -> raise (Json.Of_json ("Expected object for content", j))

     

       322
       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
       +
       

     

       323
       771
        
       (* Message types *)

     

       324
       772
        
       

     

       325
       773
        
       module PromptMessage = struct

     
···

       411
       859
        
       end

     

       412
       860
        
       

     

       413
       861
        
       (* JSONRPC Message types *)

     

       862
       862
       +
       

     

       414
       863
        
       

     

       415
       864
        
       module JSONRPCMessage = struct

     

       416
       865
        
         type notification = {

     
···

       745
       1194
        
       let create_notification = JSONRPCMessage.create_notification

     

       746
       1195
        
       let create_request = JSONRPCMessage.create_request

     

       747
       1196
        
       let create_response = JSONRPCMessage.create_response

     

       748
       748
       -
       let create_error = JSONRPCMessage.create_error
     

       1197
       1197
       +
       let create_error = JSONRPCMessage.create_error

     

       1198
       1198
       +
       

     

       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

+156 -1

lib/mcp.mli

···

       2
       2
        
       

     

       3
       3
        
       open Jsonrpc

     

       4
       4
        
       

     

       5
       5
       +
       (** Standard error codes *)

     

       6
       6
       +
       module ErrorCode : sig

     

       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

     

       15
       15
       +
       end

     

       16
       16
       +
       

     

       5
       17
        
       (** Common types *)

     

       6
       18
        
       

     

       7
       19
        
       (** Roles for conversation participants *)

     
···

       77
       89
        
         val t_of_yojson : Json.t -> t

     

       78
       90
        
       end

     

       79
       91
        
       

     

       92
       92
       +
       (** Audio content *)

     

       93
       93
       +
       module AudioContent : sig

     

       94
       94
       +
         type t = {

     

       95
       95
       +
           data: string;

     

       96
       96
       +
           mime_type: string;

     

       97
       97
       +
           annotations: Annotated.annotation option;

     

       98
       98
       +
         }

     

       99
       99
       +
       

     

       100
       100
       +
         val yojson_of_t : t -> Json.t

     

       101
       101
       +
         val t_of_yojson : Json.t -> t

     

       102
       102
       +
       end

     

       103
       103
       +
       

     

       80
       104
        
       (** Base resource contents *)

     

       81
       105
        
       module ResourceContents : sig

     

       82
       106
        
         type t = {

     
···

       127
       151
        
       type content = 

     

       128
       152
        
         | Text of TextContent.t

     

       129
       153
        
         | Image of ImageContent.t

     

       154
       154
       +
         | Audio of AudioContent.t

     

       130
       155
        
         | Resource of EmbeddedResource.t

     

       131
       156
        
       

     

       132
       157
        
       val yojson_of_content : content -> Json.t

     
···

       265
       290
        
         end

     

       266
       291
        
       end

     

       267
       292
        
       

     

       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
       +
         }

     

       300
       300
       +
       

     

       301
       301
       +
         val yojson_of_t : t -> Json.t

     

       302
       302
       +
         val t_of_yojson : Json.t -> t

     

       303
       303
       +
       end

     

       304
       304
       +
       

     

       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

     

       316
       316
       +
       

     

       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
       +
         }

     

       327
       327
       +
       

     

       328
       328
       +
         val yojson_of_t : t -> Json.t

     

       329
       329
       +
         val t_of_yojson : Json.t -> t

     

       330
       330
       +
       end

     

       331
       331
       +
       

     

       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

     

       395
       395
       +
       

     

       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

     

       418
       418
       +
       

     

       268
       419
        
       (** Parse a JSON message into an MCP message *)

     

       269
       420
        
       val parse_message : Json.t -> JSONRPCMessage.t

     

       270
       421
        
       

     
···

       272
       423
        
       val create_notification : ?params:Json.t option -> method_:string -> unit -> JSONRPCMessage.t

     

       273
       424
        
       val create_request : ?params:Json.t option -> ?progress_token:ProgressToken.t option -> id:RequestId.t -> method_:string -> unit -> JSONRPCMessage.t

     

       274
       425
        
       val create_response : id:RequestId.t -> result:Json.t -> JSONRPCMessage.t

     

       275
       275
       -
       val create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> JSONRPCMessage.t
     

       426
       426
       +
       val create_error : id:RequestId.t -> code:int -> message:string -> ?data:Json.t option -> unit -> JSONRPCMessage.t

     

       427
       427
       +
       

     

       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

+248 -194

lib/mcp_sdk.ml

···

       16
       16
        
       

     

       17
       17
        
         let log level msg =

     

       18
       18
        
           Printf.eprintf "[%s] %s\n" (string_of_level level) msg;

     

       19
       19
       -
           flush stderr;

     

       20
       20
       -
           Printf.printf "[%s] %s\n" (string_of_level level) msg;

     

       21
       21
       -
           flush stdout

     

       19
       19
       +
           flush stderr

     

       22
       20
        
       

     

       23
       21
        
         let debug = log Debug

     

       24
       22
        
         let info = log Info

     
···

       42
       40
        
         

     

       43
       41
        
         let report_progress ctx value total =

     

       44
       42
        
           match ctx.progress_token, ctx.request_id with

     

       45
       45
       -
           | Some token, Some id ->

     

       43
       43
       +
           | Some token, Some _id ->

     

       46
       44
        
             let params = `Assoc [

     

       47
       45
        
               ("progress", `Float value);

     

       48
       46
        
               ("total", `Float total);

     
···

       135
       133
        
         let create_argument ~name ?description ?(required=false) () =

     

       136
       134
        
           { name; description; required }

     

       137
       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
       +
       

     

       138
       168
        
         let to_json prompt =

     

       139
       169
        
           let assoc = [

     

       140
       170
        
             ("name", `String prompt.name);

     
···

       171
       201
        
       let make_text_content text =

     

       172
       202
        
         Text (TextContent.{ text; annotations = None })

     

       173
       203
        
       

     

       204
       204
       +
       let make_text_content_with_annotations text annotations =

     

       205
       205
       +
         Text (TextContent.{ text; annotations = Some annotations })

     

       206
       206
       +
       

     

       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
       +
         })

     

       224
       224
       +
       

     

       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
       +
         })

     

       230
       230
       +
       

     

       174
       231
        
       let make_tool_schema properties required =

     

       175
       232
        
         let props = List.map (fun (name, schema_type, description) ->

     

       176
       233
        
           (name, `Assoc [

     
···

       185
       242
        
           ("required", required_json)

     

       186
       243
        
         ]

     

       187
       244
        
       

     

       188
       188
       -
       (* Server implementation *)

     

       189
       189
       -
       module Server = struct

     

       190
       190
       -
         type startup_hook = unit -> unit

     

       191
       191
       -
         type shutdown_hook = unit -> unit

     

       245
       245
       +
       (* Main server type *)

     

       246
       246
       +
       type server = {

     

       247
       247
       +
         name: string;

     

       248
       248
       +
         version: string;

     

       249
       249
       +
         protocol_version: string;

     

       250
       250
       +
         mutable capabilities: Json.t;

     

       251
       251
       +
         mutable tools: Tool.t list;

     

       252
       252
       +
         mutable resources: Resource.t list;

     

       253
       253
       +
         mutable prompts: Prompt.t list;

     

       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
       +
       }

     

       192
       258
        
       

     

       193
       193
       -
         type t = {

     

       194
       194
       -
           name: string;

     

       195
       195
       -
           version: string;

     

       196
       196
       -
           protocol_version: string;

     

       197
       197
       -
           mutable capabilities: Json.t;

     

       198
       198
       -
           mutable tools: Tool.t list;

     

       199
       199
       -
           mutable resources: Resource.t list;

     

       200
       200
       -
           mutable prompts: Prompt.t list;

     

       201
       201
       -
           mutable lifespan_context: (string * Json.t) list;

     

       202
       202
       -
           startup_hook: startup_hook option;

     

       203
       203
       -
           shutdown_hook: shutdown_hook option;

     

       259
       259
       +
       (* Create a new server *)

     

       260
       260
       +
       let create_server ~name ?(version="0.1.0") ?(protocol_version="2024-11-05") () =

     

       261
       261
       +
         { 

     

       262
       262
       +
           name;

     

       263
       263
       +
           version;

     

       264
       264
       +
           protocol_version;

     

       265
       265
       +
           capabilities = `Assoc [];

     

       266
       266
       +
           tools = [];

     

       267
       267
       +
           resources = [];

     

       268
       268
       +
           prompts = [];

     

       269
       269
       +
           lifespan_context = [];

     

       270
       270
       +
           startup_hook = None;

     

       271
       271
       +
           shutdown_hook = None;

     

       204
       272
        
         }

     

       205
       273
        
       

     

       206
       206
       -
         let create ~name ?(version="0.1.0") ?(protocol_version="2024-11-05") ?startup_hook ?shutdown_hook () =

     

       207
       207
       -
           { 

     

       208
       208
       -
             name;

     

       209
       209
       -
             version;

     

       210
       210
       -
             protocol_version;

     

       211
       211
       -
             capabilities = `Assoc [];

     

       212
       212
       -
             tools = [];

     

       213
       213
       -
             resources = [];

     

       214
       214
       -
             prompts = [];

     

       215
       215
       -
             lifespan_context = [];

     

       216
       216
       -
             startup_hook;

     

       217
       217
       -
             shutdown_hook;

     

       218
       218
       -
           }

     

       274
       274
       +
       (* Default capabilities for the server *)

     

       275
       275
       +
       let default_capabilities ?(with_tools=true) ?(with_resources=false) ?(with_prompts=false) () =

     

       276
       276
       +
         let caps = [] in

     

       277
       277
       +
         let caps = 

     

       278
       278
       +
           if with_tools then

     

       279
       279
       +
             ("tools", `Assoc [

     

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

     

       281
       281
       +
             ]) :: caps

     

       282
       282
       +
           else

     

       283
       283
       +
             caps

     

       284
       284
       +
         in

     

       285
       285
       +
         let caps = 

     

       286
       286
       +
           if with_resources then

     

       287
       287
       +
             ("resources", `Assoc [

     

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

     

       289
       289
       +
               ("subscribe", `Bool false)

     

       290
       290
       +
             ]) :: caps

     

       291
       291
       +
           else if not with_resources then

     

       292
       292
       +
             ("resources", `Assoc [

     

       293
       293
       +
               ("listChanged", `Bool false);

     

       294
       294
       +
               ("subscribe", `Bool false)

     

       295
       295
       +
             ]) :: caps

     

       296
       296
       +
           else

     

       297
       297
       +
             caps

     

       298
       298
       +
         in

     

       299
       299
       +
         let caps = 

     

       300
       300
       +
           if with_prompts then

     

       301
       301
       +
             ("prompts", `Assoc [

     

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

     

       303
       303
       +
             ]) :: caps

     

       304
       304
       +
           else if not with_prompts then

     

       305
       305
       +
             ("prompts", `Assoc [

     

       306
       306
       +
               ("listChanged", `Bool false)

     

       307
       307
       +
             ]) :: caps

     

       308
       308
       +
           else

     

       309
       309
       +
             caps

     

       310
       310
       +
         in

     

       311
       311
       +
         `Assoc caps

     

       219
       312
        
       

     

       220
       220
       -
         (* Register a tool *)

     

       221
       221
       -
         let register_tool server tool =

     

       222
       222
       -
           server.tools <- tool :: server.tools;

     

       223
       223
       -
           ()

     

       313
       313
       +
       (* Register a tool *)

     

       314
       314
       +
       let register_tool server tool =

     

       315
       315
       +
         server.tools <- tool :: server.tools;

     

       316
       316
       +
         tool

     

       224
       317
        
       

     

       225
       225
       -
         (* Register a resource *)

     

       226
       226
       -
         let register_resource server resource =

     

       227
       227
       -
           server.resources <- resource :: server.resources;

     

       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

     

       321
       321
       +
         let handler' ctx args =

     

       322
       322
       +
           try

     

       323
       323
       +
             Ok (handler args)

     

       324
       324
       +
           with exn ->

     

       325
       325
       +
             Error (Printexc.to_string exn)

     

       326
       326
       +
         in

     

       327
       327
       +
         let tool = Tool.create

     

       328
       328
       +
           ~name

     

       329
       329
       +
           ?description

     

       330
       330
       +
           ~input_schema

     

       331
       331
       +
           ~handler:handler'

     

       228
       332
        
           ()

     

       333
       333
       +
         in

     

       334
       334
       +
         register_tool server tool

     

       229
       335
        
       

     

       230
       230
       -
         (* Register a prompt *)

     

       231
       231
       -
         let register_prompt server prompt =

     

       232
       232
       -
           server.prompts <- prompt :: server.prompts;

     

       336
       336
       +
       (* Register a resource *)

     

       337
       337
       +
       let register_resource server resource =

     

       338
       338
       +
         server.resources <- resource :: server.resources;

     

       339
       339
       +
         resource

     

       340
       340
       +
       

     

       341
       341
       +
       (* Create and register a resource in one step *)

     

       342
       342
       +
       let add_resource server ~uri_template ?description ?mime_type handler =

     

       343
       343
       +
         let handler' _ctx params =

     

       344
       344
       +
           try

     

       345
       345
       +
             Ok (handler params)

     

       346
       346
       +
           with exn ->

     

       347
       347
       +
             Error (Printexc.to_string exn)

     

       348
       348
       +
         in

     

       349
       349
       +
         let resource = Resource.create

     

       350
       350
       +
           ~uri_template

     

       351
       351
       +
           ?description

     

       352
       352
       +
           ?mime_type

     

       353
       353
       +
           ~handler:handler'

     

       233
       354
        
           ()

     

       234
       234
       -
         

     

       235
       235
       -
         (* Default server capabilities *)

     

       236
       236
       -
         let default_capabilities ?(with_tools=true) ?(with_resources=false) ?(with_prompts=false) () =

     

       237
       237
       -
           let caps = [] in

     

       238
       238
       -
           let caps = 

     

       239
       239
       -
             if with_tools then

     

       240
       240
       -
               ("tools", `Assoc [

     

       241
       241
       -
                 ("listChanged", `Bool true)

     

       242
       242
       -
               ]) :: caps

     

       243
       243
       -
             else

     

       244
       244
       -
               caps

     

       245
       245
       -
           in

     

       246
       246
       -
           let caps = 

     

       247
       247
       -
             if with_resources then

     

       248
       248
       -
               ("resources", `Assoc [

     

       249
       249
       -
                 ("listChanged", `Bool true);

     

       250
       250
       -
                 ("subscribe", `Bool false)

     

       251
       251
       -
               ]) :: caps

     

       252
       252
       -
             else if not with_resources then

     

       253
       253
       -
               ("resources", `Assoc [

     

       254
       254
       -
                 ("listChanged", `Bool false);

     

       255
       255
       -
                 ("subscribe", `Bool false)

     

       256
       256
       -
               ]) :: caps

     

       257
       257
       -
             else

     

       258
       258
       -
               caps

     

       259
       259
       -
           in

     

       260
       260
       -
           let caps = 

     

       261
       261
       -
             if with_prompts then

     

       262
       262
       -
               ("prompts", `Assoc [

     

       263
       263
       -
                 ("listChanged", `Bool true)

     

       264
       264
       -
               ]) :: caps

     

       265
       265
       -
             else if not with_prompts then

     

       266
       266
       -
               ("prompts", `Assoc [

     

       267
       267
       -
                 ("listChanged", `Bool false)

     

       268
       268
       -
               ]) :: caps

     

       269
       269
       -
             else

     

       270
       270
       -
               caps

     

       271
       271
       -
           in

     

       272
       272
       -
           `Assoc caps

     

       355
       355
       +
         in

     

       356
       356
       +
         register_resource server resource

     

       273
       357
        
       

     

       274
       274
       -
         (* Update server capabilities *)

     

       275
       275
       -
         let update_capabilities server capabilities =

     

       276
       276
       -
           server.capabilities <- capabilities

     

       358
       358
       +
       (* Register a prompt *)

     

       359
       359
       +
       let register_prompt server prompt =

     

       360
       360
       +
         server.prompts <- prompt :: server.prompts;

     

       361
       361
       +
         prompt

     

       277
       362
        
       

     

       278
       278
       -
         (* Process a message *)

     

       279
       279
       -
         let process_message _server _json =

     

       280
       280
       -
           None

     

       281
       281
       -
         

     

       282
       282
       -
         (* Main server loop *)

     

       283
       283
       -
         let run _server =

     

       284
       284
       -
           (* Placeholder implementation *)

     

       363
       363
       +
       (* Create and register a prompt in one step *)

     

       364
       364
       +
       let add_prompt server ~name ?description ?(arguments=[]) handler =

     

       365
       365
       +
         let prompt_args = List.map (fun (name, desc, required) ->

     

       366
       366
       +
           Prompt.create_argument ~name ?description:desc ~required ()

     

       367
       367
       +
         ) arguments in

     

       368
       368
       +
         let handler' _ctx args =

     

       369
       369
       +
           try

     

       370
       370
       +
             Ok (handler args)

     

       371
       371
       +
           with exn ->

     

       372
       372
       +
             Error (Printexc.to_string exn)

     

       373
       373
       +
         in

     

       374
       374
       +
         let prompt = Prompt.create

     

       375
       375
       +
           ~name

     

       376
       376
       +
           ?description

     

       377
       377
       +
           ~arguments:prompt_args

     

       378
       378
       +
           ~handler:handler'

     

       285
       379
        
           ()

     

       286
       286
       -
       end

     

       380
       380
       +
         in

     

       381
       381
       +
         register_prompt server prompt

     

       382
       382
       +
       

     

       383
       383
       +
       (* Set server capabilities *)

     

       384
       384
       +
       let set_capabilities server capabilities =

     

       385
       385
       +
         server.capabilities <- capabilities

     

       386
       386
       +
       

     

       387
       387
       +
       (* Configure server with default capabilities based on registered components *)

     

       388
       388
       +
       let configure_server server ?with_tools ?with_resources ?with_prompts () =

     

       389
       389
       +
         let with_tools = match with_tools with

     

       390
       390
       +
           | Some b -> b

     

       391
       391
       +
           | None -> server.tools <> []

     

       392
       392
       +
         in

     

       393
       393
       +
         let with_resources = match with_resources with

     

       394
       394
       +
           | Some b -> b

     

       395
       395
       +
           | None -> server.resources <> []

     

       396
       396
       +
         in

     

       397
       397
       +
         let with_prompts = match with_prompts with

     

       398
       398
       +
           | Some b -> b

     

       399
       399
       +
           | None -> server.prompts <> []

     

       400
       400
       +
         in

     

       401
       401
       +
         let capabilities = default_capabilities ~with_tools ~with_resources ~with_prompts () in

     

       402
       402
       +
         set_capabilities server capabilities;

     

       403
       403
       +
         server

     

       404
       404
       +
       

     

       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

     

       287
       411
        
       

     

       288
       288
       -
       (* Helper function for default capabilities *)

     

       289
       289
       -
       let default_capabilities = Server.default_capabilities

     

       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 *)

     

       290
       416
        
       

     

       291
       291
       -
       (* Add syntactic sugar for creating a server *)

     

       292
       292
       -
       module MakeServer(S: sig val name: string val version: string option end) = struct

     

       293
       293
       -
         let _config = (S.name, S.version) (* Used to prevent unused parameter warning *)

     

       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 -> ());

     

       294
       434
        
         

     

       295
       295
       -
         (* Create server *)

     

       296
       296
       -
         let server = Server.create 

     

       297
       297
       -
           ~name:S.name 

     

       298
       298
       -
           ?version:S.version 

     

       299
       299
       -
           ~protocol_version:"2024-11-05" 

     

       300
       300
       -
           ()

     

       301
       301
       -
           

     

       302
       302
       -
         (* Create a tool *)

     

       303
       303
       -
         let tool ?name ?description ?(schema_properties=[]) ?(schema_required=[]) handler =

     

       304
       304
       -
           let name = match name with 

     

       305
       305
       -
                      | Some (Some n) -> n 

     

       306
       306
       -
                      | Some None | None -> "tool" in

     

       307
       307
       -
           let input_schema = make_tool_schema schema_properties schema_required in

     

       308
       308
       -
           let handler' ctx args =

     

       309
       309
       -
             try

     

       310
       310
       -
               Ok (handler args)

     

       311
       311
       -
             with exn ->

     

       312
       312
       -
               Error (Printexc.to_string exn)

     

       313
       313
       -
           in

     

       314
       314
       -
           let tool = Tool.create

     

       315
       315
       -
             ~name

     

       316
       316
       -
             ?description

     

       317
       317
       -
             ~input_schema

     

       318
       318
       -
             ~handler:handler'

     

       319
       319
       -
             ()

     

       320
       320
       -
           in

     

       321
       321
       -
           server.tools <- tool :: server.tools;

     

       322
       322
       -
           tool

     

       323
       323
       -
           

     

       324
       324
       -
         (* Create a resource *)

     

       325
       325
       -
         let resource ?uri_template ?description ?mime_type handler =

     

       326
       326
       -
           let uri_template = match uri_template with 

     

       327
       327
       -
                             | Some (Some uri) -> uri 

     

       328
       328
       -
                             | Some None | None -> "resource://" in

     

       329
       329
       -
           let handler' ctx params =

     

       330
       330
       -
             try

     

       331
       331
       -
               Ok (handler params)

     

       332
       332
       -
             with exn ->

     

       333
       333
       -
               Error (Printexc.to_string exn)

     

       334
       334
       -
           in

     

       335
       335
       -
           let resource = Resource.create

     

       336
       336
       -
             ~uri_template

     

       337
       337
       -
             ?description

     

       338
       338
       -
             ?mime_type

     

       339
       339
       -
             ~handler:handler'

     

       340
       340
       -
             ()

     

       341
       341
       -
           in

     

       342
       342
       -
           server.resources <- resource :: server.resources;

     

       343
       343
       -
           resource

     

       344
       344
       -
           

     

       345
       345
       -
         (* Create a prompt *)

     

       346
       346
       -
         let prompt ?name ?description ?(arguments=[]) handler =

     

       347
       347
       -
           let name = match name with 

     

       348
       348
       -
                     | Some (Some n) -> n 

     

       349
       349
       -
                     | Some None | None -> "prompt" in

     

       350
       350
       -
           let prompt_args = List.map (fun (name, desc, required) ->

     

       351
       351
       -
             Prompt.create_argument ~name ?description:desc ~required ()

     

       352
       352
       -
           ) arguments in

     

       353
       353
       -
           let handler' ctx args =

     

       354
       354
       -
             try

     

       355
       355
       -
               Ok (handler args)

     

       356
       356
       -
             with exn ->

     

       357
       357
       -
               Error (Printexc.to_string exn)

     

       358
       358
       -
           in

     

       359
       359
       -
           let prompt = Prompt.create

     

       360
       360
       -
             ~name

     

       361
       361
       -
             ?description

     

       362
       362
       -
             ~arguments:prompt_args

     

       363
       363
       -
             ~handler:handler'

     

       364
       364
       -
             ()

     

       365
       365
       -
           in

     

       366
       366
       -
           server.prompts <- prompt :: server.prompts;

     

       367
       367
       -
           prompt

     

       368
       368
       -
           

     

       369
       369
       -
         (* Run the server *)

     

       370
       370
       -
         let run ?with_tools ?with_resources ?with_prompts () =

     

       371
       371
       -
           let with_tools = match with_tools with

     

       372
       372
       -
             | Some b -> b

     

       373
       373
       -
             | None -> server.tools <> []

     

       374
       374
       -
           in

     

       375
       375
       -
           let with_resources = match with_resources with

     

       376
       376
       -
             | Some b -> b

     

       377
       377
       -
             | None -> server.resources <> []

     

       378
       378
       -
           in

     

       379
       379
       -
           let with_prompts = match with_prompts with

     

       380
       380
       -
             | Some b -> b

     

       381
       381
       -
             | None -> server.prompts <> []

     

       382
       382
       -
           in

     

       383
       383
       -
           let capabilities = Server.default_capabilities ~with_tools ~with_resources ~with_prompts () in

     

       384
       384
       -
           server.capabilities <- capabilities;

     

       385
       385
       -
           Log.info "Starting server...";

     

       386
       386
       -
           Log.info (Printf.sprintf "Server info: %s v%s" server.name 

     

       387
       387
       -
                     (match S.version with Some v -> v | None -> "unknown"));

     

       388
       388
       -
           Printexc.record_backtrace true;

     

       389
       389
       -
           set_binary_mode_out stdout false;

     

       390
       390
       -
           Log.info "This is just a placeholder server implementation."

     

       391
       391
       -
       end
     

       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

+67 -40

lib/mcp_sdk.mli

···

       86
       86
        
       

     

       87
       87
        
         val create : name:string -> ?description:string -> ?arguments:argument list -> handler:handler -> unit -> t

     

       88
       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

     

       89
       91
        
         val to_json : t -> Json.t

     

       90
       92
        
       end

     

       91
       93
        
       

     

       92
       92
       -
       (** Server implementation *)

     

       93
       93
       -
       module Server : sig

     

       94
       94
       -
         type startup_hook = unit -> unit

     

       95
       95
       -
         type shutdown_hook = unit -> unit

     

       94
       94
       +
       (** Main server type *)

     

       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
       +
       }

     

       107
       107
       +
       

     

       108
       108
       +
       (** Create a new server *)

     

       109
       109
       +
       val create_server : name:string -> ?version:string -> ?protocol_version:string -> unit -> server

     

       110
       110
       +
       

     

       111
       111
       +
       (** Default capabilities for the server *)

     

       112
       112
       +
       val default_capabilities : ?with_tools:bool -> ?with_resources:bool -> ?with_prompts:bool -> unit -> Json.t

     

       113
       113
       +
       

     

       114
       114
       +
       (** Register a tool with the server *)

     

       115
       115
       +
       val register_tool : server -> Tool.t -> Tool.t

     

       116
       116
       +
       

     

       117
       117
       +
       (** Create and register a tool in one step *)

     

       118
       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

     

       119
       119
       +
       

     

       120
       120
       +
       (** Register a resource with the server *)

     

       121
       121
       +
       val register_resource : server -> Resource.t -> Resource.t

     

       122
       122
       +
       

     

       123
       123
       +
       (** Create and register a resource in one step *)

     

       124
       124
       +
       val add_resource : server -> uri_template:string -> ?description:string -> ?mime_type:string -> (string list -> string) -> Resource.t

     

       125
       125
       +
       

     

       126
       126
       +
       (** Register a prompt with the server *)

     

       127
       127
       +
       val register_prompt : server -> Prompt.t -> Prompt.t

     

       128
       128
       +
       

     

       129
       129
       +
       (** Create and register a prompt in one step *)

     

       130
       130
       +
       val add_prompt : server -> name:string -> ?description:string -> ?arguments:(string * string option * bool) list -> ((string * string) list -> Prompt.message list) -> Prompt.t

     

       131
       131
       +
       

     

       132
       132
       +
       (** Set server capabilities *)

     

       133
       133
       +
       val set_capabilities : server -> Json.t -> unit

     

       134
       134
       +
       

     

       135
       135
       +
       (** Configure server with default capabilities based on registered components *)

     

       136
       136
       +
       val configure_server : server -> ?with_tools:bool -> ?with_resources:bool -> ?with_prompts:bool -> unit -> server

     

       137
       137
       +
       

     

       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

     

       96
       143
        
       

     

       97
       97
       -
         type t = {

     

       98
       98
       -
           name: string;

     

       99
       99
       -
           version: string;

     

       100
       100
       -
           protocol_version: string;

     

       101
       101
       -
           mutable capabilities: Json.t;

     

       102
       102
       -
           mutable tools: Tool.t list;

     

       103
       103
       -
           mutable resources: Resource.t list;

     

       104
       104
       -
           mutable prompts: Prompt.t list;

     

       105
       105
       -
           mutable lifespan_context: (string * Json.t) list;

     

       106
       106
       -
           startup_hook: startup_hook option;

     

       107
       107
       -
           shutdown_hook: shutdown_hook option;

     

       108
       108
       -
         }

     

       144
       144
       +
       (** Run the server using stdio transport (legacy method) *)

     

       145
       145
       +
       val run_server : server -> unit

     

       109
       146
        
       

     

       110
       110
       -
         val create : name:string -> ?version:string -> ?protocol_version:string -> ?startup_hook:startup_hook -> ?shutdown_hook:shutdown_hook -> unit -> t

     

       111
       111
       -
         val register_tool : t -> Tool.t -> unit

     

       112
       112
       -
         val register_resource : t -> Resource.t -> unit

     

       113
       113
       -
         val register_prompt : t -> Prompt.t -> unit

     

       114
       114
       -
         val default_capabilities : ?with_tools:bool -> ?with_resources:bool -> ?with_prompts:bool -> unit -> Json.t

     

       115
       115
       -
         val update_capabilities : t -> Json.t -> unit

     

       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 *)

     

       116
       151
        
       

     

       117
       117
       -
         val process_message : t -> Json.t -> JSONRPCMessage.t option

     

       118
       118
       -
         val run : t -> unit

     

       119
       119
       -
       end

     

       152
       152
       +
       (** Create and start a server with the specified transport *)

     

       153
       153
       +
       val run_server_with_transport : server -> transport_type -> unit

     

       120
       154
        
       

     

       121
       155
        
       (** Helper functions for creating common objects *)

     

       122
       156
        
       val make_text_content : string -> content

     

       123
       123
       -
       val make_tool_schema : (string * string * string) list -> string list -> Json.t

     

       124
       124
       -
       

     

       125
       125
       -
       (** Syntax sugar for creating an MCP server *)

     

       126
       126
       -
       module MakeServer : functor (S : sig

     

       127
       127
       -
         val name : string

     

       128
       128
       -
         val version : string option

     

       129
       129
       -
       end) -> sig

     

       130
       130
       -
         val _config : string * string option  (* Used to prevent unused parameter warning *)

     

       131
       131
       -
         val server : Server.t

     

       132
       132
       -
       

     

       133
       133
       -
         val tool : ?name:string option -> ?description:string -> ?schema_properties:(string * string * string) list -> ?schema_required:string list -> (Json.t -> Json.t) -> Tool.t

     

       134
       134
       -
         val resource : ?uri_template:string option -> ?description:string -> ?mime_type:string -> (string list -> string) -> Resource.t

     

       135
       135
       -
         val prompt : ?name:string option -> ?description:string -> ?arguments:(string * string option * bool) list -> ((string * string) list -> Prompt.message list) -> Prompt.t

     

       136
       136
       -
         val run : ?with_tools:bool -> ?with_resources:bool -> ?with_prompts:bool -> unit -> unit

     

       137
       137
       -
       end
     

       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

+533

lib/mcp_server.ml

···

       1
       1
       +
       open Mcp

     

       2
       2
       +
       open Mcp_sdk

     

       3
       3
       +
       

     

       4
       4
       +
       (* MCP Server module for handling JSON-RPC communication *)

     

       5
       5
       +
       

     

       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 *)

     

       10
       10
       +
       

     

       11
       11
       +
       type t = {

     

       12
       12
       +
         server: Mcp_sdk.server;

     

       13
       13
       +
         transport: transport_type;

     

       14
       14
       +
         mutable running: bool;

     

       15
       15
       +
       }

     

       16
       16
       +
       

     

       17
       17
       +
       (** Process a single message *)

     

       18
       18
       +
       let process_message server message =

     

       19
       19
       +
         try

     

       20
       20
       +
           Log.debug "Parsing message as JSONRPC message...";

     

       21
       21
       +
           match JSONRPCMessage.t_of_yojson message with

     

       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);

     

       307
       307
       +
             None

     

       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()));

     

       312
       312
       +
             None

     

       313
       313
       +
           end

     

       314
       314
       +
       

     

       315
       315
       +
       (** Read a single message from stdin *)

     

       316
       316
       +
       let read_stdio_message () =

     

       317
       317
       +
         try

     

       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

     

       349
       349
       +
       

     

       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

     

       413
       413
       +
           end

     

       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

     

       424
       424
       +
       

     

       425
       425
       +
       (** Create an MCP server *)

     

       426
       426
       +
       let create ~server ~transport () =

     

       427
       427
       +
         { server; transport; running = false }

     

       428
       428
       +
       

     

       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

     

       495
       495
       +
       

     

       496
       496
       +
       (** Start the server based on transport type *)

     

       497
       497
       +
       let start server =

     

       498
       498
       +
         server.running <- true;

     

       499
       499
       +
         

     

       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);

     

       504
       504
       +
         

     

       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);

     

       516
       516
       +
             

     

       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

+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