ocaml -sdk

This MCP server is an OCaml implementation of the Model Context Protocol (MCP) using OCaml 5's effect system via the oxcaml_effect library. It exposes a modular set of effects for transport, protocol handling, and MCP-specific capabilities such as resource and tool management. The server is designed to be run in a container (via Docker) and provides a structured interface to list and read resources, as well as call tools defined by the server. Client-side code can interact with the MCP using the provided OCaml SDK abstractions, constructing a client info object and invoking operations like list_resources_client and call_tool_client through a protocol handler that coordinates transport and protocol operations.

Typical usage involves starting the server (or attaching to a running instance in a container) and then using the OCaml MCP SDK client API to enumerate resources, read resource contents, list available tools, and execute tools with optional JSON parameters. The server emphasizes type-safe effect composition, O(1) effect dispatch via handler indices, and mode safety annotations (@ local, @ unique, @@ portable, @ contended) to support safe concurrent operation.

Prerequisites:

• Docker (for running the MCP server container)
• Alternatively, OCaml 5.x development environment with Dune and Opam if you prefer building from source
• Basic JSON handling library (Yojson) if you plan to interact directly from OCaml

Using Docker (recommended):

1. Ensure Docker is installed and running.

2. Pull and run the MCP server image:

   docker run -i bmorphism-ocaml-mcp-sdk

3. The container should expose the MCP endpoints as configured by the image. If needed, override environment variables to customize behavior (see additional_notes for common options).

Building from source (OCaml/Dune):

1. Install OCaml 5.x, Dune, and Opam.

2. Clone the repository and navigate to the project root.

3. Install dependencies and build:

   opam switch create 5.0+alt -j 4 eval $(opam env) dune build

4. Run examples (if provided by the repository) using:

   dune exec mcp_server_example dune exec mcp_client_example

Prerequisites summary: Docker for deployable runs; or OCaml 5+ with Dune/Opam for local builds.

Notes and tips:

• The server uses OCaml 5 effects with oxcaml_effect; ensure you are on OCaml 5.x to maintain compatibility.
• If you customize resources or tools, ensure proper JSON types are used (Yojson representations) to avoid encoding errors.
• When running in Docker, you may need to pass environment variables to configure endpoints, storage paths, or debugging options. Typical env vars might include MCP_RESOURCE_ROOT, MCP_TOOL_REGISTRY, or DEBUG=true (placeholders in this document).
• The architecture emphasizes O(1) dispatch via handler indices; if you extend the set of effects, keep handler lists aligned to preserve performance.
• If you encounter JSON encoding/decoding issues, verify that Yojson or the JSON library you use matches the expected shapes for resources and tool arguments.