Repository navigation
v0.8.16 — mcptoon docs: route a query to the right file
[0.8.16] - 2026-10-07
Added
-
mcptoon docs— index a Markdown tree and route a query to the right file.
A largeAGENTS.md/CONTEXT.md/docs/folder is the biggest context tax
there is: the agent opens all of it every session to answer one question.
Measured on the maintainer's machine (2026-10-07, live sessions): a monolithic
554-line context file peaks at 40,467 tokens; the same question against a
router-plus-chapters layout peaks at 17,498.mcptoon docs index <dir>
indexes a Markdown tree as first-class entries, and
mcptoon docs resolve "<question>"returns the few files worth opening.It reuses the skill router's BM25 engine rather than copying it — the adapter
that presents docs to the ranker is one function — so a machine keeps one
ranking behaviour instead of two that drift. The docs index is a separate file
from the skill index, so the two catalogs never fight over one signature, and a
machine that indexes no docs behaves exactly as before.Descriptions are synthesised from the file's own headings and the entry is
markedderived: true, so a weak match can be told apart from a weak document.
The title is the first heading of any level: a chapter file conventionally
opens at##(its parent document owns the#), and requiring#would
silently leave every such file nameless. Inline markup (**bold**,`code`)
is stripped from a derived description, because a tokenizer should match words,
not asterisks.Subcommands:
index·resolve·list·stats·doctor·clear.
It finds files; it does not read them. No embeddings, no LLM, no network.Verified on the maintainer's machine: 4/4 top-1 hits over a 19-chapter context
tree; and a fresh agent asked to answer from that tree — without being told
about mcptoon — ranmcptoon docs resolveitself and read 1 file of 19.
Changed
- The skill description gains a Chinese/English trigger block for
docs.
The frontmatter description is all an agent sees before deciding to load a
skill, so a capability missing from it is undiscoverable no matter how well it
works. The block is bilingual on purpose: a Chinese query matched nothing while
it was English-only (measured: 0/4 Chinese queries in the top 10, versus 5/5
top-1 once the Chinese trigger words were added), because this machine's
high-ranking skills all carry Chinese descriptions.
Fixed
-
mcptoon's own directory now follows the XDG Base Directory spec (issue #25).
~/.mcptoonused to be hardcoded andmkdir'd unconditionally, so a user who
wanted a clean$HOMEhad no way to relocate it short of faking$HOMEand
symlinking around it.$XDG_CONFIG_HOME/mcptoonnow holds config,
$XDG_STATE_HOME/mcptoonholds state (logs, toggles) and
$XDG_CACHE_HOME/mcptoonholds cache;MCPTOON_HOMEoverrides all three, with
--diron top of it.Two rules exist to protect installs that already work. XDG is honoured only when
the variable is actually set — an unsetXDG_CONFIG_HOMEmeans "not set", not
"use~/.config", because inventing a default moves files nobody asked to move.
And when the XDG directory does not exist yet but the legacy one does, legacy keeps
winning and the XDG directory is not created — without that guard a user
upgrading from 0.8.15 would watch their configured servers vanish while the data
sat untouched on disk.Only the directory actually in use is created now.
--diris the one wrinkle: the
path constants resolve at import time, so amcptoon --dir X …run creates the
default directory first andconfig.apply_homethen undoes exactly what it
created, once argv has been parsed. -
The
342KBwheel claim had been wrong for two releases — it is363KB.
Measured by building each tag's tree with LF endings, which reproduces the
guard's own history (v0.8.13 measures 350,785 B here against the 350,759 B
recorded intests/test_footprint_claims.py— 26 bytes apart, i.e. build-tool
noise rather than a different tree):Tag Wheel floor KB Claim then v0.8.13 350,785 B 342KB 342KB (correct) v0.8.14 355,132 B 346KB 342KB (stale) v0.8.15 358,743 B 350KB 342KB (stale) v0.8.16 372,376 B 363KB this release The guard did not catch it, and could not have:
test_footprint_claims.pypins a
string and compares the docs against that constant, so it fires when a claim
disagrees with the constant — never when the constant itself has gone stale.
342KBand346KBand350KBjoinRETIRED_KB, the claim moves to363KBon
every surface, and the comment aboveWHEEL_KBrecords the failure mode so the
next release does not repeat it.Correction, same day: this entry first said
362KB. That figure was measured
from the working tree before a concurrent session's README rewrite had merged,
and the wheel embeds README verbatim (pyprojectsetsreadme = "README.md"), so
the rewrite moved the wheel by most of the 1,521-byte difference. The authoritative
method isgit archive <tag>— the tree that actually publishes — never the working
tree.362KBjoinsRETIRED_KBtoo.