forthling

forthling-mcp

An MCP server that lets AI agents (Claude Code, Claude Desktop and other MCP clients) run Forth in forthling, always in its sandbox. The agent keeps one session: the words it defines and the stacks stay between calls.

Installing

Without Rust, as an MCP bundle: download forthling.mcpb from the latest release and open it in Claude Desktop (or another client that installs .mcpb files). The bundle holds the server for Windows (x64), macOS (Apple Silicon and Intel) and Linux (x64).

From crates.io, with Rust 1.85 or newer:

cargo install forthling-mcp

It builds SQLite along, which takes a C compiler (on Windows that of Visual Studio, which Rust there uses anyway); cargo install forthling-mcp --no-default-features leaves SQLite out. From a clone of the repository: cargo install --path mcp, or cargo build --release --manifest-path mcp/Cargo.toml, and the program is then mcp/target/release/forthling-mcp. With Claude Code:

claude mcp add forthling -- forthling-mcp

Other clients start it the same way: the command forthling-mcp, over stdio.

When a client connects, the server tells the model the basics in its instructions: the idioms that trip models up, locals rather than ROT, PICK and ROLL, the JSON words and the limits. llms.txt says the same at more length, for a model that reads it beforehand; a test keeps the limits in both the same.

Tools

A line of code, and so a string in S", is at most 1024 characters. Larger input, such as a JSON document, goes in data: the code reads it with DATA ( -- c-addr u ), which gives a copy in ALLOCATEd memory (FREE it). The data stays for later calls until a call sends other data, and may be at most as large as the Forth memory:

{"name": "forth_eval", "arguments": {"code": "ALSO JSON DATA JSON-LENGTH .", "data": "[[59],[73,41]]"}}

Each session has files of its own, in memory and never on the disk: INCLUDE, REQUIRE, the FILE words and the block words use them, and they stay until forth_reset. files puts files there before the code runs, as an object of names and texts, replacing files of the same name; so an agent can give a library once and INCLUDE it, and what the code writes, a later call can read. The files take at most 4 MiB in all; a write past that fails with the word's ior, and files that do not fit are refused.

{"name": "forth_eval", "arguments": {"code": "INCLUDE square.fs 7 SQUARE .", "files": {"square.fs": ": SQUARE DUP * ;"}}}

Each result is text the way the REPL shows it:

2401  ok

stack: 1 2

and the same as structured JSON (structuredContent, with an outputSchema): {"output": "2401 ", "stack": [1, 2], "fstack": [], "compiling": false, "error": null, "steps": …, "max_depth": …}; steps and max_depth (only for forth_eval) tell how many steps the call took and how deep the data stack went, counting the words of the system it ran (. is written in Forth, so it counts too).

An error empties the stacks, so the result also tells what they held at the error, where it happened and which words were running; the model can put it right in one go:

error -10: division by zero

at input, line 2, column 3: MAIN in: MAIN > STEP > / stack at the error: 5 1 stack: empty

and as JSON: "error": {"code": -10, "message": "division by zero", "stack": [5, 1], "fstack": [], "words": ["MAIN", "STEP", "/"], "source": "input", "line": 2, "column": 3, "token": "MAIN", …}, with isError true. A word that took its arguments before it failed, such as / here, has taken them. An undefined word that is in a word list outside the search order gets a hint, which the text adds after the word: error -13: undefined word: JSON@ (it is in the word list JSON; ALSO JSON finds it).

A runaway program can leave a hundred thousand cells on the stack, or as many words running (endless recursion). The result then keeps the top 32 cells and the innermost 32 words, the text says ... (n more) and the JSON has the full depth in stack_depth, fstack_depth and words_depth. A definition that is still open (compiling true) says so in the text: compiled (a definition is still open; ; ends it).

When the code ran T{ ... -> ... }T tests (ALSO TESTING), the result also has the counts of that call, and the text starts with tests: 1 passed, 1 failed. The failure lines (FAIL input:3 (sums): incorrect result: expected <1> 3, got <1> 2) are in the output. In JSON: "tests": {"passed": 1, "failed": 1, "failures": [{"source": "input", "line": 3, "group": "sums", "expected": [3], "expected_depth": 1, "actual": [2], "actual_depth": 1, "stack": [], "expected_floats": [], "expected_floats_depth": 0, "actual_floats": [], "actual_floats_depth": 0}], "failures_dropped": 0}. The first 32 failures are kept, and each list keeps its top 32 cells and floats (the depths tell how many there were). A file given with files shows its name as source.

What an agent sees for typical mistakes

Each case was run through forth_eval (#47); the answer is the first lines of the text. The code was run from a fresh session.

What gives no error, and so no message: an unclosed S" or ( takes the rest of the line (as the standard says); : f >R ; leaves the return stack unbalanced and 1 f returns without a word; ALLOCATE of a negative size and FREE twice answer with a non-zero ior on the stack (-59, -60), and so does a failed DB-EXEC (-261); a JSON path that is not there gives 0 0 0. These follow the standard or the word's stack effect; the agent must read the stack.

With "trace": true, forth_eval also returns a trace: each word that ran, with how deep it was nested and the data stack when it started (at most its top 8 cells), at most 1000 words; trace_dropped counts the rest. The insides of the system's own words are left out. The text starts with it, indented the way TRACE-ON prints it:

trace:

F <0> SQ <1> 3 DUP <1> 3

• <2> 3 3 1+ <1> 9

. <1> 10 end of trace 10 ok stack: empty

and the JSON has "trace": [{"word": "F", "depth": 0, "stack": [], "stack_depth": 0}, {"word": "SQ", "depth": 1, "stack": [3], "stack_depth": 1}, …], "trace_dropped": 0. The trace of a call that fails shows how it got to the error. In the code itself, ALSO DEBUG TRACE-ON … TRACE-OFF prints the same lines as output.

BREAK (also ALSO DEBUG) marks a place to look at. It does not stop the program, since no one could answer in the middle of a call; instead the result has breaks, what the program looked like at each BREAK (at most 100; breaks_dropped counts the rest), with the same fields as an error: stack, fstack, words, source, line, column and token. The text starts with a line for each:

break 1: in F > BREAK, at input, line 1, column 3: stack <2> 7 9

ALSO TUTORIAL gives the tutorial: 20 lessons of Forth, ten for beginners and ten beyond, that an agent can walk a person through (LESSONS, n LESSON, CHECK tests the answer, HINT, NEXT).

The JSON words are installed (ALSO JSON), and the SQLite words for databases in memory (ALSO SQLITE, only :memory:, which SQL stops when the time is up and which cannot grow larger than the Forth memory) and the regular expression words (ALSO REGEX, which match in linear time); without the Cargo features sqlite and regex (--no-default-features) the server is built without them.

The HTTP words (ALSO HTTP, see http/README.md) are a third feature, http, which is off by default because it reaches the network. Build the server with it (cargo install forthling-mcp --features http) and start it with the hosts that Forth code may send requests to, once for each host: forthling-mcp --allow-host api.example.com (*.example.com and * also work). Without --allow-host the network stays closed and the model is not told about the words. It is the only option that opens something outside the sandbox, and only for the hosts you name; a Forth word cannot add one.

The sandbox

Every session runs in forthling's sandbox: files only in memory, and each call at most 10 million steps, 5 seconds and 1 MiB of output; the session's definitions and the like at most 4 MiB in all. The options change these limits, each up to a ceiling the program fixes:

  -m, --memory SIZE      Forth memory (default 1M) [64M]

--max-steps N steps per call (default 10000000) [1000000000] --max-time T time per call, such as 5s or 500ms (default 5s) [60s] --max-output SIZE output per call (default 1M) [16M] --max-space SIZE definitions and the like in all (default 4M) [64M] --allow-host HOST a host that Forth code may send HTTP requests to (repeat)

There is no option to switch the sandbox off or to permit files, so changing how the server is started does not open them either. Only --allow-host opens the network, for the hosts it na