Update, October 13, 2026: pbmcp is now released on GitHub and builds natively on Linux too — 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:

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:

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.

Why Windows only, for now? Not ideology — scope. The server’s whole value is spawning your PureBasic compiler, and that compiler is Windows-hosted here. The protocol layer is platform-agnostic; the process plumbing (compiler discovery, tree-kill, CHM paths) is Windows today. Ports follow when there is a compiler to point at.

One core, two shapes

The same source files compile two ways. As the stdio exe agents configure in one JSON stanza:

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 /VERSION output 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.