github activeing123/mcptoon v0.8.16
v0.8.16 — mcptoon docs: route a query to the right file

latest releases: v0.8.40, v0.8.39, v0.8.38...
one month ago

[0.8.16] - 2026-10-07

Added

  • mcptoon docs — index a Markdown tree and route a query to the right file.
    A large AGENTS.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
    marked derived: 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
    — ran mcptoon docs resolve itself 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).
    ~/.mcptoon used to be hardcoded and mkdir'd unconditionally, so a user who
    wanted a clean $HOME had no way to relocate it short of faking $HOME and
    symlinking around it. $XDG_CONFIG_HOME/mcptoon now holds config,
    $XDG_STATE_HOME/mcptoon holds state (logs, toggles) and
    $XDG_CACHE_HOME/mcptoon holds cache; MCPTOON_HOME overrides all three, with
    --dir on top of it.

    Two rules exist to protect installs that already work. XDG is honoured only when
    the variable is actually set
    — an unset XDG_CONFIG_HOME means "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. --dir is the one wrinkle: the
    path constants resolve at import time, so a mcptoon --dir X … run creates the
    default directory first and config.apply_home then undoes exactly what it
    created, once argv has been parsed.

  • The 342KB wheel claim had been wrong for two releases — it is 363KB.
    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 in tests/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.py pins 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.
    342KB and 346KB and 350KB join RETIRED_KB, the claim moves to 363KB on
    every surface, and the comment above WHEEL_KB records 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 (pyproject sets readme = "README.md"), so
    the rewrite moved the wheel by most of the 1,521-byte difference. The authoritative
    method is git archive <tag> — the tree that actually publishes — never the working
    tree. 362KB joins RETIRED_KB too.

Don't miss a new mcptoon release

NewReleases is sending notifications on new releases.