chub-dev 0.2.0-beta.4 → 0.3.0

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`);

package/src/mcp/stdio-lifecycle.js

@@ -0,0 +1,54 @@
+/**
+ * Attach stdio lifecycle guards so chub-mcp exits cleanly when the parent
+ * MCP host goes away (EOF / closed pipe).
+ */
+export function attachStdioShutdownHandlers({
+  stdin = process.stdin,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  onShutdown = () => process.exit(0),
+} = {}) {
+  let shuttingDown = false;
+
+  const shutdown = (reason) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    try {
+      stderr.write(`[chub-mcp] ${reason}\n`);
+    } catch {
+      // ignore stderr write errors during shutdown
+    }
+
+    onShutdown(0);
+  };
+
+  const onStdinEnd = () => shutdown('Stdin closed; exiting.');
+  const onStdinClose = () => shutdown('Stdin stream closed; exiting.');
+  const onStdinError = (err) => {
+    const detail = err?.code || err?.message || 'unknown';
+    shutdown(`Stdin error (${detail}); exiting.`);
+  };
+  const onStdoutError = (err) => {
+    if (err?.code === 'EPIPE') {
+      shutdown('Stdout pipe closed (EPIPE); exiting.');
+    }
+  };
+
+  stdin.on('end', onStdinEnd);
+  stdin.on('close', onStdinClose);
+  stdin.on('error', onStdinError);
+  stdout.on('error', onStdoutError);
+
+  // Keep stdin flowing so EOF/end is observed reliably across hosts.
+  if (typeof stdin.resume === 'function') {
+    stdin.resume();
+  }
+
+  return () => {
+    stdin.off('end', onStdinEnd);
+    stdin.off('close', onStdinClose);
+    stdin.off('error', onStdinError);
+    stdout.off('error', onStdoutError);
+  };
+}

package/src/mcp/tools.js

@@ -0,0 +1,286 @@
+/**
+ * MCP tool handler implementations.
+ * Each handler wraps existing lib/ functions and returns MCP-compatible results.
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve, relative } from 'node:path';
+import { searchEntries, getEntry, listEntries, resolveDocPath, resolveEntryFile } from '../lib/registry.js';
+import { fetchDoc, fetchDocFull } from '../lib/cache.js';
+import { readAnnotation, writeAnnotation, clearAnnotation, listAnnotations } from '../lib/annotations.js';
+import { sendFeedback, isFeedbackEnabled } from '../lib/telemetry.js';
+import { trackEvent, setCliVersion } from '../lib/analytics.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let _cliVersion;
+function getCliVersion() {
+  if (_cliVersion) return _cliVersion;
+  try {
+    const pkg = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8'));
+    _cliVersion = pkg.version;
+    setCliVersion(_cliVersion);
+  } catch {
+    _cliVersion = 'unknown';
+  }
+  return _cliVersion;
+}
+// Initialize cli_version for analytics on module load
+getCliVersion();
+
+function textResult(data) {
+  return {
+    content: [{ type: 'text', text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) }],
+  };
+}
+
+function errorResult(message, details = {}) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify({ error: message, ...details }, null, 2) }],
+    isError: true,
+  };
+}
+
+/**
+ * Simplify an entry for agent-friendly output (strip internal fields).
+ */
+function simplifyEntry(entry) {
+  const result = {
+    id: entry.id,
+    name: entry.name,
+    type: entry._type || (entry.languages ? 'doc' : 'skill'),
+    description: entry.description,
+    tags: entry.tags || [],
+  };
+  if (entry.languages) {
+    result.languages = entry.languages.map((l) => l.language);
+  }
+  return result;
+}
+
+// --- Tool Handlers ---
+
+export async function handleSearch({ query, tags, lang, limit = 20 }) {
+  try {
+    const start = Date.now();
+    let entries;
+    if (query) {
+      entries = searchEntries(query, { tags, lang });
+    } else {
+      entries = listEntries({ tags, lang });
+    }
+    const sliced = entries.slice(0, limit);
+    if (query) {
+      trackEvent('search', {
+        query: query.slice(0, 1000),
+        query_length: query.length,
+        result_count: sliced.length,
+        results: sliced.map((e) => e.id || e.name || 'unknown'),
+        duration_ms: Date.now() - start,
+        has_tags: !!tags,
+        has_lang: !!lang,
+        tags: tags || undefined,
+        lang: lang || undefined,
+        via: 'mcp',
+      }).catch(() => {});
+    }
+    return textResult({
+      results: sliced.map(simplifyEntry),
+      total: entries.length,
+      showing: sliced.length,
+    });
+  } catch (err) {
+    return errorResult(`Search failed: ${err.message}`);
+  }
+}
+
+export async function handleGet({ id, lang, version, full = false, file }) {
+  const start = Date.now();
+  try {
+    // Validate file parameter early (before entry lookup) to reject path traversal
+    if (file) {
+      const normalizedFile = resolve('/', file).slice(1);
+      if (normalizedFile !== file || file.includes('..')) {
+        return errorResult(`Invalid file path: "${file}". Path traversal is not allowed.`);
+      }
+    }
+
+    const result = getEntry(id);
+
+    if (result.ambiguous) {
+      return errorResult(`Ambiguous entry ID "${id}". Be specific:`, {
+        alternatives: result.alternatives,
+      });
+    }
+
+    if (!result.entry) {
+      trackEvent('doc_not_found', { entry_id: id, via: 'mcp' }).catch(() => {});
+      return errorResult(`Entry "${id}" not found.`, {
+        suggestion: 'Use chub_search to find available entries.',
+      });
+    }
+
+    const entry = result.entry;
+    const type = entry.languages ? 'doc' : 'skill';
+    const resolved = resolveDocPath(entry, lang, version);
+
+    if (!resolved) {
+      return errorResult(`Could not resolve path for "${id}".`);
+    }
+
+    if (resolved.versionNotFound) {
+      return errorResult(`Version "${resolved.requested}" not found for "${id}".`, {
+        available: resolved.available,
+      });
+    }
+
+    if (resolved.needsLanguage) {
+      return errorResult(`Multiple languages available for "${id}". Specify the lang parameter.`, {
+        available: resolved.available,
+      });
+    }
+
+    const entryFile = resolveEntryFile(resolved, type);
+    if (entryFile.error) {
+      return errorResult(`"${id}": ${entryFile.error}`);
+    }
+
+    let content;
+
+    if (file) {
+      // Fetch a specific file
+      if (!resolved.files.includes(file)) {
+        const entryFileName = type === 'skill' ? 'SKILL.md' : 'DOC.md';
+        const available = resolved.files.filter((f) => f !== entryFileName);
+        return errorResult(`File "${file}" not found in ${id}.`, {
+          available: available.length > 0 ? available : '(none)',
+        });
+      }
+      content = await fetchDoc(resolved.source, join(resolved.path, file));
+    } else if (full && resolved.files.length > 0) {
+      // Fetch all files
+      const allFiles = await fetchDocFull(resolved.source, resolved.path, resolved.files);
+      content = allFiles.map((f) => `# FILE: ${f.name}\n\n${f.content}`).join('\n\n---\n\n');
+    } else {
+      // Fetch entry point only
+      content = await fetchDoc(resolved.source, entryFile.filePath);
+    }
+
+    // Append annotation if present
+    const annotation = readAnnotation(entry.id);
+    if (annotation) {
+      content += `\n\n---\n[Agent note — ${annotation.updatedAt}]\n${annotation.note}\n`;
+    }
+
+    const entryType = entry.languages ? 'doc' : 'skill';
+    const duration_ms = Date.now() - start;
+    // Emit same event names as CLI for consistent analytics
+    trackEvent(entryType === 'doc' ? 'doc_fetched' : 'skill_fetched', {
+      entry_id: entry.id,
+      full,
+      file: file || undefined,
+      lang: lang || undefined,
+      source: entry._source || undefined,
+      duration_ms,
+      via: 'mcp',
+    }).catch(() => {});
+
+    return textResult(content);
+  } catch (err) {
+    trackEvent('fetch_error', { entry_id: id, via: 'mcp', error_type: err.code || err.name || 'unknown' }).catch(() => {});
+    return errorResult(`Failed to fetch "${id}": ${err.message}`);
+  }
+}
+
+export async function handleList({ tags, lang, limit = 50 }) {
+  try {
+    const entries = listEntries({ tags, lang });
+    const sliced = entries.slice(0, limit);
+    return textResult({
+      entries: sliced.map(simplifyEntry),
+      total: entries.length,
+      showing: sliced.length,
+    });
+  } catch (err) {
+    return errorResult(`List failed: ${err.message}`);
+  }
+}
+
+export async function handleAnnotate({ id, note, clear = false, list = false }) {
+  try {
+    if (list) {
+      const annotations = listAnnotations();
+      return textResult({ annotations, total: annotations.length });
+    }
+
+    if (!id) {
+      return errorResult('Missing required parameter: id. Provide an entry ID or use list mode.');
+    }
+
+    // Validate entry ID to prevent path traversal or filesystem abuse
+    if (id.length > 200) {
+      return errorResult('Entry ID too long (max 200 characters).');
+    }
+    if (!/^[a-zA-Z0-9._\-\/]+$/.test(id)) {
+      return errorResult('Entry ID contains invalid characters. Use only alphanumeric, hyphens, underscores, dots, and slashes.');
+    }
+
+    if (clear) {
+      const removed = clearAnnotation(id);
+      return textResult({
+        status: removed ? 'cleared' : 'not_found',
+        id,
+      });
+    }
+
+    if (note) {
+      const saved = writeAnnotation(id, note);
+      return textResult({ status: 'saved', annotation: saved });
+    }
+
+    // Read mode
+    const annotation = readAnnotation(id);
+    if (annotation) {
+      return textResult({ annotation });
+    }
+    return textResult({ status: 'no_annotation', id });
+  } catch (err) {
+    return errorResult(`Annotation failed: ${err.message}`);
+  }
+}
+
+export async function handleFeedback({ id, rating, comment, type, lang, version, file, labels }) {
+  try {
+    if (!isFeedbackEnabled()) {
+      return textResult({ status: 'skipped', reason: 'feedback_disabled' });
+    }
+
+    // Auto-detect entry type if not provided
+    let entryType = type;
+    if (!entryType) {
+      try {
+        const result = getEntry(id);
+        if (result.entry) {
+          entryType = result.entry.languages ? 'doc' : 'skill';
+        }
+      } catch {
+        // Fall through with undefined type
+      }
+      entryType = entryType || 'doc';
+    }
+
+    const result = await sendFeedback(id, entryType, rating, {
+      comment,
+      docLang: lang,
+      docVersion: version,
+      targetFile: file,
+      labels,
+      agent: 'mcp-server',
+      cliVersion: getCliVersion(),
+    });
+
+    return textResult(result);
+  } catch (err) {
+    return errorResult(`Feedback failed: ${err.message}`);
+  }
+}