@mintlify/cli 4.0.1379 → 4.0.1380

package/__test__/indexSetup/clients.test.ts

@@ -0,0 +1,109 @@
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  ALL_CLIENT_NAMES,
+  CLIENTS,
+  detectClients,
+  INDEX_MCP_URL,
+  type SetupContext,
+} from '../../src/indexSetup/clients.js';
+
+describe('clients', () => {
+  let home: string;
+  let cwd: string;
+  let ctx: SetupContext;
+
+  beforeEach(async () => {
+    home = await fs.mkdtemp(path.join(os.tmpdir(), 'mint-index-home-'));
+    cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'mint-index-cwd-'));
+    ctx = { home, cwd, platform: 'darwin', env: {} };
+  });
+
+  afterEach(async () => {
+    await fs.remove(home);
+    await fs.remove(cwd);
+  });
+
+  it('registers all seven clients', () => {
+    expect(ALL_CLIENT_NAMES).toEqual([
+      'claude',
+      'cursor',
+      'vscode',
+      'codex',
+      'opencode',
+      'windsurf',
+      'zed',
+    ]);
+  });
+
+  it('every buildEntry points at the index MCP url', () => {
+    for (const name of ALL_CLIENT_NAMES) {
+      const entry = CLIENTS[name].buildEntry();
+      expect(Object.values(entry)).toContain(INDEX_MCP_URL);
+    }
+  });
+
+  it('claude global config respects CLAUDE_CONFIG_DIR', () => {
+    expect(CLIENTS.claude.globalConfigPaths(ctx)).toEqual([path.join(home, '.claude.json')]);
+    const custom = { ...ctx, env: { CLAUDE_CONFIG_DIR: '/tmp/claude-alt' } };
+    expect(CLIENTS.claude.globalConfigPaths(custom)).toEqual([
+      path.join('/tmp/claude-alt', '.claude.json'),
+    ]);
+  });
+
+  it('vscode paths are platform specific', () => {
+    expect(CLIENTS.vscode.globalConfigPaths(ctx)[0]).toBe(
+      path.join(home, 'Library', 'Application Support', 'Code', 'User', 'mcp.json')
+    );
+    const linux = { ...ctx, platform: 'linux' as const };
+    expect(CLIENTS.vscode.globalConfigPaths(linux)[0]).toBe(
+      path.join(home, '.config', 'Code', 'User', 'mcp.json')
+    );
+  });
+
+  it('zed paths are platform specific', () => {
+    expect(CLIENTS.zed.globalConfigPaths(ctx)[0]).toBe(
+      path.join(home, '.config', 'zed', 'settings.json')
+    );
+    const win32 = {
+      ...ctx,
+      platform: 'win32' as const,
+      env: { APPDATA: 'C:\\Users\\me\\AppData\\Roaming' },
+    };
+    expect(CLIENTS.zed.globalConfigPaths(win32)[0]).toBe(
+      path.join('C:\\Users\\me\\AppData\\Roaming', 'Zed', 'settings.json')
+    );
+    const win32NoAppData = { ...ctx, platform: 'win32' as const, env: {} };
+    expect(CLIENTS.zed.globalConfigPaths(win32NoAppData)[0]).toBe(
+      path.join(home, 'AppData', 'Roaming', 'Zed', 'settings.json')
+    );
+  });
+
+  it('entry shapes match each client protocol', () => {
+    expect(CLIENTS.claude.buildEntry()).toEqual({ type: 'http', url: INDEX_MCP_URL });
+    expect(CLIENTS.cursor.buildEntry()).toEqual({ url: INDEX_MCP_URL });
+    expect(CLIENTS.vscode.buildEntry()).toEqual({ type: 'http', url: INDEX_MCP_URL });
+    expect(CLIENTS.codex.buildEntry()).toEqual({ type: 'http', url: INDEX_MCP_URL });
+    expect(CLIENTS.opencode.buildEntry()).toEqual({
+      type: 'remote',
+      url: INDEX_MCP_URL,
+      enabled: true,
+    });
+    expect(CLIENTS.windsurf.buildEntry()).toEqual({ serverUrl: INDEX_MCP_URL });
+    expect(CLIENTS.zed.buildEntry()).toEqual({ url: INDEX_MCP_URL });
+  });
+
+  it('windsurf has no project config and zed has no rule', () => {
+    expect(CLIENTS.windsurf.projectConfigPaths).toBeUndefined();
+    expect(CLIENTS.zed.rule).toBeUndefined();
+  });
+
+  it('detectClients finds only clients whose dirs exist', async () => {
+    await fs.mkdirp(path.join(home, '.cursor'));
+    await fs.mkdirp(path.join(home, '.codex'));
+    expect(await detectClients(ctx)).toEqual(['cursor', 'codex']);
+  });
+});

package/__test__/indexSetup/configFile.test.ts

@@ -0,0 +1,171 @@
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  mergeServerEntry,
+  readJsonConfig,
+  resolveConfigPath,
+  writeJsonConfig,
+  writeJsonServerEntry,
+} from '../../src/indexSetup/configFile.js';
+
+describe('configFile', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await fs.mkdtemp(path.join(os.tmpdir(), 'mint-index-'));
+  });
+
+  afterEach(async () => {
+    await fs.remove(dir);
+  });
+
+  it('readJsonConfig returns empty object for missing file', async () => {
+    expect(await readJsonConfig(path.join(dir, 'missing.json'))).toEqual({});
+  });
+
+  it('readJsonConfig returns empty object for empty file', async () => {
+    const file = path.join(dir, 'empty.json');
+    await fs.writeFile(file, '  \n');
+    expect(await readJsonConfig(file)).toEqual({});
+  });
+
+  it('readJsonConfig parses existing config', async () => {
+    const file = path.join(dir, 'config.json');
+    await fs.writeFile(file, JSON.stringify({ mcpServers: { other: { url: 'x' } } }));
+    expect(await readJsonConfig(file)).toEqual({ mcpServers: { other: { url: 'x' } } });
+  });
+
+  it('readJsonConfig throws on invalid JSON', async () => {
+    const file = path.join(dir, 'bad.json');
+    await fs.writeFile(file, '{ not json');
+    await expect(readJsonConfig(file)).rejects.toThrow();
+  });
+
+  it('readJsonConfig throws on non-object root', async () => {
+    const file = path.join(dir, 'array.json');
+    await fs.writeFile(file, '[1, 2]');
+    await expect(readJsonConfig(file)).rejects.toThrow();
+  });
+
+  it('mergeServerEntry adds entry to empty config', () => {
+    const { config, alreadyExists } = mergeServerEntry({}, 'mcpServers', 'mintlify-index', {
+      url: 'https://index.mintlify.com/mcp',
+    });
+    expect(alreadyExists).toBe(false);
+    expect(config).toEqual({
+      mcpServers: { 'mintlify-index': { url: 'https://index.mintlify.com/mcp' } },
+    });
+  });
+
+  it('mergeServerEntry preserves sibling servers and unrelated keys', () => {
+    const existing = {
+      theme: 'dark',
+      mcpServers: { other: { url: 'x' } },
+    };
+    const { config, alreadyExists } = mergeServerEntry(existing, 'mcpServers', 'mintlify-index', {
+      url: 'y',
+    });
+    expect(alreadyExists).toBe(false);
+    expect(config).toEqual({
+      theme: 'dark',
+      mcpServers: { other: { url: 'x' }, 'mintlify-index': { url: 'y' } },
+    });
+  });
+
+  it('mergeServerEntry replaces existing entry and reports alreadyExists', () => {
+    const existing = { mcpServers: { 'mintlify-index': { url: 'old' } } };
+    const { config, alreadyExists } = mergeServerEntry(existing, 'mcpServers', 'mintlify-index', {
+      url: 'new',
+    });
+    expect(alreadyExists).toBe(true);
+    expect(config).toEqual({ mcpServers: { 'mintlify-index': { url: 'new' } } });
+  });
+
+  it('mergeServerEntry recovers when config key holds a non-object', () => {
+    const { config } = mergeServerEntry({ mcpServers: 'oops' }, 'mcpServers', 'mintlify-index', {
+      url: 'y',
+    });
+    expect(config).toEqual({ mcpServers: { 'mintlify-index': { url: 'y' } } });
+  });
+
+  it('writeJsonConfig creates parent dirs and ends with newline', async () => {
+    const file = path.join(dir, 'nested', 'deep', 'config.json');
+    await writeJsonConfig(file, { a: 1 });
+    const raw = await fs.readFile(file, 'utf-8');
+    expect(raw).toBe('{\n  "a": 1\n}\n');
+  });
+
+  it('resolveConfigPath returns first existing candidate', async () => {
+    const a = path.join(dir, 'a.json');
+    const b = path.join(dir, 'b.json');
+    await fs.writeFile(b, '{}');
+    expect(await resolveConfigPath([a, b])).toBe(b);
+  });
+
+  it('resolveConfigPath falls back to first candidate when none exist', async () => {
+    const a = path.join(dir, 'a.json');
+    expect(await resolveConfigPath([a, path.join(dir, 'b.json')])).toBe(a);
+  });
+
+  it('writeJsonServerEntry creates a fresh file when missing', async () => {
+    const file = path.join(dir, 'missing.json');
+    const { status } = await writeJsonServerEntry(file, 'mcpServers', 'mintlify-index', {
+      url: 'x',
+    });
+    expect(status).toBe('configured');
+    const raw = await fs.readFile(file, 'utf-8');
+    expect(raw).toBe(
+      '{\n  "mcpServers": {\n    "mintlify-index": {\n      "url": "x"\n    }\n  }\n}\n'
+    );
+  });
+
+  it('writeJsonServerEntry preserves comments and trailing commas in JSONC', async () => {
+    const file = path.join(dir, 'settings.json');
+    await fs.writeFile(file, '// top comment\n{\n  "theme": "dark", // inline comment\n}\n');
+    const { status } = await writeJsonServerEntry(file, 'context_servers', 'mintlify-index', {
+      url: 'x',
+    });
+    expect(status).toBe('configured');
+    const raw = await fs.readFile(file, 'utf-8');
+    expect(raw).toContain('// top comment');
+    expect(raw).toContain('// inline comment');
+    expect(raw).toContain('"theme": "dark"');
+    const parsed = await readJsonConfig(file);
+    expect(parsed).toMatchObject({
+      theme: 'dark',
+      context_servers: { 'mintlify-index': { url: 'x' } },
+    });
+  });
+
+  it('writeJsonServerEntry reports reconfigured on rerun', async () => {
+    const file = path.join(dir, 'settings.json');
+    await writeJsonServerEntry(file, 'mcpServers', 'mintlify-index', { url: 'x' });
+    const second = await writeJsonServerEntry(file, 'mcpServers', 'mintlify-index', { url: 'y' });
+    expect(second.status).toBe('reconfigured');
+  });
+
+  it('writeJsonServerEntry recovers when the config key holds a non-object value', async () => {
+    const file = path.join(dir, 'settings.json');
+    await fs.writeFile(file, '// comment\n{\n  "mcpServers": "oops",\n}\n');
+    const { status } = await writeJsonServerEntry(file, 'mcpServers', 'mintlify-index', {
+      url: 'x',
+    });
+    expect(status).toBe('configured');
+    const raw = await fs.readFile(file, 'utf-8');
+    expect(raw).toContain('// comment');
+    const parsed = await readJsonConfig(file);
+    expect(parsed).toEqual({ mcpServers: { 'mintlify-index': { url: 'x' } } });
+  });
+
+  it('writeJsonServerEntry fails without touching the file on invalid JSON', async () => {
+    const file = path.join(dir, 'bad.json');
+    await fs.writeFile(file, '{ not json');
+    await expect(
+      writeJsonServerEntry(file, 'mcpServers', 'mintlify-index', { url: 'x' })
+    ).rejects.toThrow();
+    expect(await fs.readFile(file, 'utf-8')).toBe('{ not json');
+  });
+});

package/__test__/indexSetup/engine.test.ts

@@ -0,0 +1,108 @@
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { CLIENTS, INDEX_MCP_URL, type SetupContext } from '../../src/indexSetup/clients.js';
+import { readJsonConfig } from '../../src/indexSetup/configFile.js';
+import { setupClient } from '../../src/indexSetup/engine.js';
+import { RULE_MARKER } from '../../src/indexSetup/rule.js';
+
+describe('setupClient', () => {
+  let home: string;
+  let cwd: string;
+  let ctx: SetupContext;
+
+  beforeEach(async () => {
+    home = await fs.mkdtemp(path.join(os.tmpdir(), 'mint-index-home-'));
+    cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'mint-index-cwd-'));
+    ctx = { home, cwd, platform: 'darwin', env: {} };
+  });
+
+  afterEach(async () => {
+    await fs.remove(home);
+    await fs.remove(cwd);
+  });
+
+  it('configures claude globally with entry and rule file', async () => {
+    const result = await setupClient(CLIENTS.claude, 'global', ctx);
+    expect(result.mcpStatus).toBe('configured');
+    const config = await readJsonConfig(path.join(home, '.claude.json'));
+    expect(config).toEqual({
+      mcpServers: { 'mintlify-index': { type: 'http', url: INDEX_MCP_URL } },
+    });
+    expect(result.ruleStatus).toBe('installed');
+    expect(await fs.pathExists(path.join(home, '.claude', 'rules', 'mintlify-index.md'))).toBe(
+      true
+    );
+  });
+
+  it('preserves unrelated keys in an existing claude config', async () => {
+    await fs.writeFile(
+      path.join(home, '.claude.json'),
+      JSON.stringify({ theme: 'dark', mcpServers: { other: { url: 'x' } } })
+    );
+    await setupClient(CLIENTS.claude, 'global', ctx);
+    const config = await readJsonConfig(path.join(home, '.claude.json'));
+    expect(config.theme).toBe('dark');
+    const servers = config.mcpServers;
+    expect(servers).toMatchObject({ other: { url: 'x' } });
+  });
+
+  it('rerun reports reconfigured and updated', async () => {
+    await setupClient(CLIENTS.claude, 'global', ctx);
+    const second = await setupClient(CLIENTS.claude, 'global', ctx);
+    expect(second.mcpStatus).toBe('reconfigured');
+    expect(second.ruleStatus).toBe('updated');
+  });
+
+  it('writes codex toml and appends AGENTS.md with markers', async () => {
+    const result = await setupClient(CLIENTS.codex, 'global', ctx);
+    expect(result.mcpStatus).toBe('configured');
+    const toml = await fs.readFile(path.join(home, '.codex', 'config.toml'), 'utf-8');
+    expect(toml).toContain('[mcp_servers.mintlify-index]');
+    expect(toml).toContain(`url = "${INDEX_MCP_URL}"`);
+    const agentsMd = await fs.readFile(path.join(home, '.codex', 'AGENTS.md'), 'utf-8');
+    expect(agentsMd).toContain(RULE_MARKER);
+  });
+
+  it('project scope writes into cwd for clients that support it', async () => {
+    const result = await setupClient(CLIENTS.cursor, 'project', ctx);
+    expect(result.mcpStatus).toBe('configured');
+    expect(await fs.pathExists(path.join(cwd, '.cursor', 'mcp.json'))).toBe(true);
+    expect(await fs.pathExists(path.join(cwd, '.cursor', 'rules', 'mintlify-index.mdc'))).toBe(
+      true
+    );
+  });
+
+  it('project scope falls back to global for windsurf mcp config', async () => {
+    const result = await setupClient(CLIENTS.windsurf, 'project', ctx);
+    expect(result.mcpStatus).toBe('configured');
+    expect(result.mcpDetail).toBe(path.join(home, '.codeium', 'windsurf', 'mcp_config.json'));
+  });
+
+  it('zed gets an entry under context_servers and no rule', async () => {
+    const result = await setupClient(CLIENTS.zed, 'global', ctx);
+    const config = await readJsonConfig(path.join(home, '.config', 'zed', 'settings.json'));
+    expect(config).toEqual({ context_servers: { 'mintlify-index': { url: INDEX_MCP_URL } } });
+    expect(result.ruleStatus).toBe('none');
+  });
+
+  it('unparseable config fails that client and leaves the file untouched', async () => {
+    await fs.mkdirp(path.join(home, '.cursor'));
+    await fs.writeFile(path.join(home, '.cursor', 'mcp.json'), '{ broken');
+    const result = await setupClient(CLIENTS.cursor, 'global', ctx);
+    expect(result.mcpStatus).toBe('failed');
+    expect(await fs.readFile(path.join(home, '.cursor', 'mcp.json'), 'utf-8')).toBe('{ broken');
+    expect(result.ruleStatus).toBe('installed');
+  });
+
+  it('a non-ENOENT read error fails the client instead of overwriting the config', async () => {
+    await fs.mkdirp(path.join(home, '.cursor', 'mcp.json'));
+    const result = await setupClient(CLIENTS.cursor, 'global', ctx);
+    expect(result.mcpStatus).toBe('failed');
+    expect(await fs.pathExists(path.join(home, '.cursor', 'mcp.json'))).toBe(true);
+    expect((await fs.stat(path.join(home, '.cursor', 'mcp.json'))).isDirectory()).toBe(true);
+    expect(result.ruleStatus).toBe('installed');
+  });
+});

package/__test__/indexSetup/rule.test.ts

@@ -0,0 +1,87 @@
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  appendRuleSection,
+  CURSOR_RULE,
+  RULE_BODY,
+  RULE_MARKER,
+  VSCODE_RULE,
+  writeRuleFile,
+} from '../../src/indexSetup/rule.js';
+
+describe('rule', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await fs.mkdtemp(path.join(os.tmpdir(), 'mint-index-rule-'));
+  });
+
+  afterEach(async () => {
+    await fs.remove(dir);
+  });
+
+  it('frontmatter variants wrap the shared body', () => {
+    expect(CURSOR_RULE).toContain('alwaysApply: true');
+    expect(CURSOR_RULE).toContain(RULE_BODY);
+    expect(VSCODE_RULE).toContain("applyTo: '**'");
+    expect(VSCODE_RULE).toContain(RULE_BODY);
+  });
+
+  it('writeRuleFile creates dirs and reports installed then updated', async () => {
+    const file = path.join(dir, 'rules', 'mintlify-index.md');
+    expect(await writeRuleFile(file, RULE_BODY)).toBe('installed');
+    expect(await writeRuleFile(file, RULE_BODY)).toBe('updated');
+    expect(await fs.readFile(file, 'utf-8')).toBe(RULE_BODY);
+  });
+
+  it('appendRuleSection appends to a fresh file with markers', async () => {
+    const file = path.join(dir, 'AGENTS.md');
+    expect(await appendRuleSection(file, RULE_BODY)).toBe('installed');
+    const raw = await fs.readFile(file, 'utf-8');
+    expect(raw.startsWith(RULE_MARKER)).toBe(true);
+    expect(raw).toContain(RULE_BODY);
+    expect(raw.trimEnd().endsWith(RULE_MARKER)).toBe(true);
+  });
+
+  it('appendRuleSection preserves existing user content', async () => {
+    const file = path.join(dir, 'AGENTS.md');
+    await fs.writeFile(file, '# My rules\n\nBe nice.\n');
+    await appendRuleSection(file, RULE_BODY);
+    const raw = await fs.readFile(file, 'utf-8');
+    expect(raw.startsWith('# My rules\n\nBe nice.\n')).toBe(true);
+    expect(raw).toContain(RULE_MARKER);
+  });
+
+  it('appendRuleSection replaces its own section on rerun', async () => {
+    const file = path.join(dir, 'AGENTS.md');
+    await fs.writeFile(file, `before\n${RULE_MARKER}\nstale content\n${RULE_MARKER}\nafter\n`);
+    expect(await appendRuleSection(file, RULE_BODY)).toBe('updated');
+    const raw = await fs.readFile(file, 'utf-8');
+    expect(raw).not.toContain('stale content');
+    expect(raw).toContain(RULE_BODY);
+    expect(raw.startsWith('before\n')).toBe(true);
+    expect(raw.trimEnd().endsWith('after')).toBe(true);
+  });
+
+  it('appendRuleSection appends a full section when only a stray marker exists', async () => {
+    const file = path.join(dir, 'AGENTS.md');
+    await fs.writeFile(file, `before\n${RULE_MARKER}\nafter\n`);
+    expect(await appendRuleSection(file, RULE_BODY)).toBe('installed');
+    const raw = await fs.readFile(file, 'utf-8');
+    expect(raw).toContain(`before\n${RULE_MARKER}\nafter\n`);
+    expect(raw).toContain(RULE_BODY);
+    const markerCount = raw.split(RULE_MARKER).length - 1;
+    expect(markerCount).toBe(3);
+  });
+
+  it('appendRuleSection is idempotent', async () => {
+    const file = path.join(dir, 'AGENTS.md');
+    await appendRuleSection(file, RULE_BODY);
+    const first = await fs.readFile(file, 'utf-8');
+    await appendRuleSection(file, RULE_BODY);
+    expect(await fs.readFile(file, 'utf-8')).toBe(first);
+  });
+});

package/__test__/indexSetup/setup.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveExplicitClients } from '../../src/indexSetup/setup.js';
+
+describe('resolveExplicitClients', () => {
+  it('returns empty for no flags', () => {
+    expect(resolveExplicitClients({})).toEqual([]);
+  });
+
+  it('returns flagged clients in registry order', () => {
+    expect(resolveExplicitClients({ zed: true, claude: true, vscode: true })).toEqual([
+      'claude',
+      'vscode',
+      'zed',
+    ]);
+  });
+
+  it('ignores scope and confirmation flags', () => {
+    expect(resolveExplicitClients({ project: true, yes: true })).toEqual([]);
+  });
+});

package/__test__/indexSetup/toml.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+
+import { upsertTomlServer } from '../../src/indexSetup/configFile.js';
+
+describe('upsertTomlServer', () => {
+  const entry = { type: 'http', url: 'https://index.mintlify.com/mcp' };
+  const block =
+    '[mcp_servers.mintlify-index]\ntype = "http"\nurl = "https://index.mintlify.com/mcp"\n';
+
+  it('appends to empty content', () => {
+    const result = upsertTomlServer('', 'mintlify-index', entry);
+    expect(result.alreadyExists).toBe(false);
+    expect(result.content).toBe(block);
+  });
+
+  it('appends after existing content with a blank line', () => {
+    const existing = 'model = "o3"\n';
+    const result = upsertTomlServer(existing, 'mintlify-index', entry);
+    expect(result.alreadyExists).toBe(false);
+    expect(result.content).toBe(`model = "o3"\n\n${block}`);
+  });
+
+  it('replaces an existing table without touching neighbors', () => {
+    const existing = `model = "o3"\n\n[mcp_servers.mintlify-index]\nurl = "old"\n\n[mcp_servers.other]\ncommand = "npx"\n`;
+    const result = upsertTomlServer(existing, 'mintlify-index', entry);
+    expect(result.alreadyExists).toBe(true);
+    expect(result.content).toContain(block);
+    expect(result.content).toContain('[mcp_servers.other]\ncommand = "npx"');
+    expect(result.content).not.toContain('url = "old"');
+  });
+
+  it('replaces a table that sits at the end of the file', () => {
+    const existing = `model = "o3"\n\n[mcp_servers.mintlify-index]\nurl = "old"\n`;
+    const result = upsertTomlServer(existing, 'mintlify-index', entry);
+    expect(result.alreadyExists).toBe(true);
+    expect(result.content).toBe(`model = "o3"\n\n${block}`);
+  });
+
+  it('ignores a header that appears inside a comment', () => {
+    const existing = `# [mcp_servers.mintlify-index]\nmodel = "o3"\n\n[mcp_servers.mintlify-index]\nurl = "old"\n\n[mcp_servers.other]\ncommand = "npx"\n`;
+    const result = upsertTomlServer(existing, 'mintlify-index', entry);
+    expect(result.alreadyExists).toBe(true);
+    expect(result.content).toContain('# [mcp_servers.mintlify-index]');
+    expect(result.content).toContain(block);
+    expect(result.content).toContain('[mcp_servers.other]\ncommand = "npx"');
+    expect(result.content).not.toContain('url = "old"');
+  });
+
+  it('replaces an indented header without corrupting the split', () => {
+    const existing = `model = "o3"\n\n  [mcp_servers.mintlify-index]\n  url = "old"\n\n[mcp_servers.other]\ncommand = "npx"\n`;
+    const result = upsertTomlServer(existing, 'mintlify-index', entry);
+    expect(result.alreadyExists).toBe(true);
+    expect(result.content).toContain(block);
+    expect(result.content).toContain('[mcp_servers.other]\ncommand = "npx"');
+    expect(result.content).not.toContain('url = "old"');
+  });
+
+  it('replaces a table whose header line carries a trailing comment', () => {
+    const existing = `model = "o3"\n\n[mcp_servers.mintlify-index] # managed by mint\nurl = "old"\n\n[mcp_servers.other]\ncommand = "npx"\n`;
+    const result = upsertTomlServer(existing, 'mintlify-index', entry);
+    expect(result.alreadyExists).toBe(true);
+    expect(result.content).toContain(block);
+    expect(result.content).toContain('[mcp_servers.other]\ncommand = "npx"');
+    expect(result.content).not.toContain('url = "old"');
+    const occurrences = result.content.split('[mcp_servers.mintlify-index]').length - 1;
+    expect(occurrences).toBe(1);
+  });
+
+  it('is idempotent across reruns', () => {
+    const once = upsertTomlServer('', 'mintlify-index', entry);
+    const twice = upsertTomlServer(once.content, 'mintlify-index', entry);
+    expect(twice.content).toBe(once.content);
+    expect(twice.alreadyExists).toBe(true);
+  });
+});

package/bin/cli.js

@@ -25,6 +25,7 @@ import { deslopHandler } from './deslop/index.js';
 import { resolveExplicitFiles } from './deslop/resolveFiles.js';
 import { formatHandler } from './format.js';
 import { CMD_EXEC_PATH, checkPort, checkNodeVersion, autoUpgradeIfNeeded, findDocsRoot, getVersions, isAI, 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';
@@ -438,6 +439,29 @@ export const cli = ({ packageName = 'mint' }) => {
         yield terminate(0);
     }))
         .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'), (argv) => __awaiter(void 0, void 0, void 0, function* () {
+        const code = yield runIndexSetup(argv);
+        yield terminate(code);
+    }))
         .command('update', 'Update the CLI to the latest version', () => undefined, () => __awaiter(void 0, void 0, void 0, function* () {
         yield update({ packageName });
         yield terminate(0);