@mintlify/cli 4.0.1762 → 4.0.1764

package/src/agent-setup-config.ts

@@ -0,0 +1,144 @@
+import { applyEdits, modify, parse, type ParseError } from 'jsonc-parser';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parse as parseToml } from 'smol-toml';
+
+export type SetupAgent = 'claude-code' | 'codex' | 'cursor';
+
+export const ADMIN_MCP_NAME = 'mintlify-admin';
+export const ADMIN_MCP_URL = 'https://mcp.mintlify.com';
+
+type ConfigLocation = {
+  cwd: string;
+  homeDir: string;
+  global: boolean;
+  env?: NodeJS.ProcessEnv;
+};
+
+type McpConfigPlan = {
+  path: string;
+  original: string | undefined;
+  contents: string | undefined;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+async function readConfig(file: string): Promise<string | undefined> {
+  try {
+    return await fs.readFile(file, 'utf8');
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+function configPath(agent: SetupAgent, options: ConfigLocation): string {
+  const env = options.env ?? process.env;
+  if (agent === 'codex') {
+    let directory = path.join(options.cwd, '.codex');
+    if (options.global) directory = env.CODEX_HOME || path.join(options.homeDir, '.codex');
+    return path.join(directory, 'config.toml');
+  }
+  if (agent === 'cursor') {
+    const directory = options.global ? options.homeDir : options.cwd;
+    return path.join(directory, '.cursor', 'mcp.json');
+  }
+  if (options.global) {
+    if (env.CLAUDE_CONFIG_DIR) {
+      throw new Error(
+        'CLAUDE_CONFIG_DIR is set. Configure Claude Code with: claude mcp add --scope user --transport http mintlify-admin https://mcp.mintlify.com'
+      );
+    }
+    return path.join(options.homeDir, '.claude.json');
+  }
+  return path.join(options.cwd, '.mcp.json');
+}
+
+export async function prepareMcpConfig(
+  agent: SetupAgent,
+  options: ConfigLocation
+): Promise<McpConfigPlan> {
+  const requestedPath = configPath(agent, options);
+  const file = await fs.realpath(requestedPath).catch((error: unknown) => {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return requestedPath;
+    throw error;
+  });
+  const original = await readConfig(file);
+  const source = original ?? '';
+  const key = agent === 'codex' ? 'mcp_servers' : 'mcpServers';
+  let config: unknown;
+  try {
+    if (agent === 'codex') {
+      config = parseToml(source);
+    } else {
+      const errors: ParseError[] = [];
+      config = parse(source || '{}', errors, { allowTrailingComma: true });
+      if (errors.length > 0) throw new Error('Invalid JSON');
+    }
+  } catch {
+    throw new Error(`Cannot parse ${file}. Fix its configuration before running setup.`);
+  }
+  if (!isRecord(config)) throw new Error(`Expected an object in ${file}.`);
+  const servers = config[key];
+  if (servers !== undefined && !isRecord(servers)) {
+    throw new Error(`Expected ${key} to be an object in ${file}.`);
+  }
+  const existing = servers?.[ADMIN_MCP_NAME];
+  if (existing !== undefined) {
+    if (!isRecord(existing) || existing.url !== ADMIN_MCP_URL || existing.command !== undefined) {
+      throw new Error(
+        `${ADMIN_MCP_NAME} already has a different configuration in ${file}. Rename or remove that entry before running setup.`
+      );
+    }
+    if (agent === 'claude-code' && existing.type !== 'http') {
+      throw new Error(`Set type to "http" for ${ADMIN_MCP_NAME} in ${file} before running setup.`);
+    }
+    return { path: file, original, contents: undefined };
+  }
+  const newline = source.includes('\r\n') ? '\r\n' : '\n';
+  let contents: string;
+  if (agent === 'codex') {
+    contents = `${source}${newline}[mcp_servers.${ADMIN_MCP_NAME}]${newline}url = "${ADMIN_MCP_URL}"${newline}`;
+    try {
+      parseToml(contents);
+    } catch {
+      throw new Error(
+        `Cannot safely extend ${file}. Add [mcp_servers.${ADMIN_MCP_NAME}] with url = "${ADMIN_MCP_URL}" manually.`
+      );
+    }
+  } else {
+    const server: Record<string, string> = { url: ADMIN_MCP_URL };
+    if (agent === 'claude-code') server.type = 'http';
+    contents = applyEdits(
+      source || '{}',
+      modify(source || '{}', [key, ADMIN_MCP_NAME], server, {
+        formattingOptions: { insertSpaces: true, tabSize: 2, eol: newline },
+      })
+    );
+    if (!contents.endsWith(newline)) contents += newline;
+  }
+  return { path: file, original, contents };
+}
+
+export async function writeMcpConfig(plan: McpConfigPlan): Promise<void> {
+  if ((await readConfig(plan.path)) !== plan.original) {
+    throw new Error(
+      `${plan.path} changed during setup. Run setup again to preserve those changes.`
+    );
+  }
+  if (plan.contents === undefined) return;
+  await fs.mkdir(path.dirname(plan.path), { recursive: true, mode: 0o700 });
+  let mode = 0o600;
+  if (plan.original !== undefined) mode = (await fs.stat(plan.path)).mode;
+  const temporaryPath = `${plan.path}.${randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temporaryPath, plan.contents, { mode, flag: 'wx' });
+    if (plan.original !== undefined) await fs.chmod(temporaryPath, mode);
+    await fs.rename(temporaryPath, plan.path);
+  } finally {
+    await fs.rm(temporaryPath, { force: true });
+  }
+}

package/src/agent-setup.ts

@@ -0,0 +1,165 @@
+import { checkbox } from '@inquirer/prompts';
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
+
+import {
+  ADMIN_MCP_NAME,
+  ADMIN_MCP_URL,
+  prepareMcpConfig,
+  writeMcpConfig,
+  type SetupAgent,
+} from './agent-setup-config.js';
+import { detectAgent } from './agent.js';
+
+export const SETUP_AGENTS: SetupAgent[] = ['claude-code', 'codex', 'cursor'];
+
+const AGENT_LABELS: Record<SetupAgent, string> = {
+  'claude-code': 'Claude Code',
+  codex: 'Codex',
+  cursor: 'Cursor',
+};
+
+type SetupOptions = {
+  agents?: string[];
+  global: boolean;
+};
+
+function isSetupAgent(value: string): value is SetupAgent {
+  return SETUP_AGENTS.some((agent) => agent === value);
+}
+
+function detectedAgents(): SetupAgent[] {
+  const homeDir = os.homedir();
+  const current = detectAgent();
+  return SETUP_AGENTS.filter((agent) => {
+    if (agent === 'codex') {
+      return (
+        current === 'codex_cli' ||
+        existsSync(process.env.CODEX_HOME || path.join(homeDir, '.codex'))
+      );
+    }
+    if (agent === 'claude-code') {
+      return (
+        current === 'claude_code' ||
+        existsSync(process.env.CLAUDE_CONFIG_DIR || path.join(homeDir, '.claude'))
+      );
+    }
+    return (
+      current === 'cursor' || current === 'cursor-cli' || existsSync(path.join(homeDir, '.cursor'))
+    );
+  });
+}
+
+export function installSkills(agents: SetupAgent[], global: boolean): Promise<void> {
+  const args = [
+    '--yes',
+    'skills@1.7.4',
+    'add',
+    'https://mintlify.com/docs',
+    '--agent',
+    ...agents,
+    '--yes',
+  ];
+  if (global) args.push('--global');
+  return new Promise((resolve, reject) => {
+    const child = spawn('npx', args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: process.platform === 'win32',
+    });
+    let output = '';
+    const recordOutput = (chunk: Buffer) => {
+      output = (output + chunk.toString()).slice(-65_536);
+    };
+    child.stdout.on('data', (chunk: Buffer) => {
+      recordOutput(chunk);
+      process.stdout.write(chunk.toString());
+    });
+    child.stderr.on('data', (chunk: Buffer) => {
+      recordOutput(chunk);
+      process.stderr.write(chunk.toString());
+    });
+    child.on('error', () =>
+      reject(new Error('Could not run npx. Install npm and run setup again.'))
+    );
+    child.on('close', (code, signal) => {
+      if (code !== 0 || /Failed to install\s+\d+/.test(stripVTControlCharacters(output))) {
+        reject(
+          new Error(
+            `Skills installation failed (${signal ?? code}). Review the installer output and run setup again.`
+          )
+        );
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+export async function setupAgent(options: SetupOptions): Promise<void> {
+  const [major = 0, minor = 0] = process.versions.node.split('.').map(Number);
+  if (major < 22 || (major === 22 && minor < 20)) {
+    throw new Error(
+      'mint agent setup requires Node.js 22.20 or later to install skills. Upgrade Node.js and try again.'
+    );
+  }
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  let agents: SetupAgent[] = [];
+  for (const agent of options.agents ?? []) {
+    if (!isSetupAgent(agent)) throw new Error(`Unsupported agent: ${agent}`);
+    if (!agents.includes(agent)) agents.push(agent);
+  }
+  if (agents.length === 0) {
+    const detected = detectedAgents();
+    if (!interactive) {
+      agents = detected;
+    } else {
+      agents = await checkbox({
+        message: 'Which agents should use Mintlify?',
+        choices: SETUP_AGENTS.map((agent) => ({
+          name: AGENT_LABELS[agent],
+          value: agent,
+          checked: detected.includes(agent),
+        })),
+        required: true,
+      });
+    }
+  }
+  if (agents.length === 0) {
+    throw new Error('No supported agents detected. Pass --agent claude-code, codex, or cursor.');
+  }
+  const location = { cwd: process.cwd(), homeDir: os.homedir(), global: options.global };
+  const plans = await Promise.all(agents.map((agent) => prepareMcpConfig(agent, location)));
+  const scope = options.global ? 'your user account' : 'this project';
+  process.stdout.write(`Setting up Mintlify skills and Admin MCP for ${scope}.\n`);
+  await installSkills(agents, options.global);
+  for (const plan of plans) {
+    await writeMcpConfig(plan);
+    const action = plan.contents === undefined ? 'Already configured' : 'Configured';
+    process.stdout.write(`${action}: ${plan.path}\n`);
+  }
+  process.stdout.write(
+    '\nAdmin MCP is configured. Complete OAuth sign-in to grant account and project access:\n'
+  );
+  for (const agent of agents) {
+    if (agent === 'codex') {
+      let command = `codex mcp login ${ADMIN_MCP_NAME}`;
+      if (!options.global) {
+        const config = `mcp_servers.${ADMIN_MCP_NAME}.url='${ADMIN_MCP_URL}'`;
+        command = `codex -c "${config}" mcp login ${ADMIN_MCP_NAME}`;
+      }
+      process.stdout.write(
+        `  Codex: run ${command}. Trust the project before using its MCP configuration.\n`
+      );
+    } else if (agent === 'claude-code') {
+      process.stdout.write(
+        `  Claude Code: open /mcp and authenticate ${ADMIN_MCP_NAME}. Approve the project server if prompted.\n`
+      );
+    } else {
+      process.stdout.write(`  Cursor: open MCP settings and connect ${ADMIN_MCP_NAME}.\n`);
+    }
+  }
+  process.stdout.write('Setup: https://mintlify.com/docs/ai/mintlify-mcp\n');
+}

package/src/cli.tsx

@@ -15,6 +15,7 @@ import { hideBin } from 'yargs/helpers';
 import { accessibilityCheck } from './accessibilityCheck.js';
 import { addDomain } from './addDomain.js';
 import { claimDeployment, createAgentClaimLink } from './agent-claim.js';
+import { SETUP_AGENTS, setupAgent } from './agent-setup.js';
 import { analyticsBuilder } from './analytics/index.js';
 import { brokenLinksHandler } from './brokenLinks.js';
 import { comingSoon } from './comingSoon.js';
@@ -41,6 +42,13 @@ import { login } from './login.js';
 import { logout } from './logout.js';
 import { mdxLinter } from './mdxLinter.js';
 import { createTelemetryMiddleware } from './middlewares/telemetryMiddleware.js';
+import {
+  agents,
+  listMigrationDocs,
+  migrateWithAgent,
+  migrationInstructions,
+  type AgentName,
+} from './migrate.js';
 import { ogCommand } from './og.js';
 import { buildOverlayRegistryForCheck, checkOpenApiFile } from './openApiCheck.js';
 import { scoreHandler } from './score/index.js';
@@ -113,6 +121,49 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
       .middleware(checkNodeVersion)
       .middleware(suppressConsoleWarnings)
       .middleware(telemetryMiddleware)
+      .command('agent', 'Set up AI coding agents for Mintlify', (yargs) =>
+        yargs
+          .command(
+            'setup',
+            'Install Mintlify skills and configure Admin MCP',
+            (yargs) =>
+              yargs
+                .exitProcess(false)
+                .option('agent', {
+                  alias: 'a',
+                  type: 'string',
+                  array: true,
+                  choices: SETUP_AGENTS,
+                  description: 'Agents to configure (defaults to interactive selection)',
+                })
+                .option('global', {
+                  alias: 'g',
+                  type: 'boolean',
+                  default: false,
+                  description: 'Set up agents for your user account instead of this project',
+                })
+                .example('$0 agent setup', 'Choose agents and set up the current project')
+                .example(
+                  '$0 agent setup --agent codex --global',
+                  'Set up Codex for your user account'
+                )
+                .epilog(
+                  'Requires Node.js 22.20 or later and npm. Admin MCP requires a separate OAuth sign-in in each agent.'
+                ),
+            async (argv) => {
+              try {
+                await setupAgent({ agents: argv.agent, global: argv.global });
+                await terminate(0);
+              } catch (error) {
+                process.stderr.write(
+                  `${error instanceof Error ? error.message : 'Agent setup failed.'}\n`
+                );
+                await terminate(1);
+              }
+            }
+          )
+          .demandCommand(1, 'Run mint agent setup to configure your coding agents.')
+      )
       .command(
         'claim',
         'Claim a site created with mint deploy',
@@ -886,6 +937,46 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
             .example('mint format', 'format all MDX files in the current directory'),
         formatHandler
       )
+      .command(
+        'migrate',
+        'Print instructions for migrating a docs site to Mintlify',
+        (yargs: Argv) =>
+          yargs
+            .option('from', {
+              type: 'string',
+              choices: listMigrationDocs('sources'),
+              description: 'Include instructions for a source platform',
+            })
+            .option('topic', {
+              type: 'string',
+              choices: listMigrationDocs('topics'),
+              description: 'Print a single topic',
+            })
+            .option('agent', {
+              type: 'string',
+              choices: Object.keys(agents) as AgentName[],
+              description: 'Run the migration with a coding agent',
+            })
+            .option('claude', {
+              type: 'boolean',
+              description: 'Alias for --agent claude',
+            }),
+        async (argv) => {
+          const agent = argv.agent ?? (argv.claude ? 'claude' : undefined);
+          if (agent) {
+            try {
+              return await terminate(await migrateWithAgent(agent, argv.from));
+            } catch (error) {
+              addLog(<ErrorLog message={error instanceof Error ? error.message : String(error)} />);
+              return await terminate(1);
+            }
+          }
+          await new Promise<void>((resolve) =>
+            process.stdout.write(migrationInstructions(argv), () => resolve())
+          );
+          await terminate(0);
+        }
+      )
       // Coming soon commands — visible in help, tracked via telemetry to gauge interest.
       .command(
         'ai',

package/src/migrate.ts

@@ -0,0 +1,76 @@
+import { spawn } from 'node:child_process';
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { windowsCompatibleSpawnOptions } from './helpers.js';
+
+type Section = 'topics' | 'sources';
+
+const root = fileURLToPath(new URL('../migrate', import.meta.url));
+
+const read = (...segments: string[]) => readFileSync(path.join(root, ...segments), 'utf8');
+
+export const listMigrationDocs = (section: Section) =>
+  readdirSync(path.join(root, section))
+    .filter((file) => file.endsWith('.md'))
+    .map((file) => file.slice(0, -3))
+    .sort();
+
+const overview = () =>
+  [
+    read('index.md').trimEnd(),
+    `Topics: ${listMigrationDocs('topics').join(', ')}. Run \`mint migrate --topic <name>\`.`,
+    `Sources: ${listMigrationDocs('sources').join(', ')}. Run \`mint migrate --from <name>\`.`,
+  ].join('\n\n');
+
+export const migrationInstructions = ({ from, topic }: { from?: string; topic?: string }) => {
+  if (topic) return read('topics', `${topic}.md`);
+  if (from) return `${overview()}\n\n${read('sources', `${from}.md`)}`;
+  return `${overview()}\n`;
+};
+
+const prompt = (from?: string) =>
+  `Migrate a documentation site to Mintlify in the current directory. Run \`mint migrate${from ? ` --from ${from}` : ''}\` and follow the instructions it prints.`;
+
+export const agents = {
+  claude: {
+    bin: 'claude',
+    args: (prompt: string) => [prompt],
+    install: 'npm install -g @anthropic-ai/claude-code',
+  },
+  codex: {
+    bin: 'codex',
+    args: (prompt: string) => [prompt],
+    install: 'npm install -g @openai/codex',
+  },
+  cursor: {
+    bin: 'cursor-agent',
+    args: (prompt: string) => [prompt],
+    install: 'curl https://cursor.com/install -fsS | bash',
+  },
+  gemini: {
+    bin: 'gemini',
+    args: (prompt: string) => ['-i', prompt],
+    install: 'npm install -g @google/gemini-cli',
+  },
+};
+
+export type AgentName = keyof typeof agents;
+
+export const agentArgs = (name: AgentName, from?: string) => agents[name].args(prompt(from));
+
+export const migrateWithAgent = (name: AgentName, from?: string): Promise<number> =>
+  new Promise((resolve, reject) => {
+    const { bin, install } = agents[name];
+    const args = agentArgs(name, from).map((arg) =>
+      windowsCompatibleSpawnOptions.shell ? `"${arg}"` : arg
+    );
+    const child = spawn(bin, args, { stdio: 'inherit', ...windowsCompatibleSpawnOptions });
+    child.on('error', (error: NodeJS.ErrnoException) =>
+      reject(
+        error.code === 'ENOENT' ? new Error(`${bin} not found. Install it with: ${install}`) : error
+      )
+    );
+    child.on('close', (code) => resolve(code ?? 1));
+  });

package/src/validate/files.ts

@@ -13,6 +13,7 @@ import {
   parseContent,
   relocate,
   selectEdits,
+  toOffset,
   unmapEdit,
 } from './mdx.js';
 import { PARSE_ERROR } from './rules/parseError.js';
@@ -56,16 +57,35 @@ const readFrontmatter = (content: string): Record<string, unknown> => {
 type ParseError = { line?: number; column?: number; message: string };
 
 const REASON_POSITION = /\s*\(\d+:\d+(?:-\d+:\d+)?\)$/;
+const TAG_NAME_RULES = new Set(['unexpected-character', 'unexpected-eof']);
+const ESCAPE_HINT = "; if this < isn't a tag, escape it as \\<";
 
-export const toParseError = (error: unknown): ParseError => {
+const isStrayLessThan = (
+  error: unknown,
+  content: string,
+  position: { line?: number; column?: number } | null
+) => {
+  const { source, ruleId } = (error ?? {}) as { source?: unknown; ruleId?: unknown };
+  return (
+    source === 'micromark-extension-mdx-jsx' &&
+    typeof ruleId === 'string' &&
+    TAG_NAME_RULES.has(ruleId) &&
+    position?.line != null &&
+    position.column != null &&
+    content[toOffset(content, position.line, position.column) - 1] === '<'
+  );
+};
+
+export const toParseError = (error: unknown, content = ''): ParseError => {
   const reason = (error as { reason?: unknown } | null)?.reason;
   const fallback = error instanceof Error ? error.message : 'could not parse this file';
   const text = typeof reason === 'string' ? reason : fallback;
   const position = error && typeof error === 'object' ? getErrorPosition(error) : null;
+  const hint = isStrayLessThan(error, content, position) ? ESCAPE_HINT : '';
   return {
     ...(position?.line != null && { line: position.line }),
     ...(position?.column != null && { column: position.column }),
-    message: text.replace(REASON_POSITION, ''),
+    message: text.replace(REASON_POSITION, '') + hint,
   };
 };
 
@@ -102,7 +122,7 @@ export const parseFile = (
   try {
     return { context: { ...context, tree: getAST(content, file) }, approximate: true };
   } catch (error) {
-    return { error: toParseError(error) };
+    return { error: toParseError(error, content) };
   }
 };
 

package/src/validate/mdx.ts

@@ -186,7 +186,7 @@ export const applyEdits = (content: string, edits: Edit[]): string =>
     content
   );
 
-const toOffset = (content: string, line: number, column = 1) => {
+export const toOffset = (content: string, line: number, column = 1) => {
   let offset = 0;
   for (let current = 1; current < line; current++) {
     const next = content.indexOf('\n', offset);

package/src/welcome.ts

@@ -57,6 +57,7 @@ const GROUPS: CommandGroup[] = [
   {
     title: 'CLI',
     commands: [
+      { name: 'agent setup', description: 'Install Mintlify skills and configure Admin MCP' },
       { name: 'config', description: 'Manage CLI configuration' },
       { name: 'update', description: 'Update to the latest version' },
     ],