a11y-devkit-deploy 0.7.1 → 0.8.0

package/README.md

@@ -1,8 +1,8 @@
 # A11y Devkit Deploy
 
-A **fully config-driven**, cross-platform CLI for deploying accessibility skills and MCP servers across Claude Code, Cursor, Codex, and VSCode.
+A **fully config-driven**, cross-platform CLI for deploying accessibility skills and MCP servers across multiple IDEs: Claude Code, Cursor, Codex, VSCode, Windsurf, and Factory.
 
-**Add new skills or MCP servers without writing code** - just edit the JSON config and re-run.
+**Add new skills, MCP servers, or entire IDEs without writing code** - just edit the JSON config and re-run.
 
 ## Install
 
@@ -27,8 +27,8 @@ a11y-devkit-deploy
 
 Once installation completes, you'll find a comprehensive usage guide in your IDE's skills directory:
 
-- **Local install**: `.claude/skills/README.md` (or `.cursor/skills/`, `.codex/skills/` depending on your IDE)
-- **Global install**: `~/.claude/skills/README.md` (or your IDE's global skills directory)
+- **Local install**: `.claude/skills/a11y/a11y-devkit-README.md` (or `.cursor/skills/a11y/`, `.codex/skills/a11y/` depending on your IDE)
+- **Global install**: `~/.claude/skills/a11y/a11y-devkit-README.md` (or your IDE's global skills directory)
 
 ### What's in the Guide
 
@@ -42,7 +42,7 @@ The bundled README includes:
 
 ### Preview the Guide
 
-You can preview the guide here: [templates/skills-README.md](templates/skills-README.md)
+You can preview the guide here: [templates/deploy-README.md](templates/deploy-README.md)
 
 ### Next Steps
 
@@ -75,7 +75,31 @@ This CLI automates the setup of accessibility tooling by:
      - **a11y-personas** - Accessibility personas for diverse user needs
      - **arc-issues** - Format AxeCore violations into standardized issue templates
 
-**Fully customizable** - add/remove skills or MCP servers by editing the config file.
+**Fully customizable** - add/remove skills, MCP servers, or entire IDEs by editing the config file.
+
+## Why This Tool?
+
+**Zero Hardcoded Values** - Every aspect of the tool is driven by `config/a11y.json`:
+- IDE paths and configuration files
+- Skills to install
+- 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"
+}
+```
+
+**Safe by Default** - Won't overwrite your existing:
+- Custom MCP servers in your IDE configs
+- Other skills in your skills directories
+- Creates backups if it encounters JSON parsing errors
 
 ### Skills Installed (Default)
 
@@ -118,9 +142,9 @@ The generated MCP config looks like this:
 
 ## Configuration
 
-The entire tool is **fully config-driven**. Edit `config/a11y.json` to customize everything without touching code:
+The entire tool is **fully config-driven**. Edit `config/a11y.json` to customize everything without touching code.
 
-### Example: Adding a New Skill
+### Adding a New Skill
 
 Simply add an object to the `skills` array with a `name` (npm package) and `description`:
 
@@ -139,7 +163,7 @@ Simply add an object to the `skills` array with a `name` (npm package) and `desc
 }
 ```
 
-### Example: Adding a New MCP Server
+### Adding a New MCP Server
 
 Add an object to the `mcpServers` array with name, description, command, and args:
 
@@ -162,40 +186,96 @@ Add an object to the `mcpServers` array with name, description, command, and arg
 }
 ```
 
+### Adding a New IDE
+
+Add an object to the `ides` array with the IDE's configuration:
+
+```json
+{
+  "ides": [
+    {
+      "id": "windsurf",
+      "displayName": "Windsurf",
+      "mcpServerKey": "servers",
+      "skillsFolder": ".codeium/windsurf/skills",
+      "mcpConfigFile": ".codeium/windsurf/mcp_config.json"
+    }
+  ]
+}
+```
+
+**IDE Configuration Properties:**
+- `id` - Unique identifier for the IDE
+- `displayName` - Human-readable name shown in prompts
+- `mcpServerKey` - MCP config key name (`"servers"` or `"mcpServers"`)
+- `skillsFolder` - Path to skills directory (relative to home/project root)
+- `mcpConfigFile` - Path to MCP config file (relative to home/project root)
+
 ### Config Structure
 
+- `skillsFolder` - Subfolder name to bundle skills under (e.g., "a11y")
+- `readmeTemplate` - README template file to copy into skills directories
 - `skills` - Array of skill objects with `name` (npm package) and `description`
-- `ideSkillsPaths` - IDE-specific skills directories (configurable per IDE)
-- `ideMcpPaths` - IDE-specific MCP config file paths
+- `ides` - Array of IDE configuration objects
 - `mcpServers` - MCP server definitions with name, description, command, and args
 
 All changes take effect immediately - just re-run the CLI to deploy your updated config.
 
+### Safe Merging
+
+The CLI **safely merges** with existing configurations:
+- **MCP configs** - Adds/updates only the specified servers, preserves others
+- **Skills** - Installs only the configured skills, preserves other skills in the directory
+- **Backups** - Creates `.bak` files if JSON parsing fails
+
 ## Directory Structure
 
 ### Local Install (Project-Specific)
 ```
 your-project/
-├── .claude/skills/          # Skills copied to Claude Code (if selected)
-├── .cursor/skills/          # Skills copied to Cursor (if selected)
-├── .codex/skills/           # Skills copied to Codex (if selected)
-└── .github/skills/          # Skills copied here for version control
+├── .claude/
+│   ├── mcp.json            # Claude Code MCP config
+│   └── skills/             # Claude Code skills
+├── .cursor/
+│   ├── mcp.json            # Cursor MCP config
+│   └── skills/             # Cursor skills
+├── .codex/
+│   ├── mcp.json            # 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/skills/            # Claude Code skills
-~/.cursor/skills/            # Cursor skills
-~/.codex/skills/             # Codex skills
-~/.vscode/skills/            # VSCode skills
+~/.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/
+  ├── mcp.json              # Codex global MCP config
+  └── skills/               # Codex global skills
+~/.github/
+  ├── mcp.json              # VSCode global MCP config
+  └── 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
 ```
 
-### MCP Configuration Locations
-
-MCP configurations are written to each IDE's OS-specific config path:
-- **macOS**: `~/Library/Application Support/{IDE}/mcp.json`
-- **Windows**: `%APPDATA%\{IDE}\mcp.json`
-- **Linux**: `~/.config/{IDE}/mcp.json`
+**Note:** Paths are fully customizable per IDE in `config/a11y.json`
 
 ## MCP Servers Included (Default)
 
@@ -208,3 +288,63 @@ MCP configurations are written to each IDE's OS-specific config path:
 | magentaa11y | `magentaa11y-mcp` | Component accessibility acceptance criteria |
 | a11y-personas | `a11y-personas-mcp` | Accessibility personas for diverse users |
 | arc-issues | `arc-issues-mcp` | AxeCore violation formatting |
+
+## Complete Config Example
+
+Here's what a complete `config/a11y.json` looks like:
+
+```json
+{
+  "skillsFolder": "a11y",
+  "readmeTemplate": "deploy-README.md",
+  "skills": [
+    {
+      "name": "a11y-base-web-skill",
+      "description": "Core accessibility testing utilities"
+    },
+    {
+      "name": "a11y-tester-skill",
+      "description": "Run accessibility tests"
+    }
+  ],
+  "ides": [
+    {
+      "id": "claude",
+      "displayName": "Claude Code",
+      "mcpServerKey": "servers",
+      "skillsFolder": ".claude/skills",
+      "mcpConfigFile": ".claude/mcp.json"
+    },
+    {
+      "id": "cursor",
+      "displayName": "Cursor",
+      "mcpServerKey": "mcpServers",
+      "skillsFolder": ".cursor/skills",
+      "mcpConfigFile": ".cursor/mcp.json"
+    },
+    {
+      "id": "windsurf",
+      "displayName": "Windsurf",
+      "mcpServerKey": "servers",
+      "skillsFolder": ".codeium/windsurf/skills",
+      "mcpConfigFile": ".codeium/windsurf/mcp_config.json"
+    }
+  ],
+  "mcpServers": [
+    {
+      "name": "wcag",
+      "description": "WCAG guidelines reference",
+      "command": "npx",
+      "args": ["-y", "wcag-mcp"]
+    },
+    {
+      "name": "aria",
+      "description": "ARIA specification reference",
+      "command": "npx",
+      "args": ["-y", "aria-mcp"]
+    }
+  ]
+}
+```
+
+Everything is customizable - add, remove, or modify any section to match your needs.

package/config/a11y.json

@@ -3,31 +3,45 @@
   "readmeTemplate": "deploy-README.md",
   "skills": [
     {
-      "name": "a11y-base-web-skill",
+      "name": "A11y Base Web Skill",
+      "npmName": "a11y-base-web-skill",
+      "npmURL": "https://www.npmjs.com/package/a11y-base-web-skill",
       "description": "Core accessibility testing utilities"
     },
     {
-      "name": "a11y-issue-writer-skill",
+      "name": "A11y Issue Writer Skill",
+      "npmName": "a11y-issue-writer-skill",
+      "npmURL": "https://www.npmjs.com/package/a11y-issue-writer-skill",
       "description": "Document accessibility issues"
     },
     {
-      "name": "a11y-tester-skill",
+      "name": "A11y Tester Skill",
+      "npmName": "a11y-tester-skill",
+      "npmURL": "https://www.npmjs.com/package/a11y-tester-skill",
       "description": "Run accessibility tests"
     },
     {
-      "name": "a11y-remediator-skill",
+      "name": "A11y Remediator Skill",
+      "npmName": "a11y-remediator-skill",
+      "npmURL": "https://www.npmjs.com/package/a11y-remediator-skill",
       "description": "Fix accessibility issues"
     },
     {
-      "name": "a11y-validator-skill",
+      "name": "A11y Validator Skill",
+      "npmName": "a11y-validator-skill",
+      "npmURL": "https://www.npmjs.com/package/a11y-validator-skill",
       "description": "Validate accessibility compliance"
     },
     {
-      "name": "web-standards-skill",
+      "name": "Web Standards Skill",
+      "npmName": "web-standards-skill",
+      "npmURL": "https://www.npmjs.com/package/web-standards-skill",
       "description": "Web standards reference"
     },
     {
-      "name": "a11y-audit-fix-agent-orchestrator-skill",
+      "name": "A11y Audit Fix Agent Orchestrator Skill",
+      "npmName": "a11y-audit-fix-agent-orchestrator-skill",
+      "npmURL": "https://www.npmjs.com/package/a11y-audit-fix-agent-orchestrator-skill",
       "description": "Orchestrate accessibility audits"
     }
   ],
@@ -58,7 +72,17 @@
       "displayName": "VSCode",
       "mcpServerKey": "servers",
       "skillsFolder": ".github/skills",
-      "mcpConfigFile": ".github/mcp.json"
+      "mcpConfigFile": ".github/mcp.json",
+      "globalPaths": {
+        "Win": {
+          "mcpConfigFile": "Code/User/mcp.json",
+          "skillsFolder": "Code/User/skills"
+        },
+        "macOS": {
+          "mcpConfigFile": "Code/User/mcp.json",
+          "skillsFolder": "Code/User/skills"
+        }
+      }
     },
     {
       "id": "windsurf",
@@ -106,5 +130,63 @@
       "command": "npx",
       "args": ["-y", "arc-issues-mcp"]
     }
+  ],
+  "profiles": [
+    {
+      "id": "developer",
+      "displayName": "Developer",
+      "description": "For developers building accessible applications",
+      "skills": ["a11y-base-web-skill"],
+      "mcpServers": ["magentaa11y"]
+    },
+    {
+      "id": "tester",
+      "displayName": "Tester/QA",
+      "description": "For QA engineers testing accessibility",
+      "skills": ["a11y-tester-skill"],
+      "mcpServers": ["arc-issues"]
+    },
+    {
+      "id": "a11y-sme",
+      "displayName": "Accessibility SME",
+      "description": "For accessibility subject matter experts",
+      "skills": ["web-standards-skill"],
+      "mcpServers": ["magentaa11y"]
+    },
+    {
+      "id": "product",
+      "displayName": "Product",
+      "description": "For product managers and owners",
+      "skills": ["a11y-base-web-skill"],
+      "mcpServers": ["magentaa11y"]
+    },
+    {
+      "id": "design",
+      "displayName": "Design",
+      "description": "For designers creating accessible experiences",
+      "skills": ["web-standards-skill"],
+      "mcpServers": ["aria"]
+    },
+    {
+      "id": "hybrid",
+      "displayName": "Hybrid (I want all the things)",
+      "description": "All skills and MCP servers for comprehensive accessibility support",
+      "skills": [
+        "a11y-base-web-skill",
+        "a11y-issue-writer-skill",
+        "a11y-tester-skill",
+        "a11y-remediator-skill",
+        "a11y-validator-skill",
+        "web-standards-skill",
+        "a11y-audit-fix-agent-orchestrator-skill"
+      ],
+      "mcpServers": [
+        "wcag",
+        "aria",
+        "magentaa11y",
+        "a11y-personas",
+        "arc-issues"
+      ]
+    }
   ]
 }

package/package.json

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

package/src/cli.js

@@ -4,9 +4,11 @@ import { fileURLToPath } from "url";
 import prompts from "prompts";
 
 import { header, info, warn, success, startSpinner, formatPath } from "./ui.js";
-import { getPlatform, getIdePaths, getTempDir } from "./paths.js";
+import { getPlatform, getIdePaths, getTempDir, getMcpRepoDir } from "./paths.js";
 import { installSkillsFromNpm, cleanupTemp } from "./installers/skills.js";
 import { installMcpConfig } from "./installers/mcp.js";
+import { getGitMcpPrompts, parseArgsString } from "./prompts/git-mcp.js";
+import { installGitMcp } from "./installers/git-mcp.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -32,6 +34,7 @@ function parseArgs(argv) {
       : args.has("--local")
         ? "local"
         : null,
+    gitMcp: args.has("--git-mcp"),
   };
 }
 
@@ -52,26 +55,115 @@ async function run() {
 
   header(
     `A11y Devkit Deploy v${pkg.version}`,
-    "Install skills + MCP servers across IDEs",
+    args.gitMcp
+      ? "Install MCP server from Git repository"
+      : "Install skills + MCP servers across IDEs",
   );
   info(`Detected OS: ${formatOs(platformInfo)}`);
 
-  console.log("\nSkills to install:");
-  config.skills.forEach((skill) => {
-    const name = typeof skill === "string" ? skill : skill.name;
-    const description =
-      typeof skill === "string"
-        ? "No description"
-        : skill.description || "No description";
-    console.log(`- ${name}: ${description}`);
-  });
+  // Branch to Git MCP installation flow
+  if (args.gitMcp) {
+    await runGitMcpInstallation(projectRoot, platformInfo, config, idePaths, args);
+    return;
+  }
 
-  console.log("\nMCP Servers to install:");
-  config.mcpServers.forEach((server) => {
-    const description = server.description || "No description";
-    console.log(`${server.name} - ${description}`);
-  });
-  console.log("");
+  // Prompt for profile selection
+  let selectedProfile = null;
+  let skillsToInstall = [];
+  let mcpServersToInstall = [];
+  let profileConfirmed = false;
+
+  while (!profileConfirmed) {
+    if (!args.autoYes && config.profiles) {
+      const profileChoices = config.profiles.map((profile) => ({
+        title: profile.displayName,
+        description: profile.description,
+        value: profile.id,
+      }));
+
+      const profileResponse = await prompts(
+        {
+          type: "select",
+          name: "profile",
+          message: "Select your profile:",
+          choices: profileChoices,
+        },
+        {
+          onCancel: () => {
+            warn("Setup cancelled.");
+            process.exit(0);
+          },
+        },
+      );
+
+      selectedProfile = config.profiles.find((p) => p.id === profileResponse.profile);
+
+      if (selectedProfile) {
+        // Filter skills based on profile
+        skillsToInstall = config.skills.filter((skill) => {
+          const skillNpmName = typeof skill === "string" ? skill : skill.npmName;
+          return selectedProfile.skills.includes(skillNpmName);
+        });
+
+        // Filter MCP servers based on profile
+        mcpServersToInstall = config.mcpServers.filter((server) =>
+          selectedProfile.mcpServers.includes(server.name),
+        );
+
+        console.log(`\n${selectedProfile.displayName} profile selected`);
+      }
+    } else {
+      // If no profiles or auto-yes, use all skills and servers
+      skillsToInstall = config.skills;
+      mcpServersToInstall = config.mcpServers;
+      profileConfirmed = true; // Skip confirmation for auto-yes
+    }
+
+    // Show what will be installed
+    if (!args.autoYes) {
+      console.log("\nSkills to install:");
+      skillsToInstall.forEach((skill) => {
+        const name = typeof skill === "string" ? skill : skill.name;
+        const description =
+          typeof skill === "string"
+            ? "No description"
+            : skill.description || "No description";
+        console.log(`  • ${name}`);
+        console.log(`    ${description}`);
+      });
+
+      console.log("\nMCP Servers to install:");
+      mcpServersToInstall.forEach((server) => {
+        const description = server.description || "No description";
+        console.log(`  • ${server.name}`);
+        console.log(`    ${description}`);
+      });
+      console.log("");
+
+      // Confirmation prompt
+      const confirmResponse = await prompts(
+        {
+          type: "confirm",
+          name: "continue",
+          message: "Continue with this configuration?",
+          initial: true,
+        },
+        {
+          onCancel: () => {
+            warn("Setup cancelled.");
+            process.exit(0);
+          },
+        },
+      );
+
+      if (confirmResponse.continue) {
+        profileConfirmed = true;
+      } else {
+        // User wants to go back - loop will restart profile selection
+        console.log("");
+      }
+    }
+  }
 
   const ideChoices = config.ides.map((ide) => ({
     title: ide.displayName,
@@ -81,7 +173,6 @@ async function run() {
   let scope = args.scope;
   let mcpScope = null;
   let ideSelection = config.ides.map((ide) => ide.id);
-  let installSkills = true;
 
   if (!args.autoYes) {
     const response = await prompts(
@@ -89,7 +180,7 @@ async function run() {
         {
           type: scope ? null : "select",
           name: "scope",
-          message: "Install skills + repo locally or globally?",
+          message: "Install skills locally or globally?",
           choices: [
             {
               title: `Local to this project (${formatPath(projectRoot)})`,
@@ -121,18 +212,10 @@ async function run() {
         {
           type: "multiselect",
           name: "ides",
-          message: "Configure MCP for which IDEs?",
+          message: "Configure for which IDEs?",
           choices: ideChoices,
           initial: ideChoices.map((_, index) => index),
         },
-        {
-          type: "toggle",
-          name: "installSkills",
-          message: "Install skills into IDE skills folders?",
-          active: "yes",
-          inactive: "no",
-          initial: true,
-        },
       ],
       {
         onCancel: () => {
@@ -145,7 +228,6 @@ async function run() {
     scope = scope || response.scope;
     mcpScope = response.mcpScope || "local";
     ideSelection = response.ides || ideSelection;
-    installSkills = response.installSkills;
   }
 
   if (!scope) {
@@ -166,33 +248,29 @@ async function run() {
   // Create temp directory for npm install
   const tempDir = path.join(getTempDir(), `.a11y-devkit-${Date.now()}`);
 
-  if (installSkills) {
-    const skillsSpinner = startSpinner("Installing skills from npm...");
+  const skillsSpinner = startSpinner("Installing skills from npm...");
 
-    try {
-      const skillTargets =
-        scope === "local"
-          ? ideSelection.map((ide) => idePaths[ide].localSkillsDir)
-          : ideSelection.map((ide) => idePaths[ide].skillsDir);
+  try {
+    const skillTargets =
+      scope === "local"
+        ? ideSelection.map((ide) => idePaths[ide].localSkillsDir)
+        : ideSelection.map((ide) => idePaths[ide].skillsDir);
 
-      const skillNames = config.skills.map((skill) =>
-        typeof skill === "string" ? skill : skill.name,
-      );
-      const result = await installSkillsFromNpm(
-        skillNames,
-        skillTargets,
-        tempDir,
-        config.skillsFolder,
-        config.readmeTemplate,
-      );
-      skillsSpinner.succeed(
-        `${result.installed} skills installed to ${skillTargets.length} IDE location(s).`,
-      );
-    } catch (error) {
-      skillsSpinner.fail(`Failed to install skills: ${error.message}`);
-    }
-  } else {
-    warn("Skipping skills install to IDE folders.");
+    const skillNames = skillsToInstall.map((skill) =>
+      typeof skill === "string" ? skill : skill.npmName,
+    );
+    const result = await installSkillsFromNpm(
+      skillNames,
+      skillTargets,
+      tempDir,
+      config.skillsFolder,
+      config.readmeTemplate,
+    );
+    skillsSpinner.succeed(
+      `${result.installed} skills installed to ${skillTargets.length} IDE location(s).`,
+    );
+  } catch (error) {
+    skillsSpinner.fail(`Failed to install skills: ${error.message}`);
   }
 
   // Configure MCP servers using npx (no local installation needed!)
@@ -206,7 +284,7 @@ async function run() {
     const ide = ideSelection[i];
     await installMcpConfig(
       mcpConfigPaths[i],
-      config.mcpServers,
+      mcpServersToInstall,
       idePaths[ide].mcpServerKey,
     );
   }
@@ -239,4 +317,198 @@ async function run() {
   info("Documentation: https://github.com/joe-watkins/a11y-devkit#readme");
 }
 
+async function runGitMcpInstallation(projectRoot, platformInfo, config, idePaths, args) {
+  // Check if --yes flag is used with --git-mcp
+  if (args.autoYes) {
+    warn("--yes flag not supported for Git MCP installation");
+    info("Interactive prompts required for Git MCP configuration");
+    process.exit(1);
+  }
+
+  console.log("\n");
+  info("Installing MCP server from Git repository");
+  console.log("");
+
+  // Collect Git MCP information
+  const gitMcpPrompts = getGitMcpPrompts();
+  const mcpInfo = await prompts(gitMcpPrompts, {
+    onCancel: () => {
+      warn("Git MCP installation cancelled.");
+      process.exit(0);
+    },
+  });
+
+  // Parse args string into array
+  const argsArray = parseArgsString(mcpInfo.args);
+
+  // Prompt for Repo Clone Scope (where to clone the Git repository)
+  const repoScopeResponse = await prompts(
+    {
+      type: "select",
+      name: "repoScope",
+      message: "Where to clone the Git repository?",
+      choices: [
+        {
+          title: `Local to this project (${formatPath(projectRoot)})`,
+          value: "local",
+          description: "Clone to .a11y-devkit/mcp-repos/ in project",
+        },
+        {
+          title: "Global for this user",
+          value: "global",
+          description: "Clone to user-level app support directory",
+        },
+      ],
+      initial: 0,
+    },
+    {
+      onCancel: () => {
+        warn("Git MCP installation cancelled.");
+        process.exit(0);
+      },
+    },
+  );
+
+  // Prompt for MCP Config Scope (where to write MCP configurations)
+  const 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 IDE selection
+  const ideChoices = config.ides.map((ide) => ({
+    title: ide.displayName,
+    value: ide.id,
+  }));
+
+  const ideResponse = await prompts(
+    {
+      type: "multiselect",
+      name: "ides",
+      message: "Configure MCP for which IDEs?",
+      choices: ideChoices,
+      initial: ideChoices.map((_, index) => index),
+    },
+    {
+      onCancel: () => {
+        warn("Git MCP installation cancelled.");
+        process.exit(0);
+      },
+    },
+  );
+
+  const ideSelection = ideResponse.ides || [];
+
+  if (!ideSelection.length) {
+    warn("No IDEs selected. MCP installation requires at least one IDE.");
+    process.exit(1);
+  }
+
+  const repoScope = repoScopeResponse.repoScope;
+  const mcpScope = mcpScopeResponse.mcpScope;
+
+  info(`Repository clone scope: ${repoScope === "local" ? "Local" : "Global"}`);
+  info(`MCP config scope: ${mcpScope === "local" ? "Local" : "Global"}`);
+
+  // Install Git MCP
+  const gitSpinner = startSpinner("Cloning Git repository...");
+
+  let mcpServer;
+  try {
+    mcpServer = await installGitMcp(
+      {
+        name: mcpInfo.name,
+        repoUrl: mcpInfo.repoUrl,
+        type: mcpInfo.type,
+        command: mcpInfo.command,
+        args: argsArray,
+        buildCommand: mcpInfo.buildCommand,
+      },
+      repoScope,
+      projectRoot,
+      platformInfo,
+      getMcpRepoDir,
+    );
+    gitSpinner.succeed(`Repository cloned to ${mcpServer.repoPath}`);
+  } catch (error) {
+    gitSpinner.fail(`Failed to install Git MCP: ${error.message}`);
+    process.exit(1);
+  }
+
+  // Install MCP configurations to selected IDEs
+  const mcpConfigSpinner = startSpinner("Updating MCP configurations...");
+
+  const mcpConfigPaths =
+    mcpScope === "local"
+      ? ideSelection.map((ide) => idePaths[ide].localMcpConfig)
+      : ideSelection.map((ide) => idePaths[ide].mcpConfig);
+
+  // Construct the MCP server configuration with absolute path
+  const mcpServerConfig = {
+    name: mcpServer.name,
+    type: mcpServer.type,
+    command: mcpServer.command,
+    args: mcpServer.args.length > 0 ? mcpServer.args : undefined,
+  };
+
+  // If args are provided, prepend the repo path to the first argument
+  // Otherwise, use the repo path as the only argument
+  if (mcpServerConfig.args && mcpServerConfig.args.length > 0) {
+    // Assume first arg is a relative path within the repo
+    mcpServerConfig.args = [
+      path.join(mcpServer.repoPath, mcpServerConfig.args[0]),
+      ...mcpServerConfig.args.slice(1),
+    ];
+  } else {
+    // No args provided - this might need to be handled differently
+    // For now, don't add any args
+    delete mcpServerConfig.args;
+  }
+
+  for (let i = 0; i < ideSelection.length; i++) {
+    const ide = ideSelection[i];
+    await installMcpConfig(
+      mcpConfigPaths[i],
+      [mcpServerConfig],
+      idePaths[ide].mcpServerKey,
+    );
+  }
+
+  mcpConfigSpinner.succeed(
+    `MCP configs updated for ${ideSelection.length} IDE(s) (${mcpScope} scope).`,
+  );
+
+  // Display success message
+  success("Git MCP installation complete!");
+  info(`Repository location: ${mcpServer.repoPath}`);
+  info(`MCP server '${mcpServer.name}' configured in ${ideSelection.length} IDE(s)`);
+  console.log("");
+  success("Next Steps:");
+  info("Restart your IDE to load the new MCP server");
+  info(`Repository cloned to: ${mcpServer.repoPath}`);
+  info("You can manually edit the MCP configuration files if needed");
+}
+
 export { run };

package/src/installers/git-mcp.js

@@ -0,0 +1,209 @@
+/**
+ * Git repository operations and MCP installation orchestration
+ */
+
+import fs from "fs/promises";
+import path from "path";
+import { spawn } from "child_process";
+import prompts from "prompts";
+import { warn, error as errorMsg } from "../ui.js";
+
+/**
+ * Helper function to check if a path exists
+ * @param {string} target - Path to check
+ * @returns {Promise<boolean>}
+ */
+async function pathExists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Runs a command using spawn
+ * @param {string} command - Command to run
+ * @param {string[]} args - Command arguments
+ * @param {object} options - Spawn options
+ * @returns {Promise<{stdout: string, stderr: string}>}
+ */
+function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: "pipe",
+      shell: true,
+      ...options,
+    });
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout?.on("data", (data) => {
+      stdout += data;
+    });
+    child.stderr?.on("data", (data) => {
+      stderr += data;
+    });
+
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+      reject(
+        new Error(
+          `${command} ${args.join(" ")} failed with code ${code}: ${stderr}`,
+        ),
+      );
+    });
+  });
+}
+
+/**
+ * Clones a Git repository to the target directory
+ * @param {string} repoUrl - Git repository URL
+ * @param {string} targetDir - Directory to clone into
+ * @returns {Promise<{success: boolean, stdout: string, stderr: string}>}
+ */
+export async function cloneGitRepo(repoUrl, targetDir) {
+  try {
+    const result = await run("git", ["clone", repoUrl, targetDir]);
+    return {
+      success: true,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    };
+  } catch (err) {
+    // Provide helpful error messages based on error type
+    const errorMessage = err.message.toLowerCase();
+
+    if (errorMessage.includes("authentication") || errorMessage.includes("fatal: could not read")) {
+      throw new Error(
+        `Authentication required for ${repoUrl}. Please ensure the repository is public or configure Git credentials.`,
+      );
+    }
+
+    if (errorMessage.includes("repository not found") || errorMessage.includes("not found")) {
+      throw new Error(
+        `Repository not found: ${repoUrl}. Please verify the URL is correct.`,
+      );
+    }
+
+    if (errorMessage.includes("git: command not found") || errorMessage.includes("'git' is not recognized")) {
+      throw new Error(
+        "Git is not installed. Please install Git and try again.",
+      );
+    }
+
+    // Generic error
+    throw new Error(`Failed to clone repository: ${err.message}`);
+  }
+}
+
+/**
+ * Executes build command in the repository directory
+ * @param {string} repoDir - Repository directory path
+ * @param {string} buildCommand - Build command to execute
+ * @returns {Promise<{success: boolean, stdout: string, stderr: string}>}
+ */
+export async function buildGitRepo(repoDir, buildCommand) {
+  try {
+    // Parse build command (handle multi-command strings like "npm install && npm run build")
+    // We'll execute the entire command string via shell
+    const result = await run(buildCommand, [], { cwd: repoDir });
+    return {
+      success: true,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    };
+  } catch (err) {
+    return {
+      success: false,
+      stdout: err.stdout || "",
+      stderr: err.stderr || err.message,
+    };
+  }
+}
+
+/**
+ * Removes a cloned repository directory
+ * @param {string} repoPath - Path to repository to remove
+ * @returns {Promise<void>}
+ */
+export async function cleanupGitRepo(repoPath) {
+  if (await pathExists(repoPath)) {
+    await fs.rm(repoPath, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Main orchestrator function for Git MCP installation
+ * @param {object} mcpConfig - MCP configuration {name, repoUrl, type, command, args, buildCommand}
+ * @param {string} repoScope - Where to clone repo ('local' | 'global')
+ * @param {string} projectRoot - Project root directory
+ * @param {object} platformInfo - Platform info object
+ * @param {Function} getMcpRepoDir - Function to get MCP repo directory
+ * @returns {Promise<{name: string, type: string, command: string, args: string[], repoPath: string}>}
+ */
+export async function installGitMcp(
+  mcpConfig,
+  repoScope,
+  projectRoot,
+  platformInfo,
+  getMcpRepoDir,
+) {
+  const { name, repoUrl, type, command, args, buildCommand } = mcpConfig;
+
+  // Determine repo storage location
+  const repoPath = getMcpRepoDir(repoScope, projectRoot, platformInfo, name);
+
+  // Check for existing MCP with same name
+  if (await pathExists(repoPath)) {
+    warn(`MCP server '${name}' already exists at ${repoPath}`);
+
+    const overwriteResponse = await prompts(
+      {
+        type: "confirm",
+        name: "overwrite",
+        message: "Overwrite existing installation?",
+        initial: false,
+      },
+      {
+        onCancel: () => {
+          throw new Error("Installation cancelled by user");
+        },
+      },
+    );
+
+    if (!overwriteResponse.overwrite) {
+      throw new Error("Installation cancelled - existing MCP not overwritten");
+    }
+
+    // Remove old directory
+    await cleanupGitRepo(repoPath);
+  }
+
+  // Clone repository
+  await cloneGitRepo(repoUrl, repoPath);
+
+  // Run build command (continue with warning if fails)
+  const buildResult = await buildGitRepo(repoPath, buildCommand);
+  if (!buildResult.success) {
+    warn("Build command failed but continuing with installation");
+    if (buildResult.stderr) {
+      console.error("Build error output:");
+      console.error(buildResult.stderr);
+    }
+  }
+
+  // Return MCP server object for config installation
+  return {
+    name,
+    type,
+    command,
+    args,
+    repoPath,
+  };
+}

package/src/installers/mcp.js

@@ -33,10 +33,17 @@ function mergeServers(existing, incoming, serverKey = "servers") {
   const merged = { ...existing, [serverKey]: { ...existingServers } };
 
   for (const server of incoming) {
-    merged[serverKey][server.name] = {
+    const serverConfig = {
       command: server.command,
       args: server.args || []
     };
+
+    // Include type if provided
+    if (server.type) {
+      serverConfig.type = server.type;
+    }
+
+    merged[serverKey][server.name] = serverConfig;
   }
 
   return merged;

package/src/paths.js

@@ -32,19 +32,45 @@ function getAppSupportDir(platformInfo = getPlatform()) {
 
 function getIdePaths(projectRoot, platformInfo = getPlatform(), ideConfigs = []) {
   const home = os.homedir();
+  const appSupport = getAppSupportDir(platformInfo);
   const paths = {};
 
   for (const ide of ideConfigs) {
-    // Use custom paths from config, or fall back to default pattern: ~/.{id}/
-    const skillsFolder = ide.skillsFolder || `.${ide.id}/skills`;
-    const mcpConfigFile = ide.mcpConfigFile || `.${ide.id}/mcp.json`;
+    // Default paths (used for local scope, and global scope if no overrides)
+    let skillsFolder = ide.skillsFolder || `.${ide.id}/skills`;
+    let mcpConfigFile = ide.mcpConfigFile || `.${ide.id}/mcp.json`;
+
+    // Check for platform-specific global path overrides
+    let globalSkillsFolder = skillsFolder;
+    let globalMcpConfigFile = mcpConfigFile;
+
+    if (ide.globalPaths) {
+      const platformKey = platformInfo.isWindows ? 'Win' : platformInfo.isMac ? 'macOS' : null;
+
+      if (platformKey && ide.globalPaths[platformKey]) {
+        const globalOverrides = ide.globalPaths[platformKey];
+
+        // Use app support directory + override path for global
+        if (globalOverrides.skillsFolder) {
+          globalSkillsFolder = globalOverrides.skillsFolder;
+        }
+        if (globalOverrides.mcpConfigFile) {
+          globalMcpConfigFile = globalOverrides.mcpConfigFile;
+        }
+      }
+    }
+
+    // Determine base directory for global paths
+    const useAppSupport = ide.globalPaths &&
+      (platformInfo.isWindows || platformInfo.isMac);
+    const globalBase = useAppSupport ? appSupport : home;
 
     paths[ide.id] = {
       name: ide.displayName,
-      mcpConfig: path.join(home, mcpConfigFile),
+      mcpConfig: path.join(globalBase, globalMcpConfigFile),
       localMcpConfig: path.join(projectRoot, mcpConfigFile),
       mcpServerKey: ide.mcpServerKey,
-      skillsDir: path.join(home, skillsFolder),
+      skillsDir: path.join(globalBase, globalSkillsFolder),
       localSkillsDir: path.join(projectRoot, skillsFolder)
     };
   }
@@ -52,9 +78,19 @@ function getIdePaths(projectRoot, platformInfo = getPlatform(), ideConfigs = [])
   return paths;
 }
 
+function getMcpRepoDir(scope, projectRoot, platformInfo, mcpName) {
+  if (scope === 'local') {
+    return path.join(projectRoot, '.a11y-devkit', 'mcp-repos', mcpName);
+  }
+
+  const appSupport = getAppSupportDir(platformInfo);
+  return path.join(appSupport, 'a11y-devkit', 'mcp-repos', mcpName);
+}
+
 export {
   getPlatform,
   getAppSupportDir,
   getIdePaths,
-  getTempDir
+  getTempDir,
+  getMcpRepoDir
 };

package/src/prompts/git-mcp.js

@@ -0,0 +1,140 @@
+/**
+ * Git MCP-specific prompt definitions and validation logic
+ */
+
+/**
+ * Validates MCP name according to rules:
+ * - Not empty
+ * - No spaces
+ * - Only alphanumeric characters and hyphens
+ * @param {string} name - MCP name to validate
+ * @returns {true | string} - true if valid, error message if invalid
+ */
+export function validateMcpName(name) {
+  if (!name || name.trim() === "") {
+    return "MCP name is required";
+  }
+
+  if (name.includes(" ")) {
+    return "MCP name cannot contain spaces";
+  }
+
+  const validPattern = /^[a-z0-9-]+$/i;
+  if (!validPattern.test(name)) {
+    return "MCP name can only contain letters, numbers, and hyphens";
+  }
+
+  return true;
+}
+
+/**
+ * Validates Git URL format (GitHub or GitLab)
+ * @param {string} url - Git repository URL to validate
+ * @returns {{ valid: boolean, provider: 'github'|'gitlab'|null, error: string|null }}
+ */
+export function validateGitUrl(url) {
+  if (!url || url.trim() === "") {
+    return {
+      valid: false,
+      provider: null,
+      error: "Git repository URL is required",
+    };
+  }
+
+  const gitUrlPattern =
+    /^https:\/\/(github\.com|gitlab\.com)\/[\w-]+\/[\w-]+(\.git)?$/;
+  const match = url.match(gitUrlPattern);
+
+  if (!match) {
+    if (url.includes("github.com") || url.includes("gitlab.com")) {
+      return {
+        valid: false,
+        provider: null,
+        error:
+          "Invalid Git URL format. Must be: https://github.com/user/repo.git or https://gitlab.com/user/repo.git",
+      };
+    }
+    return {
+      valid: false,
+      provider: null,
+      error: "Only GitHub and GitLab repositories are supported",
+    };
+  }
+
+  const provider = match[1].includes("github") ? "github" : "gitlab";
+
+  return {
+    valid: true,
+    provider,
+    error: null,
+  };
+}
+
+/**
+ * Parses comma-separated arguments string into array
+ * @param {string} argsString - Comma-separated arguments
+ * @returns {string[]} - Array of trimmed argument strings
+ */
+export function parseArgsString(argsString) {
+  if (!argsString || argsString.trim() === "") {
+    return [];
+  }
+
+  return argsString
+    .split(",")
+    .map((arg) => arg.trim())
+    .filter((arg) => arg !== "");
+}
+
+/**
+ * Returns prompts array for Git MCP configuration
+ * @returns {Array} - Array of prompt objects for use with prompts library
+ */
+export function getGitMcpPrompts() {
+  return [
+    {
+      type: "text",
+      name: "name",
+      message: "MCP Name (no spaces, alphanumeric with hyphens):",
+      validate: (value) => validateMcpName(value),
+    },
+    {
+      type: "text",
+      name: "repoUrl",
+      message: "Git Repository URL (GitHub or GitLab):",
+      validate: (value) => {
+        const result = validateGitUrl(value);
+        return result.valid ? true : result.error;
+      },
+    },
+    {
+      type: "select",
+      name: "type",
+      message: "MCP server transport type:",
+      choices: [
+        { title: "stdio", value: "stdio" },
+        { title: "http", value: "http" },
+        { title: "sse", value: "sse" },
+      ],
+      initial: 0,
+    },
+    {
+      type: "text",
+      name: "command",
+      message: "Command to run the MCP server:",
+      initial: "node",
+    },
+    {
+      type: "text",
+      name: "args",
+      message: "Arguments for the command (typically relative path to mcp .js example: js/index.js):",
+      initial: "",
+    },
+    {
+      type: "text",
+      name: "buildCommand",
+      message: "Build command:",
+      initial: "npm install",
+    },
+  ];
+}