blackops-onboard 0.3.0 → 0.6.0

package/README.md

@@ -8,12 +8,25 @@ Agent-first onboarding for [BlackOps Center](https://blackopscenter.com).
 npx blackops-onboard
 ```
 
-Then open Claude Code and say:
+Then open your MCP-capable agent (Claude Code, Claude Desktop, Cursor, Cline, …) and say:
 
 > Help me onboard to BlackOps Center and publish my first piece of content.
 
 That's it. The agent walks you through account creation, brand voice, social OAuth (X / Threads / LinkedIn), publishing your first four pieces of content, and getting a magic link to your dashboard.
 
+## Supported MCP clients
+
+The CLI auto-detects and writes the BlackOps MCP server entry to any of these configs it finds:
+
+| Client | Config path |
+|---|---|
+| Claude Code | `~/.claude/settings.json` |
+| Claude Desktop | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\Claude\claude_desktop_config.json` · Linux: `~/.config/Claude/claude_desktop_config.json` |
+| Cursor | `~/.cursor/mcp.json` |
+| Cline (VS Code) | `~/.cline/mcp_settings.json` |
+
+For any other MCP client, the CLI also prints a universal JSON snippet you can paste into that client's `mcpServers` config.
+
 ## Re-running
 
 Re-running detects an existing config at `~/.blackops/config.json`. You can keep the existing token (and re-paste the saved prompt) or overwrite to start fresh.

package/bin/onboard.mjs

@@ -4,8 +4,9 @@
 // What this does:
 //   1. POSTs to https://blackopscenter.com/api/install to mint an onboarding token.
 //   2. Writes ~/.blackops/config.json with token + MCP URL.
-//   3. Adds a `blackops` MCP server entry to Claude Code's settings.json.
-//   4. Prints the onboarding prompt for the user to paste into Claude Code.
+//   3. Detects installed MCP clients (Claude Code, Claude Desktop, Cursor, Cline)
+//      and adds a `blackops` MCP server entry to each one's config.
+//   4. Always prints a universal copy-paste snippet as fallback for unknown clients.
 //
 // Re-runs are idempotent: an existing ~/.blackops/config.json will prompt the
 // user before overwriting.
@@ -15,7 +16,7 @@ import path from 'node:path'
 import os from 'node:os'
 import readline from 'node:readline/promises'
 
-const VERSION = '0.3.0'
+const VERSION = '0.6.0'
 const INSTALL_URL = process.env.BLACKOPS_INSTALL_URL || 'https://blackopscenter.com/api/install'
 const CONFIG_DIR = path.join(os.homedir(), '.blackops')
 const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json')
@@ -41,18 +42,6 @@ async function confirm(question) {
   }
 }
 
-function findClaudeCodeSettingsPath() {
-  // Claude Code stores user-level settings in ~/.claude/settings.json on macOS/Linux.
-  // (The same file holds permissions, hooks, and MCP servers.)
-  const candidates = [
-    path.join(os.homedir(), '.claude', 'settings.json'),
-  ]
-  for (const p of candidates) {
-    if (fs.existsSync(p)) return p
-  }
-  return candidates[0] // first candidate; we'll create it
-}
-
 function readJsonSafe(filePath) {
   try {
     const raw = fs.readFileSync(filePath, 'utf8')
@@ -69,6 +58,105 @@ function writeJsonAtomic(filePath, value) {
   fs.renameSync(tmp, filePath)
 }
 
+// ── MCP client detection ────────────────────────────────────────────────
+//
+// Each entry is one MCP client we know how to install into. `path` is where
+// the client stores its MCP config; `installed` is a heuristic that checks
+// whether the client appears to be set up. `alwaysInstall` is true for
+// Claude Code (the canonical target — we create the file if missing).
+//
+// All known clients use the same `mcpServers.<name>.{type,url,headers}`
+// JSON shape, so a single writer covers them.
+
+// `transport: 'http'` writes the native streamable HTTP entry that
+// Claude Code and Cursor both understand:
+//   { type: 'http', url, headers: { Authorization: 'Bearer ...' } }
+//
+// `transport: 'stdio-bridge'` writes an `mcp-remote` stdio shim, used for
+// Claude Desktop and Cline which only speak stdio MCP today:
+//   { command: 'npx', args: ['-y', 'mcp-remote', url, '--header', 'Authorization: Bearer ...'] }
+
+function getClientConfigs(homedir, platform) {
+  const APPDATA = process.env.APPDATA || ''
+  return [
+    {
+      id: 'claude-code',
+      label: 'Claude Code',
+      path: path.join(homedir, '.claude', 'settings.json'),
+      transport: 'http',
+      alwaysInstall: true,
+    },
+    {
+      id: 'claude-desktop',
+      label: 'Claude Desktop',
+      path:
+        platform === 'darwin'
+          ? path.join(homedir, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
+          : platform === 'win32'
+            ? path.join(APPDATA, 'Claude', 'claude_desktop_config.json')
+            : path.join(homedir, '.config', 'Claude', 'claude_desktop_config.json'),
+      transport: 'stdio-bridge',
+    },
+    {
+      id: 'cursor',
+      label: 'Cursor',
+      path: path.join(homedir, '.cursor', 'mcp.json'),
+      transport: 'http',
+    },
+    {
+      id: 'cline',
+      label: 'Cline (VS Code)',
+      path: path.join(homedir, '.cline', 'mcp_settings.json'),
+      transport: 'stdio-bridge',
+    },
+  ]
+}
+
+function buildServerEntry(transport, { mcpUrl, token }) {
+  if (transport === 'stdio-bridge') {
+    // --transport http-only avoids mcp-remote's SSE-fallback path (which has
+    // historically hung for several minutes on slow tool calls).
+    // --timeout 30000 caps any single request at 30s instead of the 4-minute
+    // default, so a stuck call surfaces as an error the agent can recover
+    // from instead of a silent hang.
+    return {
+      command: 'npx',
+      args: [
+        '-y',
+        'mcp-remote',
+        mcpUrl,
+        '--header',
+        `Authorization: Bearer ${token}`,
+        '--transport',
+        'http-only',
+        '--timeout',
+        '30000',
+      ],
+    }
+  }
+  return {
+    type: 'http',
+    url: mcpUrl,
+    headers: { Authorization: `Bearer ${token}` },
+  }
+}
+
+function clientIsInstalled(cfg) {
+  if (cfg.alwaysInstall) return true
+  // File exists OR its parent dir exists (covers cases where the user
+  // has the app installed but hasn't created an MCP config file yet).
+  if (fs.existsSync(cfg.path)) return true
+  if (fs.existsSync(path.dirname(cfg.path))) return true
+  return false
+}
+
+function injectMcpServer(cfg, { mcpServerName, mcpUrl, token }) {
+  const existing = readJsonSafe(cfg.path) ?? {}
+  existing.mcpServers = existing.mcpServers ?? {}
+  existing.mcpServers[mcpServerName] = buildServerEntry(cfg.transport, { mcpUrl, token })
+  writeJsonAtomic(cfg.path, existing)
+}
+
 async function callInstallEndpoint() {
   const response = await fetch(INSTALL_URL, {
     method: 'POST',
@@ -86,24 +174,6 @@ async function callInstallEndpoint() {
   return data
 }
 
-function injectClaudeCodeMcp({ mcpUrl, mcpServerName, token }) {
-  const settingsPath = findClaudeCodeSettingsPath()
-  const settings = readJsonSafe(settingsPath) ?? {}
-  settings.mcpServers = settings.mcpServers ?? {}
-
-  // Use the SSE/HTTP transport — Claude Code supports `type: "http"` MCP servers.
-  settings.mcpServers[mcpServerName] = {
-    type: 'http',
-    url: mcpUrl,
-    headers: {
-      Authorization: `Bearer ${token}`,
-    },
-  }
-
-  writeJsonAtomic(settingsPath, settings)
-  return settingsPath
-}
-
 async function main() {
   log(`${BOLD}${CYAN}BlackOps Center — agent-first onboarding${RESET}`)
   log(`${DIM}v${VERSION}${RESET}`)
@@ -146,26 +216,63 @@ async function main() {
   writeJsonAtomic(CONFIG_PATH, config)
   log(`${GREEN}✓${RESET} Saved config to ${CONFIG_PATH}`)
 
-  // 3. Wire up Claude Code MCP.
-  let settingsPath
-  try {
-    settingsPath = injectClaudeCodeMcp({
-      mcpUrl: config.mcp_url,
-      mcpServerName: config.mcp_server_name,
-      token: config.token,
-    })
-    log(`${GREEN}✓${RESET} Added MCP server "${config.mcp_server_name}" to ${settingsPath}`)
-  } catch (e) {
-    err(`Could not write Claude Code settings: ${e.message}`)
-    log('You can configure manually by adding this MCP server to your Claude Code settings:')
-    log(JSON.stringify({ [config.mcp_server_name]: { type: 'http', url: config.mcp_url, headers: { Authorization: `Bearer ${config.token}` } } }, null, 2))
+  // 3. Detect installed MCP clients and write to each one we recognize.
+  const clientConfigs = getClientConfigs(os.homedir(), process.platform)
+  const installedTo = []
+  const failed = []
+  for (const c of clientConfigs) {
+    if (!clientIsInstalled(c)) continue
+    try {
+      injectMcpServer(c, {
+        mcpServerName: config.mcp_server_name,
+        mcpUrl: config.mcp_url,
+        token: config.token,
+      })
+      installedTo.push(c)
+    } catch (e) {
+      failed.push({ client: c, error: e.message })
+    }
+  }
+
+  if (installedTo.length === 0) {
+    log(`${YELLOW}No supported MCP client configs detected.${RESET}`)
+  } else {
+    for (const c of installedTo) {
+      log(`${GREEN}✓${RESET} Added MCP server "${config.mcp_server_name}" to ${c.label} (${c.path})`)
+    }
   }
+  for (const f of failed) {
+    err(`Could not write ${f.client.label} config: ${f.error}`)
+  }
+
+  // 4. Always print universal snippets as fallback for any other MCP client.
+  // Two formats — pick whichever your client supports.
+  log()
+  log(`${DIM}Using a different MCP client? Add ONE of these to its config under \`mcpServers\`:${RESET}`)
+  log()
+  log(`${DIM}// HTTP transport (Claude Code, Cursor, etc.):${RESET}`)
+  log(
+    `${DIM}${JSON.stringify(
+      { [config.mcp_server_name]: buildServerEntry('http', { mcpUrl: config.mcp_url, token: config.token }) },
+      null,
+      2
+    )}${RESET}`
+  )
+  log()
+  log(`${DIM}// stdio bridge (Claude Desktop, Cline, anything stdio-only):${RESET}`)
+  log(
+    `${DIM}${JSON.stringify(
+      { [config.mcp_server_name]: buildServerEntry('stdio-bridge', { mcpUrl: config.mcp_url, token: config.token }) },
+      null,
+      2
+    )}${RESET}`
+  )
 
-  // 4. Tell the user the one thing to say next. Single line, copy-pasteable.
+  // 5. Tell the user the one thing to say next. Single line, copy-pasteable.
   log()
   log(`${GREEN}✓${RESET} Installed.`)
   log()
-  log(`Open ${BOLD}Claude Code${RESET} and say:`)
+  log(`Open your MCP-capable agent (Claude Code, Cursor, etc.) and say:`)
   log()
   log(`  ${CYAN}${config.prompt}${RESET}`)
   log()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blackops-onboard",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "Agent-first onboarding for BlackOps Center. Run via `npx blackops-onboard` to provision your account through Claude Code.",
   "type": "module",
   "publishConfig": {