test-execution-platform-mcp 0.6.0-rc2

package/README.md

@@ -0,0 +1,86 @@
+# Test Execution Platform MCP Server
+
+Local stdio MCP server for `https://qc.vivas.vn`.
+
+## Build
+
+```bash
+npm install
+npm run build
+```
+
+## MCP config per agent
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+Path:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `$XDG_CONFIG_HOME/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "test-execution-platform": {
+      "command": "node",
+      "args": ["/path/to/test_execution_platform/mcp-server/dist/index.js"],
+      "env": {
+        "TEST_EXECUTION_API_BASE_URL": "https://qc.vivas.vn",
+        "TEST_EXECUTION_MCP_TOKEN": "tep_mcp_xxx"
+      }
+    }
+  }
+}
+```
+
+### Claude Code (`~/.claude.json`)
+
+```json
+{
+  "mcpServers": {
+    "test-execution-platform": {
+      "command": "node",
+      "args": ["/path/to/test_execution_platform/mcp-server/dist/index.js"],
+      "env": {
+        "TEST_EXECUTION_API_BASE_URL": "https://qc.vivas.vn",
+        "TEST_EXECUTION_MCP_TOKEN": "tep_mcp_xxx"
+      }
+    }
+  }
+}
+```
+
+### Codex CLI (`$CODEX_HOME/config.toml`)
+
+Path: `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`; override with the `CODEX_HOME` env var).
+
+```toml
+[mcp_servers.test-execution-platform]
+command = "node"
+args = ["/path/to/test_execution_platform/mcp-server/dist/index.js"]
+env = { TEST_EXECUTION_API_BASE_URL = "https://qc.vivas.vn", TEST_EXECUTION_MCP_TOKEN = "tep_mcp_xxx" }
+```
+
+> Tip: chạy `dist/setup/cli.js` (hoặc `qc-mcp.exe setup` sau khi bundle) để wizard tự detect Claude Desktop, Claude Code, **và Codex CLI** rồi ghi config cho cả ba.
+
+## Tool groups
+
+### Core tools
+
+- Projects/rounds: `list_projects`, `create_project`, `update_project`, `delete_project`, `list_rounds`, `create_round`, `update_round`, `delete_round`
+- Sessions: `open_session`, `list_sessions`, `get_session`, `close_session`, `list_branches`
+- Files/user stories: `get_file_tree`, `get_user_story_file`, `check_user_story_file_exists`, `delete_file`
+- Testcases: `get_testcases_by_path`, `create_testcase`, `update_testcase`, `delete_testcase`, `update_testcase_dev_status`
+- Notes: `get_notes`, `create_note`, `update_note`, `delete_note`
+- Excel: `analyze_excel`, `import_excel`
+
+### Workflow tools
+
+- `prepare_review_context`
+- `import_excel_with_preview`
+- `bulk_update_testcases_with_preview`
+- `prepare_ci_execution_context`
+
+## Guardrails
+
+Use `dry_run: true` before executing import, bulk update, and delete tools. Single testcase updates and note creation execute directly using the MCP token user's permissions.

package/dist/config.js

@@ -0,0 +1,11 @@
+export function loadConfig(env = process.env) {
+    const token = env.TEST_EXECUTION_MCP_TOKEN?.trim();
+    if (!token) {
+        throw new Error('TEST_EXECUTION_MCP_TOKEN is required');
+    }
+    const rawBaseUrl = env.TEST_EXECUTION_API_BASE_URL?.trim() || 'https://qc.vivas.vn';
+    return {
+        apiBaseUrl: rawBaseUrl.replace(/\/+$/, ''),
+        mcpToken: token,
+    };
+}

package/dist/http/client.js

@@ -0,0 +1,70 @@
+export class ApiError extends Error {
+    status;
+    backendError;
+    nextSteps;
+    constructor(status, message, backendError, nextSteps) {
+        super(message);
+        this.status = status;
+        this.backendError = backendError;
+        this.nextSteps = nextSteps;
+        this.name = 'ApiError';
+    }
+}
+export class ApiClient {
+    config;
+    fetchImpl;
+    constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    get(path) {
+        return this.request('GET', path);
+    }
+    post(path, body) {
+        return this.request('POST', path, body);
+    }
+    put(path, body) {
+        return this.request('PUT', path, body);
+    }
+    patch(path, body) {
+        return this.request('PATCH', path, body);
+    }
+    delete(path) {
+        return this.request('DELETE', path);
+    }
+    async request(method, path, body) {
+        const response = await this.fetchImpl(this.toUrl(path), {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.config.mcpToken}`,
+                'Content-Type': 'application/json',
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const data = await response.json().catch(() => ({}));
+        if (!response.ok) {
+            const message = typeof data?.error === 'string' ? data.error : `Backend returned HTTP ${response.status}`;
+            throw new ApiError(response.status, message, data, nextStepsForStatus(response.status));
+        }
+        return data;
+    }
+    toUrl(path) {
+        const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+        return `${this.config.apiBaseUrl}${normalizedPath}`;
+    }
+}
+function nextStepsForStatus(status) {
+    if (status === 401)
+        return ['Check TEST_EXECUTION_MCP_TOKEN or regenerate the token in account UI.'];
+    if (status === 403)
+        return ['Check the user role associated with the MCP token.'];
+    if (status === 404)
+        return ['Call list/get tools to verify the resource ID or path.'];
+    if (status === 409)
+        return ['Resolve duplicate/conflicting project, round, or testcase data.'];
+    if (status === 422)
+        return ['Validate markdown, Excel input, or testcase payload before retrying.'];
+    if (status >= 500)
+        return ['Check backend, Python service, or Git workspace logs before retrying.'];
+    return ['Check the tool input and retry.'];
+}

package/dist/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './config.js';
+import { ApiClient } from './http/client.js';
+import { createCoreTools } from './tools/core.js';
+import { createWorkflowTools } from './tools/workflows.js';
+import { dispatch as setupDispatch } from './setup/cli.js';
+// Single-binary dispatch: if argv contains a setup subcommand, forward to
+// the wizard CLI instead of starting the stdio MCP server. This keeps the
+// bundled binary to one file per platform.
+const SETUP_SUBCOMMANDS = new Set([
+    'setup',
+    'verify',
+    'update',
+    'uninstall',
+    'version',
+    'help',
+    '--help',
+    '-h',
+]);
+const sub = process.argv[2];
+if (sub && SETUP_SUBCOMMANDS.has(sub)) {
+    // Hand off to the setup CLI. The setup module guards its own argv entry
+    // via isDirectInvocation, so this import is safe.
+    setupDispatch(sub)
+        .then((code) => process.exit(code))
+        .catch((err) => {
+        console.error('Unhandled error:', err);
+        process.exit(1);
+    });
+}
+else {
+    // stdio MCP server path. Config is loaded lazily here so a missing token
+    // does not prevent `--help` / `--version` style commands from working.
+    const config = loadConfig();
+    const apiClient = new ApiClient(config);
+    const server = new McpServer({ name: 'test-execution-platform', version: '0.1.0' });
+    server.tool('health_check', 'Check backend connectivity and MCP token configuration.', {}, async () => {
+        const result = await apiClient.get('/health');
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    const coreTools = createCoreTools(apiClient);
+    const workflowTools = createWorkflowTools(apiClient);
+    for (const [name, definition] of Object.entries(coreTools)) {
+        server.tool(name, definition.description, definition.inputSchema.shape, async (input) => {
+            const result = await definition.handler(input);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        });
+    }
+    for (const [name, definition] of Object.entries(workflowTools)) {
+        server.tool(name, definition.description, definition.inputSchema.shape, async (input) => {
+            const result = await definition.handler(input);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        });
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/setup/cli.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+import { exit } from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { existsSync, writeFileSync, unlinkSync } from 'node:fs';
+import { getVersion } from './version.js';
+import { formatBanner, formatStep, formatSuccess, formatWarn, formatError, prompt } from './ui.js';
+import { detectClaudePaths } from './detect.js';
+import { buildMcpEntry, mergeMcpServer, readJsonSafe, writeConfigWithBackup } from './config.js';
+import { readTomlSafe, mergeCodexMcpServer, writeTomlWithBackup } from './toml-config.js';
+import { verifyMcpHandshake } from './verify.js';
+import { restoreOrRemoveMcpServer, restoreOrRemoveCodexMcpServer } from './uninstall.js';
+import { fetchLatestRelease, fetchChecksums, parseChecksums, verifySha256, swapBinary, getInstalledVersion, compareVersions, selectAssetForPlatform, downloadToFile, confirmUpdate, } from './update.js';
+// __filename / __dirname: when compiled to CommonJS, these are runtime
+// globals; when compiled to ESM we derive them from import.meta.url.
+const localFilename = typeof __filename !== 'undefined'
+    ? __filename
+    : fileURLToPath(import.meta.url);
+const localDirname = typeof __dirname !== 'undefined'
+    ? __dirname
+    : dirname(localFilename);
+const DEFAULT_API_BASE_URL = 'https://qc.vivas.vn';
+const SERVER_NAME = 'test-execution-platform';
+const TOKEN_PATTERN = /^tep_mcp_[a-f0-9]{64,}$/;
+function printUsage() {
+    const lines = [
+        'QC MCP Setup Wizard',
+        '',
+        'Usage:',
+        '  qc-mcp-setup.exe              # run setup wizard (interactive)',
+        '  qc-mcp.exe setup              # same as above',
+        '  qc-mcp.exe verify             # run stdio handshake check',
+        '  qc-mcp.exe update [flags]     # download and replace binary',
+        '  qc-mcp.exe uninstall          # restore Claude/Codex config from backup',
+        '  qc-mcp.exe version            # print version',
+        '  qc-mcp.exe help               # this message',
+        '',
+        'Update flags:',
+        '  --yes, -y                 skip interactive confirmation',
+        '  --binary <path>           override binary path (default: process.execPath)',
+        '  --project <path>          GitLab project path (default: dungnt/test_execution_platform)',
+        '  --gitlab-url <url>        GitLab base URL (default: https://gitlab.vivas.vn)',
+        '',
+        'Environment:',
+        '  TEST_EXECUTION_GITLAB_TOKEN  GitLab Project Access Token (scope: read_api)',
+    ];
+    process.stdout.write(lines.join('\n') + '\n');
+}
+async function runSetup() {
+    const banner = formatBanner('QC MCP Setup Wizard', '(c) 2026 Test Execution Platform');
+    console.log(banner);
+    // Step 1: detect
+    const paths = detectClaudePaths();
+    console.log('\n' + formatStep(1, 4, 'Detecting Claude / Codex installations...'));
+    console.log(paths.claudeDesktopConfig ? `  ✓ Claude Desktop config: ${paths.claudeDesktopConfig}` : '  - Claude Desktop not found');
+    console.log(paths.claudeCodeConfig ? `  ✓ Claude Code config: ${paths.claudeCodeConfig}` : '  - Claude Code not found');
+    console.log(paths.codexConfig ? `  ✓ Codex CLI config: ${paths.codexConfig}` : '  - Codex CLI not found');
+    if (!paths.claudeDesktopConfig && !paths.claudeCodeConfig && !paths.codexConfig) {
+        console.log('\n' + formatError('No Claude/Codex installations detected. Install Claude Desktop, Claude Code, or Codex CLI first.'));
+        return 1;
+    }
+    // Step 2: ask token
+    console.log('\n' + formatStep(2, 4, 'Configuration'));
+    const tokenRaw = await prompt('MCP Token (paste from account UI):');
+    const token = tokenRaw.trim();
+    if (!TOKEN_PATTERN.test(token)) {
+        console.log(formatError("Token must start with 'tep_mcp_' and contain only hex characters."));
+        return 1;
+    }
+    console.log('  ' + formatSuccess('Token format looks good'));
+    // Step 3: write configs
+    console.log('\n' + formatStep(3, 4, 'Writing config files'));
+    const binaryPath = process.argv[0] === 'node' ? resolve(localDirname, '..', '..', '..', 'qc-mcp.exe') : process.execPath;
+    const entry = buildMcpEntry(binaryPath, DEFAULT_API_BASE_URL, token);
+    const targets = [];
+    if (paths.claudeDesktopConfig)
+        targets.push({ path: paths.claudeDesktopConfig, name: 'Claude Desktop', format: 'json' });
+    if (paths.claudeCodeConfig)
+        targets.push({ path: paths.claudeCodeConfig, name: 'Claude Code', format: 'json' });
+    if (paths.codexConfig)
+        targets.push({ path: paths.codexConfig, name: 'Codex CLI', format: 'toml' });
+    for (const target of targets) {
+        if (target.format === 'json') {
+            const current = readJsonSafe(target.path);
+            const merged = mergeMcpServer(current, SERVER_NAME, entry);
+            writeConfigWithBackup(target.path, merged);
+        }
+        else {
+            const current = readTomlSafe(target.path);
+            const merged = mergeCodexMcpServer(current, SERVER_NAME, entry);
+            writeTomlWithBackup(target.path, merged);
+        }
+        console.log('  ' + formatSuccess(`${target.name}: ${target.path}`));
+    }
+    // Step 4: verify
+    console.log('\n' + formatStep(4, 4, 'Verification'));
+    const verifyResult = await verifyMcpHandshake({
+        binary: binaryPath,
+        apiBaseUrl: DEFAULT_API_BASE_URL,
+        token,
+    });
+    if (verifyResult.ok) {
+        console.log('  ' + formatSuccess(`Server: ${verifyResult.serverName ?? 'unknown'} v${verifyResult.serverVersion ?? '?'}`));
+        console.log('  ' + formatSuccess(`health_check: ${verifyResult.healthCheckText ?? 'ok'}`));
+    }
+    else {
+        console.log('  ' + formatWarn(`Verify failed: ${verifyResult.error ?? 'unknown'}`));
+        console.log('  ' + formatWarn('Config written. Please re-check token and restart Claude.'));
+    }
+    console.log('\n' + formatSuccess('All set! Restart Claude Desktop to load MCP.'));
+    return 0;
+}
+async function runVerify() {
+    const binaryPath = process.argv[0] === 'node' ? resolve(localDirname, '..', '..', '..', 'qc-mcp.exe') : process.execPath;
+    if (!existsSync(binaryPath)) {
+        console.log(formatError(`Binary not found at ${binaryPath}`));
+        return 1;
+    }
+    const token = process.env.TEST_EXECUTION_MCP_TOKEN ?? '';
+    if (!token) {
+        console.log(formatError('TEST_EXECUTION_MCP_TOKEN env var required for verify.'));
+        return 1;
+    }
+    const result = await verifyMcpHandshake({
+        binary: binaryPath,
+        apiBaseUrl: process.env.TEST_EXECUTION_API_BASE_URL ?? DEFAULT_API_BASE_URL,
+        token,
+    });
+    if (result.ok) {
+        console.log(formatSuccess(`Server: ${result.serverName} v${result.serverVersion}`));
+        console.log(formatSuccess(`health_check: ${result.healthCheckText}`));
+        return 0;
+    }
+    console.log(formatError(`Verify failed: ${result.error}`));
+    return 1;
+}
+async function runUpdate() {
+    console.log(formatBanner('QC MCP Update', '(c) 2026 Test Execution Platform'));
+    const args = process.argv.slice(3);
+    const flags = {
+        yes: args.includes('--yes') || args.includes('-y'),
+        binary: getFlagValue(args, '--binary') ?? process.execPath,
+        project: getFlagValue(args, '--project') ?? 'dungnt/test_execution_platform',
+        baseUrl: getFlagValue(args, '--gitlab-url') ?? 'https://gitlab.vivas.vn',
+    };
+    const token = process.env.TEST_EXECUTION_GITLAB_TOKEN ?? '';
+    if (!token) {
+        console.log(formatError('TEST_EXECUTION_GITLAB_TOKEN env var required (Project Access Token with read_api scope).'));
+        return 1;
+    }
+    if (!existsSync(flags.binary)) {
+        console.log(formatError(`Binary not found at ${flags.binary}`));
+        return 1;
+    }
+    // Step 1: installed version
+    const installed = getInstalledVersion(flags.binary);
+    if (installed === '0.0.0') {
+        console.log(formatWarn('Cannot determine installed version. Skipping update.'));
+        return 0;
+    }
+    console.log(formatStep(1, 5, `Installed: v${installed}`));
+    // Step 2: fetch latest release
+    const release = await fetchLatestRelease(flags.project, flags.baseUrl, token);
+    if (!release) {
+        console.log(formatError('No release found on GitLab.'));
+        return 1;
+    }
+    const latest = release.tag.replace(/^v/, '');
+    console.log(formatStep(2, 5, `Latest:    v${latest}`));
+    // Step 3: compare
+    const cmp = compareVersions(installed, latest);
+    if (cmp >= 0) {
+        console.log(formatSuccess(`Already up to date (v${installed}).`));
+        return 0;
+    }
+    console.log(formatStep(3, 5, `Update available: v${installed} → v${latest}`));
+    // Step 4: select platform asset
+    const assetName = selectAssetForPlatform(release.assets, process.platform, process.arch);
+    if (!assetName) {
+        console.log(formatError(`No binary available for ${process.platform}-${process.arch}.`));
+        return 1;
+    }
+    const assetUrl = release.assets.get(assetName);
+    console.log(formatStep(4, 5, `Asset:     ${assetName}`));
+    // Step 5: fetch SHA256SUMS.txt + verify expected hash exists
+    const checksumsUrl = release.assets.get('SHA256SUMS.txt');
+    if (!checksumsUrl) {
+        console.log(formatError('No SHA256SUMS.txt in release assets.'));
+        return 1;
+    }
+    const checksumsText = await fetchChecksums(checksumsUrl, token);
+    if (!checksumsText) {
+        console.log(formatError('Cannot fetch SHA256SUMS.txt.'));
+        return 1;
+    }
+    const checksums = parseChecksums(checksumsText);
+    const expectedSha = checksums.get(assetName);
+    if (!expectedSha) {
+        console.log(formatError(`No SHA256 in SHA256SUMS.txt for ${assetName}.`));
+        return 1;
+    }
+    // Get asset size (HEAD request) — fall back to 0 if HEAD not supported
+    const size = await getContentLength(assetUrl, token);
+    // Confirm (skip if --yes)
+    if (!flags.yes) {
+        const ok = await confirmUpdate({ from: installed, to: latest, size, sha256: expectedSha });
+        if (!ok) {
+            console.log(formatWarn('Update cancelled.'));
+            return 0;
+        }
+    }
+    // Download
+    const tmpPath = `${flags.binary}.new`;
+    console.log(formatStep(5, 5, 'Downloading...'));
+    try {
+        await downloadToFile(assetUrl, tmpPath, token, (bytes, total) => {
+            const pct = total > 0 ? Math.round((bytes / total) * 100) : 0;
+            process.stdout.write(`\r  ${pct}% (${(bytes / 1024 / 1024).toFixed(1)}/${(total / 1024 / 1024).toFixed(1)} MB)`);
+        });
+        process.stdout.write('\n');
+    }
+    catch (err) {
+        if (existsSync(tmpPath))
+            unlinkSync(tmpPath);
+        console.log(formatError(`Download failed: ${err.message}`));
+        return 1;
+    }
+    // Verify SHA256
+    if (!verifySha256(tmpPath, expectedSha)) {
+        if (existsSync(tmpPath))
+            unlinkSync(tmpPath);
+        console.log(formatError(`SHA256 mismatch for ${assetName}.`));
+        return 1;
+    }
+    // Swap
+    if (!swapBinary(flags.binary, tmpPath)) {
+        console.log(formatError('Swap failed. Current binary preserved.'));
+        return 1;
+    }
+    // Update version file
+    writeFileSync(`${flags.binary}.version`, `${latest}\n`);
+    console.log(formatSuccess(`Updated to v${latest}. Restart to apply.`));
+    return 0;
+}
+async function getContentLength(url, token) {
+    const headers = {};
+    if (token)
+        headers['PRIVATE-TOKEN'] = token;
+    const res = await fetch(url, { method: 'HEAD', headers });
+    if (!res.ok)
+        return 0;
+    return Number(res.headers.get('content-length') ?? 0);
+}
+function getFlagValue(args, flag) {
+    const i = args.indexOf(flag);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+}
+async function runUninstall() {
+    const paths = detectClaudePaths();
+    let anyChange = false;
+    if (paths.claudeDesktopConfig) {
+        const result = restoreOrRemoveMcpServer(paths.claudeDesktopConfig, SERVER_NAME);
+        console.log(`Claude Desktop: ${result.restored ? 'restored from backup' : result.removed ? 'removed key' : 'no change'}`);
+        anyChange = true;
+    }
+    if (paths.claudeCodeConfig) {
+        const result = restoreOrRemoveMcpServer(paths.claudeCodeConfig, SERVER_NAME);
+        console.log(`Claude Code: ${result.restored ? 'restored from backup' : result.removed ? 'removed key' : 'no change'}`);
+        anyChange = true;
+    }
+    if (paths.codexConfig) {
+        const result = restoreOrRemoveCodexMcpServer(paths.codexConfig, SERVER_NAME);
+        console.log(`Codex CLI: ${result.restored ? 'restored from backup' : result.removed ? 'removed key' : 'no change'}`);
+        anyChange = true;
+    }
+    if (!anyChange) {
+        console.log('No Claude/Codex configs found.');
+    }
+    return 0;
+}
+export async function dispatch(sub) {
+    switch (sub) {
+        case 'setup':
+        case undefined:
+            return runSetup();
+        case 'verify':
+            return runVerify();
+        case 'update':
+            return runUpdate();
+        case 'uninstall':
+            return runUninstall();
+        case 'version':
+            process.stdout.write(getVersion() + '\n');
+            return 0;
+        case 'help':
+        case '--help':
+        case '-h':
+            printUsage();
+            return 0;
+        default:
+            printUsage();
+            return 2;
+    }
+}
+// CLI entry — only run when invoked directly, not when imported by tests.
+const isDirectInvocation = process.argv[1] && (() => {
+    try {
+        return fileURLToPath(import.meta.url) === process.argv[1];
+    }
+    catch {
+        return false;
+    }
+})();
+if (isDirectInvocation) {
+    dispatch(process.argv[2])
+        .then((code) => exit(code))
+        .catch((err) => {
+        console.error('Unhandled error:', err);
+        exit(1);
+    });
+}

package/dist/setup/config.js

@@ -0,0 +1,80 @@
+import { readFileSync, writeFileSync, existsSync, copyFileSync, readdirSync, unlinkSync, mkdirSync } from 'node:fs';
+import { dirname, join, basename, sep, win32 as win32Path } from 'node:path';
+export function readJsonSafe(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const raw = readFileSync(path, 'utf-8');
+        if (raw.trim() === '')
+            return {};
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export function mergeMcpServer(current, serverName, entry) {
+    const mcpServers = { ...(current.mcpServers ?? {}) };
+    mcpServers[serverName] = { ...(mcpServers[serverName] ?? {}), ...entry };
+    return { ...current, mcpServers };
+}
+export function buildMcpEntry(command, baseUrl, token) {
+    return {
+        command,
+        env: {
+            TEST_EXECUTION_API_BASE_URL: baseUrl,
+            TEST_EXECUTION_MCP_TOKEN: token,
+        },
+    };
+}
+function backupPathFor(file) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    // Use the platform-appropriate path join so Windows gets backslashes.
+    const joiner = sep === win32Path.sep ? win32Path.join : join;
+    return joiner(dirname(file), `${basename(file)}.bak-${ts}`);
+}
+export { backupPathFor };
+export function writeConfigWithBackup(file, content) {
+    const dir = dirname(file);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    if (existsSync(file)) {
+        copyFileSync(file, backupPathFor(file));
+    }
+    writeFileSync(file, JSON.stringify(content, null, 2), 'utf-8');
+}
+export function listBackups(file) {
+    const dir = dirname(file);
+    const base = basename(file);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((name) => name.startsWith(`${base}.bak-`))
+        .map((name) => join(dir, name))
+        .sort()
+        .reverse();
+}
+export function restoreLatestBackup(file) {
+    const backups = listBackups(file);
+    if (backups.length === 0)
+        return false;
+    const latest = backups[0];
+    const content = readFileSync(latest, 'utf-8');
+    writeFileSync(file, content, 'utf-8');
+    return true;
+}
+export function removeMcpServer(file, serverName) {
+    const data = readJsonSafe(file);
+    if (!data.mcpServers || !data.mcpServers[serverName])
+        return false;
+    delete data.mcpServers[serverName];
+    writeFileSync(file, JSON.stringify(data, null, 2), 'utf-8');
+    return true;
+}
+export function cleanupOldBackups(file, keep) {
+    const backups = listBackups(file);
+    for (const old of backups.slice(keep)) {
+        unlinkSync(old);
+    }
+}

package/dist/setup/detect.js

@@ -0,0 +1,46 @@
+import { join, win32 } from 'node:path';
+import { homedir } from 'node:os';
+function envPath(...names) {
+    for (const name of names) {
+        const v = process.env[name];
+        if (v && v.length > 0)
+            return v;
+    }
+    return null;
+}
+function codexHome(platform) {
+    const explicit = envPath('CODEX_HOME');
+    if (explicit)
+        return explicit;
+    const home = envPath('HOME', 'USERPROFILE') ?? homedir();
+    if (platform === 'win32')
+        return win32.join(home, '.codex');
+    return join(home, '.codex');
+}
+export function detectClaudePaths(platform = process.platform) {
+    if (platform === 'win32') {
+        const appdata = envPath('APPDATA') ?? win32.join(homedir(), 'AppData', 'Roaming');
+        const home = envPath('USERPROFILE') ?? homedir();
+        return {
+            claudeDesktopConfig: win32.join(appdata, 'Claude', 'claude_desktop_config.json'),
+            claudeCodeConfig: win32.join(home, '.claude.json'),
+            codexConfig: win32.join(codexHome(platform), 'config.toml'),
+        };
+    }
+    if (platform === 'darwin') {
+        const home = envPath('HOME') ?? homedir();
+        return {
+            claudeDesktopConfig: join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
+            claudeCodeConfig: join(home, '.claude.json'),
+            codexConfig: join(codexHome(platform), 'config.toml'),
+        };
+    }
+    // linux and others
+    const home = envPath('HOME') ?? homedir();
+    const xdg = envPath('XDG_CONFIG_HOME') ?? join(home, '.config');
+    return {
+        claudeDesktopConfig: join(xdg, 'Claude', 'claude_desktop_config.json'),
+        claudeCodeConfig: join(home, '.claude.json'),
+        codexConfig: join(codexHome(platform), 'config.toml'),
+    };
+}

package/dist/setup/index.js

@@ -0,0 +1,8 @@
+export * from './version.js';
+export * from './ui.js';
+export * from './detect.js';
+export * from './config.js';
+export * from './toml-config.js';
+export * from './verify.js';
+export * from './update.js';
+export * from './uninstall.js';