mcp-server-mcpindex 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to `mcp-server-mcpindex` are recorded here.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-06-08
+
+### Added
+
+- **Update notice on startup.** After the server connects, it does a best-effort check against the npm registry and, if a newer version is published, prints one advisory line to stderr and (if the host enabled MCP logging) sends a `notifications/message` the host may render — including the reminder to **restart your MCP host to load the new version**. The check is time-boxed (~2.5s), fail-silent on any error, fire-and-forget (it can never delay or crash startup), sends no telemetry beyond the standard registry GET, and never follows a redirect off the pinned registry host. Opt out with `MCPINDEX_NO_UPDATE_CHECK=1`.
+
+### Changed
+
+- **The running version is now read from `package.json`** instead of a hardcoded constant (which had drifted to `0.2.1` while the package was `0.2.2`), so the User-Agent and the update check always reflect what npm actually shipped.
+- The `logging` server capability is now declared (required to deliver the update notice as an MCP notification).
+
+### Internal
+
+- New `src/update-check.mjs` (pure, injected-`fetch`, unit-tested) + `test/update-check.test.mjs`. `npm run build` now syntax-checks it too.
+
 ## [0.2.2] - 2026-05-31
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-mcpindex",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "An MCP server for finding MCP servers, plus advisory trust verdicts (check_tool_trust, assess_server) for agent frameworks. Drop-in for Claude Desktop, Cursor, Cline, Zed.",
   "keywords": [
     "mcp",
@@ -39,7 +39,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "node --check src/index.mjs && node --check src/trust.mjs",
+    "build": "node --check src/index.mjs && node --check src/trust.mjs && node --check src/update-check.mjs",
     "test": "node --test test/*.test.mjs",
     "check-published": "node scripts/check-published.mjs",
     "release": "node scripts/release.mjs"

package/src/index.mjs

@@ -8,14 +8,20 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
+import { createRequire } from 'node:module';
 export { checkToolTrust, assessServer, VERDICT_CONTRACT_VERSION, V1_HONEST_LIMITS } from './trust.mjs';
+import { notifyUpdateIfAvailable } from './update-check.mjs';
 
 const API_BASE = process.env.MCPINDEX_API_BASE ?? 'https://mcpindex.ai';
-const PKG_VERSION = '0.2.1';
+// Single source of truth for the running version — read from package.json so the
+// User-Agent and the update-check can never drift from what npm actually shipped.
+const PKG_VERSION = createRequire(import.meta.url)('../package.json').version;
 
 const server = new Server(
   { name: 'mcp-server-mcpindex', version: PKG_VERSION },
-  { capabilities: { tools: {} } },
+  // `logging` lets us push the update notice as an MCP notifications/message the
+  // host may render to the user; `sendLoggingMessage` no-ops without it.
+  { capabilities: { tools: {}, logging: {} } },
 );
 
 const TOOLS = [
@@ -284,3 +290,8 @@ function formatCompare(rows) {
 const transport = new StdioServerTransport();
 await server.connect(transport);
 console.error('[mcp-server-mcpindex] connected via stdio');
+
+// Fire-and-forget: tell the user if a newer version exists (stderr + best-effort
+// MCP notification). Dropped onto the event loop AFTER connect so it can never
+// delay or crash startup; all errors are swallowed inside.
+notifyUpdateIfAvailable({ currentVersion: PKG_VERSION, server }).catch(() => {});

package/src/update-check.mjs

@@ -0,0 +1,120 @@
+// update-check.mjs — best-effort "a newer mcp-server-mcpindex exists" notice.
+//
+// Why this is safe to ship in a server that already egresses:
+//   - outbound to the PINNED npm registry host only, https, no redirect-following
+//     (no SSRF pivot), time-boxed, and fail-silent on ANY error;
+//   - fire-and-forget — it never blocks or crashes startup (the caller drops it
+//     onto the event loop after connect and ignores rejections);
+//   - no telemetry beyond the standard registry GET (no version of the user, no
+//     machine id — just "what's the latest published version of this package");
+//   - opt-out via MCPINDEX_NO_UPDATE_CHECK.
+//
+// Pure + injectable (fetchImpl) so it is unit-testable with no network.
+
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+const DEFAULT_PKG = 'mcp-server-mcpindex';
+const DEFAULT_TIMEOUT_MS = 2500;
+
+/** major.minor.patch -> [n,n,n]; drops prerelease/build; 9-digit cap (DoS guard).
+ *  Returns null for anything non-canonical (so an odd tag never triggers a nag). */
+export function parseSemver(v) {
+  if (typeof v !== 'string') return null;
+  const core = v.trim().split('+')[0].split('-')[0];
+  const parts = core.split('.');
+  if (parts.length !== 3) return null;
+  const nums = [];
+  for (const p of parts) {
+    if (!/^\d{1,9}$/.test(p)) return null;
+    nums.push(Number(p));
+  }
+  return nums;
+}
+
+/** true iff `current` is a strictly-older canonical semver than `latest`.
+ *  Unparseable on either side -> false (never nag on ambiguity). */
+export function isOlder(current, latest) {
+  const a = parseSemver(current);
+  const b = parseSemver(latest);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i += 1) {
+    if (a[i] < b[i]) return true;
+    if (a[i] > b[i]) return false;
+  }
+  return false;
+}
+
+/** The user-facing line. Advisory voice; carries the restart reminder because a
+ *  running MCP server is only replaced when the host restarts it. */
+export function formatUpdateMessage(current, latest) {
+  return (
+    `mcp-server-mcpindex ${current} -> ${latest} available. ` +
+    `Update: npm i -g mcp-server-mcpindex@latest ` +
+    `(or npx fetches it on next launch), then restart your MCP host ` +
+    `(Claude Desktop / Cursor / Cline / Zed) to load it.`
+  );
+}
+
+/** Disabled when MCPINDEX_NO_UPDATE_CHECK is set to any non-falsey value. */
+export function updateCheckDisabled(env = process.env) {
+  const raw = (env.MCPINDEX_NO_UPDATE_CHECK ?? '').trim().toLowerCase();
+  return raw !== '' && raw !== '0' && raw !== 'false' && raw !== 'no' && raw !== 'off';
+}
+
+/** Fetch the latest published version string, or null on ANY failure/timeout.
+ *  Never throws. `fetchImpl` is injectable for tests. */
+export async function fetchLatestVersion({
+  registry = DEFAULT_REGISTRY,
+  pkg = DEFAULT_PKG,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  fetchImpl = fetch,
+} = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(`${registry}/${encodeURIComponent(pkg)}/latest`, {
+      signal: controller.signal,
+      headers: { Accept: 'application/json' },
+      redirect: 'error', // SSRF: never follow a redirect off the pinned host
+    });
+    if (!res || !res.ok) return null;
+    const body = await res.json();
+    const v = body && typeof body.version === 'string' ? body.version : null;
+    return v && parseSemver(v) ? v : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Orchestration: check, and if a newer version exists, emit on BOTH channels.
+ *  stderr is the reliable channel; the MCP logging notification is best-effort
+ *  (only delivered if the host enabled `logging` and didn't filter `info`).
+ *  Returns the message it emitted (or null) — handy for tests/callers.
+ *  Never throws; never blocks the caller meaningfully (caller fire-and-forgets). */
+export async function notifyUpdateIfAvailable({
+  currentVersion,
+  server = null,
+  env = process.env,
+  log = (m) => console.error(`[mcp-server-mcpindex] ${m}`),
+  fetchImpl = fetch,
+  pkg = DEFAULT_PKG,
+} = {}) {
+  try {
+    if (updateCheckDisabled(env)) return null;
+    const latest = await fetchLatestVersion({ pkg, fetchImpl });
+    if (!latest || !isOlder(currentVersion, latest)) return null;
+    const msg = formatUpdateMessage(currentVersion, latest);
+    log(msg); // stderr — reliable
+    if (server && typeof server.sendLoggingMessage === 'function') {
+      try {
+        await server.sendLoggingMessage({ level: 'info', logger: 'mcpindex', data: msg });
+      } catch {
+        /* host didn't enable logging / filtered the level — stderr already covered it */
+      }
+    }
+    return msg;
+  } catch {
+    return null; // belt-and-suspenders: this path must never surface an error
+  }
+}