@mintlify/cli 4.0.1379 → 4.0.1381

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1379",
+  "version": "4.0.1381",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -45,12 +45,12 @@
   },
   "dependencies": {
     "@inquirer/prompts": "7.9.0",
-    "@mintlify/common": "1.0.1071",
-    "@mintlify/link-rot": "3.0.1268",
+    "@mintlify/common": "1.0.1072",
+    "@mintlify/link-rot": "3.0.1269",
     "@mintlify/models": "0.0.344",
-    "@mintlify/prebuild": "1.0.1222",
-    "@mintlify/previewing": "4.0.1292",
-    "@mintlify/validation": "0.1.816",
+    "@mintlify/prebuild": "1.0.1223",
+    "@mintlify/previewing": "4.0.1293",
+    "@mintlify/validation": "0.1.817",
     "adm-zip": "0.5.16",
     "chalk": "5.2.0",
     "color": "4.2.3",
@@ -59,6 +59,7 @@
     "ink": "6.3.0",
     "inquirer": "12.3.0",
     "js-yaml": "4.1.1",
+    "jsonc-parser": "^3.3.1",
     "mdast-util-mdx-jsx": "3.2.0",
     "open": "8.4.2",
     "openid-client": "6.8.2",
@@ -81,7 +82,7 @@
     "keytar": "7.9.0"
   },
   "devDependencies": {
-    "@mintlify/editor": "0.0.281",
+    "@mintlify/editor": "0.0.282",
     "@mintlify/ts-config": "2.0.2",
     "@tsconfig/recommended": "1.0.2",
     "@types/adm-zip": "0.5.7",
@@ -101,5 +102,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "24e02114e244af78c8f5b90759cdfc93052cab28"
+  "gitHead": "735d5f6fa89b67ed4919b057d13479ee067af0c4"
 }

package/src/cli.tsx

@@ -38,6 +38,7 @@ import {
   suppressConsoleWarnings,
   terminate,
 } from './helpers.js';
+import { runIndexSetup } from './indexSetup/setup.js';
 import { init } from './init.js';
 import { getAccessToken } from './keyring.js';
 import { login } from './login.js';
@@ -582,6 +583,35 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
           )
           .demandCommand(1, 'specify a subcommand: set, get, or clear')
       )
+      .command(
+        'index',
+        'Install the Mintlify index MCP server into your coding agents',
+        (yargs) =>
+          yargs
+            .option('claude', { type: 'boolean', description: 'Set up Claude Code' })
+            .option('cursor', { type: 'boolean', description: 'Set up Cursor' })
+            .option('vscode', { type: 'boolean', description: 'Set up VS Code' })
+            .option('codex', { type: 'boolean', description: 'Set up Codex' })
+            .option('opencode', { type: 'boolean', description: 'Set up OpenCode' })
+            .option('windsurf', { type: 'boolean', description: 'Set up Windsurf' })
+            .option('zed', { type: 'boolean', description: 'Set up Zed' })
+            .option('project', {
+              type: 'boolean',
+              description: 'Write project-level config instead of global',
+            })
+            .option('yes', {
+              alias: 'y',
+              type: 'boolean',
+              description: 'Skip prompts and set up all detected agents',
+            })
+            .usage('usage: mintlify index [options]')
+            .example('mintlify index', 'interactive picker')
+            .example('mintlify index --claude --cursor', 'set up specific agents'),
+        async (argv) => {
+          const code = await runIndexSetup(argv);
+          await terminate(code);
+        }
+      )
       .command(
         'update',
         'Update the CLI to the latest version',

package/src/indexSetup/clients.ts

@@ -0,0 +1,206 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+import { CURSOR_RULE, RULE_BODY, VSCODE_RULE } from './rule.js';
+
+export const INDEX_MCP_URL = 'https://index.mintlify.com/mcp';
+export const SERVER_NAME = 'mintlify-index';
+
+export type ClientName = 'claude' | 'cursor' | 'vscode' | 'codex' | 'opencode' | 'windsurf' | 'zed';
+
+export type Scope = 'global' | 'project';
+
+export interface SetupContext {
+  home: string;
+  cwd: string;
+  platform: NodeJS.Platform;
+  env: Record<string, string | undefined>;
+}
+
+export interface RuleSpec {
+  kind: 'file' | 'append';
+  content: string;
+  globalPath: (ctx: SetupContext) => string;
+  projectPath?: (ctx: SetupContext) => string;
+}
+
+export interface ClientDefinition {
+  name: ClientName;
+  displayName: string;
+  format: 'json' | 'toml';
+  configKey: string;
+  globalConfigPaths: (ctx: SetupContext) => string[];
+  projectConfigPaths?: (ctx: SetupContext) => string[];
+  buildEntry: () => Record<string, unknown>;
+  rule?: RuleSpec;
+  detectPaths: (ctx: SetupContext) => string[];
+}
+
+function claudeConfigDir(ctx: SetupContext): string {
+  const override = ctx.env.CLAUDE_CONFIG_DIR;
+  return override !== undefined && override !== '' ? override : path.join(ctx.home, '.claude');
+}
+
+function claudeGlobalConfigPath(ctx: SetupContext): string {
+  const override = ctx.env.CLAUDE_CONFIG_DIR;
+  return override !== undefined && override !== ''
+    ? path.join(override, '.claude.json')
+    : path.join(ctx.home, '.claude.json');
+}
+
+function zedUserDir(ctx: SetupContext): string {
+  if (ctx.platform === 'win32') {
+    const appData = ctx.env.APPDATA;
+    const base =
+      appData !== undefined && appData !== '' ? appData : path.join(ctx.home, 'AppData', 'Roaming');
+    return path.join(base, 'Zed');
+  }
+  return path.join(ctx.home, '.config', 'zed');
+}
+
+function vscodeUserDir(ctx: SetupContext): string {
+  if (ctx.platform === 'darwin') {
+    return path.join(ctx.home, 'Library', 'Application Support', 'Code', 'User');
+  }
+  if (ctx.platform === 'win32') {
+    const appData = ctx.env.APPDATA;
+    const base =
+      appData !== undefined && appData !== '' ? appData : path.join(ctx.home, 'AppData', 'Roaming');
+    return path.join(base, 'Code', 'User');
+  }
+  return path.join(ctx.home, '.config', 'Code', 'User');
+}
+
+export const CLIENTS: Record<ClientName, ClientDefinition> = {
+  claude: {
+    name: 'claude',
+    displayName: 'Claude Code',
+    format: 'json',
+    configKey: 'mcpServers',
+    globalConfigPaths: (ctx) => [claudeGlobalConfigPath(ctx)],
+    projectConfigPaths: (ctx) => [path.join(ctx.cwd, '.mcp.json')],
+    buildEntry: () => ({ type: 'http', url: INDEX_MCP_URL }),
+    rule: {
+      kind: 'file',
+      content: RULE_BODY,
+      globalPath: (ctx) => path.join(claudeConfigDir(ctx), 'rules', 'mintlify-index.md'),
+      projectPath: (ctx) => path.join(ctx.cwd, '.claude', 'rules', 'mintlify-index.md'),
+    },
+    detectPaths: (ctx) => [claudeConfigDir(ctx)],
+  },
+  cursor: {
+    name: 'cursor',
+    displayName: 'Cursor',
+    format: 'json',
+    configKey: 'mcpServers',
+    globalConfigPaths: (ctx) => [path.join(ctx.home, '.cursor', 'mcp.json')],
+    projectConfigPaths: (ctx) => [path.join(ctx.cwd, '.cursor', 'mcp.json')],
+    buildEntry: () => ({ url: INDEX_MCP_URL }),
+    rule: {
+      kind: 'file',
+      content: CURSOR_RULE,
+      globalPath: (ctx) => path.join(ctx.home, '.cursor', 'rules', 'mintlify-index.mdc'),
+      projectPath: (ctx) => path.join(ctx.cwd, '.cursor', 'rules', 'mintlify-index.mdc'),
+    },
+    detectPaths: (ctx) => [path.join(ctx.home, '.cursor')],
+  },
+  vscode: {
+    name: 'vscode',
+    displayName: 'VS Code',
+    format: 'json',
+    configKey: 'servers',
+    globalConfigPaths: (ctx) => [path.join(vscodeUserDir(ctx), 'mcp.json')],
+    projectConfigPaths: (ctx) => [path.join(ctx.cwd, '.vscode', 'mcp.json')],
+    buildEntry: () => ({ type: 'http', url: INDEX_MCP_URL }),
+    rule: {
+      kind: 'file',
+      content: VSCODE_RULE,
+      globalPath: (ctx) =>
+        path.join(vscodeUserDir(ctx), 'prompts', 'mintlify-index.instructions.md'),
+      projectPath: (ctx) =>
+        path.join(ctx.cwd, '.github', 'instructions', 'mintlify-index.instructions.md'),
+    },
+    detectPaths: (ctx) => [vscodeUserDir(ctx)],
+  },
+  codex: {
+    name: 'codex',
+    displayName: 'Codex',
+    format: 'toml',
+    configKey: 'mcp_servers',
+    globalConfigPaths: (ctx) => [path.join(ctx.home, '.codex', 'config.toml')],
+    projectConfigPaths: (ctx) => [path.join(ctx.cwd, '.codex', 'config.toml')],
+    buildEntry: () => ({ type: 'http', url: INDEX_MCP_URL }),
+    rule: {
+      kind: 'append',
+      content: RULE_BODY,
+      globalPath: (ctx) => path.join(ctx.home, '.codex', 'AGENTS.md'),
+      projectPath: (ctx) => path.join(ctx.cwd, 'AGENTS.md'),
+    },
+    detectPaths: (ctx) => [path.join(ctx.home, '.codex')],
+  },
+  opencode: {
+    name: 'opencode',
+    displayName: 'OpenCode',
+    format: 'json',
+    configKey: 'mcp',
+    globalConfigPaths: (ctx) => [path.join(ctx.home, '.config', 'opencode', 'opencode.json')],
+    projectConfigPaths: (ctx) => [path.join(ctx.cwd, 'opencode.json')],
+    buildEntry: () => ({ type: 'remote', url: INDEX_MCP_URL, enabled: true }),
+    rule: {
+      kind: 'append',
+      content: RULE_BODY,
+      globalPath: (ctx) => path.join(ctx.home, '.config', 'opencode', 'AGENTS.md'),
+      projectPath: (ctx) => path.join(ctx.cwd, 'AGENTS.md'),
+    },
+    detectPaths: (ctx) => [path.join(ctx.home, '.config', 'opencode')],
+  },
+  windsurf: {
+    name: 'windsurf',
+    displayName: 'Windsurf',
+    format: 'json',
+    configKey: 'mcpServers',
+    globalConfigPaths: (ctx) => [path.join(ctx.home, '.codeium', 'windsurf', 'mcp_config.json')],
+    buildEntry: () => ({ serverUrl: INDEX_MCP_URL }),
+    rule: {
+      kind: 'append',
+      content: RULE_BODY,
+      globalPath: (ctx) =>
+        path.join(ctx.home, '.codeium', 'windsurf', 'memories', 'global_rules.md'),
+      projectPath: (ctx) => path.join(ctx.cwd, '.windsurf', 'rules', 'mintlify-index.md'),
+    },
+    detectPaths: (ctx) => [path.join(ctx.home, '.codeium', 'windsurf')],
+  },
+  zed: {
+    name: 'zed',
+    displayName: 'Zed',
+    format: 'json',
+    configKey: 'context_servers',
+    globalConfigPaths: (ctx) => [path.join(zedUserDir(ctx), 'settings.json')],
+    projectConfigPaths: (ctx) => [path.join(ctx.cwd, '.zed', 'settings.json')],
+    buildEntry: () => ({ url: INDEX_MCP_URL }),
+    detectPaths: (ctx) => [zedUserDir(ctx)],
+  },
+};
+
+export const ALL_CLIENT_NAMES: ClientName[] = [
+  'claude',
+  'cursor',
+  'vscode',
+  'codex',
+  'opencode',
+  'windsurf',
+  'zed',
+];
+
+export async function detectClients(ctx: SetupContext): Promise<ClientName[]> {
+  const detected: ClientName[] = [];
+  for (const name of ALL_CLIENT_NAMES) {
+    for (const candidate of CLIENTS[name].detectPaths(ctx)) {
+      if (await fs.pathExists(candidate)) {
+        detected.push(name);
+        break;
+      }
+    }
+  }
+  return detected;
+}

package/src/indexSetup/configFile.ts

@@ -0,0 +1,140 @@
+import fs from 'fs-extra';
+import { applyEdits, modify, parse, type ParseError } from 'jsonc-parser';
+import path from 'path';
+
+function isEnoent(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+}
+
+export async function readJsonConfig(filePath: string): Promise<Record<string, unknown>> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(filePath, 'utf-8');
+  } catch (error) {
+    if (isEnoent(error)) {
+      return {};
+    }
+    throw error;
+  }
+  if (raw.trim() === '') {
+    return {};
+  }
+  const errors: ParseError[] = [];
+  const parsed = parse(raw, errors, { allowTrailingComma: true });
+  if (errors.length > 0) {
+    throw new Error(`invalid JSON at ${filePath}`);
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`expected a JSON object at ${filePath}`);
+  }
+  return parsed;
+}
+
+export function mergeServerEntry(
+  config: Record<string, unknown>,
+  configKey: string,
+  serverName: string,
+  entry: Record<string, unknown>
+): { config: Record<string, unknown>; alreadyExists: boolean } {
+  const section = config[configKey];
+  const servers: Record<string, unknown> = {};
+  if (typeof section === 'object' && section !== null && !Array.isArray(section)) {
+    Object.assign(servers, section);
+  }
+  const alreadyExists = serverName in servers;
+  servers[serverName] = entry;
+  return { config: { ...config, [configKey]: servers }, alreadyExists };
+}
+
+export async function writeJsonConfig(
+  filePath: string,
+  config: Record<string, unknown>
+): Promise<void> {
+  await fs.mkdirp(path.dirname(filePath));
+  await fs.writeFile(filePath, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+export async function writeJsonServerEntry(
+  filePath: string,
+  configKey: string,
+  serverName: string,
+  entry: Record<string, unknown>
+): Promise<{ status: 'configured' | 'reconfigured' }> {
+  let raw: string | undefined;
+  try {
+    raw = await fs.readFile(filePath, 'utf-8');
+  } catch (error) {
+    if (!isEnoent(error)) {
+      throw error;
+    }
+  }
+  if (raw === undefined || raw.trim() === '') {
+    const { config } = mergeServerEntry({}, configKey, serverName, entry);
+    await writeJsonConfig(filePath, config);
+    return { status: 'configured' };
+  }
+  const errors: ParseError[] = [];
+  const parsed = parse(raw, errors, { allowTrailingComma: true });
+  if (errors.length > 0 || typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`unable to parse existing config at ${filePath}`);
+  }
+  const section = parsed[configKey];
+  const sectionIsObject =
+    typeof section === 'object' && section !== null && !Array.isArray(section);
+  const alreadyExists = sectionIsObject && serverName in section;
+  const edits = sectionIsObject
+    ? modify(raw, [configKey, serverName], entry, {
+        formattingOptions: { insertSpaces: true, tabSize: 2 },
+      })
+    : modify(
+        raw,
+        [configKey],
+        { [serverName]: entry },
+        {
+          formattingOptions: { insertSpaces: true, tabSize: 2 },
+        }
+      );
+  await fs.mkdirp(path.dirname(filePath));
+  await fs.writeFile(filePath, applyEdits(raw, edits));
+  return { status: alreadyExists ? 'reconfigured' : 'configured' };
+}
+
+export async function resolveConfigPath(candidates: string[]): Promise<string> {
+  for (const candidate of candidates) {
+    if (await fs.pathExists(candidate)) {
+      return candidate;
+    }
+  }
+  const fallback = candidates[0];
+  if (fallback === undefined) {
+    throw new Error('no config path candidates');
+  }
+  return fallback;
+}
+
+export function upsertTomlServer(
+  content: string,
+  serverName: string,
+  entry: Record<string, string>
+): { content: string; alreadyExists: boolean } {
+  const header = `[mcp_servers.${serverName}]`;
+  const escapedName = serverName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const headerPattern = new RegExp(
+    `^[ \\t]*\\[mcp_servers\\.${escapedName}\\][ \\t]*(?:#.*)?$`,
+    'm'
+  );
+  const lines = Object.entries(entry).map(([key, value]) => `${key} = ${JSON.stringify(value)}`);
+  const block = `${[header, ...lines].join('\n')}\n`;
+  const match = headerPattern.exec(content);
+  if (match === null) {
+    const separator = content.length === 0 ? '' : content.endsWith('\n') ? '\n' : '\n\n';
+    return { content: `${content}${separator}${block}`, alreadyExists: false };
+  }
+  const headerIndex = match.index + match[0].indexOf('[');
+  const rest = content.slice(headerIndex + header.length);
+  const nextTable = rest.search(/\n\s*\[/);
+  const end = nextTable === -1 ? content.length : headerIndex + header.length + nextTable + 1;
+  const before = content.slice(0, headerIndex);
+  const after = content.slice(end).replace(/^\n+/, '\n');
+  return { content: `${before}${block}${after}`, alreadyExists: true };
+}

package/src/indexSetup/engine.ts

@@ -0,0 +1,113 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+import {
+  SERVER_NAME,
+  type ClientDefinition,
+  type ClientName,
+  type Scope,
+  type SetupContext,
+} from './clients.js';
+import { resolveConfigPath, upsertTomlServer, writeJsonServerEntry } from './configFile.js';
+import { appendRuleSection, writeRuleFile } from './rule.js';
+
+export interface ClientSetupResult {
+  client: ClientName;
+  displayName: string;
+  mcpStatus: 'configured' | 'reconfigured' | 'failed';
+  mcpDetail: string;
+  ruleStatus: 'installed' | 'updated' | 'failed' | 'none';
+  ruleDetail: string;
+}
+
+async function writeMcpEntry(
+  definition: ClientDefinition,
+  scope: Scope,
+  ctx: SetupContext
+): Promise<{ status: 'configured' | 'reconfigured'; configPath: string }> {
+  const projectPaths = definition.projectConfigPaths?.(ctx) ?? [];
+  const candidates =
+    scope === 'project' && projectPaths.length > 0
+      ? projectPaths
+      : definition.globalConfigPaths(ctx);
+  const configPath = await resolveConfigPath(candidates);
+  if (definition.format === 'toml') {
+    let existing = '';
+    try {
+      existing = await fs.readFile(configPath, 'utf-8');
+    } catch (error) {
+      if (
+        !(typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT')
+      ) {
+        throw error;
+      }
+    }
+    const entry: Record<string, string> = {};
+    for (const [key, value] of Object.entries(definition.buildEntry())) {
+      if (typeof value === 'string') {
+        entry[key] = value;
+      }
+    }
+    const { content, alreadyExists } = upsertTomlServer(existing, SERVER_NAME, entry);
+    await fs.mkdirp(path.dirname(configPath));
+    await fs.writeFile(configPath, content);
+    return { status: alreadyExists ? 'reconfigured' : 'configured', configPath };
+  }
+  const { status } = await writeJsonServerEntry(
+    configPath,
+    definition.configKey,
+    SERVER_NAME,
+    definition.buildEntry()
+  );
+  return { status, configPath };
+}
+
+async function writeRule(
+  definition: ClientDefinition,
+  scope: Scope,
+  ctx: SetupContext
+): Promise<{ status: 'installed' | 'updated' | 'none'; rulePath: string }> {
+  const rule = definition.rule;
+  if (rule === undefined) {
+    return { status: 'none', rulePath: '' };
+  }
+  const projectPath = rule.projectPath?.(ctx);
+  const rulePath =
+    scope === 'project' && projectPath !== undefined ? projectPath : rule.globalPath(ctx);
+  const status =
+    rule.kind === 'file'
+      ? await writeRuleFile(rulePath, rule.content)
+      : await appendRuleSection(rulePath, rule.content);
+  return { status, rulePath };
+}
+
+export async function setupClient(
+  definition: ClientDefinition,
+  scope: Scope,
+  ctx: SetupContext
+): Promise<ClientSetupResult> {
+  const result: ClientSetupResult = {
+    client: definition.name,
+    displayName: definition.displayName,
+    mcpStatus: 'failed',
+    mcpDetail: '',
+    ruleStatus: 'none',
+    ruleDetail: '',
+  };
+  try {
+    const { status, configPath } = await writeMcpEntry(definition, scope, ctx);
+    result.mcpStatus = status;
+    result.mcpDetail = configPath;
+  } catch (error) {
+    result.mcpDetail = error instanceof Error ? error.message : String(error);
+  }
+  try {
+    const { status, rulePath } = await writeRule(definition, scope, ctx);
+    result.ruleStatus = status;
+    result.ruleDetail = rulePath;
+  } catch (error) {
+    result.ruleStatus = 'failed';
+    result.ruleDetail = error instanceof Error ? error.message : String(error);
+  }
+  return result;
+}

package/src/indexSetup/rule.ts

@@ -0,0 +1,56 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+export const RULE_MARKER = '<!-- mintlify-index -->';
+
+export const RULE_BODY = `Use the Mintlify index \`context\` tool whenever you research how to use a library, framework, SDK, API, or CLI tool, including syntax, configuration, migration, and setup questions. Use it even for well-known libraries, since training data may be stale, and prefer it over web search for developer documentation. Do not use it for general programming concepts or for debugging business logic.
+`;
+
+export const CURSOR_RULE = `---
+alwaysApply: true
+---
+
+${RULE_BODY}`;
+
+export const VSCODE_RULE = `---
+applyTo: '**'
+---
+
+${RULE_BODY}`;
+
+export async function writeRuleFile(
+  filePath: string,
+  content: string
+): Promise<'installed' | 'updated'> {
+  const exists = await fs.pathExists(filePath);
+  await fs.mkdirp(path.dirname(filePath));
+  await fs.writeFile(filePath, content);
+  return exists ? 'updated' : 'installed';
+}
+
+export async function appendRuleSection(
+  filePath: string,
+  content: string
+): Promise<'installed' | 'updated'> {
+  const section = `${RULE_MARKER}\n${content}${RULE_MARKER}`;
+  let existing = '';
+  try {
+    existing = await fs.readFile(filePath, 'utf-8');
+  } catch (error) {
+    if (
+      !(typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT')
+    ) {
+      throw error;
+    }
+  }
+  const escaped = RULE_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(`${escaped}\\n[\\s\\S]*?${escaped}`);
+  if (pattern.test(existing)) {
+    await fs.writeFile(filePath, existing.replace(pattern, section));
+    return 'updated';
+  }
+  const separator = existing.length === 0 ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
+  await fs.mkdirp(path.dirname(filePath));
+  await fs.writeFile(filePath, `${existing}${separator}${section}\n`);
+  return 'installed';
+}