@luquimbo/bi-superpowers 3.0.0 → 3.1.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
     "url": "https://github.com/luquimbo"
   },
   "metadata": {
-    "description": "AI-powered skills for Power BI, Microsoft Fabric, and Excel development. 24 skills covering DAX, Power Query, data modeling, report design, governance, and more.",
-    "version": "3.0.0",
+    "description": "AI-powered skills for Power BI Desktop development. Works with Claude Code, GitHub Copilot, Codex, Gemini CLI, and Kilo Code.",
+    "version": "3.1.0",
     "repository": "https://github.com/luquimbo/bi-superpowers"
   },
   "plugins": [
     {
       "name": "bi-superpowers",
-      "description": "24 AI skills for Power BI, Fabric & Excel — DAX, Power Query, data modeling, star schema design, report design, governance, deployment, and more.",
+      "description": "2 AI skills + Power BI Modeling and Microsoft Learn MCP servers for local Power BI Desktop workflows across 5 AI agents.",
       "source": "./",
       "strict": false,
       "skills": [

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "bi-superpowers",
   "description": "Claude Code plugin for Power BI, Microsoft Fabric, and semantic model workflows powered by the official Microsoft MCP servers.",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "author": {
     "name": "Lucas Sanchez"
   }

package/.claude-plugin/skill-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "bi-superpowers",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "skillCount": 2,
   "skills": [
     {

package/.plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "spec": "open-plugin-spec@1",
   "name": "bi-superpowers",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Claude Code plugin for Power BI, Microsoft Fabric, and semantic model workflows powered by the official Microsoft MCP servers.",
   "author": {
     "name": "Lucas Sanchez"

package/README.md

@@ -89,6 +89,25 @@ super install --all --yes
 
 ---
 
+## Alternativas para instalar los MCPs
+
+`super install` escribe automáticamente los 2 MCPs en el config file de cada agente. Pero hay otras formas de instalar los mismos MCPs — cualquiera de estas funciona igual de bien:
+
+### Para Power BI Modeling MCP (local)
+
+- **Extensión de VS Code** — Microsoft publica "Power BI Modeling MCP" en el VS Code Marketplace. Si la instalás, VS Code + Copilot lo descubren automáticamente sin tocar archivos de config.
+- **Extensión de Cursor** — misma extensión, Cursor la detecta.
+- **Manual** — descargá el binario `.exe` y configurá `BI_SUPERPOWERS_POWERBI_MODELING_MCP_PATH` apuntando al ejecutable.
+
+### Para Microsoft Learn MCP (HTTP)
+
+- **MCP marketplace oficial de Anthropic** — en Claude Code se puede hacer `/plugin marketplace add anthropic/mcp-registry` y después `/plugin install microsoft-learn` (según disponibilidad).
+- **Agregarlo a mano** en el config file del agente con la URL `https://learn.microsoft.com/api/mcp`.
+
+Si ya instalaste los MCPs por alguno de estos caminos, no necesitás correr `super install` — o, si lo corrés, los configs se mergean sin conflicto (cada agente tiene merge por clave, no por overwrite).
+
+---
+
 ## Requisitos
 
 - **Node.js ≥ 18**

package/bin/commands/install.js

@@ -276,6 +276,44 @@ function performInstall(skillsSourceDir, skillDirs, selectedAgents, baseDir) {
   return { agentResults, copyFallbacks };
 }
 
+/**
+ * Configura los 2 MCP servers (powerbi-modeling + microsoft-learn)
+ * para cada agente seleccionado escribiendo el config file en el path
+ * y formato que cada agente espera.
+ *
+ * Los errores por agente no interrumpen el flujo: se recolectan en los
+ * resultados para mostrarlos al final y que el caller decida qué hacer
+ * con el exit code.
+ *
+ * @param {string[]} selectedAgents - IDs de agentes seleccionados
+ * @param {string} packageDir - Absolute path al paquete instalado
+ * @param {string} baseDir - Home directory del usuario (para display)
+ * @param {Object} chalk - chalk instance para colorear output
+ * @returns {Array<{agent: string, success: boolean, configPath?: string, error?: string}>}
+ */
+function configureMcpsForAgents(selectedAgents, packageDir, baseDir, chalk) {
+  console.log(
+    chalk.cyan('\n  Configurando MCP servers (Power BI Modeling + Microsoft Learn)...\n')
+  );
+
+  const results = [];
+  for (const agentId of selectedAgents) {
+    const agent = AGENTS[agentId];
+    try {
+      const configPath = writeMcpConfigForAgent(agentId, packageDir);
+      if (configPath) {
+        const relPath = configPath.replace(baseDir, '~');
+        console.log(chalk.green(`  ✓ ${relPath} — ${agent.name}`));
+        results.push({ agent: agent.name, configPath, success: true });
+      }
+    } catch (err) {
+      console.log(chalk.red(`  ✗ ${agent.name}: ${err.message}`));
+      results.push({ agent: agent.name, success: false, error: err.message });
+    }
+  }
+  return results;
+}
+
 /**
  * Handler principal del comando install.
  * @param {string[]} args - Argumentos CLI
@@ -386,33 +424,30 @@ async function installCommand(args, config) {
   }
 
   // Configurar MCPs para cada agente seleccionado
-  console.log(
-    chalk.cyan('\n  Configurando MCP servers (Power BI Modeling + Microsoft Learn)...\n')
-  );
-  const mcpResults = [];
-  for (const agentId of selectedAgents) {
-    const agent = AGENTS[agentId];
-    try {
-      const configPath = writeMcpConfigForAgent(agentId, packageDir);
-      if (configPath) {
-        const relPath = configPath.replace(baseDir, '~');
-        console.log(chalk.green(`  ✓ ${relPath} — ${agent.name}`));
-        mcpResults.push({ agent: agent.name, configPath, success: true });
-      }
-    } catch (err) {
-      console.log(chalk.yellow(`  ⚠ ${agent.name}: ${err.message}`));
-      mcpResults.push({ agent: agent.name, success: false, error: err.message });
-    }
-  }
+  const mcpResults = configureMcpsForAgents(selectedAgents, packageDir, baseDir, chalk);
 
   // Resumen
   const totalAgents = agentResults.length + (universalAgents.length > 0 ? 1 : 0);
   const mcpSuccess = mcpResults.filter((r) => r.success).length;
+  const mcpFailures = mcpResults.filter((r) => !r.success);
+  const hasFailures = mcpFailures.length > 0;
+
+  const successMsg = `Instalados ${skillDirs.length} skills + 2 MCPs para ${totalAgents} agentes`;
+  const failureMsg = `Instalados ${skillDirs.length} skills. MCPs: ${mcpSuccess}/${mcpResults.length} agentes ✓, ${mcpFailures.length} con errores.`;
+  const headerLine = hasFailures ? chalk.yellow.bold(failureMsg) : chalk.green.bold(successMsg);
+
+  const failureDetail = hasFailures
+    ? '\n' +
+      chalk.red('Agentes con errores en MCP:') +
+      '\n' +
+      mcpFailures.map((r) => chalk.red(`  ✗ ${r.agent}: ${r.error}`)).join('\n') +
+      '\n'
+    : '';
+
   console.log(
     boxen(
-      chalk.green.bold(
-        `Instalados ${skillDirs.length} skills + 2 MCPs para ${totalAgents} agentes`
-      ) +
+      headerLine +
+        failureDetail +
         '\n\n' +
         chalk.gray(`MCPs configurados en ${mcpSuccess}/${mcpResults.length} agentes.`) +
         '\n' +
@@ -427,10 +462,17 @@ async function installCommand(args, config) {
         padding: 1,
         margin: { top: 1 },
         borderStyle: 'round',
-        borderColor: 'green',
+        borderColor: hasFailures ? 'yellow' : 'green',
       }
     )
   );
+
+  if (hasFailures) {
+    // Non-zero exit so CI/scripts know something went wrong, but skills
+    // still got installed — we use exit code 2 to distinguish from total
+    // failure (exit 1).
+    process.exitCode = 2;
+  }
 }
 
 // Exports internos para testing

package/bin/commands/install.test.js

@@ -210,3 +210,80 @@ describe('install command - module exports', () => {
     assert.strictEqual(typeof installCommand.formatFsError, 'function');
   });
 });
+
+describe('install command - integration: --all --yes', () => {
+  let tempHome;
+  let tempPkg;
+  let origHome;
+
+  beforeEach(() => {
+    tempHome = fs.mkdtempSync(path.join(os.tmpdir(), 'bi-install-int-home-'));
+    tempPkg = fs.mkdtempSync(path.join(os.tmpdir(), 'bi-install-int-pkg-'));
+
+    // Minimal fake package layout: skills/<name>/SKILL.md + launcher file
+    const skillsDir = path.join(tempPkg, 'skills');
+    for (const skillName of ['project-kickoff', 'pbi-connect']) {
+      const dir = path.join(skillsDir, skillName);
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(
+        path.join(dir, 'SKILL.md'),
+        `---\nname: ${skillName}\ndescription: fake skill for test\n---\n# ${skillName}\n`
+      );
+    }
+    fs.mkdirSync(path.join(tempPkg, 'bin', 'mcp'), { recursive: true });
+    fs.writeFileSync(
+      path.join(tempPkg, 'bin', 'mcp', 'powerbi-modeling-launcher.js'),
+      '// fake launcher\n'
+    );
+
+    origHome = os.homedir;
+    os.homedir = () => tempHome;
+  });
+
+  afterEach(() => {
+    os.homedir = origHome;
+    fs.rmSync(tempHome, { recursive: true, force: true });
+    fs.rmSync(tempPkg, { recursive: true, force: true });
+  });
+
+  test('installs skills and writes MCP config for all 5 agents', async () => {
+    const origExitCode = process.exitCode;
+    try {
+      await installCommand(['--all', '--yes'], {
+        packageDir: tempPkg,
+        version: '9.9.9-test',
+      });
+    } finally {
+      // Reset exit code so subsequent tests aren't affected
+      process.exitCode = origExitCode;
+    }
+
+    // Skills installed at universal path
+    assert.ok(
+      fs.existsSync(path.join(tempHome, '.agents', 'skills', 'project-kickoff', 'SKILL.md'))
+    );
+    assert.ok(fs.existsSync(path.join(tempHome, '.agents', 'skills', 'pbi-connect', 'SKILL.md')));
+
+    // MCP configs written for all 5 agents
+    const expectedMcpFiles = [
+      path.join(tempHome, '.claude.json'),
+      path.join(tempHome, '.copilot', 'mcp-config.json'),
+      path.join(tempHome, '.codex', 'config.toml'),
+      path.join(tempHome, '.gemini', 'settings.json'),
+      path.join(tempHome, '.kilocode', 'mcp_settings.json'),
+    ];
+    for (const filePath of expectedMcpFiles) {
+      assert.ok(fs.existsSync(filePath), `expected MCP config at ${filePath}`);
+    }
+
+    // Claude Code config has both servers under mcpServers
+    const claudeConfig = JSON.parse(fs.readFileSync(path.join(tempHome, '.claude.json'), 'utf8'));
+    assert.ok(claudeConfig.mcpServers['powerbi-modeling']);
+    assert.ok(claudeConfig.mcpServers['microsoft-learn']);
+
+    // Codex TOML has both sections
+    const codexToml = fs.readFileSync(path.join(tempHome, '.codex', 'config.toml'), 'utf8');
+    assert.ok(codexToml.includes('[mcp_servers.powerbi-modeling]'));
+    assert.ok(codexToml.includes('[mcp_servers.microsoft-learn]'));
+  });
+});

package/bin/lib/generators/claude-plugin.js

@@ -193,7 +193,14 @@ async function generate(targetDir, skills, options = {}) {
     JSON.stringify(pluginManifest, null, 2) + '\n'
   );
 
-  // Generate marketplace.json with all skills listed and synced version
+  // Generate marketplace.json with all skills listed and synced version.
+  // The descriptions are derived from the actual skill count so they never
+  // drift out of sync with the real plugin contents.
+  const skillCount = skills.length;
+  const skillsPlural = skillCount === 1 ? 'skill' : 'skills';
+  const metadataDescription = `AI-powered ${skillsPlural} for Power BI Desktop development. Works with Claude Code, GitHub Copilot, Codex, Gemini CLI, and Kilo Code.`;
+  const pluginDescription = `${skillCount} AI ${skillsPlural} + Power BI Modeling and Microsoft Learn MCP servers for local Power BI Desktop workflows across 5 AI agents.`;
+
   const marketplaceManifest = {
     name: 'bi-superpowers',
     owner: {
@@ -201,16 +208,14 @@ async function generate(targetDir, skills, options = {}) {
       url: 'https://github.com/luquimbo',
     },
     metadata: {
-      description:
-        'AI-powered skills for Power BI, Microsoft Fabric, and Excel development. 24 skills covering DAX, Power Query, data modeling, report design, governance, and more.',
+      description: metadataDescription,
       version,
       repository: 'https://github.com/luquimbo/bi-superpowers',
     },
     plugins: [
       {
         name: 'bi-superpowers',
-        description:
-          '24 AI skills for Power BI, Fabric & Excel — DAX, Power Query, data modeling, star schema design, report design, governance, deployment, and more.',
+        description: pluginDescription,
         source: './',
         strict: false,
         skills: skills.map((skill) => `./skills/${skill.name}`).sort(),

package/bin/lib/mcp-config.js

@@ -52,10 +52,28 @@ function readJsonSafe(filePath) {
   }
 }
 
+/**
+ * Reject symlink attacks before writing to a file. We use lstatSync so
+ * we detect the link itself (not what it points to). If a user home has
+ * `~/.claude.json` pointing to `/etc/passwd`, we refuse to write.
+ * @throws {Error} if filePath exists and is a symbolic link
+ */
+function assertNotSymlink(filePath) {
+  if (!fs.existsSync(filePath)) return;
+  if (fs.lstatSync(filePath).isSymbolicLink()) {
+    throw new Error(
+      `Refusing to write MCP config: ${filePath} is a symbolic link. ` +
+        'Remove the symlink and re-run the install.'
+    );
+  }
+}
+
 /**
  * Write a JSON file, creating parent dirs if needed.
+ * Refuses to overwrite symbolic links for safety.
  */
 function writeJson(filePath, data) {
+  assertNotSymlink(filePath);
   const dir = path.dirname(filePath);
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
@@ -65,56 +83,141 @@ function writeJson(filePath, data) {
 
 /**
  * Escape a string for use inside TOML double-quoted strings.
+ * Covers backslash, quote, and the control characters that TOML spec
+ * requires escaping in basic strings: \b \t \n \f \r
+ *
+ * Note: `\b` in a JS regex is word-boundary, NOT backspace (0x08).
+ * We use \x08 explicitly to match the backspace character itself.
  */
 function tomlEscape(str) {
-  return String(str).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  return (
+    String(str)
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"')
+      // eslint-disable-next-line no-control-regex
+      .replace(/\x08/g, '\\b')
+      .replace(/\t/g, '\\t')
+      .replace(/\n/g, '\\n')
+      .replace(/\f/g, '\\f')
+      .replace(/\r/g, '\\r')
+  );
 }
 
-// ============================================
-// CLAUDE CODE
-// ============================================
-// Writes ~/.claude.json, adding to `mcpServers`. Preserves other user-level
-// config in that file (projects, settings, etc.).
-function writeClaudeCodeConfig(packageDir) {
-  const configPath = path.join(os.homedir(), '.claude.json');
-  const existing = readJsonSafe(configPath) || {};
-  const mcpServers = { ...(existing.mcpServers || {}) };
-
-  mcpServers[MODELING_SERVER_NAME] = {
-    command: 'node',
-    args: [getLauncherAbsolutePath(packageDir)],
-  };
-  mcpServers[LEARN_SERVER_NAME] = {
-    type: 'http',
-    url: MICROSOFT_LEARN_URL,
-  };
-
-  writeJson(configPath, { ...existing, mcpServers });
-  return configPath;
+/**
+ * Escape a string for safe use inside a regex pattern (as a literal).
+ */
+function escapeRegex(str) {
+  return String(str).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
 // ============================================
-// GITHUB COPILOT CLI
+// JSON AGENT CONFIGURATIONS
 // ============================================
-// Writes ~/.copilot/mcp-config.json. Copilot uses `servers` (NOT mcpServers)
-// and each server has an explicit `type` field.
-function writeCopilotConfig(packageDir) {
-  const configPath = path.join(os.homedir(), '.copilot', 'mcp-config.json');
-  const existing = readJsonSafe(configPath) || {};
-  const servers = { ...(existing.servers || {}) };
-
-  servers[MODELING_SERVER_NAME] = {
-    type: 'stdio',
+// The 4 JSON-based agents (Claude Code, GitHub Copilot, Gemini CLI,
+// Kilo Code) all follow the same pattern: read existing JSON, merge
+// our 2 servers into a wrapper key, write back. Each agent differs
+// only in:
+//  - The config file path
+//  - The wrapper key (`mcpServers` vs `servers`)
+//  - Whether the stdio entry needs an explicit `type` field
+//  - The HTTP URL field name (`url` vs `httpUrl`)
+//
+// We describe each agent in a single table and build the writer functions
+// from it so adding a new JSON agent is a one-line change.
+
+const JSON_AGENT_CONFIGS = {
+  'claude-code': {
+    // Claude Code user-scope MCP config lives in ~/.claude.json under
+    // mcpServers. stdio entries omit `type`, HTTP entries include it.
+    configPath: () => path.join(os.homedir(), '.claude.json'),
+    wrapperKey: 'mcpServers',
+    stdioIncludesType: false,
+    httpIncludesType: true,
+    httpField: 'url',
+  },
+  'github-copilot': {
+    // Copilot CLI uses `servers` (NOT mcpServers) and every server needs
+    // an explicit `type` field.
+    configPath: () => path.join(os.homedir(), '.copilot', 'mcp-config.json'),
+    wrapperKey: 'servers',
+    stdioIncludesType: true,
+    httpIncludesType: true,
+    httpField: 'url',
+  },
+  'gemini-cli': {
+    // Gemini uses `httpUrl` (NOT `url`) for HTTP transports and omits
+    // `type` — it's inferred from which key is present.
+    configPath: () => path.join(os.homedir(), '.gemini', 'settings.json'),
+    wrapperKey: 'mcpServers',
+    stdioIncludesType: false,
+    httpIncludesType: false,
+    httpField: 'httpUrl',
+  },
+  kilo: {
+    // Kilo uses the canonical `mcpServers` with `url` for HTTP.
+    configPath: () => path.join(os.homedir(), '.kilocode', 'mcp_settings.json'),
+    wrapperKey: 'mcpServers',
+    stdioIncludesType: false,
+    httpIncludesType: false,
+    httpField: 'url',
+  },
+};
+
+/**
+ * Build the two-server JSON payload for a JSON-format agent.
+ * Each agent differs in whether it wants `type` fields and which key
+ * holds the HTTP URL (`url` vs `httpUrl`).
+ *
+ * @param {Object} agentConfig - Descriptor from JSON_AGENT_CONFIGS
+ * @param {string} packageDir - Absolute path to the installed package
+ * @returns {Object} Map of server name → server config
+ */
+function buildJsonServers(agentConfig, packageDir) {
+  // Modeling (stdio local launcher)
+  const modelingEntry = {
     command: 'node',
     args: [getLauncherAbsolutePath(packageDir)],
   };
-  servers[LEARN_SERVER_NAME] = {
-    type: 'http',
-    url: MICROSOFT_LEARN_URL,
+  if (agentConfig.stdioIncludesType) {
+    // Put type first for readability
+    const { command, args } = modelingEntry;
+    Object.keys(modelingEntry).forEach((k) => delete modelingEntry[k]);
+    modelingEntry.type = 'stdio';
+    modelingEntry.command = command;
+    modelingEntry.args = args;
+  }
+
+  // Microsoft Learn (HTTP)
+  const learnEntry = {};
+  if (agentConfig.httpIncludesType) {
+    learnEntry.type = 'http';
+  }
+  learnEntry[agentConfig.httpField] = MICROSOFT_LEARN_URL;
+
+  return {
+    [MODELING_SERVER_NAME]: modelingEntry,
+    [LEARN_SERVER_NAME]: learnEntry,
   };
+}
 
-  writeJson(configPath, { ...existing, servers });
-  return configPath;
+/**
+ * Create a writer function for a JSON-format agent.
+ * The returned function reads the existing config (if any), merges in
+ * our 2 servers, and writes back, preserving all other fields.
+ */
+function makeJsonWriter(agentId) {
+  const agentConfig = JSON_AGENT_CONFIGS[agentId];
+  return function jsonWriter(packageDir) {
+    const configPath = agentConfig.configPath();
+    const existing = readJsonSafe(configPath) || {};
+    const wrapperKey = agentConfig.wrapperKey;
+
+    const newServers = buildJsonServers(agentConfig, packageDir);
+    const mergedServers = { ...(existing[wrapperKey] || {}), ...newServers };
+
+    writeJson(configPath, { ...existing, [wrapperKey]: mergedServers });
+    return configPath;
+  };
 }
 
 // ============================================
@@ -125,6 +228,7 @@ function writeCopilotConfig(packageDir) {
 // appending the fresh ones.
 function writeCodexConfig(packageDir) {
   const configPath = path.join(os.homedir(), '.codex', 'config.toml');
+  assertNotSymlink(configPath);
   const launcher = getLauncherAbsolutePath(packageDir);
 
   let existing = '';
@@ -134,9 +238,11 @@ function writeCodexConfig(packageDir) {
 
   // Remove any previous bi-superpowers MCP sections so re-running install
   // doesn't duplicate them. Strips each section from its header to the
-  // next [ header or EOF.
+  // next [ header or EOF. Server names are escaped for regex safety even
+  // though current values are literal — defensive against future renames.
+  const namePattern = [MODELING_SERVER_NAME, LEARN_SERVER_NAME].map(escapeRegex).join('|');
   const stripPattern = new RegExp(
-    `\\n?\\[mcp_servers\\.(${MODELING_SERVER_NAME}|${LEARN_SERVER_NAME})\\][\\s\\S]*?(?=\\n\\[|$)`,
+    `\\n?\\[mcp_servers\\.(${namePattern})\\][\\s\\S]*?(?=\\n\\[|$)`,
     'g'
   );
   existing = existing.replace(stripPattern, '');
@@ -158,59 +264,17 @@ function writeCodexConfig(packageDir) {
   return configPath;
 }
 
-// ============================================
-// GEMINI CLI
-// ============================================
-// Writes ~/.gemini/settings.json. Gemini uses `mcpServers` and `httpUrl`
-// (not `url`) for HTTP transports.
-function writeGeminiConfig(packageDir) {
-  const configPath = path.join(os.homedir(), '.gemini', 'settings.json');
-  const existing = readJsonSafe(configPath) || {};
-  const mcpServers = { ...(existing.mcpServers || {}) };
-
-  mcpServers[MODELING_SERVER_NAME] = {
-    command: 'node',
-    args: [getLauncherAbsolutePath(packageDir)],
-  };
-  mcpServers[LEARN_SERVER_NAME] = {
-    httpUrl: MICROSOFT_LEARN_URL,
-  };
-
-  writeJson(configPath, { ...existing, mcpServers });
-  return configPath;
-}
-
-// ============================================
-// KILO CODE
-// ============================================
-// Writes ~/.kilocode/mcp_settings.json. Kilo uses `mcpServers` and `url`
-// for HTTP transports.
-function writeKiloConfig(packageDir) {
-  const configPath = path.join(os.homedir(), '.kilocode', 'mcp_settings.json');
-  const existing = readJsonSafe(configPath) || {};
-  const mcpServers = { ...(existing.mcpServers || {}) };
-
-  mcpServers[MODELING_SERVER_NAME] = {
-    command: 'node',
-    args: [getLauncherAbsolutePath(packageDir)],
-  };
-  mcpServers[LEARN_SERVER_NAME] = {
-    url: MICROSOFT_LEARN_URL,
-  };
-
-  writeJson(configPath, { ...existing, mcpServers });
-  return configPath;
-}
-
 /**
  * Registry mapping agent IDs to their MCP config writers.
+ * JSON agents are generated from JSON_AGENT_CONFIGS via makeJsonWriter;
+ * Codex is the only TOML-based agent and has its own writer.
  */
 const MCP_WRITERS = {
-  'claude-code': writeClaudeCodeConfig,
-  'github-copilot': writeCopilotConfig,
+  'claude-code': makeJsonWriter('claude-code'),
+  'github-copilot': makeJsonWriter('github-copilot'),
   codex: writeCodexConfig,
-  'gemini-cli': writeGeminiConfig,
-  kilo: writeKiloConfig,
+  'gemini-cli': makeJsonWriter('gemini-cli'),
+  kilo: makeJsonWriter('kilo'),
 };
 
 /**
@@ -238,5 +302,7 @@ module.exports = {
   readJsonSafe,
   writeJson,
   tomlEscape,
+  escapeRegex,
+  assertNotSymlink,
   getLauncherAbsolutePath,
 };

package/bin/lib/mcp-config.test.js

@@ -14,6 +14,8 @@ const {
   LEARN_SERVER_NAME,
   MICROSOFT_LEARN_URL,
   tomlEscape,
+  escapeRegex,
+  assertNotSymlink,
   getLauncherAbsolutePath,
 } = require('./mcp-config');
 
@@ -29,6 +31,55 @@ describe('mcp-config helpers', () => {
     assert.strictEqual(tomlEscape('C:\\path\\to\\file'), 'C:\\\\path\\\\to\\\\file');
     assert.strictEqual(tomlEscape('say "hello"'), 'say \\"hello\\"');
   });
+
+  test('tomlEscape escapes TOML control characters', () => {
+    assert.strictEqual(tomlEscape('line1\nline2'), 'line1\\nline2');
+    assert.strictEqual(tomlEscape('tab\there'), 'tab\\there');
+    assert.strictEqual(tomlEscape('cr\rhere'), 'cr\\rhere');
+    // \x08 = backspace, \f = form feed
+    assert.strictEqual(tomlEscape('\x08\f'), '\\b\\f');
+  });
+
+  test('escapeRegex escapes all regex metacharacters', () => {
+    assert.strictEqual(escapeRegex('plain'), 'plain');
+    assert.strictEqual(escapeRegex('a.b'), 'a\\.b');
+    assert.strictEqual(escapeRegex('a[b]c'), 'a\\[b\\]c');
+    assert.strictEqual(escapeRegex('a+b*c?'), 'a\\+b\\*c\\?');
+    assert.strictEqual(escapeRegex('(hello)'), '\\(hello\\)');
+  });
+});
+
+describe('assertNotSymlink', () => {
+  let tempDir;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bi-mcp-symlink-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test('allows non-existent paths', () => {
+    assert.doesNotThrow(() => {
+      assertNotSymlink(path.join(tempDir, 'nope.json'));
+    });
+  });
+
+  test('allows regular files', () => {
+    const file = path.join(tempDir, 'regular.json');
+    fs.writeFileSync(file, '{}');
+    assert.doesNotThrow(() => assertNotSymlink(file));
+  });
+
+  test('throws on symbolic links', () => {
+    const target = path.join(tempDir, 'target.json');
+    const link = path.join(tempDir, 'link.json');
+    fs.writeFileSync(target, '{}');
+    fs.symlinkSync(target, link);
+
+    assert.throws(() => assertNotSymlink(link), /is a symbolic link/);
+  });
 });
 
 describe('MCP_WRITERS registry', () => {
@@ -127,6 +178,81 @@ describe('MCP writers — JSON agents', () => {
     assert.ok(config.mcpServers[MODELING_SERVER_NAME]);
     assert.ok(config.mcpServers[LEARN_SERVER_NAME]);
   });
+
+  // Re-install de-duplication for JSON writers — each should replace its
+  // own entries cleanly without duplicating them on repeated runs.
+  for (const agentId of ['claude-code', 'github-copilot', 'gemini-cli', 'kilo']) {
+    test(`${agentId} re-install replaces entries without duplicating`, () => {
+      // First install
+      MCP_WRITERS[agentId](fakePkgDir);
+      // Second install (same args)
+      const configPath = MCP_WRITERS[agentId](fakePkgDir);
+
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      const serversKey = agentId === 'github-copilot' ? 'servers' : 'mcpServers';
+      const servers = config[serversKey];
+
+      // Our 2 servers should each appear exactly once (via object keys)
+      assert.ok(servers[MODELING_SERVER_NAME], 'modeling server missing after re-install');
+      assert.ok(servers[LEARN_SERVER_NAME], 'learn server missing after re-install');
+
+      // And no stray duplicates of our keys
+      const ourKeys = Object.keys(servers).filter(
+        (k) => k === MODELING_SERVER_NAME || k === LEARN_SERVER_NAME
+      );
+      assert.strictEqual(ourKeys.length, 2, `expected 2 of our keys, found ${ourKeys.length}`);
+    });
+  }
+
+  // Cross-agent sanity check: verifies each JSON agent writes the HTTP
+  // URL under the correct key per its spec. Catches copy-paste errors
+  // where someone might accidentally use `url` for Gemini (which expects
+  // `httpUrl`) or vice versa.
+  test('each JSON agent uses the correct HTTP field name', () => {
+    const expectations = {
+      'claude-code': { key: 'url', wrapperKey: 'mcpServers' },
+      'github-copilot': { key: 'url', wrapperKey: 'servers' },
+      'gemini-cli': { key: 'httpUrl', wrapperKey: 'mcpServers' },
+      kilo: { key: 'url', wrapperKey: 'mcpServers' },
+    };
+
+    for (const [agentId, expected] of Object.entries(expectations)) {
+      // Reset home for each agent so configs don't leak between writes.
+      fs.rmSync(tempHome, { recursive: true, force: true });
+      fs.mkdirSync(tempHome, { recursive: true });
+
+      const configPath = MCP_WRITERS[agentId](fakePkgDir);
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      const learnEntry = config[expected.wrapperKey][LEARN_SERVER_NAME];
+
+      assert.strictEqual(
+        learnEntry[expected.key],
+        MICROSOFT_LEARN_URL,
+        `${agentId} should use "${expected.key}" for HTTP URL`
+      );
+
+      // And it should NOT use the wrong key (defensive check)
+      const wrongKey = expected.key === 'url' ? 'httpUrl' : 'url';
+      assert.strictEqual(
+        learnEntry[wrongKey],
+        undefined,
+        `${agentId} should NOT have "${wrongKey}"`
+      );
+    }
+  });
+
+  test('writeJson refuses to overwrite symlinked target', () => {
+    const realFile = path.join(tempHome, 'real-claude.json');
+    const linkFile = path.join(tempHome, '.claude.json');
+    fs.writeFileSync(realFile, '{"mcpServers":{}}');
+    fs.symlinkSync(realFile, linkFile);
+
+    assert.throws(() => MCP_WRITERS['claude-code'](fakePkgDir), /symbolic link/);
+
+    // The real file content must not have been touched.
+    const content = JSON.parse(fs.readFileSync(realFile, 'utf8'));
+    assert.deepStrictEqual(content, { mcpServers: {} });
+  });
 });
 
 describe('codex writer — TOML', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luquimbo/bi-superpowers",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Plugin-first Claude Code toolkit for Power BI, Microsoft Fabric, and Excel workflows powered by official Microsoft MCP servers.",
   "main": "bin/cli.js",
   "bin": {

package/skills/pbi-connect/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "pbi-connect"
 description: "Use when the user asks about Power BI MCP Connection Skill, especially phrases like \"connect Power BI\", \"modeling mcp\", \"Power BI Desktop\", \"conectar Power BI\", \"can't connect to Power BI\"."
-version: "3.0.0"
+version: "3.1.0"
 ---
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/pbi-connect.md instead. -->

package/skills/project-kickoff/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "project-kickoff"
 description: "Project Kickoff Skill: Project analysis and planning."
-version: "3.0.0"
+version: "3.1.0"
 ---
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/project-kickoff.md instead. -->