@clix-so/clix-agent-skills 0.1.6 → 0.1.7

package/README.md

@@ -16,9 +16,9 @@ you can install skills in different ways.
 
 ### Universal CLI (Recommended)
 
-For **Cursor**, **VS Code**, **Claude Desktop**, **OpenCode**, **Goose**,
-**GitHub Copilot**, **Amp**, and **Letta**, use our CLI tool to install skills
-and configure the Clix MCP Server automatically:
+For **Cursor**, **VS Code**, **Claude Code**, **OpenCode**, **Goose**, **GitHub
+Copilot**, **Amp**, and **Letta**, use our tool to install skills and configure
+the Clix MCP Server automatically:
 
 #### Installation Modes
 
@@ -66,16 +66,16 @@ npx @clix-so/clix-agent-skills@latest install --all --client cursor --global
 
 **Supported Clients:**
 
-| Client         | Flag                | Default Path       |
-| :------------- | :------------------ | :----------------- |
-| Amp            | `--client amp`      | `.amp/skills/`     |
-| Claude         | `--client claude`   | `.claude/skills/`  |
-| Codex          | `--client codex`    | `.codex/skills/`   |
-| Cursor         | `--client cursor`   | `.cursor/skills/`  |
-| GitHub Copilot | `--client github`   | `.github/skills/`  |
-| Goose          | `--client goose`    | `.goose/skills/`   |
-| Letta          | `--client letta`    | `.skills/`         |
-| OpenCode       | `--client opencode` | `.opencode/skill/` |
+| Client         | Flag                                 | Default Path       |
+| :------------- | :----------------------------------- | :----------------- |
+| Amp            | `--client amp`                       | `.amp/skills/`     |
+| Claude Code    | `--client claude` (or `claude-code`) | `.claude/skills/`  |
+| Codex          | `--client codex`                     | `.codex/skills/`   |
+| Cursor         | `--client cursor`                    | `.cursor/skills/`  |
+| GitHub Copilot | `--client github`                    | `.github/skills/`  |
+| Goose          | `--client goose`                     | `.goose/skills/`   |
+| Letta          | `--client letta`                     | `.skills/`         |
+| OpenCode       | `--client opencode`                  | `.opencode/skill/` |
 
 ### Claude Code
 

package/dist/bin/cli.js

@@ -25,7 +25,7 @@ program
 program
     .command("install [skill]")
     .description("Install agent skill(s)")
-    .option("-c, --client <client>", "Target AI client (cursor, claude, vscode, amp, kiro, amazonq, codex, opencode, manual)")
+    .option("-c, --client <client>", "Target AI client (cursor, claude|claude-code, vscode, amp, kiro, amazonq, codex, opencode, manual)")
     .option("-p, --path <path>", "Custom installation path (default: .clix/skills)")
     .option("-a, --all", "Install all available skills")
     .option("-g, --global", "Install globally to system root (default: installs to repo root)")

package/dist/bin/commands/install.js

@@ -64,6 +64,8 @@ async function installSkill(skillName, options) {
     else if (options.client) {
         switch (options.client.toLowerCase()) {
             case "claude":
+            case "claude-code":
+                // Claude Code uses the .claude/ folder convention, but MCP is configured via `claude mcp ...`
                 relativeDest = ".claude/skills";
                 break;
             case "cursor":

package/dist/bin/utils/mcp.js

@@ -43,6 +43,7 @@ const os_1 = __importDefault(require("os"));
 const chalk_1 = __importDefault(require("chalk"));
 const inquirer_1 = __importDefault(require("inquirer"));
 const TOML = __importStar(require("@iarna/toml"));
+const child_process_1 = require("child_process");
 // ============================================================================
 // Constants
 // ============================================================================
@@ -50,6 +51,17 @@ const CLIX_MCP_SERVER_ENTRY = {
     command: "npx",
     args: ["-y", "@clix-so/clix-mcp-server@latest"],
 };
+const CLAUDE_CODE_MCP_ADD_ARGS = [
+    "mcp",
+    "add",
+    "--transport",
+    "stdio",
+    "clix-mcp-server",
+    "--",
+    "npx",
+    "-y",
+    "@clix-so/clix-mcp-server@latest",
+];
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -62,6 +74,47 @@ function getErrorMessage(error) {
     }
     return String(error);
 }
+function hasClixServerInClaudeMcpListOutput(output) {
+    return output.toLowerCase().includes("clix-mcp-server");
+}
+/**
+ * Configure MCP for Claude Code using the `claude` CLI (no config file editing).
+ */
+async function configureClaudeCode() {
+    console.log(chalk_1.default.blue("Checking MCP config via Claude Code CLI (`claude mcp`)..."));
+    // Verify Claude CLI exists and supports MCP.
+    const helpRes = (0, child_process_1.spawnSync)("claude", ["mcp", "--help"], { encoding: "utf8" });
+    if (helpRes.error) {
+        console.log(chalk_1.default.yellow(`Could not run Claude CLI (${getErrorMessage(helpRes.error)}). Skipping MCP configuration.`));
+        return;
+    }
+    if (helpRes.status !== 0) {
+        console.log(chalk_1.default.yellow("Claude CLI does not appear to support `claude mcp`. Skipping MCP configuration."));
+        return;
+    }
+    // Best-effort idempotency: if list works and already contains the server, skip.
+    const listRes = (0, child_process_1.spawnSync)("claude", ["mcp", "list"], { encoding: "utf8" });
+    const listOut = `${listRes.stdout ?? ""}\n${listRes.stderr ?? ""}`;
+    if (!listRes.error && listRes.status === 0 && hasClixServerInClaudeMcpListOutput(listOut)) {
+        console.log(chalk_1.default.green("✔ Clix MCP Server is already configured."));
+        return;
+    }
+    const addRes = (0, child_process_1.spawnSync)("claude", CLAUDE_CODE_MCP_ADD_ARGS, { encoding: "utf8" });
+    if (addRes.error || addRes.status !== 0) {
+        const out = `${addRes.stdout ?? ""}\n${addRes.stderr ?? ""}`.trim();
+        console.log(chalk_1.default.yellow(`Failed to configure MCP via Claude Code CLI. ${out ? `Output:\n${out}` : "No output captured."}`));
+        return;
+    }
+    console.log(chalk_1.default.green("✔ Added Clix MCP Server to configuration. Please restart claude."));
+}
+function isClaudeCodeClient(client) {
+    const c = client.toLowerCase();
+    return (c === "claude" ||
+        c === "claude_code" ||
+        c === "claude-code" ||
+        c === "claudecode" ||
+        c === "claude code");
+}
 /**
  * Gets the MCP servers object from JSON config based on client type
  */
@@ -106,19 +159,6 @@ function getClientConfig(client) {
                 format: "json",
             };
         }
-        case "claude": {
-            let configPath = null;
-            if (process.platform === "darwin") {
-                configPath = path_1.default.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
-            }
-            else if (process.platform === "win32") {
-                configPath = path_1.default.join(process.env.APPDATA || "", "Claude", "claude_desktop_config.json");
-            }
-            else if (process.platform === "linux") {
-                configPath = path_1.default.join(home, ".config", "Claude", "claude_desktop_config.json");
-            }
-            return configPath ? { path: configPath, configKey: "mcpServers", format: "json" } : null;
-        }
         case "vscode":
             return {
                 path: path_1.default.join(home, ".vscode", "mcp.json"),
@@ -306,7 +346,7 @@ async function configureMCP(client) {
                 message: "Which AI client are you using?",
                 choices: [
                     { name: "Cursor", value: "cursor" },
-                    { name: "Claude Desktop", value: "claude" },
+                    { name: "Claude Code", value: "claude" },
                     { name: "VS Code", value: "vscode" },
                     { name: "Amp", value: "amp" },
                     { name: "Kiro", value: "kiro" },
@@ -322,10 +362,19 @@ async function configureMCP(client) {
         ]);
         targetClient = answers.client;
     }
+    if (!targetClient) {
+        console.log(chalk_1.default.yellow("No client selected. Skipping MCP configuration."));
+        return;
+    }
     if (targetClient === "manual") {
         console.log(chalk_1.default.blue("Skipping automatic MCP configuration."));
         return;
     }
+    // Claude Code is configured via the `claude` CLI (no file editing).
+    if (targetClient && isClaudeCodeClient(targetClient)) {
+        await configureClaudeCode();
+        return;
+    }
     // Handle OpenCode separately (different JSON structure)
     if (targetClient === "opencode") {
         await configureOpenCode();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clix-so/clix-agent-skills",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "An open collection of agent skills for Clix.",
   "main": "dist/index.js",
   "bin": {

package/skills/event-tracking/SKILL.md

@@ -97,7 +97,7 @@ bash <skill-dir>/scripts/validate-event-plan.sh event-plan.json
 The skill directory is typically:
 
 - `.cursor/skills/event-tracking/` (Cursor)
-- `.claude/skills/event-tracking/` (Claude Desktop)
+- `.claude/skills/event-tracking/` (Claude Code)
 - `.vscode/skills/event-tracking/` (VS Code/Amp)
 - Or check where this skill was installed
 

package/skills/integration/SKILL.md

@@ -38,11 +38,12 @@ latest verified SDK source code.
   1. **Ask the user**: "The Clix MCP Server is not detected. It provides the
      latest official SDK code. Would you like me to install it now?"
   2. **If User says YES**:
-     - Run: `bash scripts/install-mcp.sh`
+     - Run: `bash scripts/install-mcp.sh --client <your-client>`
      - The script will:
        - Verify the package is available
-       - Auto-detect the MCP client (OpenCode, Amp, Codex, Cursor, Claude
-         Desktop, VS Code, etc.)
+       - Configure the MCP server for the specified client
+       - (If you omit `--client` and multiple clients are installed, the script
+         will stop and ask you to choose.)
        - Automatically configure the MCP server in the appropriate config file
        - Provide clear instructions for restart
      - Instruct user to restart their agent/IDE to load the new server.

package/skills/integration/references/mcp-integration.md

@@ -263,26 +263,6 @@ claude mcp add --transport stdio clix-mcp-server -- npx -y @clix-so/clix-mcp-ser
 }
 ```
 
-#### Claude Desktop App
-
-**Setup**
-
-1. Open config
-   (`~/Library/Application Support/Claude/claude_desktop_config.json` or
-   `%APPDATA%\\Claude\\claude_desktop_config.json`).
-2. Add and restart:
-
-```json
-{
-  "mcpServers": {
-    "clix-mcp-server": {
-      "command": "npx",
-      "args": ["-y", "@clix-so/clix-mcp-server@latest"]
-    }
-  }
-}
-```
-
 #### Amp
 
 **Setup**

package/skills/integration/scripts/install-mcp.sh

@@ -18,6 +18,64 @@ log() {
   printf "%b\n" "$1"
 }
 
+log_err() {
+  printf "%b\n" "$1" >&2
+}
+
+usage() {
+  cat <<'EOF'
+Clix MCP Server Installer
+
+Usage:
+  bash scripts/install-mcp.sh [--client <client>]
+
+Options:
+  --client <client>      Explicitly select the MCP client to configure.
+                         Supported: claude, claude-code, opencode, amp, codex, cursor, vscode
+  --help                 Show this help.
+
+Environment:
+  CLIX_MCP_CLIENT         Same as --client (takes precedence).
+
+Notes:
+  If multiple MCP clients are detected on this machine, you MUST pass --client
+  (or set CLIX_MCP_CLIENT). A shell script cannot reliably know "which client is
+  currently running" on a machine with multiple clients installed.
+EOF
+}
+
+# Parse args/env
+CLIENT_OVERRIDE="${CLIX_MCP_CLIENT:-}"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    --client)
+      shift
+      CLIENT_OVERRIDE="${1:-}"
+      ;;
+    --client=*)
+      CLIENT_OVERRIDE="${1#*=}"
+      ;;
+    *)
+      log_err "${YELLOW}⚠️  Unknown argument: $1${RESET}"
+      usage
+      exit 2
+      ;;
+  esac
+  shift || true
+done
+
+validate_client() {
+  case "${1:-}" in
+    claude|claude-code|opencode|amp|codex|cursor|vscode) return 0 ;;
+    "") return 1 ;;
+    *) return 1 ;;
+  esac
+}
+
 # Detect platform
 detect_platform() {
   case "$(uname -s)" in
@@ -35,6 +93,10 @@ get_config_path() {
   local platform=$(detect_platform)
 
   case "$client" in
+    claude-code)
+      # Claude Code CLI manages MCP via `claude mcp ...` commands (no direct config file here)
+      echo ""
+      ;;
     codex)
       echo "${home}/.codex/config.toml"
       ;;
@@ -47,13 +109,8 @@ get_config_path() {
       fi
       ;;
     claude)
-      if [ "$platform" = "darwin" ]; then
-        echo "${home}/Library/Application Support/Claude/claude_desktop_config.json"
-      elif [ "$platform" = "win32" ]; then
-        echo "${APPDATA:-}/Claude/claude_desktop_config.json"
-      else
-        echo "${home}/.config/claude/claude_desktop_config.json"
-      fi
+      # Alias for Claude Code
+      echo ""
       ;;
     vscode)
       echo "${home}/.vscode/mcp.json"
@@ -88,6 +145,25 @@ get_config_path() {
   esac
 }
 
+# Configure MCP for Claude Code CLI
+configure_claude_code() {
+  if ! command -v claude &> /dev/null; then
+    log "${RED}❌ Claude CLI not found on PATH.${RESET}"
+    exit 1
+  fi
+
+  # Best-effort: avoid failing if already configured.
+  # If list isn't supported, we'll just attempt add.
+  if claude mcp list 2>/dev/null | grep -q "clix-mcp-server"; then
+    log "${GREEN}✔ Clix MCP Server already configured in Claude Code${RESET}"
+    return 0
+  fi
+
+  # Configure via CLI (non-interactive)
+  claude mcp add --transport stdio clix-mcp-server -- npx -y @clix-so/clix-mcp-server@latest
+  log "${GREEN}✔ Configured Clix MCP Server in Claude Code${RESET}"
+}
+
 # Configure MCP for Codex (TOML format)
 configure_codex() {
   local config_path="$1"
@@ -158,7 +234,7 @@ configure_amp() {
     return 0
   fi
 
-  # Use node to safely update JSON
+  # Use node to safely update JSON/JSONC (VS Code settings often allow comments)
   if command -v node &> /dev/null; then
     node <<EOF
 const fs = require('fs');
@@ -166,7 +242,61 @@ const path = '$config_path';
 let config = {};
 try {
   const content = fs.readFileSync(path, 'utf8');
-  config = JSON.parse(content);
+  const stripJsonc = (input) => {
+    // Strips // and /* */ comments, but preserves anything inside strings.
+    let out = '';
+    let inStr = false;
+    let esc = false;
+    let inLine = false;
+    let inBlock = false;
+    for (let i = 0; i < input.length; i++) {
+      const c = input[i];
+      const n = input[i + 1];
+      if (inLine) {
+        if (c === '\n') {
+          inLine = false;
+          out += c;
+        }
+        continue;
+      }
+      if (inBlock) {
+        if (c === '*' && n === '/') {
+          inBlock = false;
+          i++;
+        }
+        continue;
+      }
+      if (inStr) {
+        out += c;
+        if (esc) {
+          esc = false;
+        } else if (c === '\\\\') {
+          esc = true;
+        } else if (c === '"') {
+          inStr = false;
+        }
+        continue;
+      }
+      if (c === '"') {
+        inStr = true;
+        out += c;
+        continue;
+      }
+      if (c === '/' && n === '/') {
+        inLine = true;
+        i++;
+        continue;
+      }
+      if (c === '/' && n === '*') {
+        inBlock = true;
+        i++;
+        continue;
+      }
+      out += c;
+    }
+    return out;
+  };
+  config = JSON.parse(stripJsonc(content));
 } catch (e) {
   config = {};
 }
@@ -218,17 +348,72 @@ EOF
 const fs = require('fs');
 const path = '$config_path';
 let content = fs.readFileSync(path, 'utf8');
-// Remove comments for JSONC parsing (simple approach)
-let jsonContent = content.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
-let config = JSON.parse(jsonContent);
+const stripJsonc = (input) => {
+  // Strips // and /* */ comments, but preserves anything inside strings.
+  let out = '';
+  let inStr = false;
+  let esc = false;
+  let inLine = false;
+  let inBlock = false;
+  for (let i = 0; i < input.length; i++) {
+    const c = input[i];
+    const n = input[i + 1];
+    if (inLine) {
+      if (c === '\n') {
+        inLine = false;
+        out += c;
+      }
+      continue;
+    }
+    if (inBlock) {
+      if (c === '*' && n === '/') {
+        inBlock = false;
+        i++;
+      }
+      continue;
+    }
+    if (inStr) {
+      out += c;
+      if (esc) {
+        esc = false;
+      } else if (c === '\\\\') {
+        esc = true;
+      } else if (c === '"') {
+        inStr = false;
+      }
+      continue;
+    }
+    if (c === '"') {
+      inStr = true;
+      out += c;
+      continue;
+    }
+    if (c === '/' && n === '/') {
+      inLine = true;
+      i++;
+      continue;
+    }
+    if (c === '/' && n === '*') {
+      inBlock = true;
+      i++;
+      continue;
+    }
+    out += c;
+  }
+  return out;
+};
+let config = {};
+try {
+  config = JSON.parse(stripJsonc(content));
+} catch (e) {
+  config = {};
+}
 if (!config.mcp) config.mcp = {};
 config.mcp['clix-mcp-server'] = {
   type: 'local',
   command: ['npx', '-y', '@clix-so/clix-mcp-server@latest'],
   enabled: true
 };
-// Write back as JSONC if original was .jsonc, otherwise JSON
-const isJsonc = path.endsWith('.jsonc');
 fs.writeFileSync(path, JSON.stringify(config, null, 2) + '\n');
 EOF
     log "${GREEN}✔ Configured Clix MCP Server in OpenCode${RESET}"
@@ -291,48 +476,93 @@ EOF
   fi
 }
 
-# Auto-detect client
-detect_client() {
-  # Check for OpenCode (check for opencode.json/jsonc or opencode command)
+# Detect all matching clients (heuristics). Output one per line.
+detect_clients() {
+  # Claude Code CLI (supports `claude mcp ...`)
+  if command -v claude &> /dev/null && claude mcp --help &> /dev/null; then
+    echo "claude"
+  fi
+
+  # OpenCode (project config files or opencode command)
   if [ -f "opencode.json" ] || [ -f "opencode.jsonc" ] || command -v opencode &> /dev/null; then
     echo "opencode"
-    return
   fi
 
-  # Check for Amp (check for amp.mcpServers in settings.json or amp command)
+  # Amp (amp command or amp.mcpServers present)
   if command -v amp &> /dev/null || \
      grep -q "amp.mcpServers" ".vscode/settings.json" 2>/dev/null || \
      grep -q "amp.mcpServers" "${HOME}/.vscode/settings.json" 2>/dev/null; then
     echo "amp"
-    return
   fi
 
-  # Check for Codex
+  # Codex
   if [ -f "${HOME}/.codex/config.toml" ] || command -v codex &> /dev/null; then
     echo "codex"
-    return
   fi
 
-  # Check for Cursor
+  # Cursor
   if [ -f "${HOME}/.cursor/mcp.json" ] || [ -f ".cursor/mcp.json" ]; then
     echo "cursor"
+  fi
+
+  # VS Code
+  if [ -f "${HOME}/.vscode/mcp.json" ]; then
+    echo "vscode"
+  fi
+}
+
+choose_client() {
+  if [ -n "${CLIENT_OVERRIDE:-}" ]; then
+    if ! validate_client "$CLIENT_OVERRIDE"; then
+      log_err "${RED}❌ Invalid --client / CLIX_MCP_CLIENT: ${CLIENT_OVERRIDE}${RESET}"
+      usage
+      exit 2
+    fi
+    if [ "$CLIENT_OVERRIDE" = "claude-code" ]; then
+      echo "claude"
+      return
+    fi
+    echo "$CLIENT_OVERRIDE"
     return
   fi
 
-  # Check for Claude Desktop
-  if [ -f "${HOME}/Library/Application Support/Claude/claude_desktop_config.json" ] 2>/dev/null || \
-     [ -f "${APPDATA:-}/Claude/claude_desktop_config.json" ] 2>/dev/null; then
-    echo "claude"
+  local detected
+  detected="$(detect_clients | awk 'NF' | sort -u)"
+  local count
+  count="$(printf "%s\n" "$detected" | awk 'NF' | wc -l | tr -d ' ')"
+
+  if [ "${count:-0}" -eq 0 ]; then
+    echo "unknown"
     return
   fi
 
-  # Check for VS Code
-  if [ -f "${HOME}/.vscode/mcp.json" ]; then
-    echo "vscode"
+  if [ "${count:-0}" -eq 1 ]; then
+    printf "%s\n" "$detected"
     return
   fi
 
-  echo "unknown"
+  # Multiple detected: we can't know which one is "currently running".
+  log_err "${YELLOW}⚠️  Multiple MCP clients detected on this machine:${RESET}"
+  printf "%s\n" "$detected" | sed 's/^/  - /' >&2
+
+  if [ -t 0 ]; then
+    log_err "${BLUE}Select which client to configure:${RESET}"
+    local options=()
+    while IFS= read -r line; do options+=("$line"); done <<<"$detected"
+    options+=("cancel")
+    select opt in "${options[@]}"; do
+      if [ "$opt" = "cancel" ] || [ -z "${opt:-}" ]; then
+        log_err "${YELLOW}Cancelled.${RESET}"
+        exit 2
+      fi
+      echo "$opt"
+      return
+    done
+  fi
+
+  log_err "${RED}❌ Ambiguous MCP client selection in non-interactive mode.${RESET}"
+  log_err "${YELLOW}Please re-run with: bash scripts/install-mcp.sh --client <client>${RESET}"
+  exit 2
 }
 
 log "${BLUE}📦 Installing Clix MCP Server...${RESET}"
@@ -355,13 +585,18 @@ fi
 
 # Auto-detect and configure
 log "${BLUE}🔍 Detecting MCP client...${RESET}"
-detected_client=$(detect_client)
+detected_client=$(choose_client)
 
 if [ "$detected_client" != "unknown" ]; then
   log "${GREEN}Detected: $detected_client${RESET}"
   config_path=$(get_config_path "$detected_client")
 
-  if [ -n "$config_path" ]; then
+  if [ "$detected_client" = "claude" ]; then
+    log "${BLUE}Configuring MCP server for Claude Code...${RESET}"
+    configure_claude_code
+    log "${GREEN}✅ Successfully configured Clix MCP Server!${RESET}"
+    log "${YELLOW}⚠️  IMPORTANT: Please RESTART Claude Code for the changes to take effect.${RESET}"
+  elif [ -n "$config_path" ]; then
     log "${BLUE}Configuring MCP server for $detected_client...${RESET}"
 
     if [ "$detected_client" = "codex" ]; then
@@ -387,7 +622,7 @@ else
   log "${BLUE}  - Amp: Add to .vscode/settings.json or ~/.vscode/settings.json${RESET}"
   log "${BLUE}  - Codex: Add to ~/.codex/config.toml${RESET}"
   log "${BLUE}  - Cursor: Add to .cursor/mcp.json or ~/.cursor/mcp.json${RESET}"
-  log "${BLUE}  - Claude Desktop: Add to config file${RESET}"
+  log "${BLUE}  - Claude Code: Run: claude mcp add --transport stdio clix-mcp-server -- npx -y @clix-so/clix-mcp-server@latest${RESET}"
   log "${BLUE}See references/mcp-integration.md for detailed instructions.${RESET}"
 fi