chore(distribution): standardise tool count on 19 + amend cascade docs (Glama auto-publish verified)#46
Merged
Conversation
Diagnosis-only commit. Lands BEFORE any copy is changed per sprint hard rule "diagnosis lands as a commit before any copy is changed". Findings summary: - siteStats.ts:5 toolCount: 18 → 19 (propagates to homepage, /about, /api-docs) - siteStats.ts:7 mcpToolCount: 18 → 19 (genuinely stale; MCP surface IS 19, verified by scripts/smoke-test.mjs assertion at lines 633/647/660/ 675 plus hasTool: 'get_subscribe_link') - FREIGHTUTILS_STRATEGY.md:54 "live v2.1.0 / 18 tools" → "live v2.1.1 / 19 tools" - All other in-repo "11 / 18" occurrences are historical narrative (STATE.md PR-#45 entry, CHANGELOG.md release notes, changelog-data.ts archive, distribution-cascade audit doc forensic record). LEAVE. Surface architecture documented: - REST API surface = 18 (api-tools-registry.ts) - MCP surface = 19 (REST 18 + get_subscribe_link meta-tool) - STATE.md:10 leads with the MCP-surface number for both surfaces, per sprint directive to standardise. External follow-ups for the PR body (out of this sandbox's repo scope): - SoapyRED/freightutils-mcp README.md, server.json (≤100 char), package. json descriptions — must enumerate 19 tools and tag get_subscribe_link as a meta-tool, not a freight calculator - Glama listing description (dashboard-only edit) — currently frozen at "11 freight calculation and reference tools" - punkpeye/awesome-mcp-servers PR #5358 — already targets 19, confirm pre-merge - Smithery, Glama Overview, mcp.directory — will re-derive on next scrape Glama mental-model amendment (Phase 3 prep): Chrome verification confirms Glama auto-publishes builds when they succeed. The "Build succeeded for FreightUtils MCP Server" email is informational, no maintainer click required. CLAUDE.md + STATE.md currently lead with the Releases-scrape framing without noting the auto-publish behaviour.
Phase 2 + Phase 3 of the distribution-closure sprint. Diagnosis (Phase 1)
landed in the prior commit at docs/audit/tool-count-standardise-2026-05-17.md.
Phase 2 — copy standardisation:
- lib/constants/siteStats.ts: toolCount 18 → 19, mcpToolCount 18 → 19.
Propagates to homepage ("19 tools and 19 API endpoints"), /about
("19 free freight calculators"), and /api-docs ("AI agents direct
access to all 19 freight calculation and reference tools").
- FREIGHTUTILS_STRATEGY.md: mcp.directory bullet "live v2.1.0 / 18 tools"
→ "live v2.1.1 / 19 tools".
- Historical "11" / "18" mentions in changelog entries, STATE.md PR-#45
record, and the distribution-cascade audit doc's forensic record are
LEFT — they correctly describe past or external state. See the Phase 1
audit doc for the full leave-vs-update inventory.
Phase 3 — cascade-doc amendments (Glama mental-model correction):
- CLAUDE.md "Distribution cascade" section Glama bullet rewritten to
reflect verified reality: Glama auto-publishes its build artefact on
successful scrape-derived build — the "Build succeeded for FreightUtils
MCP Server" maintainer email is informational, no "Create a release"
click required. Added one-liner "Glama mental-model history: cascade
was repeatedly mis-described in our docs/memory. Verify Glama
behaviour, do not predict it — Chrome it, do not infer it from
registry semantics." Third drift in three days.
- STATE.md distribution surfaces table: Glama row Maintenance grade
C → B (post-publish). Notes amended to remove any wording implying a
manual maintainer publish step. Auto-publish behaviour now explicit.
- docs/audit/distribution-cascade-2026-05-16.md: third amendment block
"Amendment 2026-05-17 (afternoon): Glama auto-publishes on successful
build" appended. Documents the recurring-lesson table (three cascade
drifts since 2026-05-15) and confirms Maintenance grade C → B
post-publish.
FAULT 5:
- CHANGELOG.md + lib/changelog-data.ts entries added for /changelog page.
- tsc clean. next build green. Static HTML for /, /about, /api-docs,
/changelog all render 19 / new entry.
External follow-ups (out of this sandbox's repo access; listed in the PR
body with exact target text + URLs):
- SoapyRED/freightutils-mcp README.md: enumerate 19 tools, add a
"Subscription helpers" subsection tagging get_subscribe_link as a
meta-tool (not a freight calculator).
- SoapyRED/freightutils-mcp server.json description: ≤100 char, must
mention 19 tools. Suggested: "AI agent access to 19 freight tools —
DG, HS, customs, airlines, UN/LOCODE, more" (89 chars).
- SoapyRED/freightutils-mcp package.json description (npm registry):
match server.json target.
- Glama dashboard description field (frozen, not in glama.json): refresh
via dashboard edit to mirror the server.json target.
- punkpeye/awesome-mcp-servers PR #5358: confirm description already
states "19 freight tools" pre-merge.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Sprint
distribution-closure-tool-count-and-cascade-docs. Two commits:docs(audit): tool-count standardise diagnosis (Phase 1)). Audit-only commit listing every stale tool-count occurrence in this repo with file:line and what each should become. Landed BEFORE any copy was changed per sprint hard rule.chore(distribution): standardise tool count on 19; amend cascade docs). Both phases in one commit since they're tightly coupled and Phase 1 was the gating commit.Phase 1 — audit findings (committed at
docs/audit/tool-count-standardise-2026-05-17.md)The canonical count is 19 (MCP-surface — 18 REST endpoints +
get_subscribe_linkmeta-tool). Verified byscripts/smoke-test.mjs:633/647/660/675which assertstoolCount: 19andhasTool: 'get_subscribe_link'on/api/mcptools/list.Surface-by-surface truth table:
/api/tools,/api/health)lib/api-tools-registry.ts)/api/mcp,/api/mcp/mcp, npmfreightutils-mcp, MCP Registry)get_subscribe_link)Per sprint hard rule "standardise on 19 across all copy. Do not introduce 18 anywhere new", the site copy now reports 19.
Phase 2 — in-repo edits
lib/constants/siteStats.tstoolCount: 18 → 19,mcpToolCount: 18 → 19. Propagates automatically to homepage, /about, /api-docs.FREIGHTUTILS_STRATEGY.md"live v2.1.0 / 18 tools"→"live v2.1.1 / 19 tools".LEFT as-is (historical narrative correctly describing past/external state — see Phase 1 audit doc §"In-repo findings — historical / no-change" for the full list):
CHANGELOG.md,lib/changelog-data.tsreferencing "11 tools" / "18 tools" in past-state context (PR fix(distribution): cut GitHub Releases on tag push (Glama tracking gap) #45, B003 bug-fix entry, etc.).STATE.mdlines 63 / 144 / 224 describing past Glama state.docs/audit/distribution-cascade-2026-05-16.mdforensic record (lines 99, 104, 112, 192, 258, 322, 346).Build verification on local prod-build:
Phase 3 — cascade-doc amendments (Glama mental-model correction)
Chrome verification confirmed: Glama auto-publishes its build artefact when the scrape-derived build succeeds. The "Build succeeded for FreightUtils MCP Server" maintainer email is informational, no "Create a release" click required. Maintenance grade
C → Bconfirmed post-publish.Recurring lesson — third cascade drift in three days:
Encoded changes:
CLAUDE.md"Distribution cascade" → Glama bullet rewritten + new one-liner: "verify Glama behaviour, do not predict it — Chrome it, do not infer it from registry semantics."STATE.mddistribution surfaces table → Glama row Maintenance gradeC → B (post-publish); wording implying manual maintainer publish step removed.docs/audit/distribution-cascade-2026-05-16.md→ third amendment appended ("Amendment 2026-05-17 (afternoon): Glama auto-publishes on successful build").External follow-ups (out of this sandbox's
SoapyRED/freightutils-mcprepo access)Listed in
docs/audit/tool-count-standardise-2026-05-17.md§"External" with exact target text + URLs. Summary:SoapyRED/freightutils-mcp/README.mdget_subscribe_linkas a meta-tool (not a freight calculator) so users don't expect another calculator.SoapyRED/freightutils-mcp/server.jsondescription (≤100 chars — do NOT regress past 100)"AI agent access to 19 freight tools — DG, HS, customs, airlines, UN/LOCODE, more"(89 chars)SoapyRED/freightutils-mcp/package.jsondescription (npm registry surface)glama.jsononly acceptsmaintainers)freightutils-mcpREADME + server.json + package.json land.punkpeye/awesome-mcp-serversPR #5358docs/audit/distribution-cascade-2026-05-16.md:198.FAULT 5 release-hygiene checklist
siteStats.tsupdated (toolCount 18→19, mcpToolCount 18→19).CHANGELOG.mdentry added (top of 2026-05-17 section).lib/changelog-data.tsmirror entry added (new entry above the existing 17 May MCP Update entry)./changelogrenders the new entry (verified in built static HTML — both versions render).app/sitemap.tsuntouched (N/A).public/openapi.jsonuntouched (N/A).Sprint exit criteria
docs/audit/tool-count-standardise-2026-05-17.mdcommitted listing every stale-count occurrence found (Phase 1).docs/audit/distribution-cascade-2026-05-16.mdthird amendment committed (Phase 3).🤖 Generated with Claude Code
Generated by Claude Code