OCaml MCP SDK with oxcaml_effect

An OCaml implementation of the Model Context Protocol (MCP) using Jane Street's oxcaml_effect library for algebraic effects.

Overview

This SDK provides a complete implementation of MCP using OCaml 5's effect system through Jane Street's oxcaml_effect library, which provides:

• O(1) effect dispatch using handler indices
• Typed handler lists using GADTs
• Mode annotations for safe concurrent programming (@@ portable, @ local, @ unique, @ contended)
• Efficient continuations with proper memory management

Architecture

The SDK is organized into several effect modules:

Transport Effect

Handles low-level I/O operations:

type 'a t =
  | Read : string t
  | Write : string -> unit t
  | Close : unit t

Protocol Effect

Manages JSON-RPC protocol:

type 'a t =
  | Send_request : { method_: string; params: json option } -> json t
  | Send_notification : { method_: string; params: json option } -> unit t
  | Receive_message : message t
  | Send_response : { id: json option; result: json option } -> unit t
  | Send_error : { id: json option; code: int; message: string; data: json option } -> unit t

Resource, Tool, and Prompt Effects

Implement MCP capabilities:

(* Resource operations *)
type 'a t =
  | List_resources : json list t
  | Read_resource : string -> json t

(* Tool operations *)  
type 'a t =
  | List_tools : json list t
  | Call_tool : { name: string; arguments: json option } -> json t

Usage

Creating a Client

open Ocaml_mcp_sdk

let () =
  let client_info = {
    Mcp_client.name = "My Client";
    version = "1.0.0";
  } in
  
  Mcp_client.run_client ~client_info (fun protocol_handler server_info ->
    (* List and read resources *)
    let resources = Mcp_client.list_resources_client protocol_handler in
    
    (* Call tools *)
    let result = Mcp_client.call_tool_client protocol_handler 
      ~name:"my_tool" 
      ~arguments:(Some (`Assoc [("param", `String "value")])) in
    
    Printf.printf "Result: %s\n" (Yojson.Safe.to_string result)
  )

Creating a Server

open Ocaml_mcp_sdk

let () =
  let config = {
    Mcp_server.name = "My Server";
    version = "1.0.0";
    resources = [
      ("file:///data.json", fun () ->
        `Assoc [("data", `String "Hello from OCaml")]
      );
    ];
    tools = [
      ("echo", fun args ->
        match args with
        | Some (`Assoc params) ->
            `Assoc [("echoed", List.assoc "message" params)]
        | _ -> `Assoc [("error", `String "Invalid arguments")]
      );
    ];
    prompts = [];
  } in
  
  Mcp_server.run_server config

Building

The project uses dune and requires OCaml 5.0 or later:

# Build the project
dune build

# Run examples
dune exec mcp_server_example
dune exec mcp_client_example

Implementation Details

Effect Composition

The SDK uses oxcaml_effect's typed handler lists to compose multiple effects:

Transport.fiber_with [Handler.List.Length.X; Handler.List.Length.X] 
  (fun handlers ->
    match handlers with
    | protocol_h :: resource_h :: _ ->
        (* Use handlers here *)
    | _ -> failwith "Invalid handler list"
  )

Mode Safety

The implementation leverages OCaml 5's mode system through oxcaml_effect:

• @ local - Stack-allocated values
• @ unique - Linear/affine types
• @@ portable - Thread-safe values
• @ contended - Values that may be accessed concurrently

Handler Indices

Effect dispatch is O(1) using handler indices, making the system efficient even with many active effects.

Dependencies

• OCaml >= 5.0
• dune >= 3.16
• yojson (for JSON handling)
• unix (for stdio)
• oxcaml_effect (vendored from Jane Street's with-extensions branch)

License

MIT