activeing123/mcptoon v0.7.17

mcptoon 0.7.17 — bench, and a README built around both halves

on GitHub

Added

• mcptoon bench — prove the savings on your own machine, in one command.
  The README's token claims had a proof, but it needed a clone: the scripts live
  in scripts/, which the wheel does not ship. bench is inside the wheel, so
  pip install mcptoon && mcptoon bench measures both halves at once — tool
  schemas against the name index, and every SKILL.md against the resident
  pointer and one lookup. tiktoken is used when present (exact numbers, the ones
  the README quotes); without it the table says "estimate" rather than passing a
  guess off as a measurement. It is read-only: it reads the schema cache and the
  skill index and never writes the usage ledger.
  • The skill half counts one level deep, excludes _index, and de-duplicates
    roots by real path. On a machine whose agent folders are junctions onto one
    catalog — the common multi-agent layout, and this one — a naive walk counted
    the same catalog four times (3,710,031 tokens instead of 931,339). The skipped
    duplicate count is printed, not hidden.
  • mcptoon bench --json emits the same numbers for scripts; --roots points
    it at any catalog.

Changed

• Both READMEs were rewritten around the two halves of one toolbox. The old
  text led with MCP and treated skills as an add-on bolted on later. The
  subtitle, the definition, How it works and Works with every AI agent now
  describe one gateway managing both, in the same words, and a new Technical
  specification section pairs the two sides feature by feature.
  • The self-proof block no longer tells a reader to git clone; it runs
    mcptoon bench.
  • Three evidence links (Anthropic's engineering blog, Firecrawl, Scalekit)
    became plain-text citations: the evidence stays, the outbound clicks do not.
    No competitor product page is linked anywhere in the README.

Fixed

• The wheel-size claim said 180KB; the wheel is 188KB. This release adds
  src/mcptoon/bench.py (~13KB) on top of skills.py, and the README — which is
  embedded in the wheel METADATA — grew by ~10KB when it began documenting the
  skills family. python -m build now yields 192,988 bytes (188.46 KB),
  identical across builds. All eighteen surfaces that stated the old figure are
  corrected, including the two shipped SKILL.md cards and the Claude plugin.

• The suite total was stale on eight surfaces after bench brought tests of
  its own: README.md, README.zh-CN.md, DEVELOPERS.md, ROADMAP.md, both
  landing pages and docs/tiktoken-benchmarks.md now read 1049 passed, 1 skipped
  (the passed count, matching the badge convention), and the module/line counts
  moved to 25 / 15,656.

• Skills became a managed catalog, not just a search index. v0.7.16 taught
  mcptoon skills to index and route a skill catalog. This release adds the
  other half — distribution and lifecycle — so the same one-source-of-truth
  model that already governs MCP servers now governs skills too:

  • mcptoon skills sync [SRC] [VIEW ...] distributes a source catalog into
    every agent's skill folder. Views are links (a junction on Windows, no
    admin needed), so one edit at the source is instantly visible everywhere and
    there is no second copy to drift. --copy forces real directories, --dry
    prints the plan without writing. A real directory where a link belongs is
    archived, never deleted; removal happens at the source and the views
    follow; a link owned by another manager is reported and left untouched.
  • mcptoon skills add <name> [--desc D] and mcptoon skills remove <name>
    manage the source. Removal moves the skill into a dated archive beside
    the source — a wrong removal is a mv back, not a re-clone.
  • mcptoon skills list [--usage] [--all] lists the catalog; --usage adds
    per-skill hit counts. Counts cover skills mcptoon routed (via
    resolve/route); a skill an agent loaded directly is invisible, and the
    output says so rather than implying full coverage.

• The gateway now has a voice. serve returns an instructions field from
  the MCP initialize handshake — the protocol's official channel for a server to
  brief the model — so every client that honours it learns what mcptoon is
  without anyone editing a system prompt. The one-line end-of-turn disclosure it
  steers ("mcptoon saved ~N tokens this session") is backed by a new first-party
  tool, mcptoon_usage, which returns the real figures, so the model never has
  to estimate them. Turn it off with mcptoon config set footer off; the setting
  persists and suppresses the field entirely on the next connection.

• mcptoon config [get|set] reads and writes gateway settings
  (~/.mcptoon/settings.json, separate from server config so a settings write
  can never corrupt a server definition). Unknown keys fail loudly.

• The catalog manager reached parity with the script it replaces. Taking over
  from a long-running sync script means matching it byte for byte, not just
  approximately — a derived view that differs by a line ending is a diff the next
  sync has to fight. Four capabilities close the gap, each one learned from a real
  failure in that lineage:

  • mcptoon skills sync --version-gate blocks a skill whose content changed but
    whose frontmatter version did not, and prints why. It reads the same
    ledger file the other manager wrote (skill_versions.json, overridable with
    MCPTOON_SKILLS_LEDGER), so during a hand-over both reach the same verdict on
    the same bytes. --force is the escape hatch (lets the change through and
    rebaselines); a skill with no version is warned about rather than blocked;
    the ledger's own files are excluded from the hash so the tool that owns the
    ledger cannot gate itself forever.
  • mcptoon skills sync --derived roo|opencode|all regenerates the flat
    <slug>.md views (plus each skill's .py attachments as <slug>_<file>.py)
    that Roo and OpenCode read. Output is byte-identical to the incumbent's — 422
    files per view verified against the live folders — including the platform line
    endings a text-mode write produces. Stale entries are moved to the graveyard,
    never deleted.
  • mcptoon skills remove --tombstone commits the removal so a two-way git sync
    cannot resurrect a deleted skill. The commit is path-scoped; a whole-repo
    git add -A is refused on purpose, because the repo holding a real skill
    source routinely has hundreds of unrelated edits in flight and sweeping them
    into a "tombstone" is how one manager silently commits another session's work.
  • --archive DIR points drift and removals at a shared graveyard, so a
    rollback is the same mv whichever manager performed the removal.

Fixed

• mcptoon skills was invisible in mcptoon help. The command family worked
  and was tested, but the top-level usage block never listed it — so the headline
  feature of this release could not be discovered from the CLI at all. The block
  now carries the four common forms (list, resolve, sync, add|remove), and
  tests/test_command_coverage.py fails the build if a command the help advertises
  is missing from either README.

• Both READMEs never documented the skills catalog. The skills family was
  absent from the "All commands" block and had no section of its own, even though
  it is what this release is about. discover, init, health and policy were
  missing from the list too. All are now documented, and the new coverage guard
  keeps the README and the CLI in step.

• The wheel size claim said 156KB; the wheel is 179KB. This release adds
  src/mcptoon/skills.py, a new ~68KB module, which grew the wheel from 155.5 KB
  to 179.4 KB (measured with python -m build, identical across builds). Thirty-odd
  surfaces still advertised the old figure — README (both languages), the landing
  pages, docs/comparison.md, docs/tiktoken-benchmarks.md, the shipped skill card
  and the Claude plugin scripts. All are corrected, and the footprint guard's
  WHEEL_KB constant with them, so the guard stops pinning a stale number.

• The landing pages advertised v0.7.16 to crawlers. Both docs/index.html and
  docs/index-zh.html still carried "softwareVersion": "0.7.16" in their JSON-LD
  block while the visible copy said 0.7.17.

• _index is no longer published as a skill. The vault keeps its index card
  at skills/_index/SKILL.md; it carries a SKILL.md but is not a skill. mcptoon
  walked into it and would have written a phantom _index.md into every derived
  view — caught by the byte-parity check against the live ~/.roo/commands, which
  had 371 files to mcptoon's 372. The name is now skipped everywhere a tree is
  walked, matching the incumbent's behaviour in all 13 of its walkers.

• The footprint guard could not see a comma-glued test total. Its regex
  required whitespace before the separator, so a line reading 956 passed, 1 skipped never matched and a stale suite total hid in the README for two days.
  The pattern now tolerates optional whitespace on both sides, and a regression
  test pins every separator spelling.