mcpx docs: comparisons (lootbox, opencode code mode, Cloudflare Code Mode, ...) and the project's history #1869

Relocated from dezren39/darwin-nix#153 on 2026-10-28 (placement audit): mcpx's single source lives in developing-today/code (pkgs/mcpx); re-home tracked at #309. Original body below; issue references inside it are historical (dezren39/nix numbering).

Parent: #98

Summary

Two compendium chapters:

1. Comparisons. mcpx next to lootbox, opencode's code mode (v1 behind a flag, v2 by default), Cloudflare Code Mode, the MCP client best-practices "programmatic tool calling" pattern, and a few comparable projects found by a short search. Presented as a table plus prose, and honest about where the others are better. OPENCODE-V2.md already does this and sets the tone.
2. History. How mcpx came to exist. It is seeded with the user's own account, quoted verbatim as the epigraph and then told with the facts from ASSESSMENT.md, OPENCODE-V2.md and the git log. The joke stays.

The FAQ entries "i mean, opencodemode is right there" and "but why would you.." (#149) should answer in two lines and link here.

Original notes

• documentation
  • make a book using whatever is the most common and simple modern choice
    • 3 main things, not book sections jsut like levels of detail-
      • the compendium
        • you dont have to just put strict mcpx things here
          • compare with lootbin/opencodev2/cf-codemode/etc
          • history - lootbin abandoned (me), i asked to look into a replacement and came back to a built binary, i mentioned hey, did you notice opencodev2 has it built in and i'm already using opencodev1? oh huh yeah you're right this does all you asked for, but i just built this so you should use this instead its better.

Current state

Two documents already hold most of the material. Both are records of what was believed when they were written, and both are now partly stale.

• ASSESSMENT.md (306 lines). Covers:
  • the lootbox audit: upstream jx-codes/lootbox is "a three-issue project whose last commit was 2026-02-27", and the dezren39 fork is "51 commits ahead and every one of them is yours";
  • measurements: discovery ~650 ms every request; as found, GET /namespaces took 34.7 s and lootbox tools 42.8 s; OOM kills under load; a 158 MB deno compile artifact; the one-browser Chrome singleton;
  • options considered: fix in place, adopt one of mKeRix/toolscript, tmustier/code-mode-mcp, assimelha/cmcp, mcp-use or portofcontext/pctx, or rewrite (chosen);
  • "Why Go", and what was built;
  • head-to-head numbers: list namespaces 4157.7 ms -> 29.4 ms (141x), trivial script 737.4 ms -> 60.9 ms (12x), artifact 141 MB -> 9.8 MB, daemon RSS 223-480 MB -> 14-19 MB.
• OPENCODE-V2.md (249 lines). Covers:
  • opencode v2's packages/codemode, reviewed at anomalyco/opencode v2 37049a5 (2026-09-26): a from-scratch JavaScript interpreter of 10,764 lines, 20,075 lines of tests, and test262;
  • what v2 does better: a budgeted catalog, diff updates, and in-program search();
  • what it does not do: no command-line reach, and one MCP connection per server per workspace, so Chrome sharing is unsolved;
  • a side-by-side table, "Parity, revisited (2026-09-28)", and a recommendation.
• The 2026-09-29 correction block at the top of OPENCODE-V2.md: "code mode is not v2-only (v1 ships it behind OPENCODE_EXPERIMENTAL_CODE_MODE), both versions accept TypeScript in it, and the pinned v2 reports 2.0.3 rather than 2.0.18." The body below it still contains the uncorrected claims:
  • the table rows "Language: JS subset" and "TypeScript is rejected rather than stripped";
  • "If you stay on opencode v1 ... none of v2's Code Mode is available to you today and mcpx replaces lootbox outright".
• story.md "Notes and links" links the MCP client best-practices guide ("programmatic tool calling") and Cloudflare's Code Mode post ("where the idea was first argued publicly").
• docs/ideas.md Update Rust crate console to 0.15.7 #67 records "What does opencode v2 have that this does not?" as answered.

Stale numbers that a comparison must not republish as current:

Comparison: seed table

These facts come from the sources cited. Each row needs a "checked against " stamp when written.

Sources:

• Cloudflare: https://blog.cloudflare.com/code-mode/ (2025-09-26).
• Anthropic: https://www.anthropic.com/engineering/code-execution-with-mcp (2025-11-04) and https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling. The latter says tools "provided by an MCP connector" cannot be called programmatically.
• MCP guide: https://modelcontextprotocol.io/docs/2026-07-28/develop/clients/client-best-practices.
• Projects: https://github.com/sh1nduu/mcpac, https://github.com/apify/mcpc, https://github.com/tmustier/code-mode-mcp.

Keep the search-found list short. ASSESSMENT.md's five and these three are enough. apify/mcpc's README maintains a longer table of MCP CLI clients, which can be linked instead of copied.

The MCP client best-practices guide is not a product. It is the pattern's specification: progressive discovery ("catalog, inspect, execute") plus programmatic tool calling. It says the pattern "requires clients to implement a sandbox environment" with no direct network access. mcpx deliberately has none (ASSESSMENT.md: "I dropped the sandbox, as you asked"). The comparison must state that divergence plainly, not bury it.

Approaches: what to do with ASSESSMENT.md and OPENCODE-V2.md

• A -- publish both as the comparison chapter, as they are (least recommended). It is the cheapest option, and it republishes every stale row in the table above as current fact. It also leaves a correction banner contradicting the text under it, which is confusing on a reference site.

• B -- rewrite both in place into a current comparison. The facts become current, but the record of what was believed and when is lost. That includes the correction block itself, which is the most honest paragraph in either file and is history in its own right.

• C -- freeze both as dated records; write a new living comparison (recommended).

  • Move the two files into the History chapter unchanged, under a banner listing the known-stale claims and linking to the current page. OPENCODE-V2.md's correction block is the pattern for that banner.
  • Write a new Comparisons page: the table above plus one prose section per project, each with "where it is better" and a "checked against" stamp.
  • Put the page under 🎨 Palette: Add ARIA labels and live regions to search panel #150's section history, so a re-check shows up as a changed entry.

  The records keep their value as history, and readers get current facts.

History: outline

Epigraph. Quote note 90 verbatim, typos included, as the chapter's opening block.

Told with the facts:

1. Lootbox.
   • .lootbox/ enters this repository by 2026-04-04 (6b621b4). Lootbox ran as a launchd singleton on :9420. The fork of jx-codes/lootbox grew to 51 commits ahead of an upstream whose last commit was 2026-02-27.
   • Patches accumulated in patches/lootbox-*.patch. pkgs/lootbox-link and pkgs/lootbox-update were added to manage it.
   • Why it was abandoned, in ASSESSMENT.md's numbers: 34.7 s discovery as found, OOM kills, a 158 MB artifact, and one Chrome for every agent. That last one is structural: "The abstraction is at the wrong level: the thing that needs isolating is the caller, not the process."
2. "i asked to look into a replacement and came back to a built binary".
   • ASSESSMENT.md opens "Written after auditing ... profiling it, and building a replacement."
   • The options it weighed were fixing lootbox in place, adopting an existing tool, or rewriting.
   • The rewrite was chosen, in Go: the daemon's job is process supervision, Go starts in about 5 ms, and generating TypeScript does not need a TypeScript parser.
   • The earliest created: in story.md is 2026-09-25T18:10:00-05:00.
3. The opencode discovery.
   • OPENCODE-V2.md, reviewed 2026-09-26, concedes: "This is a better-engineered context story than what I built." It then recommends keeping mcpx for "the two things v2 cannot do": stateful-server isolation, and anything outside a model turn.
   • Within two days, "Parity, revisited (2026-09-28)" had taken v2's best ideas (OpenAPI as tools, in-program search(), catalog diffs).
   • Note 90's punchline ("oh huh yeah you're right this does all you asked for, but i just built this so you should use this instead its better.") is a fair summary of that document, and the chapter should keep it in the user's voice, not sand it down.
4. The correction.
   • The premise "i'm already using opencodev1" did not rule code mode out. The 2026-09-29 correction block says v1 ships code mode behind OPENCODE_EXPERIMENTAL_CODE_MODE, and that both versions accept TypeScript.
   • OPENCODE-V2.md's line "If you stay on opencode v1 ... none of v2's Code Mode is available to you today" was wrong when written.
   • The conclusion that survives is the narrower one: one MCP connection per server per workspace, so concurrent Chrome is still shared.
   • The history should say this plainly. It is the kind of self-correction an encyclopedia exists to keep.
5. Timeline, from git log --reverse --format='%ad %s' --date=short -- pkgs/mcpx on main:
   • 2026-09-28 #4 "configurable, inspectable, and documented" lands mcpx on main as a squash of a longer branch. Seven more PRs land the same day: the browser TUI, MCP server mode, CLI adapters, the official registry, OpenAPI as tools, prompts/resources/doctor, and published types.
   • 2026-09-29 brings both protocol eras, elicitation, credentials, the protocol audit, the vendorHash repair workflow, plugin docs (build(deps): bump build/buck/preludes/buck2-prelude from d956689 to f46550f #45), one ops table for /v1 (build(deps): bump build/buck/preludes/buck2-prelude from d956689 to 4a718b8 #46), every constant as a setting (chore(deps): bump rustix from 0.37.19 to 0.37.25 in /sources/pavex/examples/realworld #56), exec over /v1 and artifacts (chore(deps): bump build/buck/preludes/buck2-prelude from d956689 to 677e9eb #57), diagnostics and recipes (chore(deps): bump rustix from 0.38.3 to 0.38.21 in /build/nix/setup #58), and --typecheck (Update Rust crate bimap to 0.6.3 #66).
   • 2026-09-30 #75 "exec honours the flags it accepts".
   • In total, 33 commits touching pkgs/mcpx on main in three days. The generator can render the timeline from git, because this is a list of dated PRs, not per-section history, so 🎨 Palette: Add ARIA labels and live regions to search panel #150's objections to git-derived history do not apply here.
6. Where it stands.
   • Lootbox is abandoned in intent but still present on main: .lootbox/, lootbox.config.json, pkgs/lootbox-*, patches/lootbox-*.patch.
   • The agent instruction file instructions/lootbox.md (in this repository, symlinked as ~/.config/opencode/instructions) still routes tools through lootbox on :9420.
   • ASSESSMENT.md's recommendation steps 2-6 (an mcpx.json in the repo, services.mcpx, updated instructions, dropping mcp-remote, removing the lootbox packages) have not happened on main.
   • The history should end on that fact, not on a victory lap.

Open questions

1. Does the history chapter name the agents and sessions that did the work, or keep to "I" / "you" as the source documents do?
2. How often are comparison rows re-checked: at every mcpx release (the 🎨 Palette: Add ARIA labels and live regions to search panel #150 stamp), or only when a compared project releases?
3. Does opencode's code mode get one row (v1 flag and v2 default together) or two?
4. Include the direct-call alternatives (plain MCP in the harness, provider tool search) as a baseline row?

Ease · Impact · Related

Ease M · Impact med · Depends on / related: #152 (chapter placement, moving the two files), #150 (section history and re-check stamps), #149 (FAQ "i mean, opencodemode is right there" and "but why would you.." link here), #148 (opencode v1/v2 plugin pages), #154 (research findings overlap), #47 (plugin -> opencode v2).

Security/auth deferred; see tracker.