@mintlify/cli 4.0.1761 → 4.0.1763

package/bin/welcome.js

@@ -44,6 +44,7 @@ const GROUPS = [
     {
         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' },
         ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1761",
+  "version": "4.0.1763",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -61,6 +61,7 @@
     "ink": "6.3.0",
     "inquirer": "12.3.0",
     "js-yaml": "4.3.1",
+    "jsonc-parser": "3.3.1",
     "katex": "0.16.47",
     "mdast-util-mdx-jsx": "3.2.0",
     "open": "8.4.2",
@@ -75,6 +76,7 @@
     "remark-mdx": "3.1.1",
     "remark-smartypants": "3.0.2",
     "remark-stringify": "11.0.0",
+    "smol-toml": "1.6.0",
     "unified": "11.0.5",
     "unist-util-visit": "5.0.0",
     "yaml": "2.8.3",
@@ -104,5 +106,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "6eb170479a6da561bf94e7b19483819ec2fcfa5e"
+  "gitHead": "d6eeac40a96827ff665321df5a7d42af749f575d"
 }

package/src/agent-deployment.ts

@@ -21,7 +21,7 @@ const existingSchema = z.discriminatedUnion('status', [
   }),
   z.object({
     status: z.literal('expired'),
-    code: z.literal('deployment_already_exists'),
+    code: z.enum(['deployment_already_exists', 'deployment_claim_expired']),
     deploymentId: z.string(),
     subdomain: z.string(),
     expiresAt: z.iso.datetime().optional(),

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';
@@ -113,6 +114,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',

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' },
     ],