Public: anyone can read this; the crew can change it.
A small forge loads less at boot: the TUI, boards and studio modules load on first use #12549
Check · Review · Land · Live done — Landed and live in production.
The MCP server and its tool index now load on the first request that needs them, not at boot. The boot import graph drops from 2,653 modules to 2,433, and resting memory drops by about 55 MiB. The terminal UI already loaded lazily on main (#12349), so this pull adds the second family the issue asks for.
shipped production is serving it deploy 7612a18
The MCP server and its tool index now load on the first request that needs them, not at boot. The boot import graph drops from 2,653 modules to 2,433, and resting memory drops by about 55 MiB. The terminal UI already loaded lazily on main (#12349), so this pull adds the second family the issue asks for.
Measured on this machine (fresh forge with FORGE_SSH_PORT=0 FORGE_APPS=0, run from source, VmRSS read 20 s after /healthz answers):
| RSS at rest | |
|---|---|
| Before | 313, 326, 333 MiB |
| After | 269, 271, 265 MiB |
The first request that loads the tools takes about 0.1 s; later requests don't wait. / takes about 30 ms before and after.
What moved
src/http/mcp/load.ts(loadMcp): importsmcp.tsand the tool index once. It also hands the tool list to/llms.txt(setMcpTools) and to the cards (setCardTools); before,server.tsdid that at boot. If the import fails, the request gets an error that says the MCP tools failed to load, and the next request tries again.src/http/lazy_routes.ts(lazyRoutes): registersPOST/GET/DELETE /mcpin the route table at boot. The handler behind them loads the module on the first request and hands it on to the handler the module adds, so route matching, the admin gate, 405s and HEAD behave as before.RoutergainshandlerOf(method, pattern).- Readers of the tool list wait for the load first:
- /llms.txt, /.well-known/mcp.json and /.well-known/agent-card.json in standards.ts
- /agents
- sayYes in actions/conversation_confirms.ts, which loads before it claims the confirm, so a failed load leaves the confirm waiting instead of using it up.
- Docs:
AGENTS.mdnames the new shared in-memory state, anddocs/features/footprint.mdsays what loads on first use and gives the numbers above.
Tests (test/boot-lazy.test.ts):
- The boot's static imports reach none of
http/mcp.ts,http/mcp/tools.tsorhttp/mcp/tools/*. MCP_ROUTESmatches whatmcpRoutesadds, so the two can't drift.lazyRoutesloads once, retries after a failed load, and names a route the module no longer adds.
What to look at:
- One existing test fails on this branch and on the base commit alike, so it isn't caused by this change:
test/mcp-refusal-hints.test.ts"a stranger calling every listed tool…" (expects 401, gets 200). - The parameter in
lazy_routes.tsis namedtable, notrouter, becausetest/helpers/registered_routes.tscountsrouter.add(calls in the source text.
Not done:
- The OpenAPI contract's route descriptions (443 modules) are the largest family still loaded at boot. The admin gate (
admin_gate.ts) and the cursor guard (cursor_lists.ts) read them on every request. Deferring them would mean getting those two facts without loading the document, which is a riskier change than this issue allows. - Boards and the studio are small (boards saves 14 modules) or imported from all over, so lazy loading them would barely help.
- I didn't keep a plan with
keep_planor record an estimate: neither tool was available in this run.
Checks run: bun scripts/gate.ts, bun x tsc --noEmit and bun scripts/design-lint.ts pass. I ran the 437 test files that reach /mcp, /llms.txt, the cards, /agents or the confirms. The two other failures from that run, in test/capacity.test.ts and test/holds.test.ts, came from a run disturbed by a stash I made while it was going, and both pass on a clean re-run. fast.ts named 2,183 test files, too many to run here, so the forge's check runs the full suite.
Try it: on the preview, open /llms.txt and /.well-known/mcp.json, then POST /mcp with tools/list and a token. Each should list the same tools as production.
🤖 Generated with Claude Code
Clean. The MCP server and tool index load on first use behind route-table entries registered at boot, so matching, the admin gate and 405s are unchanged. Every reader of the tool list (/llms.txt, /agents, both cards, sayYes) awaits loadMcp first. sayYes loads before it claims the confirm, so a failed load leaves the confirm waiting. A failed load is retried. Tests cover the boot graph, MCP_ROUTES against mcpRoutes, and lazyRoutes. AGENTS.md and docs/features/footprint.md are updated, and README is untouched. Preview: /llms.txt, /.well-known/mcp.json and /agents answer 200 and list tools; /mcp answers 401 to a forge token, as expected. No new dependency, and src/web changes are logic only, with no markup or design change.
The MCP server and its tool index now load on the first request that needs them, not at boot. The boot import graph drops from 2,653 modules to 2,433, and resting memory drops by about 55 MiB. The terminal UI already loaded lazily on main (#12349), so this pull adds the second family the issue asks for.
Measured on this machine (fresh forge with
FORGE_SSH_PORT=0 FORGE_APPS=0, run from source, VmRSS read 20 s after/healthzanswers):The first request that loads the tools takes about 0.1 s; later requests don't wait.
/takes about 30 ms before and after.What moved
src/http/mcp/load.ts(loadMcp): importsmcp.tsand the tool index once. It also hands the tool list to/llms.txt(setMcpTools) and to the cards (setCardTools); before,server.tsdid that at boot. If the import fails, the request gets an error that says the MCP tools failed to load, and the next request tries again.src/http/lazy_routes.ts(lazyRoutes): registersPOST/GET/DELETE /mcpin the route table at boot. The handler behind them loads the module on the first request and hands it on to the handler the module adds, so route matching, the admin gate, 405s and HEAD behave as before.RoutergainshandlerOf(method, pattern).-
/llms.txt,/.well-known/mcp.jsonand/.well-known/agent-card.jsoninstandards.ts-/agents-sayYesinactions/conversation_confirms.ts, which loads before it claims the confirm, so a failed load leaves the confirm waiting instead of using it up.AGENTS.mdnames the new shared in-memory state, anddocs/features/footprint.mdsays what loads on first use and gives the numbers above.Tests (
test/boot-lazy.test.ts):http/mcp.ts,http/mcp/tools.tsorhttp/mcp/tools/*.MCP_ROUTESmatches whatmcpRoutesadds, so the two can't drift.lazyRoutesloads once, retries after a failed load, and names a route the module no longer adds.What to look at:
test/mcp-refusal-hints.test.ts"a stranger calling every listed tool…" (expects 401, gets 200).lazy_routes.tsis namedtable, notrouter, becausetest/helpers/registered_routes.tscountsrouter.add(calls in the source text.Not done:
admin_gate.ts) and the cursor guard (cursor_lists.ts) read them on every request. Deferring them would mean getting those two facts without loading the document, which is a riskier change than this issue allows.keep_planor record an estimate: neither tool was available in this run.Checks run:
bun scripts/gate.ts,bun x tsc --noEmitandbun scripts/design-lint.tspass. I ran the 437 test files that reach/mcp,/llms.txt, the cards,/agentsor the confirms. The two other failures from that run, intest/capacity.test.tsandtest/holds.test.ts, came from a run disturbed by a stash I made while it was going, and both pass on a clean re-run.fast.tsnamed 2,183 test files, too many to run here, so the forge's check runs the full suite.Try it: on the preview, open
/llms.txtand/.well-known/mcp.json, thenPOST /mcpwithtools/listand a token. Each should list the same tools as production.🤖 Generated with Claude Code
Closes #12521