a11y-devkit-deploy 0.9.7 → 1.0.0

package/README.md

@@ -18,13 +18,15 @@ npx a11y-devkit-deploy
 a11y-devkit-deploy
 ```
 
-### Flags
-
-- `--local` / `--global`: Skip the scope prompt.
-- `--yes`: Use defaults (local scope, all IDEs, install skills).
-- `--uninstall`: Remove skills and MCP entries installed by this tool.
-
-## After Installation
+### Flags
+
+- `--local` / `--global`: Skip the scope prompt.
+- `--yes`: Use defaults (local scope, all IDEs, install skills).
+- `--uninstall`: Remove skills and MCP entries installed by this tool.
+
+**Note:** MCP configs are always written globally (AppData/Application Support). The scope flag only affects skills.
+
+## After Installation
 
 Once installation completes, you'll find a comprehensive usage guide in your IDE's skills directory:
 
@@ -86,16 +88,16 @@ This CLI automates the setup of accessibility tooling by:
 - MCP servers to configure
 - Even the IDE list itself
 
-**Adding Support for a New IDE** takes just 5 lines of JSON:
-```json
-{
-  "id": "new-ide",
-  "displayName": "New IDE",
-  "mcpServerKey": "servers",
-  "skillsFolder": ".new-ide/skills",
-  "mcpConfigFile": ".new-ide/mcp.json"
-}
-```
+**Adding Support for a New IDE** takes just 5 lines of JSON:
+```json
+{
+  "id": "new-ide",
+  "displayName": "New IDE",
+  "mcpServerKey": "servers",
+  "skillsFolder": ".new-ide/skills",
+  "mcpConfigFile": ".new-ide/mcp.json"
+}
+```
 
 **Safe by Default** - Won't overwrite your existing:
 - Custom MCP servers in your IDE configs
@@ -193,38 +195,34 @@ Add an object to the `hostApplications` array with the host application's config
 
 ```json
 {
-  "hostApplications": [
-    {
-      "id": "windsurf",
-      "displayName": "Windsurf",
-      "mcpServerKey": "servers",
-      "skillsFolder": ".codeium/windsurf/skills",
-      "mcpConfigFile": ".codeium/windsurf/mcp_config.json"
-    },
-    {
-      "id": "vscode",
-      "displayName": "VSCode",
-      "mcpServerKey": "servers",
-      "skillsFolder": ".github/skills",
-      "mcpConfigFile": ".github/mcp.json",
-      "globalMcpConfigFile": "Code/User/mcp.json"
-    }
-  ]
-}
-```
-
-**Note:** The `globalMcpConfigFile` property is optional. When specified, the global MCP config path is relative to the platform's app support directory (AppData on Windows, Application Support on macOS) instead of the home directory.
-
-**Host Application Configuration Properties:**
-- `id` - Unique identifier for the host application
-- `displayName` - Human-readable name shown in prompts
-- `mcpServerKey` - MCP config key name (`"servers"`, `"mcpServers"`, or `"mcp_servers"` for TOML)
-- `skillsFolder` - Path to skills directory (relative to home/project root)
-- `mcpConfigFile` - Path to MCP config file (relative to home/project root). Supports both JSON (`.json`) and TOML (`.toml`) formats. TOML format is auto-detected by file extension (used by Codex).
-- `globalMcpConfigFile` - (Optional) Path to global MCP config relative to AppData/Application Support instead of home directory. Used for hosts like VSCode that store configs in platform-specific app directories:
-  - Windows: `%APPDATA%` (e.g., `C:\Users\name\AppData\Roaming`)
-  - macOS: `~/Library/Application Support`
-  - Linux: `$XDG_CONFIG_HOME` or `~/.config`
+  "hostApplications": [
+    {
+      "id": "windsurf",
+      "displayName": "Windsurf",
+      "mcpServerKey": "servers",
+      "skillsFolder": ".codeium/windsurf/skills",
+      "mcpConfigFile": ".codeium/windsurf/mcp_config.json"
+    },
+    {
+      "id": "vscode",
+      "displayName": "VSCode",
+      "mcpServerKey": "servers",
+      "skillsFolder": ".github/skills",
+      "mcpConfigFile": "Code/User/mcp.json"
+    }
+  ]
+}
+```
+
+**Host Application Configuration Properties:**
+- `id` - Unique identifier for the host application
+- `displayName` - Human-readable name shown in prompts
+- `mcpServerKey` - MCP config key name (`"servers"`, `"mcpServers"`, or `"mcp_servers"` for TOML)
+- `skillsFolder` - Path to skills directory (relative to home/project root)
+- `mcpConfigFile` - Path to MCP config file (relative to AppData/Application Support). Supports both JSON (`.json`) and TOML (`.toml`) formats. TOML format is auto-detected by file extension (used by Codex):
+  - Windows: `%APPDATA%` (e.g., `C:\Users\name\AppData\Roaming`)
+  - macOS: `~/Library/Application Support`
+  - Linux: `$XDG_CONFIG_HOME` or `~/.config`
 
 **Note:** Codex uses TOML format for its MCP configuration (`~/.codex/config.toml`), which requires the `mcpServerKey` to be `"mcp_servers"` and generates config entries like:
 ```toml
@@ -252,53 +250,48 @@ The CLI **safely merges** with existing configurations:
 
 ## Directory Structure
 
-### Local Install (Project-Specific)
-```
-your-project/
-├── .claude/
-│   ├── mcp.json            # Claude Code MCP config
-│   └── skills/             # Claude Code skills
-├── .cursor/
-│   ├── mcp.json            # Cursor MCP config
-│   └── skills/             # Cursor skills
-├── .codex/
-│   ├── config.toml         # Codex MCP config
-│   └── skills/             # Codex skills
-├── .github/
-│   ├── mcp.json            # VSCode MCP config
-│   └── skills/             # VSCode skills
-├── .codeium/windsurf/
-│   ├── mcp_config.json     # Windsurf MCP config
-│   └── skills/             # Windsurf skills
-└── .factory/
-    ├── mcp.json            # Factory MCP config
-    └── skills/             # Factory skills
-```
-
-### Global Install (User-Wide)
-```
-~/.claude/
-  ├── mcp.json              # Claude Code global MCP config
-  └── skills/               # Claude Code global skills
-~/.cursor/
-  ├── mcp.json              # Cursor global MCP config
-  └── skills/               # Cursor global skills
-~/.codex/
-  ├── config.toml           # Codex global MCP config
-  └── skills/               # Codex global skills
-~/.github/
-  └── skills/               # VSCode global skills
-~/.codeium/windsurf/
-  ├── mcp_config.json       # Windsurf global MCP config
-  └── skills/               # Windsurf global skills
-~/.factory/
-  ├── mcp.json              # Factory global MCP config
-  └── skills/               # Factory global skills
-
-# VSCode MCP config lives in AppData/Application Support:
-# Windows: %APPDATA%/Code/User/mcp.json
-# macOS:   ~/Library/Application Support/Code/User/mcp.json
-```
+### Local Install (Project-Specific)
+```
+your-project/
+├── .claude/
+│   └── skills/             # Claude Code skills
+├── .cursor/
+│   └── skills/             # Cursor skills
+├── .codex/
+│   └── skills/             # Codex skills
+├── .github/
+│   └── skills/             # VSCode skills
+├── .codeium/windsurf/
+│   └── skills/             # Windsurf skills
+└── .factory/
+    └── skills/             # Factory skills
+```
+
+### Global Install (User-Wide)
+```
+~/.claude/
+  └── skills/               # Claude Code global skills
+~/.cursor/
+  └── skills/               # Cursor global skills
+~/.codex/
+  └── skills/               # Codex global skills
+~/.github/
+  └── skills/               # VSCode global skills
+~/.codeium/windsurf/
+  └── skills/               # Windsurf global skills
+~/.factory/
+  └── skills/               # Factory global skills
+
+# MCP config files live in AppData/Application Support:
+# Windows: %APPDATA%/.claude.json
+# Windows: %APPDATA%/.cursor/mcp.json
+# Windows: %APPDATA%/.codex/config.toml
+# Windows: %APPDATA%/Code/User/mcp.json
+# Windows: %APPDATA%/.codeium/windsurf/mcp_config.json
+# Windows: %APPDATA%/.factory/mcp.json
+# macOS:   ~/Library/Application Support/<same paths as above>
+# Linux:   $XDG_CONFIG_HOME/<same paths as above> (or ~/.config)
+```
 
 **Note:** Paths are fully customizable per IDE in `config/settings.json`
 

package/config/settings.json

@@ -1,7 +1,6 @@
 {
   "skillsFolder": "a11y",
   "readmeTemplate": "deploy-README.md",
-  "supportLocalMcpInstallation": false,
   "skills": [
     {
       "name": "A11y Base Web Skill",
@@ -50,51 +49,50 @@
     {
       "id": "claude",
       "displayName": "Claude Code",
-      "mcpServerKey": "servers",
-      "globalMcpServerKey": "mcpServers",
+      "mcpServerKey": "mcpServers",
       "skillsFolder": ".claude/skills",
-      "mcpConfigFile": ".claude.json"
+      "mcpConfigFile": ".claude.json",
+      "nestSkillsFolder": false
     },
     {
       "id": "cursor",
       "displayName": "Cursor",
       "mcpServerKey": "mcpServers",
-      "globalMcpServerKey": "mcpServers",
       "skillsFolder": ".cursor/skills",
-      "mcpConfigFile": ".cursor/mcp.json"
+      "mcpConfigFile": ".cursor/mcp.json",
+      "nestSkillsFolder": true
     },
     {
       "id": "codex",
       "displayName": "Codex",
       "mcpServerKey": "mcp_servers",
-      "globalMcpServerKey": "mcp_servers",
       "skillsFolder": ".codex/skills",
-      "mcpConfigFile": ".codex/config.toml"
+      "mcpConfigFile": ".codex/config.toml",
+      "nestSkillsFolder": true
     },
     {
       "id": "vscode",
       "displayName": "VSCode",
       "mcpServerKey": "servers",
-      "globalMcpServerKey": "servers",
       "skillsFolder": ".github/skills",
-      "mcpConfigFile": ".github/mcp.json",
-      "globalMcpConfigFile": "Code/User/mcp.json"
+      "mcpConfigFile": "Code/User/mcp.json",
+      "nestSkillsFolder": true
     },
     {
       "id": "windsurf",
       "displayName": "Windsurf",
       "mcpServerKey": "servers",
-      "globalMcpServerKey": "servers",
       "skillsFolder": ".codeium/windsurf/skills",
-      "mcpConfigFile": ".codeium/windsurf/mcp_config.json"
+      "mcpConfigFile": ".codeium/windsurf/mcp_config.json",
+      "nestSkillsFolder": true
     },
     {
       "id": "factory",
       "displayName": "Factory",
       "mcpServerKey": "mcpServers",
-      "globalMcpServerKey": "mcpServers",
       "skillsFolder": ".factory/skills",
-      "mcpConfigFile": ".factory/mcp.json"
+      "mcpConfigFile": ".factory/mcp.json",
+      "nestSkillsFolder": true
     }
   ],
   "mcpServers": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a11y-devkit-deploy",
-  "version": "0.9.7",
+  "version": "1.0.0",
   "description": "CLI to deploy a11y skills and MCP servers across IDEs",
   "license": "MIT",
   "type": "module",

package/src/cli.js

@@ -231,7 +231,6 @@ async function run() {
   }));
 
   let scope = args.scope;
-  let mcpScope = null;
   let hostSelection = config.hostApplications.map((host) => host.id);
 
   if (!args.autoYes) {
@@ -250,26 +249,6 @@ async function run() {
           ],
           initial: 0,
         },
-        {
-          type: config.supportLocalMcpInstallation ? "select" : null,
-          name: "mcpScope",
-          message: "Install MCP configs locally or globally?",
-          choices: [
-            {
-              title: `Local to this project (${formatPath(projectRoot)})`,
-              value: "local",
-              description:
-                "Write to project-level host application config folders (version-controllable)",
-            },
-            {
-              title: "Global for this user",
-              value: "global",
-              description:
-                "Write to user-level host application config folders",
-            },
-          ],
-          initial: 0,
-        },
         {
           type: "multiselect",
           name: "hosts",
@@ -287,18 +266,12 @@ async function run() {
     );
 
     scope = scope || response.scope;
-    mcpScope =
-      response.mcpScope ||
-      (config.supportLocalMcpInstallation ? "local" : "global");
     hostSelection = response.hosts || hostSelection;
   }
 
   if (!scope) {
     scope = "local";
   }
-  if (!mcpScope) {
-    mcpScope = config.supportLocalMcpInstallation ? "local" : "global";
-  }
 
   if (!hostSelection.length) {
     warn(
@@ -308,7 +281,7 @@ async function run() {
   }
 
   info(`Skills scope: ${scope === "local" ? "Local" : "Global"}`);
-  info(`MCP scope: ${mcpScope === "local" ? "Local" : "Global"}`);
+  info("MCP configs: Global (user-level)");
 
   // Create temp directory for npm install
   const tempDir = path.join(getTempDir(), `.a11y-devkit-${Date.now()}`);
@@ -316,10 +289,17 @@ async function run() {
   const skillsSpinner = startSpinner("Installing skills from npm...");
 
   try {
-    const skillTargets =
-      scope === "local"
-        ? hostSelection.map((host) => hostPaths[host].localSkillsDir)
-        : hostSelection.map((host) => hostPaths[host].skillsDir);
+    const skillTargets = hostSelection.map((hostId) => {
+      const host = config.hostApplications.find((h) => h.id === hostId);
+      const targetPath =
+        scope === "local"
+          ? hostPaths[hostId].localSkillsDir
+          : hostPaths[hostId].skillsDir;
+      return {
+        path: targetPath,
+        shouldNest: host.nestSkillsFolder ?? true, // Default to true for backwards compatibility
+      };
+    });
 
     const skillNames = skillsToInstall.map((skill) =>
       typeof skill === "string" ? skill : skill.npmName,
@@ -340,24 +320,20 @@ async function run() {
 
   // Configure MCP servers using npx (no local installation needed!)
   const mcpSpinner = startSpinner("Updating MCP configurations...");
-  const mcpConfigPaths =
-    mcpScope === "local"
-      ? hostSelection.map((host) => hostPaths[host].localMcpConfig)
-      : hostSelection.map((host) => hostPaths[host].mcpConfig);
+  const mcpConfigPaths = hostSelection.map((host) => hostPaths[host].mcpConfig);
 
   for (let i = 0; i < hostSelection.length; i++) {
     const host = hostSelection[i];
-    const serverKey = mcpScope === "global"
-      ? hostPaths[host].globalMcpServerKey
-      : hostPaths[host].mcpServerKey;
+    const serverKey = hostPaths[host].mcpServerKey;
     await installMcpConfig(
       mcpConfigPaths[i],
       mcpServersToInstall,
       serverKey,
+      platformInfo,
     );
   }
   mcpSpinner.succeed(
-    `MCP configs updated for ${hostSelection.length} host application(s) (${mcpScope} scope).`,
+    `MCP configs updated for ${hostSelection.length} host application(s) (global scope).`,
   );
 
   // Clean up temporary directory
@@ -370,11 +346,15 @@ async function run() {
   info("MCP servers use npx - no local installation needed!");
   console.log("");
   success("Next Steps:");
-  const skillsFolderPath = config.skillsFolder ? `${config.skillsFolder}/` : "";
-  const skillsPath =
-    scope === "local"
-      ? `.claude/skills/${skillsFolderPath}README.md (or your host application's equivalent)`
-      : `~/.claude/skills/${skillsFolderPath}README.md (or your host application's global skills directory)`;
+  // Determine the README path based on the first selected host's nesting preference
+  const firstHost = config.hostApplications.find((h) => h.id === hostSelection[0]);
+  const firstHostSkillsPath = scope === "local"
+    ? hostPaths[hostSelection[0]].localSkillsDir
+    : hostPaths[hostSelection[0]].skillsDir;
+  const skillsFolderPath = (firstHost?.nestSkillsFolder ?? true) && config.skillsFolder
+    ? `${config.skillsFolder}/`
+    : "";
+  const skillsPath = `${firstHostSkillsPath}/${skillsFolderPath}a11y-devkit-README.md`;
   info(`📖 Check ${skillsPath} for comprehensive usage guide`);
   info("✨ Includes 70+ example prompts for all skills and MCP servers");
   info(
@@ -399,7 +379,6 @@ async function runUninstall(
   let removeSkills = true;
   let removeMcp = true;
   let scope = args.scope;
-  let mcpScope = null;
   let hostSelection = config.hostApplications.map((host) => host.id);
 
   if (!args.autoYes) {
@@ -456,29 +435,6 @@ async function runUninstall(
       });
     }
 
-    if (removeMcp && config.supportLocalMcpInstallation) {
-      questions.push({
-        type: "select",
-        name: "mcpScope",
-        message: "Remove MCP configs locally or globally?",
-        choices: [
-          {
-            title: `Local to this project (${formatPath(projectRoot)})`,
-            value: "local",
-            description:
-              "Remove from project-level host application config folders (version-controllable)",
-          },
-          {
-            title: "Global for this user",
-            value: "global",
-            description:
-              "Remove from user-level host application config folders",
-          },
-        ],
-        initial: 0,
-      });
-    }
-
     questions.push({
       type: "multiselect",
       name: "hosts",
@@ -495,7 +451,6 @@ async function runUninstall(
     });
 
     scope = scope || response.scope;
-    mcpScope = response.mcpScope || mcpScope;
     hostSelection = response.hosts || hostSelection;
   }
 
@@ -503,10 +458,6 @@ async function runUninstall(
     scope = "local";
   }
 
-  if (removeMcp && !mcpScope) {
-    mcpScope = config.supportLocalMcpInstallation ? "local" : "global";
-  }
-
   if (!hostSelection.length) {
     warn(
       "No host applications selected. Uninstall requires at least one host application.",
@@ -518,16 +469,23 @@ async function runUninstall(
     info(`Skills scope: ${scope === "local" ? "Local" : "Global"}`);
   }
   if (removeMcp) {
-    info(`MCP scope: ${mcpScope === "local" ? "Local" : "Global"}`);
+    info("MCP configs: Global (user-level)");
   }
 
   if (removeSkills) {
     const skillsSpinner = startSpinner("Removing skills...");
     try {
-      const skillTargets =
-        scope === "local"
-          ? hostSelection.map((host) => hostPaths[host].localSkillsDir)
-          : hostSelection.map((host) => hostPaths[host].skillsDir);
+      const skillTargets = hostSelection.map((hostId) => {
+        const host = config.hostApplications.find((h) => h.id === hostId);
+        const targetPath =
+          scope === "local"
+            ? hostPaths[hostId].localSkillsDir
+            : hostPaths[hostId].skillsDir;
+        return {
+          path: targetPath,
+          shouldNest: host.nestSkillsFolder ?? true, // Default to true for backwards compatibility
+        };
+      });
 
       const skillNames = config.skills.map((skill) =>
         typeof skill === "string" ? skill : skill.npmName,
@@ -549,19 +507,14 @@ async function runUninstall(
 
   if (removeMcp) {
     const mcpSpinner = startSpinner("Removing MCP configurations...");
-    const mcpConfigPaths =
-      mcpScope === "local"
-        ? hostSelection.map((host) => hostPaths[host].localMcpConfig)
-        : hostSelection.map((host) => hostPaths[host].mcpConfig);
+    const mcpConfigPaths = hostSelection.map((host) => hostPaths[host].mcpConfig);
 
     let removedCount = 0;
     const serverNames = config.mcpServers.map((server) => server.name);
 
     for (let i = 0; i < hostSelection.length; i++) {
       const host = hostSelection[i];
-      const serverKey = mcpScope === "global"
-        ? hostPaths[host].globalMcpServerKey
-        : hostPaths[host].mcpServerKey;
+      const serverKey = hostPaths[host].mcpServerKey;
       const result = await removeMcpConfig(
         mcpConfigPaths[i],
         serverNames,
@@ -572,7 +525,7 @@ async function runUninstall(
 
     if (removedCount > 0) {
       mcpSpinner.succeed(
-        `Removed ${removedCount} MCP entries from ${hostSelection.length} host application(s) (${mcpScope} scope).`,
+        `Removed ${removedCount} MCP entries from ${hostSelection.length} host application(s) (global scope).`,
       );
     } else {
       mcpSpinner.succeed("No matching MCP entries found to remove.");
@@ -640,40 +593,6 @@ async function runGitMcpInstallation(
     },
   );
 
-  // Prompt for MCP Config Scope (where to write MCP configurations)
-  // Skip if local MCP installation is not supported
-  let mcpScopeResponse = {
-    mcpScope: config.supportLocalMcpInstallation ? null : "global",
-  };
-
-  if (config.supportLocalMcpInstallation) {
-    mcpScopeResponse = await prompts(
-      {
-        type: "select",
-        name: "mcpScope",
-        message: "Where to write MCP configurations?",
-        choices: [
-          {
-            title: `Local to this project (${formatPath(projectRoot)})`,
-            value: "local",
-            description: "Write to project-level IDE config folders",
-          },
-          {
-            title: "Global for this user",
-            value: "global",
-            description: "Write to user-level IDE config folders",
-          },
-        ],
-        initial: 0,
-      },
-      {
-        onCancel: () => {
-          warn("Git MCP installation cancelled.");
-          process.exit(0);
-        },
-      },
-    );
-  }
 
   // Prompt for host application selection
   const hostChoices = config.hostApplications.map((host) => ({
@@ -707,10 +626,9 @@ async function runGitMcpInstallation(
   }
 
   const repoScope = repoScopeResponse.repoScope;
-  const mcpScope = mcpScopeResponse.mcpScope;
 
   info(`Repository clone scope: ${repoScope === "local" ? "Local" : "Global"}`);
-  info(`MCP config scope: ${mcpScope === "local" ? "Local" : "Global"}`);
+  info("MCP configs: Global (user-level)");
 
   // Install Git MCP
   const gitSpinner = startSpinner("Cloning Git repository...");
@@ -740,10 +658,7 @@ async function runGitMcpInstallation(
   // Install MCP configurations to selected host applications
   const mcpConfigSpinner = startSpinner("Updating MCP configurations...");
 
-  const mcpConfigPaths =
-    mcpScope === "local"
-      ? hostSelection.map((host) => hostPaths[host].localMcpConfig)
-      : hostSelection.map((host) => hostPaths[host].mcpConfig);
+  const mcpConfigPaths = hostSelection.map((host) => hostPaths[host].mcpConfig);
 
   // Construct the MCP server configuration with absolute path
   const mcpServerConfig = {
@@ -769,18 +684,17 @@ async function runGitMcpInstallation(
 
   for (let i = 0; i < hostSelection.length; i++) {
     const host = hostSelection[i];
-    const serverKey = mcpScope === "global"
-      ? hostPaths[host].globalMcpServerKey
-      : hostPaths[host].mcpServerKey;
+    const serverKey = hostPaths[host].mcpServerKey;
     await installMcpConfig(
       mcpConfigPaths[i],
       [mcpServerConfig],
       serverKey,
+      platformInfo,
     );
   }
 
   mcpConfigSpinner.succeed(
-    `MCP configs updated for ${hostSelection.length} host application(s) (${mcpScope} scope).`,
+    `MCP configs updated for ${hostSelection.length} host application(s) (global scope).`,
   );
 
   // Display success message

package/src/installers/mcp.js

@@ -143,7 +143,7 @@ async function loadConfig(filePath) {
   return isTomlFile(filePath) ? loadToml(filePath) : loadJson(filePath);
 }
 
-function mergeServers(existing, incoming, serverKey = "servers") {
+function mergeServers(existing, incoming, serverKey = "servers", platformInfo = null) {
   const existingServers = existing[serverKey] && typeof existing[serverKey] === "object"
     ? existing[serverKey]
     : {};
@@ -151,9 +151,18 @@ function mergeServers(existing, incoming, serverKey = "servers") {
   const merged = { ...existing, [serverKey]: { ...existingServers } };
 
   for (const server of incoming) {
+    let command = server.command;
+    let args = server.args || [];
+
+    // On Windows, wrap npx commands with cmd /c
+    if (platformInfo?.isWindows && command === "npx") {
+      command = "cmd";
+      args = ["/c", "npx", ...args];
+    }
+
     const serverConfig = {
-      command: server.command,
-      args: server.args || [],
+      command,
+      args,
       startup_timeout_sec: 30
     };
 
@@ -201,10 +210,10 @@ function removeServers(existing, removeNames, serverKey = "servers") {
   return { updated, removed };
 }
 
-async function installMcpConfig(configPath, servers, serverKey = "servers") {
+async function installMcpConfig(configPath, servers, serverKey = "servers", platformInfo = null) {
   await fs.mkdir(path.dirname(configPath), { recursive: true });
   const existing = await loadConfig(configPath);
-  const updated = mergeServers(existing, servers, serverKey);
+  const updated = mergeServers(existing, servers, serverKey, platformInfo);
 
   if (isTomlFile(configPath)) {
     await fs.writeFile(configPath, stringifySimpleToml(updated), "utf8");

package/src/installers/skills.js

@@ -77,7 +77,7 @@ async function removeDirIfEmpty(targetDir) {
  * 4. Returns temp directory path for cleanup
  *
  * @param {string[]} skills - Array of npm package names
- * @param {string[]} targetDirs - Array of target directories to install skills to
+ * @param {Array<{path: string, shouldNest: boolean}>} targetConfigs - Array of target configs with path and nesting preference
  * @param {string} tempDir - Temporary directory for npm install
  * @param {string} skillsFolder - Optional subfolder name to bundle skills (e.g., "a11y")
  * @param {string} readmeTemplate - README template filename from templates folder
@@ -85,7 +85,7 @@ async function removeDirIfEmpty(targetDir) {
  */
 async function installSkillsFromNpm(
   skills,
-  targetDirs,
+  targetConfigs,
   tempDir,
   skillsFolder = null,
   readmeTemplate = "deploy-README.md",
@@ -117,9 +117,12 @@ async function installSkillsFromNpm(
   const nodeModulesDir = path.join(tempDir, "node_modules");
   let installedCount = 0;
 
-  for (const targetDir of targetDirs) {
+  for (const targetConfig of targetConfigs) {
+    const targetDir = targetConfig.path;
+    const shouldNest = targetConfig.shouldNest;
+
     // Determine the actual skills directory (with or without bundle folder)
-    const skillsDir = skillsFolder
+    const skillsDir = shouldNest && skillsFolder
       ? path.join(targetDir, skillsFolder)
       : targetDir;
 
@@ -156,7 +159,7 @@ async function installSkillsFromNpm(
   }
 
   return {
-    installed: installedCount / targetDirs.length,
+    installed: installedCount / targetConfigs.length,
     tempDir,
   };
 }
@@ -165,21 +168,24 @@ async function installSkillsFromNpm(
  * Remove skills installed by this tool from target directories.
  *
  * @param {string[]} skills - Array of npm package names
- * @param {string[]} targetDirs - Array of target directories to uninstall from
+ * @param {Array<{path: string, shouldNest: boolean}>} targetConfigs - Array of target configs with path and nesting preference
  * @param {string} skillsFolder - Optional subfolder name used for bundled skills
  * @param {string} readmeTemplate - README template filename from templates folder
  * @returns {Promise<{removed: number}>}
  */
 async function uninstallSkillsFromTargets(
   skills,
-  targetDirs,
+  targetConfigs,
   skillsFolder = null,
   readmeTemplate = "deploy-README.md",
 ) {
   let removedCount = 0;
 
-  for (const targetDir of targetDirs) {
-    const skillsDir = skillsFolder
+  for (const targetConfig of targetConfigs) {
+    const targetDir = targetConfig.path;
+    const shouldNest = targetConfig.shouldNest;
+
+    const skillsDir = shouldNest && skillsFolder
       ? path.join(targetDir, skillsFolder)
       : targetDir;
 
@@ -198,7 +204,7 @@ async function uninstallSkillsFromTargets(
       await fs.rm(readmePath, { force: true });
     }
 
-    if (skillsFolder) {
+    if (shouldNest && skillsFolder) {
       await removeDirIfEmpty(skillsDir);
     }
   }

package/src/paths.js

@@ -36,32 +36,28 @@ function getHostApplicationPaths(projectRoot, platformInfo = getPlatform(), host
   const paths = {};
 
   for (const host of hostConfigs) {
-    // Default paths for local scope (relative to home or project)
+    // Default paths for global scope (relative to home)
     const skillsFolder = host.skillsFolder || `.${host.id}/skills`;
     const mcpConfigFile = host.mcpConfigFile || `.${host.id}/mcp.json`;
 
-    // MCP config: use AppData/Application Support if globalMcpConfigFile specified, otherwise home
+    // MCP config: use AppData/Application Support for config files
     // appSupport resolves to:
     //   - Windows: %APPDATA% (e.g., C:\Users\name\AppData\Roaming)
     //   - macOS: ~/Library/Application Support
     //   - Linux: $XDG_CONFIG_HOME or ~/.config
-    const globalMcpConfig = host.globalMcpConfigFile
-      ? path.join(appSupport, host.globalMcpConfigFile)
-      : path.join(home, mcpConfigFile);
+    const mcpConfig = path.join(appSupport, mcpConfigFile);
 
-    // Skills always use home directory (skills live at project level, not in AppData)
-    const globalSkillsDir = path.join(home, skillsFolder);
+    // Skills always use home directory
+    const skillsDir = path.join(home, skillsFolder);
 
-    paths[host.id] = {
-      name: host.displayName,
-      mcpConfig: globalMcpConfig,
-      localMcpConfig: path.join(projectRoot, mcpConfigFile),
-      mcpServerKey: host.mcpServerKey,
-      globalMcpServerKey: host.globalMcpServerKey || host.mcpServerKey,
-      skillsDir: globalSkillsDir,
-      localSkillsDir: path.join(projectRoot, skillsFolder)
-    };
-  }
+    paths[host.id] = {
+      name: host.displayName,
+      mcpConfig: mcpConfig,
+      mcpServerKey: host.mcpServerKey,
+      skillsDir: skillsDir,
+      localSkillsDir: path.join(projectRoot, skillsFolder) // Still needed for skills scope
+    };
+  }
 
   return paths;
 }
@@ -81,4 +77,4 @@ export {
   getHostApplicationPaths,
   getTempDir,
   getMcpRepoDir
-};
+};