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

Tool	Arguments
forth_eval	code, data, files, trace	runs Forth code; returns the output, the data and float stacks, and the error if there was one
forth_stack		the stacks, without running anything
forth_words		the words defined in this session, the latest first
forth_help	word	the stack effect of a word, what it does, an example, and the word list it is in; for a name that is not defined, close names. Words of the session show the ( ) comment after their name
forth_reset		a new session: every definition, stack value, the data and the files are gone

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.

Mistake	Code	Answer
undefined word	1 2 FOO .	error -13: undefined word: FOO, the column, the stack at the error 1 2
word in a word list not in the search order	S" :memory:" DB-OPEN	error -13: undefined word: DB-OPEN (it is in the word list SQLITE; ALSO SQLITE finds it)
undefined word in a definition	: sq DUPP * ;	error -13: undefined word: DUPP, at its column
stack underflow	: add2 + ; 1 add2	error -4: stack underflow, in: ADD2 > +, the stack at the error
word that eats too much	: f ( n -- ) DROP ; f	error -4, in: F > DROP
IF, DO, BEGIN outside a definition	1 IF 2 THEN	error -14: interpreting a compile-only word: IF
unclosed IF	: foo 1 IF 2 ;	error -22: control structure mismatch, at the ;
LOOP without DO	: f LOOP ;	error -22: control structure mismatch
unclosed definition	: foo 1 2 +	compiled (a definition is still open; ; ends it)
division by zero	1 0 /	error -10: division by zero, in: /, stack at the error empty (/ took its arguments)
bad address	12345678 @	error -9: invalid memory address: 12345678
step limit	: spin BEGIN 1 DROP AGAIN ; spin	error -258: limit exceeded: steps, in: SPIN > DROP
output limit	: p BEGIN 65 EMIT AGAIN ; p	the output up to the limit, then error -258: limit exceeded: output
endless stack growth	: grow BEGIN 1 AGAIN ; grow	error -3: stack overflow, the top 32 cells and ... (n more)
endless recursion	: r RECURSE ; r	error -5: return stack overflow, the innermost 32 words
missing file	S" nofile.fth" INCLUDED	error -38: non-existent file: nofile.fth: no such file
error inside EVALUATE	S" 1 2 FOO" EVALUATE	at evaluate, line 1, column 5: FOO, stack 1 2
line over 1024 characters	S" xxxx…" TYPE	error -18: parsed string overflow: input line too long
ABORT"	: chk 0= ABORT" zero" ; 0 chk	error -2: aborted: zero
CATCH	: t 1 0 / ; : u ['] t CATCH . ; u	prints -10, no error result

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) and the vector, matrix, linear algebra and special function words (ALSO SCIENCE); without the Cargo features sqlite, regex and science (--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 names (see above).

What enforces it. The sandbox is enforced by the server, not by what the model is told or promises: the tools take only Forth code (other arguments are refused), and no Forth word can change a limit or a permission. A user who asks the AI to get around the sandbox cannot do it through forthling. An agent that also has other tools, such as a shell or editing files, can however go around it: change the MCP configuration, or start another program. Against that, forthling cannot help; use the permissions of the agent instead. In Claude Code: deny or limit the shell, deny edits to the MCP configuration (.mcp.json, ~/.claude.json), and allow only the MCP servers you want through managed settings. For extra safety against a bug in forthling, run the server in a container or as a user with few rights.

Testing

cargo test --manifest-path mcp/Cargo.toml
cargo test --manifest-path mcp/Cargo.toml --no-default-features
cargo test --manifest-path mcp/Cargo.toml --all-features

Links

• Source and the rest of forthling: https://github.com/DeSchaker/forthling
• The MCP Registry knows this server as io.github.DeSchaker/forthling (the line below lets it check that the crate is ours).
• mcp-name: io.github.DeSchaker/forthling