@mintlify/cli 4.0.1762 → 4.0.1764

package/README.md

@@ -1,3 +1,21 @@
 # @mintlify/cli
 
 The Mintlify CLI. See [mintlify](https://www.npmjs.com/package/mintlify) for more documentation.
+
+## Agent setup
+
+Run `mint agent setup` to install [Mintlify skills](https://mintlify.com/docs/ai/skillmd) and configure the [Admin MCP](https://mintlify.com/docs/ai/mintlify-mcp) for Claude Code, Codex, or Cursor. The command requires Node.js 22.20 or later and npm.
+
+```sh
+mint agent setup
+mint agent setup --agent claude-code codex cursor
+mint agent setup --agent codex --global
+```
+
+Setup defaults to the current project. Use `--global` for your user account. Pass `--agent` to configure specific agents directly. Otherwise, interactive setup lets you choose agents, with detected agents selected by default. Without a terminal, setup uses detected agents and requires `--agent` if none are detected.
+
+Skills are installed with `npx --yes skills@1.7.4 add https://mintlify.com/docs`, using the selected agents and scope. Rerunning setup refreshes these downloaded skills and replaces local edits to them.
+
+Admin MCP uses the server name `mintlify-admin` and URL `https://mcp.mintlify.com`. Setup preserves existing configuration and skips a matching server entry. A conflicting entry or invalid configuration stops setup before skills are installed. Codex configurations with an inline `mcp_servers` table need manual setup, as do global Claude Code configurations using `CLAUDE_CONFIG_DIR`.
+
+After configuration, complete OAuth sign-in in each agent to grant access to your Mintlify account and projects. In Claude Code, use `/mcp`; in Cursor, connect the server in MCP settings. For Codex project setup, the printed login command passes the server URL explicitly because some CLI versions do not read project configuration for `mcp login`. Global Codex setup uses `codex mcp login mintlify-admin`. Project configurations may require trusting the project and approving the server first. The command does not reuse `mint login` credentials or complete OAuth on your behalf.

package/__test__/agent-setup-config.test.ts

@@ -0,0 +1,314 @@
+import { parse as parseJsonc } from 'jsonc-parser';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { parse as parseToml } from 'smol-toml';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  ADMIN_MCP_NAME,
+  ADMIN_MCP_URL,
+  prepareMcpConfig,
+  writeMcpConfig,
+  type SetupAgent,
+} from '../src/agent-setup-config.js';
+
+let directory: string;
+let cwd: string;
+let homeDir: string;
+
+const projectPaths: [SetupAgent, string][] = [
+  ['claude-code', '.mcp.json'],
+  ['codex', '.codex/config.toml'],
+  ['cursor', '.cursor/mcp.json'],
+];
+
+const globalPaths: [SetupAgent, string][] = [
+  ['claude-code', '.claude.json'],
+  ['codex', '.codex/config.toml'],
+  ['cursor', '.cursor/mcp.json'],
+];
+
+function options(global = false, env: NodeJS.ProcessEnv = {}) {
+  return { cwd, homeDir, global, env };
+}
+
+async function fixture(filePath: string, contents: string) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, contents);
+}
+
+beforeEach(async () => {
+  directory = await fs.mkdtemp(path.join(os.tmpdir(), 'mint-agent-setup-config-'));
+  cwd = path.join(directory, 'project');
+  homeDir = path.join(directory, 'home');
+  await fs.mkdir(cwd);
+  await fs.mkdir(homeDir);
+});
+
+afterEach(async () => {
+  await fs.rm(directory, { recursive: true, force: true });
+});
+
+describe('agent setup MCP configuration', () => {
+  it.each(projectPaths)(
+    'prepares project configuration for %s without writing it',
+    async (agent, relativePath) => {
+      const plan = await prepareMcpConfig(agent, options());
+
+      expect(plan.path).toBe(path.join(cwd, relativePath));
+      expect(plan.original).toBeUndefined();
+      expect(plan.contents).toEqual(expect.any(String));
+      await expect(fs.readFile(plan.path, 'utf8')).rejects.toThrow();
+
+      if (plan.contents === undefined) throw new Error('Missing prepared configuration');
+      if (agent === 'codex') {
+        expect(parseToml(plan.contents)).toMatchObject({
+          mcp_servers: { [ADMIN_MCP_NAME]: { url: ADMIN_MCP_URL } },
+        });
+        return;
+      }
+
+      const expectedServer: { url: string; type?: string } = { url: ADMIN_MCP_URL };
+      if (agent === 'claude-code') expectedServer.type = 'http';
+      expect(parseJsonc(plan.contents)).toEqual({
+        mcpServers: { [ADMIN_MCP_NAME]: expectedServer },
+      });
+    }
+  );
+
+  it.each(globalPaths)(
+    'uses the user configuration path for global %s setup',
+    async (agent, relativePath) => {
+      const plan = await prepareMcpConfig(agent, options(true));
+
+      expect(plan.path).toBe(path.join(homeDir, relativePath));
+      expect(plan.original).toBeUndefined();
+      expect(plan.contents).toContain(ADMIN_MCP_URL);
+    }
+  );
+
+  it('honors CODEX_HOME for global setup while retaining project scope', async () => {
+    const codexHome = path.join(directory, 'custom-codex');
+    const env = { CODEX_HOME: codexHome };
+
+    const globalPlan = await prepareMcpConfig('codex', options(true, env));
+    const projectPlan = await prepareMcpConfig('codex', options(false, env));
+
+    expect(globalPlan.path).toBe(path.join(codexHome, 'config.toml'));
+    expect(projectPlan.path).toBe(path.join(cwd, '.codex/config.toml'));
+  });
+
+  it('refuses an unsupported Claude global directory without blocking project setup', async () => {
+    const env = { CLAUDE_CONFIG_DIR: path.join(directory, 'custom-claude') };
+
+    await expect(prepareMcpConfig('claude-code', options(true, env))).rejects.toThrow();
+    const projectPlan = await prepareMcpConfig('claude-code', options(false, env));
+    expect(projectPlan.path).toBe(path.join(cwd, '.mcp.json'));
+  });
+
+  it.each(['claude-code', 'cursor'])(
+    'preserves JSONC comments, trailing commas, and other %s settings',
+    async (client) => {
+      const agent = projectPaths.find(([name]) => name === client);
+      if (agent === undefined) throw new Error('Missing test agent');
+      const [name, relativePath] = agent;
+      const original = `{
+  // Personal preferences
+  "theme": "dark",
+  "mcpServers": {
+    "other": { "url": "https://example.com/mcp", },
+  },
+}
+`;
+      await fixture(path.join(cwd, relativePath), original);
+
+      const plan = await prepareMcpConfig(name, options());
+
+      expect(plan.original).toBe(original);
+      expect(plan.contents).toContain('// Personal preferences');
+      if (plan.contents === undefined) throw new Error('Missing prepared configuration');
+      expect(parseJsonc(plan.contents)).toMatchObject({
+        theme: 'dark',
+        mcpServers: {
+          other: { url: 'https://example.com/mcp' },
+          [ADMIN_MCP_NAME]: { url: ADMIN_MCP_URL },
+        },
+      });
+      expect(await fs.readFile(plan.path, 'utf8')).toBe(original);
+    }
+  );
+
+  it('appends Codex settings while preserving existing TOML text and tables', async () => {
+    const original =
+      '# Personal preferences\nmodel = "example-model"\n\n[mcp_servers.other]\nurl = "https://example.com/mcp"\n';
+    await fixture(path.join(cwd, '.codex/config.toml'), original);
+
+    const plan = await prepareMcpConfig('codex', options());
+
+    expect(plan.original).toBe(original);
+    expect(plan.contents?.startsWith(original)).toBe(true);
+    if (plan.contents === undefined) throw new Error('Missing prepared configuration');
+    expect(parseToml(plan.contents)).toMatchObject({
+      model: 'example-model',
+      mcp_servers: {
+        other: { url: 'https://example.com/mcp' },
+        [ADMIN_MCP_NAME]: { url: ADMIN_MCP_URL },
+      },
+    });
+  });
+
+  it.each(['claude-code', 'cursor'])(
+    'skips a matching %s server without changing extra fields',
+    async (client) => {
+      const agent = projectPaths.find(([name]) => name === client);
+      if (agent === undefined) throw new Error('Missing test agent');
+      const [name, relativePath] = agent;
+      const original = JSON.stringify({
+        mcpServers: {
+          [ADMIN_MCP_NAME]: {
+            url: ADMIN_MCP_URL,
+            type: 'http',
+            disabled: true,
+            headers: { Example: 'value' },
+          },
+        },
+      });
+      await fixture(path.join(cwd, relativePath), original);
+
+      const plan = await prepareMcpConfig(name, options());
+
+      expect(plan.original).toBe(original);
+      expect(plan.contents).toBeUndefined();
+      await writeMcpConfig(plan);
+      expect(await fs.readFile(plan.path, 'utf8')).toBe(original);
+    }
+  );
+
+  it('skips a matching Codex server without enabling or rewriting it', async () => {
+    const original = `[mcp_servers.${ADMIN_MCP_NAME}]\nurl = "${ADMIN_MCP_URL}"\nenabled = false\nstartup_timeout_sec = 20\n`;
+    await fixture(path.join(cwd, '.codex/config.toml'), original);
+
+    const plan = await prepareMcpConfig('codex', options());
+
+    expect(plan.original).toBe(original);
+    expect(plan.contents).toBeUndefined();
+    await writeMcpConfig(plan);
+    expect(await fs.readFile(plan.path, 'utf8')).toBe(original);
+  });
+
+  it.each([undefined, 'stdio'])('rejects an invalid Claude server transport %s', async (type) => {
+    const original = JSON.stringify({
+      mcpServers: { [ADMIN_MCP_NAME]: { url: ADMIN_MCP_URL, type } },
+    });
+    await fixture(path.join(cwd, '.mcp.json'), original);
+
+    await expect(prepareMcpConfig('claude-code', options())).rejects.toThrow('type');
+    expect(await fs.readFile(path.join(cwd, '.mcp.json'), 'utf8')).toBe(original);
+  });
+
+  it('detects changes to a server that was already configured', async () => {
+    const original = `[mcp_servers.${ADMIN_MCP_NAME}]\nurl = "${ADMIN_MCP_URL}"\n`;
+    const filePath = path.join(cwd, '.codex/config.toml');
+    await fixture(filePath, original);
+    const plan = await prepareMcpConfig('codex', options());
+    await fs.writeFile(filePath, '# Changed during installation\n');
+
+    await expect(writeMcpConfig(plan)).rejects.toThrow('changed during setup');
+    expect(await fs.readFile(filePath, 'utf8')).toBe('# Changed during installation\n');
+  });
+
+  it.each([
+    { url: 'https://example.com/different' },
+    { command: 'example-server', args: ['serve'] },
+  ])('refuses a conflicting JSON server %j', async (server) => {
+    for (const [agent, relativePath] of projectPaths) {
+      if (agent === 'codex') continue;
+      const original = JSON.stringify({ mcpServers: { [ADMIN_MCP_NAME]: server } });
+      const filePath = path.join(cwd, relativePath);
+      await fixture(filePath, original);
+
+      await expect(prepareMcpConfig(agent, options())).rejects.toThrow();
+      expect(await fs.readFile(filePath, 'utf8')).toBe(original);
+    }
+  });
+
+  it.each([
+    `url = "https://example.com/different"`,
+    `command = "example-server"\nargs = ["serve"]`,
+  ])('refuses a conflicting Codex server with %s', async (server) => {
+    const original = `[mcp_servers.${ADMIN_MCP_NAME}]\n${server}\n`;
+    const filePath = path.join(cwd, '.codex/config.toml');
+    await fixture(filePath, original);
+
+    await expect(prepareMcpConfig('codex', options())).rejects.toThrow();
+    expect(await fs.readFile(filePath, 'utf8')).toBe(original);
+  });
+
+  it.each(['{', '[]', '{"mcpServers": []}', '{"mcpServers": null}'])(
+    'rejects malformed or incompatible JSON configuration %s',
+    async (original) => {
+      const filePath = path.join(cwd, '.cursor/mcp.json');
+      await fixture(filePath, original);
+
+      await expect(prepareMcpConfig('cursor', options())).rejects.toThrow();
+      expect(await fs.readFile(filePath, 'utf8')).toBe(original);
+    }
+  );
+
+  it.each([
+    '[mcp_servers\n',
+    'mcp_servers = "example"\n',
+    'mcp_servers = { other = { url = "https://example.com/mcp" } }\n',
+  ])('rejects malformed or incompatible TOML configuration %s', async (original) => {
+    const filePath = path.join(cwd, '.codex/config.toml');
+    await fixture(filePath, original);
+
+    await expect(prepareMcpConfig('codex', options())).rejects.toThrow();
+    expect(await fs.readFile(filePath, 'utf8')).toBe(original);
+  });
+
+  it.each([0o640, 0o664])(
+    'writes the prepared contents while preserving permissions %i',
+    async (mode) => {
+      const filePath = path.join(cwd, '.mcp.json');
+      await fixture(filePath, '{"theme":"dark"}\n');
+      await fs.chmod(filePath, mode);
+      const plan = await prepareMcpConfig('claude-code', options());
+
+      await writeMcpConfig(plan);
+
+      expect(await fs.readFile(filePath, 'utf8')).toBe(plan.contents);
+      if (process.platform !== 'win32') expect((await fs.stat(filePath)).mode & 0o777).toBe(mode);
+      const rerun = await prepareMcpConfig('claude-code', options());
+      expect(rerun.contents).toBeUndefined();
+    }
+  );
+
+  it.each([false, true])(
+    'refuses configuration drift when an original file existed: %s',
+    async (existing) => {
+      const filePath = path.join(cwd, '.mcp.json');
+      if (existing) await fixture(filePath, '{}\n');
+      const plan = await prepareMcpConfig('claude-code', options());
+      const changed = '{"theme":"new-preference"}\n';
+      await fixture(filePath, changed);
+
+      await expect(writeMcpConfig(plan)).rejects.toThrow();
+      expect(await fs.readFile(filePath, 'utf8')).toBe(changed);
+    }
+  );
+
+  it('refuses to replace a configuration symlink or change its target', async () => {
+    const filePath = path.join(cwd, '.mcp.json');
+    const targetPath = path.join(directory, 'shared-config.json');
+    const original = '{"theme":"shared"}\n';
+    await fixture(targetPath, original);
+    const plan = await prepareMcpConfig('claude-code', options());
+    await fs.symlink(targetPath, filePath);
+
+    await expect(writeMcpConfig(plan)).rejects.toThrow();
+    expect((await fs.lstat(filePath)).isSymbolicLink()).toBe(true);
+    expect(await fs.readFile(targetPath, 'utf8')).toBe(original);
+  });
+});

package/__test__/agent-setup.test.ts

@@ -0,0 +1,207 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { parse as parseToml } from 'smol-toml';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { installSkills, setupAgent } from '../src/agent-setup.js';
+
+let directory: string;
+let argumentsFile: string;
+let project: string;
+const originalIsTTY = process.stdin.isTTY;
+
+function executablePath(command: string): string {
+  const extension = process.platform === 'win32' ? '.cmd' : '';
+  return path.join(directory, `${command}${extension}`);
+}
+
+async function fakeExecutable(command: string, source: string) {
+  if (process.platform === 'win32') {
+    const script = path.join(directory, `${command}.cjs`);
+    await fs.writeFile(script, source);
+    await fs.writeFile(executablePath(command), `@"${process.execPath}" "${script}" %*\r\n`);
+    return;
+  }
+  await fs.writeFile(executablePath(command), `#!${process.execPath}\n${source}\n`, {
+    mode: 0o755,
+  });
+}
+
+beforeEach(async () => {
+  directory = await fs.mkdtemp(path.join(os.tmpdir(), 'mint-agent-setup-'));
+  argumentsFile = path.join(directory, 'arguments.json');
+  project = path.join(directory, 'project');
+  await fs.mkdir(project);
+  vi.stubEnv('PATH', directory);
+  vi.stubEnv('CODEX_HOME', '');
+  vi.stubEnv('CLAUDE_CONFIG_DIR', '');
+  vi.spyOn(process, 'cwd').mockReturnValue(project);
+  vi.spyOn(os, 'homedir').mockReturnValue(path.join(directory, 'home'));
+  process.stdin.isTTY = false;
+  await fakeExecutable(
+    'npx',
+    `require('node:fs').writeFileSync(${JSON.stringify(argumentsFile)}, JSON.stringify(process.argv.slice(2)));`
+  );
+});
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  process.stdin.isTTY = originalIsTTY;
+  vi.unstubAllEnvs();
+  await fs.rm(directory, { recursive: true, force: true });
+});
+
+describe('agent setup skills installer', () => {
+  it('passes explicit agents and project scope without an interactive installer', async () => {
+    await installSkills(['claude-code', 'codex', 'cursor'], false);
+
+    expect(JSON.parse(await fs.readFile(argumentsFile, 'utf8'))).toEqual([
+      '--yes',
+      'skills@1.7.4',
+      'add',
+      'https://mintlify.com/docs',
+      '--agent',
+      'claude-code',
+      'codex',
+      'cursor',
+      '--yes',
+    ]);
+  });
+
+  it('forwards global scope to the skills installer', async () => {
+    await installSkills(['codex'], true);
+
+    expect(JSON.parse(await fs.readFile(argumentsFile, 'utf8'))).toContain('--global');
+  });
+
+  it('rejects a nonzero installer exit', async () => {
+    await fakeExecutable('npx', 'process.exit(1);');
+
+    await expect(installSkills(['codex'], false)).rejects.toThrow('Skills installation failed');
+  });
+
+  it('rejects partial installation failures even when the pinned installer exits zero', async () => {
+    await fakeExecutable('npx', "console.error('\\u001b[31mFailed to install 1\\u001b[0m');");
+
+    await expect(installSkills(['codex'], false)).rejects.toThrow('Skills installation failed');
+  });
+
+  it('rejects a missing npm runner', async () => {
+    await fs.unlink(executablePath('npx'));
+    const message =
+      process.platform === 'win32' ? 'Skills installation failed' : 'Could not run npx';
+
+    await expect(installSkills(['codex'], false)).rejects.toThrow(message);
+  });
+});
+
+describe('agent setup orchestration', () => {
+  it('passes a TOML URL override without embedded native argument quotes', async () => {
+    let output = '';
+    vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+      output += chunk.toString();
+      return true;
+    });
+    await fakeExecutable(
+      'codex',
+      `require('node:fs').writeFileSync(${JSON.stringify(argumentsFile)}, JSON.stringify(process.argv.slice(2)));`
+    );
+
+    await setupAgent({ agents: ['codex'], global: false });
+    const command = output.match(/Codex: run (.+)\. Trust/)?.[1];
+    if (command === undefined) throw new Error('Missing Codex login command');
+
+    const result = spawnSync(command, { shell: true, env: process.env });
+    expect(result.status).toBe(0);
+    const args: unknown = JSON.parse(await fs.readFile(argumentsFile, 'utf8'));
+    if (!Array.isArray(args) || typeof args[1] !== 'string') {
+      throw new Error('Missing Codex configuration override');
+    }
+    expect(args[0]).toBe('-c');
+    expect(args[1]).not.toContain('"');
+    expect(args.slice(2)).toEqual(['mcp', 'login', 'mintlify-admin']);
+    expect(parseToml(args[1])).toEqual({
+      mcp_servers: { 'mintlify-admin': { url: 'https://mcp.mintlify.com' } },
+    });
+  });
+
+  it('preflights every target before installing skills or changing configuration', async () => {
+    await fs.mkdir(path.join(project, '.cursor'));
+    const conflict = '{"mcpServers":{"mintlify-admin":{"url":"https://example.com/mcp"}}}';
+    await fs.writeFile(path.join(project, '.cursor/mcp.json'), conflict);
+
+    await expect(setupAgent({ agents: ['codex', 'cursor'], global: false })).rejects.toThrow(
+      'different configuration'
+    );
+    await expect(fs.readFile(argumentsFile)).rejects.toThrow();
+    await expect(fs.readFile(path.join(project, '.codex/config.toml'))).rejects.toThrow();
+    expect(await fs.readFile(path.join(project, '.cursor/mcp.json'), 'utf8')).toBe(conflict);
+  });
+
+  it('leaves MCP configuration untouched when skills installation fails', async () => {
+    await fakeExecutable('npx', 'process.exit(1);');
+
+    await expect(setupAgent({ agents: ['codex'], global: false })).rejects.toThrow();
+    await expect(fs.readFile(path.join(project, '.codex/config.toml'))).rejects.toThrow();
+  });
+
+  it('configures all selected agents after skills finish and deduplicates targets', async () => {
+    await setupAgent({
+      agents: ['codex', 'claude-code', 'cursor', 'codex'],
+      global: false,
+    });
+
+    const args: unknown = JSON.parse(await fs.readFile(argumentsFile, 'utf8'));
+    expect(args).toEqual([
+      '--yes',
+      'skills@1.7.4',
+      'add',
+      'https://mintlify.com/docs',
+      '--agent',
+      'codex',
+      'claude-code',
+      'cursor',
+      '--yes',
+    ]);
+    for (const file of ['.codex/config.toml', '.mcp.json', '.cursor/mcp.json']) {
+      expect(await fs.readFile(path.join(project, file), 'utf8')).toContain(
+        'https://mcp.mintlify.com'
+      );
+    }
+  });
+
+  it('configures detected agents when running without a terminal', async () => {
+    vi.stubEnv('AI_AGENT', 'codex_cli');
+
+    await setupAgent({ global: false });
+
+    expect(JSON.parse(await fs.readFile(argumentsFile, 'utf8'))).toEqual([
+      '--yes',
+      'skills@1.7.4',
+      'add',
+      'https://mintlify.com/docs',
+      '--agent',
+      'codex',
+      '--yes',
+    ]);
+    expect(await fs.readFile(path.join(project, '.codex/config.toml'), 'utf8')).toContain(
+      'https://mcp.mintlify.com'
+    );
+  });
+
+  it('requires agent selection when no supported agents are detected without a terminal', async () => {
+    vi.stubEnv('AI_AGENT', 'unknown-agent');
+
+    await expect(setupAgent({ global: false })).rejects.toThrow('Pass --agent');
+    await expect(fs.readFile(argumentsFile)).rejects.toThrow();
+  });
+
+  it('rejects unsupported agent names before spawning a command', async () => {
+    await expect(setupAgent({ agents: ['codex;echo unsafe'], global: false })).rejects.toThrow(
+      'Unsupported agent'
+    );
+    await expect(fs.readFile(argumentsFile)).rejects.toThrow();
+  });
+});