@expokit/cli 0.0.0-stage → 0.3.0

package/bin/lib.mjs

@@ -0,0 +1,343 @@
+/**
+ * Pure helpers for the expo-kit CLI (no I/O, no dependencies) — kept separate so they can be unit-tested.
+ */
+
+/** Thrown for user-facing errors; the CLI entry point prints `message` and exits 1. */
+export class CliError extends Error {}
+
+// ---------------------------------------------------------------------------
+// JSONC (tsconfig-style JSON with comments and trailing commas)
+// ---------------------------------------------------------------------------
+
+/** Removes // and /* *\/ comments outside strings (newlines kept so error positions stay close). */
+export function stripJsonComments(text) {
+  let out = '';
+  let i = 0;
+  const n = text.length;
+  while (i < n) {
+    const ch = text[i];
+    if (ch === '"') {
+      const end = scanStringEnd(text, i);
+      out += text.slice(i, end);
+      i = end;
+    } else if (ch === '/' && text[i + 1] === '/') {
+      while (i < n && text[i] !== '\n' && text[i] !== '\r') i += 1;
+    } else if (ch === '/' && text[i + 1] === '*') {
+      const close = text.indexOf('*/', i + 2);
+      const end = close === -1 ? n : close + 2;
+      out += text.slice(i, end).replace(/[^\r\n]/g, ' ');
+      i = end;
+    } else {
+      out += ch;
+      i += 1;
+    }
+  }
+  return out;
+}
+
+/** Index just past the closing quote of the string starting at `start` (handles backslash escapes). */
+function scanStringEnd(text, start) {
+  let i = start + 1;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '\\') i += 2;
+    else if (ch === '"') return i + 1;
+    else i += 1;
+  }
+  return text.length; // unterminated — JSON.parse will report it
+}
+
+/** Removes commas that are directly followed (ignoring whitespace) by } or ] — outside strings. Input must be comment-free. */
+export function stripTrailingCommas(text) {
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '"') {
+      const end = scanStringEnd(text, i);
+      out += text.slice(i, end);
+      i = end;
+      continue;
+    }
+    if (ch === ',') {
+      let j = i + 1;
+      while (j < text.length && /\s/.test(text[j])) j += 1;
+      if (text[j] === '}' || text[j] === ']') {
+        i += 1;
+        continue;
+      }
+    }
+    out += ch;
+    i += 1;
+  }
+  return out;
+}
+
+/** JSON.parse for JSONC: comments and trailing commas are allowed (outside strings), BOM ignored. */
+export function parseJsonc(text) {
+  const clean = stripTrailingCommas(stripJsonComments(String(text).replace(/^/, '')));
+  return JSON.parse(clean);
+}
+
+/** True when the text has comments or trailing commas, i.e. a plain JSON.stringify rewrite would lose something. */
+export function hasJsoncExtras(text) {
+  const body = String(text).replace(/^/, '');
+  return stripTrailingCommas(stripJsonComments(body)) !== body;
+}
+
+/** Tokens of a JSONC document (whitespace and comments skipped) with source offsets. */
+function tokenize(text) {
+  const tokens = [];
+  let i = 0;
+  const n = text.length;
+  while (i < n) {
+    const ch = text[i];
+    if (/\s/.test(ch) || ch === '') {
+      i += 1;
+    } else if (ch === '/' && text[i + 1] === '/') {
+      while (i < n && text[i] !== '\n') i += 1;
+    } else if (ch === '/' && text[i + 1] === '*') {
+      const close = text.indexOf('*/', i + 2);
+      i = close === -1 ? n : close + 2;
+    } else if (ch === '"') {
+      const end = scanStringEnd(text, i);
+      tokens.push({ type: 'string', start: i, end, raw: text.slice(i, end) });
+      i = end;
+    } else if ('{}[]:,'.includes(ch)) {
+      tokens.push({ type: ch, start: i, end: i + 1 });
+      i += 1;
+    } else {
+      let j = i;
+      while (j < n && !/[\s{}[\]:,"/]/.test(text[j])) j += 1;
+      if (j === i) j = i + 1;
+      tokens.push({ type: 'literal', start: i, end: j });
+      i = j;
+    }
+  }
+  return tokens;
+}
+
+/** Within the object opened at tokens[openIdx], the token index of `key`'s value (or -1) and of the closing brace. */
+function findMember(tokens, openIdx, key) {
+  let depth = 0;
+  for (let i = openIdx + 1; i < tokens.length; i += 1) {
+    const t = tokens[i];
+    if (t.type === '{' || t.type === '[') depth += 1;
+    else if (t.type === '}' || t.type === ']') {
+      if (depth === 0) return { valueIdx: -1, closeIdx: i };
+      depth -= 1;
+    } else if (depth === 0 && t.type === 'string' && tokens[i + 1]?.type === ':') {
+      let name;
+      try {
+        name = JSON.parse(t.raw);
+      } catch {
+        name = null;
+      }
+      if (name === key) return { valueIdx: i + 2, closeIdx: -1 };
+    }
+  }
+  return { valueIdx: -1, closeIdx: -1 };
+}
+
+function lineIndentAt(text, offset) {
+  const lineStart = text.lastIndexOf('\n', offset - 1) + 1;
+  return text.slice(lineStart).match(/^[ \t]*/)[0];
+}
+
+function detectIndentUnit(text) {
+  const m = text.match(/\n([ \t]+)\S/);
+  return m ? (m[1].startsWith('\t') ? '\t' : m[1]) : '  ';
+}
+
+/** Inserts `memberText` (may span lines, already indented after its first line) as the first member of an object. */
+function insertFirstMember(text, tokens, openIdx, memberText, memberIndent, closeIndent) {
+  const open = tokens[openIdx];
+  const isEmpty = tokens[openIdx + 1]?.type === '}';
+  const insertion = isEmpty
+    ? `\n${memberIndent}${memberText}\n${closeIndent}`
+    : `\n${memberIndent}${memberText},`;
+  if (isEmpty) {
+    // replace whatever whitespace sat between { and }
+    const close = tokens[openIdx + 1];
+    return text.slice(0, open.end) + insertion + text.slice(close.start);
+  }
+  return text.slice(0, open.end) + insertion + text.slice(open.end);
+}
+
+function minimalAliasEdit(text, alias, target) {
+  const tokens = tokenize(text);
+  if (tokens[0]?.type !== '{') return null;
+  const unit = detectIndentUnit(text);
+  const valueJson = JSON.stringify(target).replace(/","/g, '", "');
+  const entry = `${JSON.stringify(alias)}: ${valueJson}`;
+
+  const co = findMember(tokens, 0, 'compilerOptions');
+  if (co.valueIdx === -1) {
+    const ind = lineIndentAt(text, tokens[0].start);
+    const m = ind + unit;
+    const member = `"compilerOptions": {\n${m}${unit}"paths": {\n${m}${unit}${unit}${entry}\n${m}${unit}}\n${m}}`;
+    return insertFirstMember(text, tokens, 0, member, m, ind);
+  }
+  const coIdx = co.valueIdx;
+  if (tokens[coIdx]?.type !== '{') return null;
+  const coIndent = lineIndentAt(text, tokens[coIdx].start);
+  const coMember = coIndent + unit;
+
+  const p = findMember(tokens, coIdx, 'paths');
+  if (p.valueIdx === -1) {
+    const member = `"paths": {\n${coMember}${unit}${entry}\n${coMember}}`;
+    return insertFirstMember(text, tokens, coIdx, member, coMember, coIndent);
+  }
+  const pIdx = p.valueIdx;
+  if (tokens[pIdx]?.type !== '{') return null;
+  const pIndent = lineIndentAt(text, tokens[pIdx].start);
+  return insertFirstMember(text, tokens, pIdx, entry, pIndent + unit, pIndent);
+}
+
+/**
+ * Ensures `compilerOptions.paths[alias]` exists in a tsconfig source. Leaves the file untouched when the alias
+ * is already present. Otherwise does a minimal text insert that keeps comments/formatting; only if that can't
+ * be done safely does it fall back to a full JSON rewrite (`commentsLost` tells the caller to warn).
+ * Throws (SyntaxError) when the source isn't valid JSONC.
+ */
+export function addTsconfigPathAlias(text, alias, target) {
+  const parsed = parseJsonc(text);
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new SyntaxError('tsconfig.json must contain a JSON object');
+  }
+  if (parsed.compilerOptions?.paths?.[alias] !== undefined) {
+    return { changed: false, text, method: 'none', commentsLost: false };
+  }
+
+  const verify = (candidate) => {
+    try {
+      const out = parseJsonc(candidate);
+      const { paths, ...restCo } = out.compilerOptions ?? {};
+      const { paths: origPaths, ...origRestCo } = parsed.compilerOptions ?? {};
+      const { compilerOptions: _a, ...rest } = out;
+      const { compilerOptions: _b, ...origRest } = parsed;
+      return (
+        JSON.stringify(paths?.[alias]) === JSON.stringify(target) &&
+        JSON.stringify({ ...paths, [alias]: undefined }) === JSON.stringify({ ...origPaths, [alias]: undefined }) &&
+        JSON.stringify(restCo) === JSON.stringify(origRestCo) &&
+        JSON.stringify(rest) === JSON.stringify(origRest)
+      );
+    } catch {
+      return false;
+    }
+  };
+
+  const minimal = minimalAliasEdit(text, alias, target);
+  if (minimal !== null && verify(minimal)) {
+    return { changed: true, text: minimal, method: 'minimal', commentsLost: false };
+  }
+
+  const next = structuredClone(parsed);
+  if (next.compilerOptions === null || typeof next.compilerOptions !== 'object' || Array.isArray(next.compilerOptions)) {
+    next.compilerOptions = {};
+  }
+  if (next.compilerOptions.paths === null || typeof next.compilerOptions.paths !== 'object' || Array.isArray(next.compilerOptions.paths)) {
+    next.compilerOptions.paths = {};
+  }
+  next.compilerOptions.paths[alias] = target;
+  return {
+    changed: true,
+    text: `${JSON.stringify(next, null, 2)}\n`,
+    method: 'rewrite',
+    commentsLost: hasJsoncExtras(text),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Names
+// ---------------------------------------------------------------------------
+
+/** Valid PascalCase React component name for a tab route (`my-tab` → `MyTabScreen`, `index` → `HomeScreen`). */
+export function tabComponentName(tabName) {
+  if (tabName === 'index') return 'HomeScreen';
+  const words = String(tabName)
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean);
+  let base = words.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+  if (!base) base = 'Tab';
+  if (/^[0-9]/.test(base)) base = `Tab${base}`;
+  return `${base}Screen`;
+}
+
+/** Registry item names: lowercase slug, no path characters. */
+export function isValidItemName(name) {
+  return typeof name === 'string' && /^[a-z0-9][a-z0-9-]{0,99}$/.test(name);
+}
+
+/**
+ * npm package name, optionally with a simple version (`@1.2.3`, `@~14.0.0`, `@^2`). It reaches
+ * `npx expo install` through a shell on Windows, so no `< > | =` or spaces — ranges like `>=1` are out.
+ */
+export function isSafePackageSpec(spec) {
+  return (
+    typeof spec === 'string' &&
+    spec.length <= 214 &&
+    /^(@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*(@[A-Za-z0-9.^~*-]+)?$/.test(spec)
+  );
+}
+
+/** `export const KIT_VERSION = n` of a kit.tsx (1 for files from before the marker), or null if the file isn't one. */
+export function kitVersion(text) {
+  const m = /^export const KIT_VERSION = (\d+);/m.exec(text);
+  if (m) return Number(m[1]);
+  return /export function KitProvider\b/.test(text) ? 1 : null;
+}
+
+/** Union of dependency lists, order preserved. */
+export function mergeDependencies(...lists) {
+  const out = [];
+  for (const list of lists) {
+    for (const dep of list ?? []) if (!out.includes(dep)) out.push(dep);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Site URL + token guard
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_SITE_URL = 'https://expokit.karandev.in';
+
+export function isLoopbackHost(hostname) {
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]' || hostname === '::1';
+}
+
+/** Parses the site URL; throws CliError unless it is https (or http on localhost / 127.0.0.1). */
+export function parseSiteUrl(siteUrl) {
+  let url;
+  try {
+    url = new URL(siteUrl);
+  } catch {
+    throw new CliError(`EXPO_KIT_URL is not a valid URL: ${JSON.stringify(siteUrl)}`);
+  }
+  if (url.protocol === 'https:') return url;
+  if (url.protocol === 'http:' && isLoopbackHost(url.hostname)) return url;
+  throw new CliError(
+    `Refusing to use ${url.origin}: the site must be https:// (plain http is only allowed for localhost / 127.0.0.1). Check EXPO_KIT_URL.`
+  );
+}
+
+function originOf(u) {
+  try {
+    return new URL(u).origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether a token may be sent to `siteUrl`. Saved credentials go only to the origin they were created for
+ * (stored as `url` by `login`) or the default site; an EXPO_KIT_TOKEN only to the default site or a loopback dev server.
+ */
+export function canSendToken({ siteUrl, credsUrl, fromEnv = false, defaultUrl = DEFAULT_SITE_URL }) {
+  const target = originOf(siteUrl);
+  if (!target) return false;
+  if (target === originOf(defaultUrl)) return true;
+  if (fromEnv) return isLoopbackHost(new URL(siteUrl).hostname);
+  return Boolean(credsUrl) && target === originOf(credsUrl);
+}

package/bin/mcp.mjs

@@ -0,0 +1,345 @@
+/**
+ * `expo-kit mcp` — a Model Context Protocol server over stdio, so AI coding assistants
+ * (Claude Code, Cursor, VS Code, Codex…) can browse ExpoKit and add items with the CLI.
+ *
+ * Zero dependencies: MCP over stdio is newline-delimited JSON-RPC 2.0, and this server only
+ * offers tools. It reads the registry bundled with this package and never touches the network
+ * or the user's token. stdout carries protocol messages only — diagnostics go to stderr.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Newest first; we answer with the client's version when we know it, else our newest. */
+export const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+
+const PACKAGE = '@expokit/cli';
+const TYPES = ['component', 'chart', 'block', 'template', 'lib'];
+
+const INSTRUCTIONS = `ExpoKit is a shadcn-style kit of copy-paste UI for Expo / React Native (iOS + Android first).
+Items are copied into the user's app as source files by the expo-kit CLI — they are not an npm package.
+Workflow: search_items or list_items → view_item (props, import line, examples) → get_add_command, then run that command in the app's root folder.
+The CLI creates components.json, adds the @/* tsconfig alias, copies files under src/ (or the root app layout) and installs npm deps with \`npx expo install\`.
+Import components from '@/components/...' and wrap the app in <KitProvider> from '@/lib/kit' (added with the first item).
+Pro items need an ExpoKit Pro plan: the user runs \`npx ${PACKAGE}@latest login\` once (token from https://expokit.karandev.in/account). Never ask the user to paste a token into chat.`;
+
+// ---------------------------------------------------------------------------
+// Registry access (bundled JSON)
+// ---------------------------------------------------------------------------
+
+export function loadCatalog(registryDir, aliases = {}) {
+  const items = fs
+    .readdirSync(registryDir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => JSON.parse(fs.readFileSync(path.join(registryDir, f), 'utf8')))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const docs = new Map();
+  for (const it of items) {
+    const p = path.join(registryDir, '_docs', `${it.name}.json`);
+    docs.set(it.name, fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : null);
+  }
+  const byName = new Map(items.map((it) => [it.name, it]));
+  const alias = new Map(Object.entries(aliases));
+  for (const [name, d] of docs) for (const a of d?.aliases ?? []) alias.set(a, name);
+  return {
+    items,
+    docs,
+    find(name) {
+      const key = String(name ?? '').trim().toLowerCase();
+      return byName.get(key) ?? byName.get(alias.get(key)) ?? null;
+    },
+  };
+}
+
+function itemLine(it) {
+  return `- ${it.name} (${it.type}${it.tier === 'pro' ? ', PRO' : ''}) — ${it.title}: ${it.description}`;
+}
+
+/** `import { Button } from '@/components/ui/button';` from the item's main file. */
+function importLine(it, doc) {
+  if (!doc?.exportName) return null;
+  const main = doc.files.find((f) => f.endsWith(`/${it.name}.tsx`)) ?? doc.files[0];
+  if (!main) return null;
+  return `import { ${doc.exportName} } from '@/${main.replace(/^src\//, '').replace(/\.tsx?$/, '')}';`;
+}
+
+function addCommand(names) {
+  return `npx ${PACKAGE}@latest add ${names.join(' ')}`;
+}
+
+function searchScore(it, doc, words) {
+  const fields = [
+    [it.name, 6],
+    [(doc?.aliases ?? []).join(' '), 5],
+    [it.title, 4],
+    [doc?.category ?? '', 3],
+    [it.type, 2],
+    [it.description, 1],
+  ].map(([text, weight]) => [String(text).toLowerCase(), weight]);
+  let score = 0;
+  for (const w of words) {
+    let best = 0;
+    for (const [text, weight] of fields) if (text.includes(w)) best = Math.max(best, weight);
+    if (!best) return 0; // every word must match somewhere
+    score += best;
+  }
+  return score;
+}
+
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
+
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+
+export const TOOLS = [
+  {
+    name: 'list_items',
+    title: 'List ExpoKit items',
+    description: 'List every ExpoKit item (components, charts, blocks, templates) with type, tier (free/PRO) and a one-line description. Optional filters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: { type: 'string', enum: TYPES, description: 'Only items of this type.' },
+        tier: { type: 'string', enum: ['free', 'pro'], description: 'Only free or only Pro items.' },
+      },
+      additionalProperties: false,
+    },
+    annotations: READ_ONLY,
+  },
+  {
+    name: 'search_items',
+    title: 'Search ExpoKit items',
+    description: 'Find ExpoKit items by keywords (e.g. "bottom sheet", "line chart", "glass tab bar", "onboarding"). Matches names, aliases, titles, categories and descriptions.',
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string', description: 'Keywords.' } },
+      required: ['query'],
+      additionalProperties: false,
+    },
+    annotations: READ_ONLY,
+  },
+  {
+    name: 'view_item',
+    title: 'View an ExpoKit item',
+    description: 'Details for one item: description, import line, props, npm and registry dependencies, usage examples (free items) and the command that adds it. Set include_source to also get the source files of a free item.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Item name or alias, e.g. "button".' },
+        include_source: { type: 'boolean', description: "Also return the item's own source files (free items only). Default false." },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+    annotations: READ_ONLY,
+  },
+  {
+    name: 'get_add_command',
+    title: 'Get the add command',
+    description: "The exact CLI command that copies one or more items into the user's Expo app (run it in the app's root folder), plus what it will do.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        names: { type: 'array', items: { type: 'string' }, minItems: 1, description: 'Item names or aliases.' },
+      },
+      required: ['names'],
+      additionalProperties: false,
+    },
+    annotations: READ_ONLY,
+  },
+];
+
+class ToolError extends Error {}
+
+function requireItem(catalog, name) {
+  const it = catalog.find(name);
+  if (!it) throw new ToolError(`Unknown item "${name}". Use search_items or list_items to find the right name.`);
+  return it;
+}
+
+function listItems(catalog, { type, tier } = {}) {
+  const items = catalog.items.filter((it) => (!type || it.type === type) && (!tier || it.tier === tier));
+  if (!items.length) return 'No items match those filters.';
+  return `${items.length} item(s):\n${items.map(itemLine).join('\n')}`;
+}
+
+function searchItems(catalog, { query }) {
+  const words = String(query ?? '').toLowerCase().split(/[\s,]+/).filter(Boolean);
+  if (!words.length) throw new ToolError('query is empty.');
+  const hits = catalog.items
+    .map((it) => ({ it, score: searchScore(it, catalog.docs.get(it.name), words) }))
+    .filter((h) => h.score > 0)
+    .sort((a, b) => b.score - a.score || a.it.name.localeCompare(b.it.name))
+    .slice(0, 15);
+  if (!hits.length) return `Nothing matches "${query}". Try fewer or broader words, or list_items.`;
+  return `${hits.length} match(es) for "${query}":\n${hits.map((h) => itemLine(h.it)).join('\n')}\n\nNext: view_item with a name.`;
+}
+
+function viewItem(catalog, registryDir, { name, include_source: includeSource = false }) {
+  const it = requireItem(catalog, name);
+  const doc = catalog.docs.get(it.name);
+  const out = [`# ${it.title} (${it.name})`, '', ...(doc?.summary ? [doc.summary, ''] : []), it.description, ''];
+  out.push(`Type: ${it.type} · Tier: ${it.tier === 'pro' ? 'PRO (needs an ExpoKit Pro plan)' : 'free'}${doc?.category ? ` · Category: ${doc.category}` : ''}`);
+  if (doc?.aliases?.length) out.push(`Aliases: ${doc.aliases.join(', ')}`);
+  out.push('', `Add: \`${addCommand([it.name])}\``);
+  const imp = importLine(it, doc);
+  if (imp) out.push(`Import: \`${imp}\``);
+  if (doc?.files?.length) out.push(`Files it adds: ${doc.files.join(', ')}`);
+  if (it.dependencies.length) out.push(`npm deps (installed by the CLI): ${it.dependencies.join(', ')}`);
+  if (it.registryDependencies.length) out.push(`Also adds: ${it.registryDependencies.join(', ')}`);
+
+  if (doc?.props?.length) {
+    out.push('', '## Props', '', '| Prop | Type | Default | Description |', '| --- | --- | --- | --- |');
+    const cell = (s) => String(s ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ');
+    for (const [prop, type, def, desc] of doc.props) out.push(`| ${cell(prop)} | ${cell(type)} | ${cell(def)} | ${cell(desc)} |`);
+  }
+
+  if (doc?.behavior?.length) {
+    out.push('', '## Behaviour & accessibility', '');
+    for (const [label, text] of doc.behavior) out.push(`- **${label}:** ${text}`);
+  }
+
+  if (doc?.usage) out.push('', '## Usage', '', '```tsx', doc.usage.trimEnd(), '```');
+
+  if (doc?.examples?.length) {
+    out.push('', '## Examples');
+    for (const ex of doc.examples) out.push('', `### ${ex.title}`, '', '```tsx', ex.code.trimEnd(), '```');
+  } else if (it.tier === 'pro') {
+    out.push('', 'Usage examples and source for Pro items are on https://expokit.karandev.in after signing in, and in the files the add command copies.');
+  }
+
+  if (includeSource) {
+    if (it.tier === 'pro' || !it.filesDir) {
+      out.push('', 'Source: not bundled for Pro items. After `add`, read the copied files in the project.');
+    } else {
+      out.push('', '## Source');
+      for (const rel of doc?.files ?? []) {
+        const file = path.join(registryDir, it.filesDir, rel);
+        if (!fs.existsSync(file)) continue;
+        out.push('', `### ${rel}`, '', '```tsx', fs.readFileSync(file, 'utf8').trimEnd(), '```');
+      }
+    }
+  }
+  return out.join('\n');
+}
+
+function getAddCommand(catalog, { names }) {
+  if (!Array.isArray(names) || !names.length) throw new ToolError('names must be a non-empty array.');
+  const items = names.map((n) => requireItem(catalog, n));
+  const unique = [...new Set(items.map((it) => it.name))];
+  const pro = items.filter((it) => it.tier === 'pro').map((it) => it.name);
+  const lines = [
+    `Run in the root folder of the Expo app (where package.json lists "expo"):`,
+    '',
+    addCommand(unique),
+    '',
+    '- First run creates components.json and the @/* tsconfig alias (same as `init`).',
+    '- Copies the files (and their registry dependencies) into src/ or the root app layout, and runs `npx expo install` for npm deps.',
+    '- Existing files are never overwritten unless `--force` is added; add `--dry-run` to preview.',
+  ];
+  if (pro.length)
+    lines.push(
+      `- PRO: ${pro.join(', ')} ${pro.length === 1 ? 'needs' : 'need'} an ExpoKit Pro plan. If the command reports "not logged in", ask the user to run \`npx ${PACKAGE}@latest login\` themselves (token from https://expokit.karandev.in/account). Never ask for the token in chat.`
+    );
+  return lines.join('\n');
+}
+
+export function callTool(catalog, registryDir, name, args = {}) {
+  switch (name) {
+    case 'list_items':
+      return listItems(catalog, args);
+    case 'search_items':
+      return searchItems(catalog, args);
+    case 'view_item':
+      return viewItem(catalog, registryDir, args);
+    case 'get_add_command':
+      return getAddCommand(catalog, args);
+    default:
+      return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// JSON-RPC / MCP
+// ---------------------------------------------------------------------------
+
+const rpcError = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+/** One incoming JSON-RPC message → the response object, or null for notifications. */
+export function handleMessage(msg, ctx) {
+  if (!msg || typeof msg !== 'object' || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
+    return msg && 'id' in msg ? rpcError(msg.id ?? null, -32600, 'Invalid request') : null;
+  }
+  const isRequest = 'id' in msg && msg.id !== null;
+  if (!isRequest) return null; // notifications/initialized, notifications/cancelled, …
+  const { id, method, params = {} } = msg;
+  const ok = (result) => ({ jsonrpc: '2.0', id, result });
+
+  switch (method) {
+    case 'initialize': {
+      const asked = params.protocolVersion;
+      return ok({
+        protocolVersion: PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: 'expokit', title: 'ExpoKit', version: ctx.version },
+        instructions: INSTRUCTIONS,
+      });
+    }
+    case 'ping':
+      return ok({});
+    case 'tools/list':
+      return ok({ tools: TOOLS });
+    case 'tools/call': {
+      const tool = TOOLS.find((t) => t.name === params.name);
+      if (!tool) return rpcError(id, -32602, `Unknown tool: ${params.name}`);
+      try {
+        const text = callTool(ctx.catalog, ctx.registryDir, params.name, params.arguments ?? {});
+        return ok({ content: [{ type: 'text', text }] });
+      } catch (e) {
+        const text = e instanceof ToolError ? e.message : `Internal error: ${e?.message ?? e}`;
+        return ok({ content: [{ type: 'text', text }], isError: true });
+      }
+    }
+    // Clients may probe these even though we don't advertise them.
+    case 'resources/list':
+      return ok({ resources: [] });
+    case 'resources/templates/list':
+      return ok({ resourceTemplates: [] });
+    case 'prompts/list':
+      return ok({ prompts: [] });
+    default:
+      return rpcError(id, -32601, `Method not found: ${method}`);
+  }
+}
+
+/** Serves MCP on stdin/stdout until stdin closes. */
+export function startMcpServer({ registryDir, version, aliases }) {
+  const ctx = { registryDir, version, catalog: loadCatalog(registryDir, aliases) };
+  const send = (obj) => process.stdout.write(`${JSON.stringify(obj)}\n`);
+  let buffer = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+    let nl;
+    while ((nl = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        send(rpcError(null, -32700, 'Parse error'));
+        continue;
+      }
+      // Batches came and went in 2025-03-26; answer them anyway.
+      const replies = (Array.isArray(msg) ? msg : [msg]).map((m) => handleMessage(m, ctx)).filter(Boolean);
+      if (Array.isArray(msg)) {
+        if (replies.length) send(replies);
+      } else if (replies[0]) send(replies[0]);
+    }
+  });
+  process.stdin.on('end', () => process.exit(0));
+  console.error(`expo-kit MCP server ${version} ready on stdio (${ctx.catalog.items.length} items)`);
+}