bi-superpowers 1.0.0

package/bin/lib/microsoft-mcp.js

@@ -0,0 +1,206 @@
+/**
+ * Official Microsoft MCP Configuration Helpers
+ * ============================================
+ *
+ * Single source of truth for the MCP servers that bi-superpowers ships.
+ * Currently ships 2 servers, both from Microsoft:
+ *
+ * - powerbi-modeling-mcp: local stdio launcher that talks to Power BI Desktop
+ *   via XMLA on localhost. Requires Power BI Desktop running with a model open.
+ * - microsoft-learn: HTTP MCP that pipes Microsoft Learn docs into the agent.
+ *
+ * @module lib/microsoft-mcp
+ */
+
+const path = require('path');
+
+const MICROSOFT_LEARN_URL = 'https://learn.microsoft.com/api/mcp';
+const MODELING_SERVER_NAME = 'powerbi-modeling-mcp';
+const LEARN_SERVER_NAME = 'microsoft-learn';
+const ABSOLUTE_LAUNCHER_MODE = 'absolute';
+const PLUGIN_ROOT_LAUNCHER_MODE = 'plugin-root';
+
+/**
+ * Resolve the launcher script path used to start the official Modeling MCP.
+ *
+ * @param {Object} options - Path resolution options
+ * @param {string} [options.packageDir] - Installed package directory
+ * @param {string} [options.launcherMode] - `absolute` or `plugin-root`
+ * @returns {string} Launcher path expression
+ */
+function resolveModelingLauncherPath(options = {}) {
+  const { packageDir, launcherMode = ABSOLUTE_LAUNCHER_MODE } = options;
+
+  if (launcherMode === PLUGIN_ROOT_LAUNCHER_MODE) {
+    return '${CLAUDE_PLUGIN_ROOT}/bin/mcp/powerbi-modeling-launcher.js';
+  }
+
+  return path.join(packageDir || process.cwd(), 'bin', 'mcp', 'powerbi-modeling-launcher.js');
+}
+
+/**
+ * Create the canonical flat MCP config used by Claude Code plugins.
+ *
+ * @param {Object} options - Generation options
+ * @param {string} [options.packageDir] - Installed package directory
+ * @param {string} [options.launcherMode] - `absolute` or `plugin-root`
+ * @returns {Object} Flat MCP server object
+ */
+function createPluginMcpConfig(options = {}) {
+  const launcherPath = resolveModelingLauncherPath(options);
+
+  return {
+    [MODELING_SERVER_NAME]: {
+      type: 'stdio',
+      command: 'node',
+      args: [launcherPath],
+    },
+    [LEARN_SERVER_NAME]: {
+      type: 'http',
+      url: MICROSOFT_LEARN_URL,
+    },
+  };
+}
+
+/**
+ * Convert the canonical flat config to the target client format.
+ *
+ * @param {string} format - Target format identifier
+ * @param {Object} options - Generation options
+ * @returns {Object} Config object in the target format
+ */
+function createMcpConfigForFormat(format, options = {}) {
+  const flatConfig = createPluginMcpConfig(options);
+
+  switch (format) {
+    case 'plugin':
+    case 'cursor':
+      return flatConfig;
+
+    case 'claude':
+    case 'vscode':
+      return { mcpServers: flatConfig };
+
+    case 'kilo':
+      return {
+        mcp: Object.fromEntries(
+          Object.entries(flatConfig).map(([name, config]) => {
+            if (config.type === 'http') {
+              return [
+                name,
+                {
+                  type: 'remote',
+                  url: config.url,
+                  enabled: true,
+                  timeout: 15000,
+                },
+              ];
+            }
+
+            return [
+              name,
+              {
+                type: 'local',
+                command: [config.command, ...(config.args || [])],
+                enabled: true,
+                timeout: 10000,
+              },
+            ];
+          })
+        ),
+      };
+
+    case 'opencode':
+      return {
+        mcp: Object.fromEntries(
+          Object.entries(flatConfig).map(([name, config]) => {
+            if (config.type === 'http') {
+              return [name, config];
+            }
+
+            const quotedArgs = (config.args || []).map((arg) =>
+              /\s/.test(arg) ? JSON.stringify(arg) : arg
+            );
+
+            return [
+              name,
+              {
+                type: 'local',
+                command: [config.command, ...quotedArgs].join(' '),
+              },
+            ];
+          })
+        ),
+      };
+
+    default:
+      return { mcpServers: flatConfig };
+  }
+}
+
+/**
+ * Merge a generated MCP config into an existing config object.
+ *
+ * @param {Object} existingConfig - Existing parsed config
+ * @param {Object} newConfig - Generated MCP config
+ * @param {string} format - Target format identifier
+ * @returns {Object} Merged config
+ */
+function mergeMcpConfig(existingConfig, newConfig, format) {
+  const existing = existingConfig || {};
+
+  switch (format) {
+    case 'plugin':
+    case 'cursor':
+      return {
+        ...existing,
+        ...newConfig,
+      };
+
+    case 'claude':
+    case 'vscode':
+      return {
+        ...existing,
+        mcpServers: {
+          ...(existing.mcpServers || {}),
+          ...(newConfig.mcpServers || {}),
+        },
+      };
+
+    case 'kilo':
+      return {
+        ...existing,
+        mcp: {
+          ...(existing.mcp || {}),
+          ...(newConfig.mcp || {}),
+        },
+      };
+
+    case 'opencode':
+      return {
+        ...existing,
+        mcp: {
+          ...(existing.mcp || {}),
+          ...(newConfig.mcp || {}),
+        },
+      };
+
+    default:
+      return {
+        ...existing,
+        ...newConfig,
+      };
+  }
+}
+
+module.exports = {
+  ABSOLUTE_LAUNCHER_MODE,
+  PLUGIN_ROOT_LAUNCHER_MODE,
+  MICROSOFT_LEARN_URL,
+  MODELING_SERVER_NAME,
+  LEARN_SERVER_NAME,
+  resolveModelingLauncherPath,
+  createPluginMcpConfig,
+  createMcpConfigForFormat,
+  mergeMcpConfig,
+};

package/bin/lib/powerbi-mcp-session.js

@@ -0,0 +1,140 @@
+/**
+ * Power BI Modeling MCP Session
+ * =============================
+ *
+ * Tiny JSON-RPC client for the official Microsoft Power BI Modeling MCP
+ * executable. The session is stdio-based and speaks newline-delimited JSON.
+ *
+ * @module lib/powerbi-mcp-session
+ */
+
+const { spawn } = require('child_process');
+
+const PROTOCOL_VERSION = '2024-11-05';
+
+function createPowerBiMcpSession(exePath, spawnFn = spawn) {
+  if (!exePath) {
+    throw new Error('A Power BI Modeling MCP executable path is required.');
+  }
+
+  const child = spawnFn(exePath, ['--readwrite', '--skip-confirmation'], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  const pending = new Map();
+  let nextId = 1;
+  let closed = false;
+  let stdoutBuffer = '';
+
+  function rejectPending(error) {
+    for (const { reject } of pending.values()) {
+      reject(error);
+    }
+    pending.clear();
+  }
+
+  function send(method, params) {
+    if (closed) {
+      return Promise.reject(new Error('MCP session is closed.'));
+    }
+
+    const id = nextId++;
+    const payload = JSON.stringify({ jsonrpc: '2.0', id, method, params });
+
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject });
+      child.stdin.write(`${payload}\n`, (error) => {
+        if (error) {
+          pending.delete(id);
+          reject(error);
+        }
+      });
+    });
+  }
+
+  child.stdout.on('data', (chunk) => {
+    stdoutBuffer += chunk.toString('utf8');
+
+    let newlineIndex;
+    while ((newlineIndex = stdoutBuffer.indexOf('\n')) >= 0) {
+      const rawLine = stdoutBuffer.slice(0, newlineIndex).trim();
+      stdoutBuffer = stdoutBuffer.slice(newlineIndex + 1);
+
+      if (!rawLine || !rawLine.startsWith('{')) {
+        continue;
+      }
+
+      let message;
+      try {
+        message = JSON.parse(rawLine);
+      } catch (_) {
+        continue;
+      }
+
+      if (Object.prototype.hasOwnProperty.call(message, 'id') && pending.has(message.id)) {
+        const request = pending.get(message.id);
+        pending.delete(message.id);
+
+        if (message.error) {
+          request.reject(new Error(JSON.stringify(message.error)));
+        } else {
+          request.resolve(message.result);
+        }
+      }
+    }
+  });
+
+  child.stderr.on('data', (chunk) => {
+    process.stderr.write(chunk);
+  });
+
+  child.on('error', (error) => {
+    rejectPending(error);
+  });
+
+  child.on('close', (code, signal) => {
+    closed = true;
+    if (pending.size > 0) {
+      rejectPending(
+        new Error(
+          `Power BI Modeling MCP session ended unexpectedly (${code ?? 'unknown'}${signal ? `, ${signal}` : ''}).`
+        )
+      );
+    }
+  });
+
+  return {
+    async initialize(clientInfo = { name: 'codex', version: '1.0.0' }) {
+      await send('initialize', {
+        protocolVersion: PROTOCOL_VERSION,
+        clientInfo,
+        capabilities: {},
+      });
+
+      child.stdin.write(
+        JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} }) + '\n'
+      );
+    },
+    callTool(name, request) {
+      return send('tools/call', {
+        name,
+        arguments: request,
+      });
+    },
+    listTools() {
+      return send('tools/list', {});
+    },
+    close() {
+      if (closed) {
+        return;
+      }
+
+      closed = true;
+      child.kill();
+    },
+  };
+}
+
+module.exports = {
+  createPowerBiMcpSession,
+};

package/bin/lib/skills.js

@@ -0,0 +1,164 @@
+/**
+ * Skill Loading Utilities
+ * =======================
+ *
+ * Centralizes how BI Agent Superpowers loads skill source files from
+ * the installed npm package. Everything ships with the package.
+ *
+ * Two skill layouts are supported:
+ *
+ *   1. Flat markdown:  src/content/skills/{name}.md
+ *      Simple skills that fit in a single file. No references/scripts.
+ *
+ *   2. Folder-based:   src/content/skills/{name}/SKILL.md
+ *                      src/content/skills/{name}/references/*.md
+ *                      src/content/skills/{name}/scripts/*
+ *      Follows Anthropic's skills convention — SKILL.md is the thin
+ *      entrypoint, `references/` holds on-demand detail that the agent
+ *      can load when it needs more schema/examples, and `scripts/` holds
+ *      deterministic helpers the agent can shell out to.
+ *
+ * @module lib/skills
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Load a single flat markdown skill file.
+ * @param {string} filePath - Absolute path to the .md file
+ * @returns {{name: string, path: string, content: string, bundleDir: null}|null}
+ */
+function loadFlatSkill(filePath) {
+  try {
+    return {
+      name: path.basename(filePath).replace(/\.md$/, ''),
+      path: filePath,
+      content: fs.readFileSync(filePath, 'utf8'),
+      bundleDir: null,
+    };
+  } catch (err) {
+    console.warn(`⚠ Could not read skill ${filePath}: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Load a folder-based skill. Expects `{folder}/SKILL.md` to exist.
+ * Returns null if the folder does not contain a SKILL.md.
+ *
+ * @param {string} folderPath - Absolute path to the skill folder
+ * @returns {{name: string, path: string, content: string, bundleDir: string}|null}
+ */
+function loadFolderSkill(folderPath) {
+  const skillMd = path.join(folderPath, 'SKILL.md');
+  if (!fs.existsSync(skillMd)) {
+    return null;
+  }
+  try {
+    return {
+      name: path.basename(folderPath),
+      path: skillMd,
+      content: fs.readFileSync(skillMd, 'utf8'),
+      bundleDir: folderPath,
+    };
+  } catch (err) {
+    console.warn(`⚠ Could not read skill ${skillMd}: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Read all skills from a directory. Each entry can be either a flat
+ * .md file OR a subfolder containing a SKILL.md.
+ *
+ * Robust against filesystem failures:
+ * - Non-existent directory → []
+ * - Unreadable directory → warning + []
+ * - Individual unreadable entry → warning + skip
+ *
+ * @param {string} directory - Directory containing skill sources
+ * @returns {Array<{name: string, path: string, content: string, bundleDir: string|null}>}
+ */
+function readSkillDirectory(directory) {
+  if (!directory || !fs.existsSync(directory)) {
+    return [];
+  }
+
+  let entries;
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch (err) {
+    console.warn(`⚠ Could not read skills directory ${directory}: ${err.message}`);
+    return [];
+  }
+
+  const skills = [];
+
+  // Sort by name for deterministic output across platforms.
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+
+  for (const entry of entries) {
+    const entryPath = path.join(directory, entry.name);
+
+    if (entry.isFile() && entry.name.endsWith('.md')) {
+      const skill = loadFlatSkill(entryPath);
+      if (skill) skills.push(skill);
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      const skill = loadFolderSkill(entryPath);
+      if (skill) skills.push(skill);
+      continue;
+    }
+
+    // Ignore other entry types (symlinks to nowhere, non-md files).
+  }
+
+  return skills;
+}
+
+/**
+ * Load skills from the package source directory.
+ *
+ * @param {Object} options - Resolution options
+ * @param {string} options.packageDir - Package installation directory
+ * @returns {Array<{name: string, path: string, content: string, bundleDir: string|null}>}
+ */
+function loadSkills(options = {}) {
+  const { packageDir } = options;
+  if (!packageDir) {
+    return [];
+  }
+  const skillsDir = path.join(packageDir, 'src', 'content', 'skills');
+  return readSkillDirectory(skillsDir);
+}
+
+/**
+ * Normalize any user-facing skill identifier into its canonical name.
+ *
+ * Accepts `dax`, `dax.md`, `folder-skill`, `folder-skill/SKILL.md`,
+ * or `folder-skill\SKILL.md` (Windows separator) and returns the
+ * canonical skill name used as the key in readSkillDirectory's
+ * output map (`dax`, `folder-skill`).
+ *
+ * Uses a single alternation regex so the longer suffix `/SKILL.md`
+ * is tried BEFORE the bare `.md`. Earlier callers chained two
+ * `.replace()` calls and stripped `.md` first, which meant the
+ * `/SKILL.md` alternative never matched — `folder-skill/SKILL.md`
+ * came out as `folder-skill/SKILL` and the lookup failed.
+ *
+ * @param {string} input - User-supplied skill identifier
+ * @returns {string} Canonical skill name
+ */
+function normalizeSkillName(input) {
+  if (typeof input !== 'string') return input;
+  return input.replace(/([/\\]SKILL\.md|\.md)$/, '');
+}
+
+module.exports = {
+  readSkillDirectory,
+  loadSkills,
+  normalizeSkillName,
+};