convez.ai
MCP ServerIntegração & APIsAvançado
tarides

Topup – Toplevel OCaml Persistente via MCP

tarides/topup

Toplevel OCaml persistente com memória tipada para assistentes IA

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que expõe um toplevel OCaml persistente, permitindo que LLMs mantenham memória de trabalho tipada entre turnos de conversa. Elimina ciclos de compilação repetidos e re-derivação de valores intermediários, aproveitando o sistema de tipos do OCaml para garantir segurança nas referências.

Instalação

$npx convez-ai tarides/topup

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 2 meses
Versão
v0.1.3
Issues abertas
1
Contribuidores
1

Casos de uso

  • Assistentes de código para OCaml que precisam manter estado entre interações
  • Prototipagem interativa com linguagens compiladas tipadas
  • Redução de custos computacionais em desenvolvimento iterativo com IA

Veredito

Ferramenta especializada e bem-arquitetada para um nicho específico: desenvolvedores OCaml que usam Claude Code. O design de persist tipado é sólido, mas exige OCaml 5.1+ e compreensão profunda do ecossistema. Produto maduro com documentação clara.

README

A tradução para o português deste README ainda está na fila.

topup

A persistent OCaml toplevel exposed as an MCP server. Lets an LLM keep typed working memory across conversation turns.

Why

LLM coding assistants in typed compiled languages pay two recurring costs: a build cycle for every idea, and re-derivation (or re-serialization) of intermediate values turn after turn. topup cuts both: phrases run inside a long-lived toplevel, and bindings persist. The model carries only names and types in its context; the toplevel holds the values. The OCaml type system makes that recall sound — the compiler catches a stale or mistyped reference before evaluation.

See DESIGN.md for the longer rationale, the phase-2 roadmap, and how topup relates to neighbouring projects. For driving toplevels on remote machines (one MCP registration, any number of hosts), see MULTIHOST.md.

Install

Requires OCaml 5.1+ and dune.

opam exec -- dune build @all
opam exec -- dune runtest

The binary lands at _build/default/bin/main.bc.exe.

Register with Claude Code (user-scoped):

claude mcp add topup $(pwd)/_build/default/bin/main.bc.exe

Or drop a project-local .mcp.json at the repo root:

{
  "mcpServers": {
    "topup": {
      "command": "/absolute/path/to/_build/default/bin/main.bc.exe"
    }
  }
}

Restart Claude Code (or run /mcp → Reconnect) so the new server is picked up.

Optional: the /caml slash command

This repo ships a small Claude Code skill that wraps the five MCP tools behind /caml. It is project-scoped (lives under .claude/skills/caml/) so it activates automatically when Claude Code is run inside a topup checkout. To use it from anywhere, copy it to your user-scope skills directory:

mkdir -p ~/.claude/skills/caml
cp .claude/skills/caml/SKILL.md ~/.claude/skills/caml/SKILL.md

Then /caml 1 + 1;;, /caml #env, /caml #reset, etc. work from any project. The skill calls mcp__topup__* directly, so the topup MCP server must still be registered.

Tools

ToolEffect
eval(source, timeout?)Evaluate one or more phrases. Returns {value_repr, type, stdout, stderr, warnings, error}.
eval_batch(sources, timeout?)Evaluate a list of sources in one round trip. Returns {results, stopped_on_error}; stops on the first failing element.
env(filter?)List current bindings as [(name, type, location, preview?)].
lookup(name)Inspect a single binding.
reset()Discard the toplevel environment.
cancel()Interrupt the running evaluation.
push_file({host, local_path, remote_path?})Copy a file from local to a registered remote, in-band over JSON-RPC.
pull_file({host, remote_path, local_path?})Reverse direction. Defaults to $TOPUP_XFER_DIR/<basename>; capped at TOPUP_XFER_MAX_BYTES (16 MiB).

Example

eval   { source: "let xs = List.init 100 (fun i -> i * i);;" }
       → value_repr: "[0; 1; 4; 9; …]", type: "int list"

eval   { source: "List.length xs;;" }
       → value_repr: "100", type: "int"

env    { filter: "xs" }
       → [{ name: "xs", type: "int list", … }]

eval   { source: "let rec spin n = spin n;;", timeout: 0.3 }
       → error: { phase: "runtime", message: "evaluation timed out" }

Workspace pattern

A topup session is a workspace, not a calculator. Bindings persist across eval calls, so the productive shape is multi-eval — name each intermediate, read it back across turns, and use env to recall what you have:

(* eval 1 — bring in a library and load raw input *)
#require "csv";;
let raw = Csv.load "boundary.csv";;
(* raw : string list list *)

(* eval 2 — derive in-memory; named, persists for later turns *)
let parsed =
  List.map
    (function [day; n] -> day, int_of_string n | _ -> assert false)
    (List.tl raw)
;;
(* parsed : (string * int) list *)

(* checkpoint — save-point before something experimental *)
(* mcp: checkpoint { label: "parsed" } *)

(* eval 3 — derive again; restore { label: "parsed" } rewinds here *)
let by_day = List.fold_left (fun acc (d, n) -> ...) [] parsed;;

(* env — recall the workspace state across turns *)
(* mcp: env {} → raw, parsed, by_day with their types *)

Discoverability nudges that make the pattern stick:

  • Reach for an existing opam package (#require "csv";;, #require "re";;) before hand-rolling. The session inherits findlib, so anything opam install-able is available.
  • Use checkpoint { label } as a save-point before risky steps; restore { label } rewinds the whole workspace, not just one binding. Snapshots live under ~/.topup/checkpoints/ and survive server restarts.
  • On a remote (host: "myhost"), push_file / pull_file carry inputs and outputs across the boundary in-band over the same JSON-RPC channel — no scp.
  • eval_batch runs a list of phrases in one round-trip — useful for the inner loop of a build-up, especially when routed.

Troubleshooting #require

Two opam/runtime quirks bite when #require'ing packages with C stubs.

stublibs path mismatch. opam stores shared stubs at <opam-root>/<switch>/lib/stublibs, but the bytecode runtime's ld.conf (read once at startup) lists <opam-root>/<switch>/lib/ocaml/stublibs. On a system with no active switch — e.g. OPAMSWITCH=<switch> selects but doesn't activate — #require fails with Cannot load required shared library dllintegers_stubs.so. Launch topup through opam exec --switch=<sw> -- so opam sets the runtime env, or append the missing path to ld.conf.

CAML_LD_LIBRARY_PATH is parsed once at startup. Setting it from inside a running session (Unix.putenv ...) has no effect on later #require calls. Export it in the shell before launching topup.

Status

Phase-1 MVP: bytecode toplevel (topup) plus an opt-in native driver (topup-opt, phrases compiled with ocamlopt -shared and Dynlink-loaded — name echoes the ocamlc/ocamlopt split). MCP over stdio (default) or a Unix domain socket (--socket <path>, one client at a time, state persists across connections). One MCP registration drives the local in-process toplevel, named local subprocess sessions with pre-warming and replica pools, and any number of SSH-tunneled remote toplevels, with per-call host / session routing (see MULTIHOST.md). checkpoint/restore ship for branching exploration. compile_to_binary promotes a stable session into a standalone native ELF via a synthesized dune project — see DESIGN.md for the phase-2 roadmap.

AI usage

topup is developed in close collaboration with Anthropic's Claude. See AI_USAGE.md for scope, provenance, and what that means for downstream users and contributors. The deployed binary has no runtime LLM dependency.

Ver o original no GitHub

Bom para

Relacionados