chub-dev 0.2.0-beta.3 → 0.3.0

package/src/lib/registry.js

@@ -1,8 +1,191 @@
-import { loadSourceRegistry } from './cache.js';
+import { loadSourceRegistry, loadSearchIndex } from './cache.js';
 import { loadConfig } from './config.js';
 import { normalizeLanguage } from './normalize.js';
+import { buildIndexFromDocuments, compactIdentifier, search as bm25Search, tokenize } from './bm25.js';
 
 let _merged = null;
+let _searchIndex = null;
+
+function getSearchLookupId(sourceName, entryId) {
+  return `${sourceName}:${entryId}`;
+}
+
+function normalizeQuery(query) {
+  return String(query || '')
+    .trim()
+    .replace(/\s+/g, ' ');
+}
+
+function splitCompactSegments(text) {
+  return [...new Set([
+    ...String(text || '').split('/').map((segment) => compactIdentifier(segment)),
+    ...String(text || '').split(/[\/_.\s-]+/).map((segment) => compactIdentifier(segment)),
+  ])].filter(Boolean);
+}
+
+function levenshteinDistance(a, b, maxDistance = Infinity) {
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+  if (Math.abs(a.length - b.length) > maxDistance) return maxDistance + 1;
+
+  let previous = Array.from({ length: b.length + 1 }, (_, idx) => idx);
+  let current = new Array(b.length + 1);
+
+  for (let i = 1; i <= a.length; i++) {
+    current[0] = i;
+    let rowMin = current[0];
+
+    for (let j = 1; j <= b.length; j++) {
+      const substitutionCost = a[i - 1] === b[j - 1] ? 0 : 1;
+      current[j] = Math.min(
+        previous[j] + 1,
+        current[j - 1] + 1,
+        previous[j - 1] + substitutionCost,
+      );
+      rowMin = Math.min(rowMin, current[j]);
+    }
+
+    if (rowMin > maxDistance) return maxDistance + 1;
+    [previous, current] = [current, previous];
+  }
+
+  return previous[b.length];
+}
+
+function scoreCompactCandidate(queryCompact, candidateCompact, weights) {
+  if (!queryCompact || !candidateCompact) return 0;
+  if (candidateCompact === queryCompact) return weights.exact;
+  if (queryCompact.length < 3) return 0;
+
+  const lengthPenalty = Math.abs(candidateCompact.length - queryCompact.length);
+  const lengthRatio = Math.min(candidateCompact.length, queryCompact.length)
+    / Math.max(candidateCompact.length, queryCompact.length);
+
+  if ((candidateCompact.startsWith(queryCompact) || queryCompact.startsWith(candidateCompact)) && lengthRatio >= 0.6) {
+    return Math.max(weights.prefix - lengthPenalty, 0);
+  }
+
+  if ((candidateCompact.includes(queryCompact) || queryCompact.includes(candidateCompact)) && lengthRatio >= 0.75) {
+    return Math.max(weights.contains - lengthPenalty, 0);
+  }
+
+  if (queryCompact.length < 5) return 0;
+
+  const maxDistance = queryCompact.length <= 5 ? 1 : queryCompact.length <= 8 ? 2 : 3;
+  const distance = levenshteinDistance(queryCompact, candidateCompact, maxDistance);
+  if (distance > maxDistance) return 0;
+
+  return Math.max(weights.fuzzy - (distance * 20) - lengthPenalty, 0);
+}
+
+function scoreEntryLexicalVariant(entry, queryCompact) {
+  if (queryCompact.length < 2) return 0;
+
+  const nameCompact = compactIdentifier(entry.name);
+  const idCompact = compactIdentifier(entry.id);
+  const idSegments = splitCompactSegments(entry.id);
+  const nameSegments = splitCompactSegments(entry.name);
+
+  let best = 0;
+
+  best = Math.max(best, scoreCompactCandidate(queryCompact, nameCompact, {
+    exact: 620,
+    prefix: 560,
+    contains: 520,
+    fuzzy: 500,
+  }));
+
+  best = Math.max(best, scoreCompactCandidate(queryCompact, idCompact, {
+    exact: 600,
+    prefix: 540,
+    contains: 500,
+    fuzzy: 470,
+  }));
+
+  for (let idx = 0; idx < idSegments.length; idx++) {
+    const segment = idSegments[idx];
+    const segmentScore = scoreCompactCandidate(queryCompact, segment, {
+      exact: 580,
+      prefix: 530,
+      contains: 490,
+      fuzzy: 460,
+    });
+    if (segmentScore === 0) continue;
+
+    let bonus = 0;
+    const isFirst = idx === 0;
+    const isLast = idx === idSegments.length - 1;
+    if (isFirst) bonus += 10;
+    if (isLast) bonus += 10;
+    if (queryCompact === idSegments[0]) bonus += 60;
+    if (queryCompact === idSegments[idSegments.length - 1]) bonus += 25;
+    if (idSegments.length > 1 && queryCompact === idSegments[0] && queryCompact === idSegments[idSegments.length - 1]) {
+      bonus += 40;
+    }
+
+    best = Math.max(best, segmentScore + bonus);
+  }
+
+  for (const segment of nameSegments) {
+    best = Math.max(best, scoreCompactCandidate(queryCompact, segment, {
+      exact: 560,
+      prefix: 520,
+      contains: 480,
+      fuzzy: 450,
+    }));
+  }
+
+  return best;
+}
+
+function scoreEntryLexicalBoost(entry, normalizedQuery, rescueTerms = []) {
+  const queryCompacts = [...new Set([
+    compactIdentifier(normalizedQuery),
+    ...rescueTerms.map((term) => compactIdentifier(term)),
+  ])].filter((queryCompact) => queryCompact.length >= 2);
+
+  let best = 0;
+  for (const queryCompact of queryCompacts) {
+    best = Math.max(best, scoreEntryLexicalVariant(entry, queryCompact));
+  }
+  return best;
+}
+
+function getMissingQueryTerms(normalizedQuery) {
+  if (!_searchIndex?.invertedIndex) {
+    return [];
+  }
+
+  return tokenize(normalizedQuery).filter((term) => !_searchIndex.invertedIndex[term]?.length);
+}
+
+function shouldRunGlobalLexicalScan(normalizedQuery, resultByKey) {
+  if (!_searchIndex || resultByKey.size === 0) {
+    return true;
+  }
+
+  if (!_searchIndex.invertedIndex) {
+    return false;
+  }
+
+  const queryTerms = tokenize(normalizedQuery);
+  if (queryTerms.length < 2) {
+    return false;
+  }
+
+  return getMissingQueryTerms(normalizedQuery).length > 0;
+}
+
+function namespaceSearchIndex(index, sourceName) {
+  return {
+    ...index,
+    documents: (index.documents || []).map((doc) => ({
+      ...doc,
+      id: getSearchLookupId(sourceName, doc.id),
+    })),
+  };
+}
 
 /**
  * Load and merge entries from all configured sources.
@@ -14,11 +197,16 @@ function getMerged() {
   const config = loadConfig();
   const allDocs = [];
   const allSkills = [];
+  const searchIndexes = [];
 
   for (const source of config.sources) {
     const registry = loadSourceRegistry(source);
     if (!registry) continue;
 
+    // Load BM25 search index if available
+    const idx = loadSearchIndex(source);
+    if (idx) searchIndexes.push(namespaceSearchIndex(idx, source.name));
+
     // Support both new format (docs/skills) and old format (entries)
     if (registry.docs) {
       for (const doc of registry.docs) {
@@ -46,6 +234,19 @@ function getMerged() {
     }
   }
 
+  // Merge search indexes (combine documents and recompute IDF)
+  if (searchIndexes.length > 0) {
+    if (searchIndexes.length === 1) {
+      const [singleIndex] = searchIndexes;
+      _searchIndex = singleIndex.invertedIndex
+        ? singleIndex
+        : buildIndexFromDocuments(singleIndex.documents, singleIndex.params);
+    } else {
+      const allDocuments = searchIndexes.flatMap((idx) => idx.documents);
+      _searchIndex = buildIndexFromDocuments(allDocuments, searchIndexes[0].params);
+    }
+  }
+
   _merged = { docs: allDocs, skills: allSkills };
   return _merged;
 }
@@ -121,11 +322,11 @@ export function getDisplayId(entry) {
 
 /**
  * Search entries by query string. Searches both docs and skills.
+ * Uses BM25 when a search index is available, falls back to keyword matching.
  */
 export function searchEntries(query, filters = {}) {
+  const normalizedQuery = normalizeQuery(query);
   const entries = applySourceFilter(getAllEntries());
-  const q = query.toLowerCase();
-  const words = q.split(/\s+/);
 
   // Deduplicate: same id+source appearing as both doc and skill → show once
   const seen = new Set();
@@ -138,27 +339,76 @@ export function searchEntries(query, filters = {}) {
     }
   }
 
-  let results = deduped.map((entry) => {
-    let score = 0;
+  // Build entry lookup by id
+  const entryById = new Map();
+  for (const entry of deduped) {
+    entryById.set(getSearchLookupId(entry._source, entry.id), entry);
+  }
 
-    if (entry.id === q) score += 100;
-    else if (entry.id.includes(q)) score += 50;
+  if (!normalizedQuery) {
+    return applyFilters(deduped, filters).map((entry) => ({ ...entry, _score: 0 }));
+  }
 
-    const nameLower = entry.name.toLowerCase();
-    if (nameLower === q) score += 80;
-    else if (nameLower.includes(q)) score += 40;
+  const resultByKey = new Map();
 
-    for (const word of words) {
-      if (entry.id.includes(word)) score += 10;
-      if (nameLower.includes(word)) score += 10;
-      if (entry.description?.toLowerCase().includes(word)) score += 5;
-      if (entry.tags?.some((t) => t.toLowerCase().includes(word))) score += 15;
+  if (_searchIndex) {
+    // BM25 search
+    for (const match of bm25Search(normalizedQuery, _searchIndex)) {
+      const entry = entryById.get(match.id);
+      if (!entry) continue;
+      const key = getSearchLookupId(entry._source, entry.id);
+      resultByKey.set(key, { entry, score: match.score });
     }
+  } else {
+    // Fallback: keyword matching
+    const q = normalizedQuery.toLowerCase();
+    const words = q.split(/\s+/);
+
+    for (const entry of deduped) {
+      let score = 0;
 
-    return { entry, score };
-  });
+      if (entry.id === q) score += 100;
+      else if (entry.id.includes(q)) score += 50;
 
-  results = results.filter((r) => r.score > 0);
+      const nameLower = entry.name.toLowerCase();
+      if (nameLower === q) score += 80;
+      else if (nameLower.includes(q)) score += 40;
+
+      for (const word of words) {
+        if (entry.id.includes(word)) score += 10;
+        if (nameLower.includes(word)) score += 10;
+        if (entry.description?.toLowerCase().includes(word)) score += 5;
+        if (entry.tags?.some((t) => t.toLowerCase().includes(word))) score += 15;
+      }
+
+      if (score > 0) {
+        const key = getSearchLookupId(entry._source, entry.id);
+        resultByKey.set(key, { entry, score });
+      }
+    }
+  }
+
+  const lexicalCandidates = !shouldRunGlobalLexicalScan(normalizedQuery, resultByKey)
+    ? [...new Set([...resultByKey.values()].map(({ entry }) => entry))]
+    : deduped;
+  const rescueTerms = resultByKey.size > 0
+    ? getMissingQueryTerms(normalizedQuery).filter((term) => term.length >= 5)
+    : [];
+
+  for (const entry of lexicalCandidates) {
+    const boost = scoreEntryLexicalBoost(entry, normalizedQuery, rescueTerms);
+    if (boost === 0) continue;
+
+    const key = getSearchLookupId(entry._source, entry.id);
+    const current = resultByKey.get(key);
+    if (current) {
+      current.score += boost;
+    } else {
+      resultByKey.set(key, { entry, score: boost });
+    }
+  }
+
+  let results = [...resultByKey.values()];
 
   const filtered = applyFilters(results.map((r) => r.entry), filters);
   const filteredSet = new Set(filtered);
@@ -173,6 +423,7 @@ export function searchEntries(query, filters = {}) {
  * type: "doc" or "skill". If null, searches both.
  */
 export function getEntry(idOrNamespacedId, type = null) {
+  const normalizedId = normalizeQuery(idOrNamespacedId);
   const { docs, skills } = getMerged();
   let pool;
   if (type === 'doc') pool = applySourceFilter(docs);
@@ -180,16 +431,16 @@ export function getEntry(idOrNamespacedId, type = null) {
   else pool = applySourceFilter([...docs, ...skills]);
 
   // Check for source:id format (colon separates source from id)
-  if (idOrNamespacedId.includes(':')) {
-    const colonIdx = idOrNamespacedId.indexOf(':');
-    const sourceName = idOrNamespacedId.slice(0, colonIdx);
-    const id = idOrNamespacedId.slice(colonIdx + 1);
+  if (normalizedId.includes(':')) {
+    const colonIdx = normalizedId.indexOf(':');
+    const sourceName = normalizedId.slice(0, colonIdx);
+    const id = normalizedId.slice(colonIdx + 1);
     const entry = pool.find((e) => e._source === sourceName && e.id === id);
     return entry ? { entry, ambiguous: false } : { entry: null, ambiguous: false };
   }
 
   // Bare id (may contain slashes like author/name)
-  const matches = pool.filter((e) => e.id === idOrNamespacedId);
+  const matches = pool.filter((e) => e.id === normalizedId);
   if (matches.length === 0) return { entry: null, ambiguous: false };
   if (matches.length === 1) return { entry: matches[0], ambiguous: false };
 
@@ -241,9 +492,7 @@ export function resolveDocPath(entry, language, version) {
   let langObj = null;
   if (lang) {
     langObj = entry.languages.find((l) => l.language === lang);
-  } else if (entry.languages.length === 1) {
-    langObj = entry.languages[0];
-  } else if (entry.languages.length > 1) {
+  } else {
     return {
       needsLanguage: true,
       available: entry.languages.map((l) => l.language),
@@ -255,6 +504,13 @@ export function resolveDocPath(entry, language, version) {
   let verObj = null;
   if (version) {
     verObj = langObj.versions?.find((v) => v.version === version);
+    if (!verObj) {
+      return {
+        versionNotFound: true,
+        requested: version,
+        available: langObj.versions?.map((v) => v.version) || [],
+      };
+    }
   } else {
     const rec = langObj.recommendedVersion;
     verObj = langObj.versions?.find((v) => v.version === rec) || langObj.versions?.[0];
@@ -272,7 +528,7 @@ export function resolveDocPath(entry, language, version) {
  * Given a resolved path and a type ("doc" or "skill"), return the entry file path.
  */
 export function resolveEntryFile(resolved, type) {
-  if (!resolved || resolved.needsLanguage) return { error: 'unresolved' };
+  if (!resolved || resolved.needsLanguage || resolved.versionNotFound) return { error: 'unresolved' };
 
   const fileName = type === 'skill' ? 'SKILL.md' : 'DOC.md';
 

package/src/lib/telemetry.js

@@ -8,6 +8,12 @@ export function isTelemetryEnabled() {
   return config.telemetry !== false;
 }
 
+export function isFeedbackEnabled() {
+  if (process.env.CHUB_FEEDBACK === '0' || process.env.CHUB_FEEDBACK === 'false') return false;
+  const config = loadConfig();
+  return config.feedback !== false;
+}
+
 export function getTelemetryUrl() {
   const url = process.env.CHUB_TELEMETRY_URL;
   if (url) return url;
@@ -33,7 +39,7 @@ export function getTelemetryUrl() {
  * @param {string} [opts.source] - Registry source name
  */
 export async function sendFeedback(entryId, entryType, rating, opts = {}) {
-  if (!isTelemetryEnabled()) return { status: 'skipped', reason: 'telemetry_disabled' };
+  if (!isFeedbackEnabled()) return { status: 'skipped', reason: 'feedback_disabled' };
 
   const { getOrCreateClientId, detectAgent, detectAgentVersion } = await import('./identity.js');
   const clientId = await getOrCreateClientId();

package/src/lib/welcome.js

@@ -0,0 +1,42 @@
+import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { getChubDir } from './config.js';
+
+const WELCOME_MARKER = '.welcome_shown';
+
+/**
+ * Show the first-run welcome notice if it hasn't been shown yet.
+ * Creates a marker file so it only displays once.
+ */
+export function showWelcomeIfNeeded(opts = {}) {
+  if (opts.json) return;
+  if (!process.stdout.isTTY || !process.stderr.isTTY) return;
+
+  const chubDir = getChubDir();
+  const markerPath = join(chubDir, WELCOME_MARKER);
+  const configPath = join(chubDir, 'config.yaml');
+
+  if (existsSync(markerPath)) return;
+
+  // Print to stderr so it doesn't interfere with JSON/piped output
+  console.error(`
+${chalk.bold('Welcome to Context Hub (chub)!')} Chub helps your AI coding agents make API calls correctly, by providing \
+the latest documentation.
+
+By using chub, you agree to the Terms of Service at ${chalk.underline('https://www.aichub.org/tos.html')}
+
+Chub asks agents to provide feedback on documentation, and this feedback is used to improve docs for the developer \
+community. If you wish to disable this feedback, add ${chalk.bold('"feedback: false"')} to ${chalk.bold(configPath)}. See \
+${chalk.underline('https://github.com/andrewyng/context-hub')} for details.
+`);
+
+  try {
+    if (!existsSync(chubDir)) {
+      mkdirSync(chubDir, { recursive: true });
+    }
+    writeFileSync(markerPath, new Date().toISOString(), 'utf8');
+  } catch {
+    // Best-effort — don't block CLI if marker can't be written
+  }
+}

package/src/mcp/server.js

@@ -0,0 +1,184 @@
+/**
+ * Context Hub MCP Server.
+ *
+ * Exposes chub search, get, list, annotate, and feedback as MCP tools
+ * for use with Claude Code, Cursor, and other MCP-compatible agents.
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { ensureRegistry } from '../lib/cache.js';
+import { listEntries } from '../lib/registry.js';
+import { handleSearch, handleGet, handleList, handleAnnotate, handleFeedback } from './tools.js';
+import { attachStdioShutdownHandlers } from './stdio-lifecycle.js';
+
+// Prevent console.log from corrupting the stdio JSON-RPC protocol.
+// Any transitive dependency (e.g. posthog-node) that calls console.log
+// would break the MCP transport without this redirect.
+const _stderr = process.stderr;
+console.log = (...args) => _stderr.write(args.join(' ') + '\n');
+console.warn = (...args) => _stderr.write('[warn] ' + args.join(' ') + '\n');
+console.info = (...args) => _stderr.write('[info] ' + args.join(' ') + '\n');
+console.debug = (...args) => _stderr.write('[debug] ' + args.join(' ') + '\n');
+
+// Read package version
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8'));
+
+// Create server
+const server = new McpServer({
+  name: 'chub',
+  version: pkg.version,
+});
+
+// --- Register Tools ---
+
+server.tool(
+  'chub_search',
+  'Search Context Hub for docs and skills by query, tags, or language',
+  {
+    query: z.string().optional().describe('Search query. Omit to list all entries.'),
+    tags: z.string().optional().describe('Comma-separated tag filter (e.g. "openai,chat")'),
+    lang: z.string().optional().describe('Filter by language (e.g. "python", "js")'),
+    limit: z.number().int().min(1).max(100).optional().describe('Max results (default 20)'),
+  },
+  async (args) => handleSearch(args),
+);
+
+server.tool(
+  'chub_get',
+  'Fetch the content of a doc or skill by ID from Context Hub',
+  {
+    id: z.string().describe('Entry ID (e.g. "openai/chat", "stripe/api"). Use source:id for disambiguation.'),
+    lang: z.string().optional().describe('Language variant (e.g. "python", "js"). Auto-selected if only one.'),
+    version: z.string().optional().describe('Specific version (e.g. "1.52.0"). Defaults to recommended.'),
+    full: z.boolean().optional().describe('Fetch all files, not just the entry point (default false)'),
+    file: z.string().optional().describe('Fetch a specific file by path (e.g. "references/streaming.md")'),
+  },
+  async (args) => handleGet(args),
+);
+
+server.tool(
+  'chub_list',
+  'List all available docs and skills in Context Hub',
+  {
+    tags: z.string().optional().describe('Comma-separated tag filter'),
+    lang: z.string().optional().describe('Filter by language'),
+    limit: z.number().int().min(1).max(500).optional().describe('Max entries (default 50)'),
+  },
+  async (args) => handleList(args),
+);
+
+server.tool(
+  'chub_annotate',
+  'Read, write, clear, or list agent annotations. Modes: (1) list=true to list all, (2) id+note to write, (3) id+clear=true to delete, (4) id alone to read. Annotations persist locally across sessions.',
+  {
+    id: z.string().optional().describe('Entry ID to annotate (e.g. "openai/chat"). Required unless using list mode.'),
+    note: z.string().optional().describe('Annotation text to save. Omit to read existing annotation.'),
+    clear: z.boolean().optional().describe('Remove the annotation for this entry (default false)'),
+    list: z.boolean().optional().describe('List all annotations (default false). When true, id is not needed.'),
+  },
+  async (args) => handleAnnotate(args),
+);
+
+server.tool(
+  'chub_feedback',
+  'Send quality feedback (thumbs up/down) for a doc or skill to help authors improve content',
+  {
+    id: z.string().describe('Entry ID to rate (e.g. "openai/chat")'),
+    rating: z.enum(['up', 'down']).describe('Thumbs up or down'),
+    comment: z.string().optional().describe('Optional comment explaining the rating'),
+    type: z.enum(['doc', 'skill']).optional().describe('Entry type. Auto-detected if omitted.'),
+    lang: z.string().optional().describe('Language variant rated'),
+    version: z.string().optional().describe('Version rated'),
+    file: z.string().optional().describe('Specific file rated'),
+    labels: z.array(z.enum([
+      'accurate', 'well-structured', 'helpful', 'good-examples',
+      'outdated', 'inaccurate', 'incomplete', 'wrong-examples',
+      'wrong-version', 'poorly-structured',
+    ])).optional().describe('Structured feedback labels'),
+  },
+  async (args) => handleFeedback(args),
+);
+
+// --- Register Resource ---
+
+server.resource(
+  'registry',
+  'chub://registry',
+  {
+    title: 'Context Hub Registry',
+    description: 'Browse the full Context Hub registry of docs and skills',
+    mimeType: 'application/json',
+  },
+  async (uri) => {
+    try {
+      const entries = listEntries({});
+      const simplified = entries.map((entry) => ({
+        id: entry.id,
+        name: entry.name,
+        type: entry._type || (entry.languages ? 'doc' : 'skill'),
+        description: entry.description,
+        tags: entry.tags || [],
+        ...(entry.languages
+          ? {
+            languages: entry.languages.map((l) => ({
+              language: l.language,
+              versions: l.versions?.map((v) => v.version) || [],
+              recommended: l.recommendedVersion,
+            })),
+          }
+          : {}),
+      }));
+      return {
+        contents: [{
+          uri: uri.href,
+          mimeType: 'application/json',
+          text: JSON.stringify({ entries: simplified, total: simplified.length }, null, 2),
+        }],
+      };
+    } catch (err) {
+      console.warn(`Registry resource error: ${err.message}`);
+      return {
+        contents: [{
+          uri: uri.href,
+          mimeType: 'application/json',
+          text: JSON.stringify({ error: 'Registry not loaded. Run "chub update" first.' }),
+        }],
+      };
+    }
+  },
+);
+
+// --- Process Safety ---
+
+// Prevent the server from crashing on unhandled errors (long-lived process)
+process.on('uncaughtException', (err) => {
+  _stderr.write(`[chub-mcp] Uncaught exception: ${err.message}\n`);
+});
+process.on('unhandledRejection', (reason) => {
+  _stderr.write(`[chub-mcp] Unhandled rejection: ${reason}\n`);
+});
+
+// --- Start Server ---
+
+// Best-effort registry load — server starts even if this fails
+try {
+  await ensureRegistry();
+} catch (err) {
+  _stderr.write(`[chub-mcp] Warning: Registry not loaded: ${err.message}\n`);
+}
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+// Exit promptly when MCP host disconnects stdio.
+// Must be after server.connect() so StdioServerTransport's data handler
+// is already wired — otherwise stdin.resume() discards incoming bytes.
+attachStdioShutdownHandlers({ stderr: _stderr });
+
+_stderr.write(`[chub-mcp] Server started (v${pkg.version})\n`);