feat: npm-version self-check + accurate aztec_status version#21
Merged
critesjosh merged 2 commits intomainfrom May 2, 2026
Merged
feat: npm-version self-check + accurate aztec_status version#21critesjosh merged 2 commits intomainfrom
critesjosh merged 2 commits intomainfrom
Conversation
Closes the staleness gap that drove this PR's parent dogfood test: the MCP server pulled its displayed version from sync metadata (populated at last `aztec_sync_repos` run, not at boot), so an upgraded package would still report the OLD version under `aztec_status`. Combined with npx's package cache, this made "running an out-of-date MCP" near-undetectable from inside a session. Three changes solve it together: 1. New `src/utils/version-self-check.ts`. At startup the server GETs `https://registry.npmjs.org/@aztec/mcp-server/latest` (2s timeout, fails silently on network/registry error). Compares against the live `MCP_VERSION` (read from package.json by `src/version.ts`). On `outdated`, the result is cached in a module-level singleton so both the InitializeResult `instructions` banner AND the `aztec_status` text can surface it without a second registry hit. 2. Banner content: `instructions` gets a multi-line "UPDATE AVAILABLE" footer that names both versions and lists the `@aztec/mcp-server@latest` upgrade paths for Claude Desktop / Cursor / Codex / Claude Code / global install. Written to be read by the LLM consumer — the model passes it through to the user. `aztec_status` gets a single-line warning so a curious user running diagnostics sees the same signal. 3. `formatStatus` now reads the live `MCP_VERSION` from the `version.ts` import — fixes the staleness bug. Sync-metadata version moves to a contextual annotation that only renders when it differs from live ("(last sync ran under MCP server v1.5.0 — re-run aztec_sync_repos to refresh metadata)"). Always-show ordering: live version, npm-latest comparison, repos dir, sync metadata. README updated: every install snippet (`npx`, `npm install -g`, `.mcp.json` examples) pinned to `@aztec/mcp-server@latest`. Added a prominent note explaining why npx caching makes the bare form a foot-gun. Tests: 264/264. New `tests/utils/version-self-check.test.ts` with 19 cases (semver edge cases incl. pre-release, fetch failure modes, cache lifecycle, banner formatting). Updated `tests/utils/format.test.ts` for the new live-version display + 4 new cases for the upgrade-line behaviors. End-to-end probe over stdio confirmed the banner reaches both `initialize` (instructions) and `tools/call aztec_status` correctly when the running version trails npm-latest. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…t-loop pin Codex review feedback on PR #21. The previous implementation only cleared the abort timer on the success path — when `fetchImpl` rejected (network error, malformed body), the catch block returned null but the timer was left running until it fired. In a long-lived MCP server that's invisible (the timer just expires harmlessly seconds later), but in short-lived processes / tests it would prevent the event loop from exiting cleanly. Two-line fix: - `timer.unref()` (Node-only, optional-chained for portability) so the timer alone never keeps the loop alive. - `clearTimeout(timer)` moved into a `finally` block so it runs on both success and exception paths. Belt-and-braces by design: either fix alone is sufficient, but together they leave no path for a stray timer. 19 version-self-check tests still pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
🎉 This PR is included in version 1.21.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
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
1 participant
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
Closes the version-staleness gap surfaced during the v1.20.0 dogfood test. Three changes together:
1. npm self-check at startup
New
src/utils/version-self-check.tsGETshttps://registry.npmjs.org/@aztec/mcp-server/latestat boot (2s timeout, fails silently on network/registry error), compares against the liveMCP_VERSION(already read frompackage.jsonbysrc/version.ts), caches the result in a module-level singleton.2. Surface the warning in two places
MCP
instructionsbanner — appended toSEMANTIC_INSTRUCTIONS/LOCAL_ONLY_INSTRUCTIONSwhen outdated. Written for the LLM consumer, who'll pass it to the user:aztec_statusoutput — single-line warning so a curious user running diagnostics sees the same signal:⚠️ UPDATE AVAILABLE: v1.20.0 → v1.21.0 on npm. Switch your MCP config to \@aztec/mcp-server@latest` and restart the client.`3. Fix the staleness bug in
aztec_statusformatStatuspreviously renderedMCP server version: ${syncMetadata.mcpVersion}— that field is set at last-sync time, not boot. After upgrading the package,aztec_statuswould still show the old version until you ranaztec_sync_repos. Fixed by reading the liveMCP_VERSIONfromsrc/version.ts. Sync-metadata version moves to a contextual annotation only rendered when different ("(last sync ran under MCP server v1.5.0 — re-run aztec_sync_repos to refresh metadata)").README
Every install snippet pinned to
@aztec/mcp-server@latest. Added a note explaining why npx caching makes the bare form a foot-gun.Test plan
npm run build(tsc clean)npx vitest run— 264/264 (was 247; +19 forversion-self-check.test.ts, +4 reworkedformat.test.tscases for the new live-version display)initialize→result.instructionscontains the upgrade banner with both versions and@aztec/mcp-server@latestguidancetools/call aztec_status→ liveMCP server version: 1.6.0+⚠️ UPDATE AVAILABLE: v1.6.0 → v1.20.0 on npm.Failure modes
fetchLatestNpmVersionreturnsnull, no banner injected,aztec_statusshows live version without an npm-latest line. Server boots normally.1.21.0-rc.1while1.20.0is on npm):compareSemverstrips the prerelease suffix, so1.21.0-rc.1does NOT flag as outdated against1.20.0. (Strictly: it flags1.21.0-rc.1as equal to1.21.0but NEWER than1.20.0— correct.)🤖 Generated with Claude Code