Total.js Forge publishes only recipes that execute, with MCP endpoints for AI assistants

The Total.js team has launched Forge, a recipe site for the Total.js 5 framework and the jComponent 20 client library where every code example is executed before it is published. According to an announcement from the team on dev.to, a recipe that fails its validation run never reaches the site. The stated goal is to eliminate a problem most developers recognise: documentation examples that were correct when written but silently rotted as the framework evolved.

The framework behind it

Total.js 5 is a Node.js framework with a dependency-free core. Routing, WebSocket, authentication, sessions, file uploads, scheduled tasks, mail, views, a proxy, localisation and an embedded NoSQL database all ship in the box, so a typical project starts without a long dependency install or a stack of upfront decisions.

Validation before publication

Each recipe is a Markdown page that carries the example code, the file paths that code belongs at, and a hidden test block. A single command, npm run validate, puts every recipe through its paces. For Total.js 5 recipes the process scaffolds a temporary application, writes the files, starts the app and runs checks against the live instance — HTTP calls, WebSocket connections, real SQLite transactions, OpenLDAP and file uploads among them. jComponent recipes are executed headless in Chromium. Every run leaves a machine-readable receipt, and any recipe that fails is blocked from publication.

What the site contains

Launch content includes more than 100 Total.js 5 recipes covering routes, actions, WebSocket, authentication, uploads, SQL and NoSQL, Flow, bundles, release mode and LDAP, plus 30 jComponent recipes with a live in-browser editor and preview. Around the recipes sit over 330 pages documenting the Componentator component catalog, each attributed to its author and source. Reference material lists every global, every CONF key, the options of the NEWACTION declaration, route syntax and input types, alongside an Express-to-Total.js migration guide and a page that pairs incorrect code with the correct version. The site is available in 15 languages — English plus 14 translations — with only the prose translated; the code shown is exactly what was executed.

Forge also hosts repeatable benchmarks pitting Total.js 5 against Total.js 4, Node.js, Express, Fastify, Koa, Hapi, Hono, Polka, Restify, NestJS, AdonisJS and Meteor. The benchmark apps, lock files, runner and raw results live in the repository, and a verify step checks that the published pages still match the underlying data.

Made to be read by models

A second design goal is that AI assistants can consume Forge without scraping. The site exposes an llms.txt index and a full-content variant, every page as Markdown, and three JSONL datasets: question-answer pairs, tasks with tests, and wrong-versus-correct code pairs. A read-only MCP server offers search, page, test and product tools plus one named Forge_verify_api: send it a code snippet and it checks each global name and member against the reference pages, so an assistant can confirm before answering that a symbol is actually part of the framework. The tool reads code but never executes it, and flags what it cannot see. Well-known files publish the MCP server card, agent skills and an API catalog. All content is licensed CC-BY-4.0, so it can be reused for training, evaluation or as context in other tools.

A finding the benchmarks turned up

While measuring throughput at tens of thousands of requests per second, the team says it found that in total5 0.0.19 clearing the list of finished requests became costly at very high rates. They documented it with a reproduction that runs in about a minute, a small patch and before-and-after numbers — with the patch, they report a single process holding the target up to 80,000 requests per second on their own machine. The write-up sits in benchmarks/FINDINGS.md as a suggestion for the framework's authors to review, which the team frames as the Forge method in miniature: measure, record what you see, make it repeatable.

Why it matters

Documentation drift is a chronic tax on developer time, and the spread of AI-assisted coding has made it worse: models trained or prompted on stale examples reproduce old APIs with confidence. Forge attacks the problem from both ends. On the human side, executable recipes with machine-readable receipts mean the cookbook cannot quietly diverge from the framework it documents. On the machine side, llms.txt, JSONL datasets, a read-only MCP server and a symbol-verification endpoint give assistants a way to check their answers against the framework's real surface instead of guessing, and the CC-BY-4.0 licence lets anyone fold the material into training or evaluation pipelines. One caveat applies: the details and figures here come from a single vendor announcement, and the throughput numbers were produced on the team's own rig, so independent verification is still outstanding.