@brain-mcps/setup 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# @brain-mcps/setup
+
+Configure AI assistant clients to connect to [Brain4AI](https://brain4ai.app) (Cerebro Externo) and [Mentor4AI](https://mentor4ai.app) (Forge Mentor) MCP servers.
+
+One command writes the correct config entry for any supported client, handling format differences (Gemini's `httpUrl`, Windsurf's `serverUrl`, Copilot's nested `mcp.servers` path, etc.).
+
+## Quick Start
+
+```bash
+npx @brain-mcps/setup gemini              # Configure Gemini CLI for Cerebro Externo
+npx @brain-mcps/setup gemini mentor       # Configure Gemini CLI for Forge Mentor
+npx @brain-mcps/setup --detect            # Auto-detect and configure all installed clients
+```
+
+After running, open the configured client. It will prompt you to authenticate via OAuth (magic link to your email).
+
+## Supported Clients
+
+| Client         | Config Format             | Key Used                           |
+| -------------- | ------------------------- | ---------------------------------- |
+| Claude Code    | `~/.claude/settings.json` | `url`                              |
+| Claude Desktop | OS-specific config        | `url`                              |
+| Gemini CLI     | `~/.gemini/settings.json` | `httpUrl`                          |
+| Codex          | `~/.codex/config.toml`    | `url` (TOML)                       |
+| Cursor         | `~/.cursor/mcp.json`      | `url`                              |
+| Windsurf       | `~/.windsurf/mcp.json`    | `serverUrl`                        |
+| GitHub Copilot | `~/.vscode/mcp.json`      | `url` (nested under `mcp.servers`) |
+
+## Usage
+
+```bash
+# Configure a specific client
+npx @brain-mcps/setup <client> [product]
+
+# Auto-detect installed clients and configure all
+npx @brain-mcps/setup --detect [product]
+
+# Preview changes without writing files
+npx @brain-mcps/setup gemini --dry-run
+
+# List all supported clients and their config paths
+npx @brain-mcps/setup --list
+```
+
+### Products
+
+- `brain` (default): Cerebro Externo at `https://mcp.brain4ai.app/mcp`
+- `mentor`: Forge Mentor at `https://mcp.mentor4ai.app/mcp`
+
+### Clients
+
+Use any of these as the `<client>` argument:
+
+`claude-code`, `claude-desktop`, `gemini`, `codex`, `cursor`, `windsurf`, `copilot`
+
+## How It Works
+
+1. Reads the target client's JSON config file (or creates it if missing)
+2. Merges in the MCP server entry with the correct key format for that client
+3. Writes the file back, preserving all existing entries
+
+If the server is already configured with the same URL, it reports `already_configured` and makes no changes.
+
+## Authentication
+
+After configuring a client, the first time you use it the client will trigger an OAuth flow:
+
+1. A browser opens for sign-in
+2. Enter the email from your alpha invite
+3. Check your inbox for a magic link
+4. Click the link to complete authentication
+
+## Troubleshooting
+
+### Config file not found
+
+Run `npx @brain-mcps/setup --list` to see the expected config path for each client. The CLI creates the file and parent directories automatically.
+
+### OAuth fails in the browser
+
+- Make sure your email matches the alpha invite
+- Magic links expire after 10 minutes; request a new one
+- Try clearing browser cookies for the authentication domain
+
+### Client doesn't pick up changes
+
+Some clients require a restart after config changes. Close and reopen the client.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("./index.js");
+// ── Constants ────────────────────────────────────────────────────────────
+const VALID_PRODUCTS = new Set(["brain", "mentor"]);
+const VALID_CLIENTS = new Set(Object.keys(index_js_1.CLIENT_DEFS));
+// ── Helpers ──────────────────────────────────────────────────────────────
+function printUsage() {
+    console.log(`
+brain-mcp-setup: Configure AI clients to connect to Brain4AI / Mentor4AI MCP servers.
+
+Usage:
+  npx @brain-mcps/setup <client> [product]
+  npx @brain-mcps/setup --detect [product]
+  npx @brain-mcps/setup --list
+
+Arguments:
+  client    Client to configure: ${[...VALID_CLIENTS].join(", ")}
+  product   Which product: brain (Cerebro Externo) or mentor (Forge Mentor)
+            Default: brain
+
+Options:
+  --detect    Auto-detect installed clients and configure all of them
+  --list      List all supported clients and their config file paths
+  --dry-run   Show what would be changed without writing any files
+  --help      Show this help message
+
+Examples:
+  npx @brain-mcps/setup gemini              # Configure Gemini CLI for Cerebro Externo
+  npx @brain-mcps/setup gemini mentor       # Configure Gemini CLI for Forge Mentor
+  npx @brain-mcps/setup claude-code brain   # Configure Claude Code for Cerebro Externo
+  npx @brain-mcps/setup --detect            # Configure all detected clients
+  npx @brain-mcps/setup --list              # Show supported clients
+`);
+}
+function printResult(result) {
+    const clientName = (0, index_js_1.getClientName)(result.client);
+    switch (result.action) {
+        case "created":
+            console.log(`  + ${clientName}: created ${result.configPath}`);
+            console.log(`    Server "${result.serverName}" added.`);
+            break;
+        case "updated":
+            console.log(`  + ${clientName}: updated ${result.configPath}`);
+            console.log(`    Server "${result.serverName}" added.`);
+            break;
+        case "already_configured":
+            console.log(`  = ${clientName}: already configured (${result.serverName})`);
+            break;
+    }
+}
+// ── Main ─────────────────────────────────────────────────────────────────
+function main() {
+    const args = process.argv.slice(2);
+    if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+        printUsage();
+        process.exit(0);
+    }
+    if (args.includes("--list")) {
+        console.log("\nSupported clients:\n");
+        const supported = (0, index_js_1.listClients)().filter((c) => (0, index_js_1.isClientSupportedOnPlatform)(c.id));
+        for (const client of supported) {
+            console.log(`  ${client.id.padEnd(16)} ${client.name.padEnd(24)} ${client.configPath}`);
+        }
+        const skipped = (0, index_js_1.listClients)().filter((c) => !(0, index_js_1.isClientSupportedOnPlatform)(c.id));
+        if (skipped.length > 0) {
+            console.log("\nNot supported on this platform:");
+            for (const client of skipped) {
+                console.log(`  ${client.id.padEnd(16)} ${client.name.padEnd(24)} (${client.supportedPlatforms.join(", ")} only)`);
+            }
+        }
+        console.log("");
+        return;
+    }
+    // Parse product from args (defaults to "brain"; errors on unknown values)
+    const nonFlagArgs = args.filter((a) => !a.startsWith("--"));
+    let product = "brain";
+    if (nonFlagArgs.length >= 2) {
+        const productArg = nonFlagArgs[1];
+        if (!VALID_PRODUCTS.has(productArg)) {
+            console.error(`Unknown product: "${productArg}". Valid products: ${[...VALID_PRODUCTS].join(", ")}`);
+            process.exit(1);
+        }
+        product = productArg;
+    }
+    const dryRun = args.includes("--dry-run");
+    const setupOpts = { dryRun };
+    if (dryRun) {
+        console.log("[dry-run] No files will be modified.\n");
+    }
+    if (args.includes("--detect")) {
+        const detected = (0, index_js_1.detectInstalledClients)();
+        if (detected.length === 0) {
+            console.log("No supported AI clients detected on this system.");
+            console.log("Run with --list to see supported clients.");
+            process.exit(1);
+        }
+        console.log(`\nDetected ${detected.length} client(s). Configuring for ${product}:\n`);
+        for (const clientId of detected) {
+            try {
+                const result = (0, index_js_1.setupClient)(clientId, product, setupOpts);
+                printResult(result);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(`  ! ${(0, index_js_1.getClientName)(clientId)}: ${msg}`);
+            }
+        }
+        if (!dryRun) {
+            console.log("\nDone. Open each client and complete the OAuth sign-in when prompted.");
+        }
+        return;
+    }
+    // Single client mode
+    const clientArg = nonFlagArgs[0];
+    if (!clientArg || !VALID_CLIENTS.has(clientArg)) {
+        console.error(`Unknown client: "${clientArg}". Valid clients: ${[...VALID_CLIENTS].join(", ")}`);
+        process.exit(1);
+    }
+    const clientId = clientArg;
+    if (!(0, index_js_1.isClientSupportedOnPlatform)(clientId)) {
+        const def = index_js_1.CLIENT_DEFS[clientId];
+        console.error(`Error: ${def.name} is not supported on ${process.platform}. ` +
+            `Supported platforms: ${def.supportedPlatforms.join(", ")}.`);
+        process.exit(1);
+    }
+    console.log(`\nConfiguring ${(0, index_js_1.getClientName)(clientId)} for ${product}:\n`);
+    const result = (0, index_js_1.setupClient)(clientId, product, setupOpts);
+    printResult(result);
+    if (result.action !== "already_configured") {
+        console.log("\nNext steps:");
+        console.log(`  1. Open ${(0, index_js_1.getClientName)(clientId)}`);
+        console.log("  2. The client will prompt you to authenticate via OAuth");
+        console.log("  3. Enter the email from your alpha invite");
+        console.log("  4. Click the magic link in your inbox to complete sign-in");
+        console.log("");
+    }
+}
+main();

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+export type Product = "brain" | "mentor";
+export type ClientId = "claude-code" | "claude-desktop" | "gemini" | "codex" | "cursor" | "windsurf" | "copilot";
+export type ConfigFormat = "json" | "toml";
+export interface ClientDef {
+    id: ClientId;
+    name: string;
+    /** Path relative to home dir (~ prefix), or absolute on Windows. */
+    configPathTemplate: string;
+    /** Config file format. Defaults to JSON. */
+    format?: ConfigFormat;
+    /** Path segments to the servers object (e.g. ["mcpServers"], ["mcp_servers"]). */
+    serversKey: string[];
+    /** Build the server entry for this client. */
+    buildEntry: (url: string) => Record<string, unknown>;
+    /** If set, only these platforms are supported. Otherwise all platforms. */
+    supportedPlatforms?: NodeJS.Platform[];
+}
+export interface ClientConfig extends ClientDef {
+    configPath: string;
+}
+export interface SetupResult {
+    client: ClientId;
+    configPath: string;
+    action: "created" | "updated" | "already_configured";
+    serverName: string;
+}
+export interface SetupOptions {
+    dryRun?: boolean;
+    /** Override home directory (for testing). */
+    homeDir?: string;
+}
+export declare const CLIENT_DEFS: Record<ClientId, ClientDef>;
+export declare function resolveConfigPath(clientId: ClientId, homeDir?: string): string;
+export declare function isClientSupportedOnPlatform(clientId: ClientId, platform?: NodeJS.Platform): boolean;
+export declare function getClientName(clientId: ClientId): string;
+export declare function setupClient(clientId: ClientId, product: Product, options?: SetupOptions): SetupResult;
+export declare function detectInstalledClients(homeDir?: string): ClientId[];
+export declare function listClients(homeDir?: string): ClientConfig[];

package/dist/index.js

@@ -0,0 +1,212 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLIENT_DEFS = void 0;
+exports.resolveConfigPath = resolveConfigPath;
+exports.isClientSupportedOnPlatform = isClientSupportedOnPlatform;
+exports.getClientName = getClientName;
+exports.setupClient = setupClient;
+exports.detectInstalledClients = detectInstalledClients;
+exports.listClients = listClients;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const smol_toml_1 = require("smol-toml");
+// ── Product URLs ─────────────────────────────────────────────────────────
+const PRODUCT_URLS = {
+    brain: "https://mcp.brain4ai.app/mcp",
+    mentor: "https://mcp.mentor4ai.app/mcp",
+};
+const PRODUCT_SERVER_NAMES = {
+    brain: "cerebro-externo",
+    mentor: "forge-mentor",
+};
+// ── Client Definitions ───────────────────────────────────────────────────
+const CLAUDE_DESKTOP_PLATFORMS = ["darwin", "win32"];
+function getClaudeDesktopTemplate() {
+    if (process.platform === "win32") {
+        return path.join(process.env.APPDATA || "", "Claude", "claude_desktop_config.json");
+    }
+    // Default to macOS path; supportedPlatforms gates use on other OSes.
+    return "~/Library/Application Support/Claude/claude_desktop_config.json";
+}
+exports.CLIENT_DEFS = {
+    "claude-code": {
+        id: "claude-code",
+        name: "Claude Code",
+        configPathTemplate: "~/.claude/settings.json",
+        serversKey: ["mcpServers"],
+        buildEntry: (url) => ({ type: "url", url }),
+    },
+    "claude-desktop": {
+        id: "claude-desktop",
+        name: "Claude Desktop",
+        configPathTemplate: getClaudeDesktopTemplate(),
+        serversKey: ["mcpServers"],
+        buildEntry: (url) => ({ url }),
+        supportedPlatforms: CLAUDE_DESKTOP_PLATFORMS,
+    },
+    gemini: {
+        id: "gemini",
+        name: "Gemini CLI",
+        configPathTemplate: "~/.gemini/settings.json",
+        serversKey: ["mcpServers"],
+        buildEntry: (url) => ({ httpUrl: url }),
+    },
+    codex: {
+        id: "codex",
+        name: "Codex (OpenAI CLI)",
+        configPathTemplate: "~/.codex/config.toml",
+        format: "toml",
+        serversKey: ["mcp_servers"],
+        buildEntry: (url) => ({ url }),
+    },
+    cursor: {
+        id: "cursor",
+        name: "Cursor",
+        configPathTemplate: "~/.cursor/mcp.json",
+        serversKey: ["mcpServers"],
+        buildEntry: (url) => ({ url }),
+    },
+    windsurf: {
+        id: "windsurf",
+        name: "Windsurf",
+        configPathTemplate: "~/.windsurf/mcp.json",
+        serversKey: ["mcpServers"],
+        buildEntry: (url) => ({ serverUrl: url }),
+    },
+    copilot: {
+        id: "copilot",
+        name: "GitHub Copilot (VS Code)",
+        configPathTemplate: "~/.vscode/mcp.json",
+        serversKey: ["mcp", "servers"],
+        buildEntry: (url) => ({ type: "http", url }),
+    },
+};
+// ── Path Resolution ──────────────────────────────────────────────────────
+function resolveConfigPath(clientId, homeDir) {
+    const home = homeDir ?? os.homedir();
+    const template = exports.CLIENT_DEFS[clientId].configPathTemplate;
+    return template.replace(/^~/, home);
+}
+function isClientSupportedOnPlatform(clientId, platform = process.platform) {
+    const def = exports.CLIENT_DEFS[clientId];
+    return !def.supportedPlatforms || def.supportedPlatforms.includes(platform);
+}
+function getClientName(clientId) {
+    return exports.CLIENT_DEFS[clientId].name;
+}
+// ── Setup Engine ─────────────────────────────────────────────────────────
+function readConfigFile(filepath, format) {
+    if (!fs.existsSync(filepath))
+        return {};
+    const raw = fs.readFileSync(filepath, "utf-8");
+    if (format === "toml") {
+        return (0, smol_toml_1.parse)(raw);
+    }
+    return JSON.parse(raw);
+}
+function writeConfigFile(filepath, data, format) {
+    const dir = path.dirname(filepath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const serialized = format === "toml"
+        ? (0, smol_toml_1.stringify)(data) + "\n"
+        : JSON.stringify(data, null, 2) + "\n";
+    fs.writeFileSync(filepath, serialized, "utf-8");
+}
+function getNestedObject(obj, keys) {
+    let current = obj;
+    for (const key of keys) {
+        const existing = current[key];
+        if (!(key in current) ||
+            existing === null ||
+            typeof existing !== "object" ||
+            Array.isArray(existing)) {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+    return current;
+}
+function setupClient(clientId, product, options = {}) {
+    const def = exports.CLIENT_DEFS[clientId];
+    if (!isClientSupportedOnPlatform(clientId)) {
+        throw new Error(`${def.name} is not supported on ${process.platform}. ` +
+            `Supported platforms: ${def.supportedPlatforms.join(", ")}.`);
+    }
+    const format = def.format ?? "json";
+    const configPath = resolveConfigPath(clientId, options.homeDir);
+    const url = PRODUCT_URLS[product];
+    const serverName = PRODUCT_SERVER_NAMES[product];
+    const config = readConfigFile(configPath, format);
+    const servers = getNestedObject(config, def.serversKey);
+    const existing = servers[serverName];
+    if (existing) {
+        const existingUrl = existing.url ??
+            existing.httpUrl ??
+            existing.serverUrl;
+        if (existingUrl === url) {
+            return {
+                client: clientId,
+                configPath,
+                action: "already_configured",
+                serverName,
+            };
+        }
+    }
+    const action = fs.existsSync(configPath) ? "updated" : "created";
+    if (!options.dryRun) {
+        servers[serverName] = def.buildEntry(url);
+        writeConfigFile(configPath, config, format);
+    }
+    return { client: clientId, configPath, action, serverName };
+}
+function detectInstalledClients(homeDir) {
+    return Object.keys(exports.CLIENT_DEFS).filter((id) => {
+        if (!isClientSupportedOnPlatform(id))
+            return false;
+        const configPath = resolveConfigPath(id, homeDir);
+        const configDir = path.dirname(configPath);
+        return fs.existsSync(configDir);
+    });
+}
+function listClients(homeDir) {
+    return Object.keys(exports.CLIENT_DEFS).map((id) => ({
+        ...exports.CLIENT_DEFS[id],
+        configPath: resolveConfigPath(id, homeDir),
+    }));
+}

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,302 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const smol_toml_1 = require("smol-toml");
+const index_js_1 = require("./index.js");
+/** Temporarily override process.platform for a test. */
+function withPlatform(platform, fn) {
+    const original = Object.getOwnPropertyDescriptor(process, "platform");
+    Object.defineProperty(process, "platform", {
+        value: platform,
+        configurable: true,
+    });
+    try {
+        fn();
+    }
+    finally {
+        if (original)
+            Object.defineProperty(process, "platform", original);
+    }
+}
+// ── Test helpers: use a real temp directory as fake $HOME ────────────────
+let tmpHome;
+(0, vitest_1.beforeEach)(() => {
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "brain-mcp-setup-test-"));
+});
+(0, vitest_1.afterEach)(() => {
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+/** Create the config directory for a client inside tmpHome. */
+function ensureConfigDir(clientId) {
+    const configPath = (0, index_js_1.resolveConfigPath)(clientId, tmpHome);
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+}
+/** Write a JSON config file for a client inside tmpHome. */
+function writeConfig(clientId, data) {
+    const configPath = (0, index_js_1.resolveConfigPath)(clientId, tmpHome);
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(data, null, 2));
+}
+/** Read a JSON config file for a client from tmpHome. */
+function readConfig(clientId) {
+    const configPath = (0, index_js_1.resolveConfigPath)(clientId, tmpHome);
+    return JSON.parse(fs.readFileSync(configPath, "utf-8"));
+}
+/** Read a TOML config file for a client from tmpHome. */
+function readTomlConfig(clientId) {
+    const configPath = (0, index_js_1.resolveConfigPath)(clientId, tmpHome);
+    return (0, smol_toml_1.parse)(fs.readFileSync(configPath, "utf-8"));
+}
+/** Write a raw string config file for a client inside tmpHome. */
+function writeRawConfig(clientId, contents) {
+    const configPath = (0, index_js_1.resolveConfigPath)(clientId, tmpHome);
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, contents);
+}
+// ── Tests ───────────────────────────────────────────────────────────────
+(0, vitest_1.describe)("listClients", () => {
+    (0, vitest_1.it)("returns all 7 supported clients", () => {
+        const clients = (0, index_js_1.listClients)();
+        (0, vitest_1.expect)(clients).toHaveLength(7);
+        const ids = clients.map((c) => c.id);
+        (0, vitest_1.expect)(ids).toContain("claude-code");
+        (0, vitest_1.expect)(ids).toContain("claude-desktop");
+        (0, vitest_1.expect)(ids).toContain("gemini");
+        (0, vitest_1.expect)(ids).toContain("codex");
+        (0, vitest_1.expect)(ids).toContain("cursor");
+        (0, vitest_1.expect)(ids).toContain("windsurf");
+        (0, vitest_1.expect)(ids).toContain("copilot");
+    });
+});
+(0, vitest_1.describe)("resolveConfigPath", () => {
+    (0, vitest_1.it)("replaces ~ with the provided home directory", () => {
+        const resolved = (0, index_js_1.resolveConfigPath)("gemini", "/fake/home");
+        (0, vitest_1.expect)(resolved).toBe("/fake/home/.gemini/settings.json");
+    });
+    (0, vitest_1.it)("uses os.homedir when no homeDir provided", () => {
+        const resolved = (0, index_js_1.resolveConfigPath)("gemini");
+        (0, vitest_1.expect)(resolved).toContain(os.homedir());
+    });
+});
+(0, vitest_1.describe)("setupClient", () => {
+    (0, vitest_1.it)("creates gemini config with httpUrl key", () => {
+        ensureConfigDir("gemini");
+        const result = (0, index_js_1.setupClient)("gemini", "brain", { homeDir: tmpHome });
+        (0, vitest_1.expect)(result.action).toBe("created");
+        (0, vitest_1.expect)(result.serverName).toBe("cerebro-externo");
+        const config = readConfig("gemini");
+        const servers = config.mcpServers;
+        (0, vitest_1.expect)(servers["cerebro-externo"].httpUrl).toBe("https://mcp.brain4ai.app/mcp");
+        // Gemini uses httpUrl, not url
+        (0, vitest_1.expect)(servers["cerebro-externo"].url).toBeUndefined();
+    });
+    (0, vitest_1.it)("creates claude-code config with type and url keys", () => {
+        ensureConfigDir("claude-code");
+        const result = (0, index_js_1.setupClient)("claude-code", "mentor", { homeDir: tmpHome });
+        (0, vitest_1.expect)(result.action).toBe("created");
+        (0, vitest_1.expect)(result.serverName).toBe("forge-mentor");
+        const config = readConfig("claude-code");
+        const servers = config.mcpServers;
+        (0, vitest_1.expect)(servers["forge-mentor"]).toEqual({
+            type: "url",
+            url: "https://mcp.mentor4ai.app/mcp",
+        });
+    });
+    (0, vitest_1.it)("creates windsurf config with serverUrl key", () => {
+        ensureConfigDir("windsurf");
+        const result = (0, index_js_1.setupClient)("windsurf", "brain", { homeDir: tmpHome });
+        (0, vitest_1.expect)(result.serverName).toBe("cerebro-externo");
+        const config = readConfig("windsurf");
+        const servers = config.mcpServers;
+        (0, vitest_1.expect)(servers["cerebro-externo"].serverUrl).toBe("https://mcp.brain4ai.app/mcp");
+    });
+    (0, vitest_1.it)("creates copilot config with nested mcp.servers path", () => {
+        ensureConfigDir("copilot");
+        (0, index_js_1.setupClient)("copilot", "brain", { homeDir: tmpHome });
+        const config = readConfig("copilot");
+        const mcp = config.mcp;
+        (0, vitest_1.expect)(mcp.servers["cerebro-externo"]).toEqual({
+            type: "http",
+            url: "https://mcp.brain4ai.app/mcp",
+        });
+    });
+    (0, vitest_1.it)("creates codex config as TOML with mcp_servers.<id>.url", () => {
+        ensureConfigDir("codex");
+        const result = (0, index_js_1.setupClient)("codex", "brain", { homeDir: tmpHome });
+        (0, vitest_1.expect)(result.action).toBe("created");
+        (0, vitest_1.expect)(result.serverName).toBe("cerebro-externo");
+        (0, vitest_1.expect)(result.configPath).toMatch(/config\.toml$/);
+        const config = readTomlConfig("codex");
+        const servers = config.mcp_servers;
+        (0, vitest_1.expect)(servers["cerebro-externo"]).toEqual({
+            url: "https://mcp.brain4ai.app/mcp",
+        });
+    });
+    (0, vitest_1.it)("merges codex config into existing TOML without losing other entries", () => {
+        writeRawConfig("codex", [
+            'model = "gpt-5"',
+            "",
+            "[mcp_servers.metalab]",
+            'command = "npx"',
+            'args = ["metalab-mcp-client"]',
+            "",
+        ].join("\n"));
+        const result = (0, index_js_1.setupClient)("codex", "mentor", { homeDir: tmpHome });
+        (0, vitest_1.expect)(result.action).toBe("updated");
+        const config = readTomlConfig("codex");
+        (0, vitest_1.expect)(config.model).toBe("gpt-5");
+        const servers = config.mcp_servers;
+        (0, vitest_1.expect)(servers.metalab).toMatchObject({
+            command: "npx",
+            args: ["metalab-mcp-client"],
+        });
+        (0, vitest_1.expect)(servers["forge-mentor"]).toEqual({
+            url: "https://mcp.mentor4ai.app/mcp",
+        });
+    });
+    (0, vitest_1.it)("returns already_configured for codex when TOML URL matches", () => {
+        writeRawConfig("codex", [
+            "[mcp_servers.cerebro-externo]",
+            'url = "https://mcp.brain4ai.app/mcp"',
+            "",
+        ].join("\n"));
+        const result = (0, index_js_1.setupClient)("codex", "brain", { homeDir: tmpHome });
+        (0, vitest_1.expect)(result.action).toBe("already_configured");
+    });
+    (0, vitest_1.it)("merges into existing config without overwriting other keys", () => {
+        writeConfig("gemini", {
+            mcpServers: { "other-server": { url: "https://other.example.com" } },
+            someOtherKey: "keep-me",
+        });
+        const result = (0, index_js_1.setupClient)("gemini", "brain", { homeDir: tmpHome });
+        (0, vitest_1.expect)(result.action).toBe("updated");
+        const config = readConfig("gemini");
+        (0, vitest_1.expect)(config.someOtherKey).toBe("keep-me");
+        const servers = config.mcpServers;
+        (0, vitest_1.expect)(servers["other-server"].url).toBe("https://other.example.com");
+        (0, vitest_1.expect)(servers["cerebro-externo"].httpUrl).toBe("https://mcp.brain4ai.app/mcp");
+    });
+    (0, vitest_1.it)("returns already_configured when URL matches", () => {
+        writeConfig("gemini", {
+            mcpServers: {
+                "cerebro-externo": { httpUrl: "https://mcp.brain4ai.app/mcp" },
+            },
+        });
+        const result = (0, index_js_1.setupClient)("gemini", "brain", { homeDir: tmpHome });
+        (0, vitest_1.expect)(result.action).toBe("already_configured");
+    });
+    (0, vitest_1.it)("dry-run does not write files", () => {
+        ensureConfigDir("gemini");
+        const configPath = (0, index_js_1.resolveConfigPath)("gemini", tmpHome);
+        const result = (0, index_js_1.setupClient)("gemini", "brain", {
+            homeDir: tmpHome,
+            dryRun: true,
+        });
+        (0, vitest_1.expect)(result.action).toBe("created");
+        (0, vitest_1.expect)(fs.existsSync(configPath)).toBe(false);
+    });
+    (0, vitest_1.it)("uses brain4ai.app for brain product", () => {
+        ensureConfigDir("claude-code");
+        (0, index_js_1.setupClient)("claude-code", "brain", { homeDir: tmpHome });
+        const config = readConfig("claude-code");
+        const servers = config.mcpServers;
+        (0, vitest_1.expect)(servers["cerebro-externo"].url).toContain("brain4ai.app");
+    });
+    (0, vitest_1.it)("uses mentor4ai.app for mentor product", () => {
+        ensureConfigDir("claude-code");
+        (0, index_js_1.setupClient)("claude-code", "mentor", { homeDir: tmpHome });
+        const config = readConfig("claude-code");
+        const servers = config.mcpServers;
+        (0, vitest_1.expect)(servers["forge-mentor"].url).toContain("mentor4ai.app");
+    });
+});
+(0, vitest_1.describe)("detectInstalledClients", () => {
+    (0, vitest_1.it)("detects clients whose config directories exist", () => {
+        // Create dirs for gemini and claude-code only
+        ensureConfigDir("gemini");
+        ensureConfigDir("claude-code");
+        const detected = (0, index_js_1.detectInstalledClients)(tmpHome);
+        (0, vitest_1.expect)(detected).toContain("gemini");
+        (0, vitest_1.expect)(detected).toContain("claude-code");
+        (0, vitest_1.expect)(detected).not.toContain("codex");
+    });
+    (0, vitest_1.it)("returns empty array when no clients are installed", () => {
+        const detected = (0, index_js_1.detectInstalledClients)(tmpHome);
+        (0, vitest_1.expect)(detected).toHaveLength(0);
+    });
+    (0, vitest_1.it)("excludes claude-desktop on linux even if config dir exists", () => {
+        ensureConfigDir("gemini");
+        ensureConfigDir("claude-desktop");
+        withPlatform("linux", () => {
+            const detected = (0, index_js_1.detectInstalledClients)(tmpHome);
+            (0, vitest_1.expect)(detected).toContain("gemini");
+            (0, vitest_1.expect)(detected).not.toContain("claude-desktop");
+        });
+    });
+});
+(0, vitest_1.describe)("isClientSupportedOnPlatform", () => {
+    (0, vitest_1.it)("returns true for any-platform clients on every OS", () => {
+        (0, vitest_1.expect)((0, index_js_1.isClientSupportedOnPlatform)("gemini", "linux")).toBe(true);
+        (0, vitest_1.expect)((0, index_js_1.isClientSupportedOnPlatform)("gemini", "darwin")).toBe(true);
+        (0, vitest_1.expect)((0, index_js_1.isClientSupportedOnPlatform)("gemini", "win32")).toBe(true);
+        (0, vitest_1.expect)((0, index_js_1.isClientSupportedOnPlatform)("codex", "linux")).toBe(true);
+    });
+    (0, vitest_1.it)("restricts claude-desktop to darwin and win32", () => {
+        (0, vitest_1.expect)((0, index_js_1.isClientSupportedOnPlatform)("claude-desktop", "darwin")).toBe(true);
+        (0, vitest_1.expect)((0, index_js_1.isClientSupportedOnPlatform)("claude-desktop", "win32")).toBe(true);
+        (0, vitest_1.expect)((0, index_js_1.isClientSupportedOnPlatform)("claude-desktop", "linux")).toBe(false);
+        (0, vitest_1.expect)((0, index_js_1.isClientSupportedOnPlatform)("claude-desktop", "freebsd")).toBe(false);
+    });
+});
+(0, vitest_1.describe)("setupClient platform restrictions", () => {
+    (0, vitest_1.it)("throws when configuring claude-desktop on linux", () => {
+        withPlatform("linux", () => {
+            (0, vitest_1.expect)(() => (0, index_js_1.setupClient)("claude-desktop", "brain", { homeDir: tmpHome })).toThrow(/not supported on linux/);
+        });
+    });
+    (0, vitest_1.it)("succeeds when configuring claude-desktop on darwin", () => {
+        ensureConfigDir("claude-desktop");
+        withPlatform("darwin", () => {
+            const result = (0, index_js_1.setupClient)("claude-desktop", "brain", {
+                homeDir: tmpHome,
+            });
+            (0, vitest_1.expect)(result.action).toBe("created");
+        });
+    });
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@brain-mcps/setup",
+  "version": "0.1.0",
+  "description": "Configure AI assistant clients to connect to Brain4AI and Mentor4AI MCP servers",
+  "bin": {
+    "brain-mcp-setup": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "check-types": "tsc --noEmit",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "clean": "rimraf dist"
+  },
+  "keywords": [
+    "mcp",
+    "ai",
+    "setup",
+    "brain4ai",
+    "mentor4ai",
+    "claude",
+    "gemini",
+    "chatgpt"
+  ],
+  "author": "SirGrimorum",
+  "license": "MIT",
+  "dependencies": {
+    "smol-toml": "^1.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.9.2"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}