build.sh, Linux compiler discovery and the online-docs
index included. This article keeps its original Windows-first telling; see
tureluut/pb-mcp for current build
steps on both platforms.
Hand a coding agent a PureBasic file and watch it hallucinate. Comments with
//, Dim As, typed Sub blocks — dialects the
PureBasic compiler has never accepted. The language is healthy, but it is nearly absent
from training data, and the agent’s only feedback loop used to be “write it,
run the compiler, squint at the console, guess again”.
An MCP server is the modern answer to that problem: a small process an AI client can call to consult tools — search documentation, validate syntax, run code. The original pbmcp was a TypeScript server on Node, and it worked. But “install Node, run npx, wait for the module tree, keep 120 MB of RSS warm” is a lot of ceremony for a tool whose whole job is to spawn one compiler. So it was ported — ground up, TypeScript reference open in one pane — into the language it serves.
Written in PureBasic, for PureBasic
That is not a slogan; it is the stack. All 4,620 lines across fifteen source files are
PureBasic 6.40, compiled to a single self-contained pbmcp.exe of roughly
700 KB. Distribution is a file copy. The server speaks MCP over stdio —
JSON-RPC 2.0, newline-framed UTF-8 — and implements the handshake, tool
listing and tool dispatch itself, down to copying request IDs and byte-equal error paths
against the TypeScript original.
The port was measured, not assumed: against the Node original, the MCP handshake completes at a p50 of 27.6 ms versus 539 ms, and resident memory sits at 15.6 MB versus 118.8 MB. The original remains the spec — golden sessions replayed through both binaries must come out identical — but nothing about the protocol needs a runtime to do it.
Five tools
The entire surface an agent sees fits in five entries:
pb_docs_search # search the command reference, filter by library
pb_command # full docs for one command: syntax, remarks, example
pb_check # syntax-check with the real compiler, structured errors
pb_run # compile to exe, run, capture stdout, kill on timeout
pb_version # server, protocol, compiler and docs-index versions
Two of them answer questions, two of them prove answers, and one keeps the pair honest about which compiler and which documentation index they are actually talking to.
The real compiler, not a lint
Plenty of editors ship hand-rolled linters that approximate a language. pbmcp refuses
the approximation: pb_check copies your file to a scratch directory and
runs pbcompiler.exe /CHECK against it — the authoritative parser, not a
lookalike — then returns structured, line-numbered errors. Your file is never touched.
pb_run goes further: compile to an exe, execute with a timeout, capture
stdout, and kill the whole process tree when the clock runs out — no orphaned children
haunting the machine after a bad loop.
This is a live transcript, from the session this article was written in. The agent had
typo’d PrcedureReturn — a Visual-Basic-flavoured reflex, exactly the
failure mode the server exists to catch:
agent: pb_check { "file": "bad2.pb" }
pbmcp:
ERRORS (1):
Line 2: Syntax error
Two hundred milliseconds later the guess is a fact, the line number is exact, and the
agent fixes the spelling instead of shipping the bug. The loop —
edit, pb_check, run — is the entire discipline.
Documentation straight out of the CHM
PureBasic’s manual ships as a Windows help file, which is great for humans and invisible to agents. One CLI command extracts the installed CHM (7-Zip does the unpacking, once, into a cache) and a native HTML scanner distills every command page into a JSON index: exact syntax, parameters, return value, remarks, example, supported OS, related commands. No web scraping, no third-party docs site, and the answers match the compiler on your disk.
The index is versioned — one file per CHM version, newest selected by modification time
— so upgrading PureBasic is a single command, and multiple installs coexist peacefully.
Misspell a command and the search returns did-you-mean suggestions instead of an empty
result. And the graceful-degradation rule is explicit: with no index built, the server
still starts and pb_check/pb_run work untouched — only the
docs tools say so and point at the one-line fix.
One core, two shapes
The same source files compile two ways. As the stdio exe agents configure in one JSON stanza:
{
"mcpServers": {
"purebasic-pb": {
"command": "C:\\tools\\pbmcp.exe"
}
}
}
And as pbmcp.dll — the identical core behind a plain C ABI, for hosts that
would rather skip the process boundary. Two levels: function exports
(PbCheck, PbDocsSearch, …) when you just want the
tools, and McpHandleLine when you want the whole protocol embedded and your
host owns stdio. The dispatch is shared with the exe, so validation errors and
truncation caps behave identically by construction. A Python ctypes binding and a
normative C header ship alongside, and a nineteen-gate smoke test drives the DLL from a
foreign host (PowerShell, P/Invoke) after every build.
Boring on purpose
- Tested against the original — 147 automated checks plus a parity harness that replays golden sessions through both binaries and demands byte-identical output, including 7-byte-dribble stress that cuts UTF-8 characters across stdin chunk boundaries.
- Encoding paranoia — every source file is UTF-8 with BOM, because BOM-less UTF-8 is silently misread as CP-1252 by the PB compilers. A build-time lint enforces it; a deliberate em-dash in stub output makes any regression visible in tool output.
-
Never trusts exit codes — compiler version detection parses
/VERSIONoutput with a regex, because the exit code lies on some versions. Capability flags key on major version with conservative defaults for unknown ones. - Quietly observable — JSONL metrics on every call (redirectable, or off with one environment variable), version reporting in one command, and an optional background preload so the first docs query isn’t the slow one.
Built by the tool it became
The best part is circular: pbmcp was written, debugged and hardened by an AI agent running pbmcp. A nine-session dogfood week measured the effect on a frozen task set: 71.4 % of tasks succeeded on the first try, and the failure class that started all of this — hallucinated documentation — dropped to zero. The server no longer just describes PureBasic to agents; it is the thing they reach for before claiming anything about the language.
The through-line is the same one this site keeps arriving at: good tools do one job close to the metal and get out of the way. A 700 KB exe that answers with the real compiler’s opinion beats a 120 MB runtime that answers with a guess.