# Quick ↔ Kiro Quickstart (for Quick Desktop)

Agent-executable setup for AWSentral MCP + Quick ↔ Kiro collaboration. When a user uploads this file and says "execute," follow each phase in order. Run what you can, prompt the user for what you can't.

---

## Phase 1: Detect OS & Set Up Environment

First, detect the user's operating system:

```bash
uname -s
```

### If macOS (Darwin):

Run all four checks in one pass:
```bash
echo "=== node ===" && node --version && echo "=== toolbox ===" && toolbox --version && echo "=== aim ===" && aim --version && echo "=== mwinit ===" && mwinit --version
```

Evaluate results and auto-install anything missing:

- **node**: Must be v22+. If missing/outdated:
  ```bash
  brew install mise 2>/dev/null || curl -fsSL https://mise.run | sh
  mise use -g node@24
  ```

- **toolbox**: If missing, try automated install first:
  ```bash
  brew tap amzn/toolbox 2>/dev/null && brew install toolbox 2>/dev/null
  ```
  If that fails (brew tap not available), try:
  ```bash
  curl -fsSL https://buildertoolbox.amazon.dev/install.sh | bash 2>/dev/null
  ```
  If both fail → tell the user: *"Builder Toolbox couldn't be installed automatically. Visit https://w.amazon.com/bin/view/BuilderToolbox/ to download the installer, then come back and say 'continue'."* Wait for confirmation.

- **aim**: If missing (but toolbox is present):
  ```bash
  toolbox install aim
  ```

- **mwinit**: If stale/failing → tell user to run `mwinit` in their terminal and confirm before continuing

### If Windows (detected by `uname` failing or returning MINGW/MSYS, or user confirms Windows):

**⚠️ All `toolbox`, `aim`, and `mwinit` commands must run inside WSL (Windows Subsystem for Linux), not in PowerShell or CMD.**

Walk the user through this setup:

**Step 1 — Check for WSL:**
Ask the user: *"Open PowerShell and run `wsl --list`. Do you see an installed Linux distribution (e.g., Ubuntu)?"*

- If **yes** → tell them to open WSL (search "Ubuntu" in Start menu) and continue from there.
- If **no** → guide them:
  ```
  1. Open PowerShell as Administrator
  2. Run: wsl --install
  3. Restart the computer
  4. Open "Ubuntu" from the Start menu
  5. Set up a username/password when prompted
  ```
  Wait for confirmation before continuing.

**Step 2 — Install prerequisites inside WSL:**
Once inside WSL, run each block in order:

```bash
# Install Node.js via mise
curl -fsSL https://mise.run | sh
mise use -g node@24
```

```bash
# Install Builder Toolbox — try automated first
curl -fsSL https://buildertoolbox.amazon.dev/install.sh | bash 2>/dev/null
```

If the curl install fails, tell the user:
> *"Builder Toolbox couldn't be installed automatically. Visit https://w.amazon.com/bin/view/BuilderToolbox/ from your browser, download the Linux installer, and run it inside WSL. Then say 'continue'."*

Wait for confirmation, then:

```bash
# Install aim via toolbox
toolbox install aim
```

**Step 4 — Verify inside WSL:**
```bash
echo "=== node ===" && node --version && echo "=== toolbox ===" && toolbox --version && echo "=== aim ===" && aim --version && echo "=== mwinit ===" && mwinit --version
```

**Step 5 — Refresh Midway inside WSL:**
```bash
mwinit -s
```

> **Important Windows note for later phases:** Quick and Kiro run natively on Windows but `aim`/`toolbox` run inside WSL. When configuring MCP command paths in Phase 3 and 4, use the `wsl.exe` wrapper:
> - Command: `wsl.exe /home/<wsl-username>/.toolbox/bin/aws-sentral-mcp`
> - Get the WSL path by running inside WSL: `command -v aws-sentral-mcp`

### For both macOS and Windows:

**Cannot be checked by Quick — ask the user to confirm:**
- "Do you have Kiro installed and running?" → If no: https://kiro.dev/
- "Can you log into AWSentral at https://aws-crm.lightning.force.com/?" → If no: request SFDC access via their manager.

---

## Phase 2: Install AWSentral MCP

> **Windows:** Run these commands inside WSL, not PowerShell.

Run:
```bash
aim mcp install aws-sentral-mcp
```

If that fails, try the fallback:
```bash
toolbox registry add s3://buildertoolbox-registry-aws-sentral-mcp-registry-us-west-2/tools.json
toolbox install aws-sentral-mcp
```

Verify:
```bash
command -v aws-sentral-mcp
```
→ Should return a path like `~/.toolbox/bin/aws-sentral-mcp`. Save this path — it's needed in Phase 3 and 4.

If `command -v` returns nothing, both install methods failed. Stop and tell the user to check [#amazon-quick-desktop-beta-feedback](https://amazon.enterprise.slack.com/archives/C0ASRR957GU) for help.

---

## Phase 3: Configure Quick Desktop MCP

Edit `~/.quickwork/mcp_config.json`. If the file exists, merge this entry into the existing `servers` array. If it doesn't exist, create it.

**macOS config:**
```json
{
  "servers": [
    {
      "id": "aws-sentral-mcp",
      "name": "AWSentral MCP",
      "transport": "stdio",
      "enabled": true,
      "command": "<full path from Phase 2>",
      "env": {
        "PATH": "<output of: echo $HOME>/.toolbox/bin:/usr/local/bin:/usr/bin:/bin",
        "HOME": "<output of: echo $HOME>"
      }
    }
  ]
}
```

**Windows config** (uses `wsl.exe` wrapper since toolbox is inside WSL):
```json
{
  "servers": [
    {
      "id": "aws-sentral-mcp",
      "name": "AWSentral MCP",
      "transport": "stdio",
      "enabled": true,
      "command": "wsl.exe",
      "args": ["<full WSL path from Phase 2, e.g., /home/username/.toolbox/bin/aws-sentral-mcp>"],
      "env": {}
    }
  ]
}
```

> **Windows:** The `~/.quickwork/` folder is on the Windows filesystem (e.g., `C:\Users\<name>\.quickwork\`), not inside WSL. Edit it from Windows Explorer or PowerShell.

After writing the config, verify the connection by calling any aws-sentral-mcp tool (e.g., `get_my_personal_details`). If it returns SFDC user data, Quick is connected. If it fails, see the Troubleshooting section.

---

## Phase 4: Configure Kiro (User Action Required)

Tell the user:

> **I've set up AWSentral MCP for Quick Desktop. Now you need to add it to Kiro manually:**
>
> Open Kiro and edit `.kiro/settings/mcp.json` in your workspace (or `~/.kiro/settings/mcp.json` for global). Merge this into the `mcpServers` object — don't replace existing servers:
>
> **macOS:**
> ```json
> {
>   "aws-sentral-mcp": {
>     "command": "<full path from Phase 2>",
>     "args": [],
>     "disabled": false,
>     "autoApprove": []
>   }
> }
> ```
>
> **Windows:**
> ```json
> {
>   "aws-sentral-mcp": {
>     "command": "wsl.exe",
>     "args": ["<full WSL path from Phase 2>"],
>     "disabled": false,
>     "autoApprove": []
>   }
> }
> ```
>
> Then ask Kiro: *"Search for my SFDC user details using aws-sentral-mcp."* Confirm it returns your Salesforce profile.

Wait for the user to confirm Kiro is connected before continuing.

---

## Phase 5: Create Handoff Directory

Run:
```bash
mkdir -p ~/quick-kiro-handoff
```

> **Windows:** This creates the directory inside WSL (`/home/<user>/quick-kiro-handoff`). If Quick/Kiro need to access it from Windows, use the WSL mount: `\\wsl$\Ubuntu\home\<user>\quick-kiro-handoff` — or create it on the Windows filesystem instead and use that path in both tools.

---

## Phase 6: Summary

Tell the user:

> **Setup complete. Here's what's running:**
>
> - **AWSentral MCP** is installed and configured in both Quick Desktop and Kiro
> - **Handoff directory** created at `~/quick-kiro-handoff/`
>
> **How the collaboration works:**
> - I (Quick) monitor Slack, email, and calendar every 15 min and write signals to `~/quick-kiro-handoff/` as `YYYY-MM-DD_<agent>_<type>.md`
> - Kiro reads handoff files, executes the action (SFDC update, email draft, account prep, or analysis), writes output back with a `kiro_` prefix, and summarizes what it did
> - **I (Quick)** handle automated bulk work (monthly tech activity logging)
> - **Kiro** handles on-demand work (opportunity updates, contact roles, insights, account summaries)
>
> If you hit issues, check [#amazon-quick-desktop-beta-feedback](https://amazon.enterprise.slack.com/archives/C0ASRR957GU).

---

## Troubleshooting

If any phase fails, check these in order:

| Problem | Fix |
|---------|-----|
| MCP stays in Error / shell timeout | Use full binary path (from `command -v`), not bare command name |
| Silent auth failure | User runs `mwinit` to refresh Midway |
| SFDC permission errors | User confirms login at https://aws-crm.lightning.force.com/ |
| MCP config disappears after restart | Edit `~/.quickwork/mcp_config.json` directly |
| Quick hangs when adding MCP | Force-quit, restart |
| `aim doesn't support windows` | You're running in PowerShell/CMD — open WSL (Ubuntu) and run from there |
| WSL not installed | PowerShell (Admin): `wsl --install`, restart, then open Ubuntu |
| `toolbox` not found in WSL | Try `curl -fsSL https://buildertoolbox.amazon.dev/install.sh \| bash`. If that fails, follow Linux instructions at https://w.amazon.com/bin/view/BuilderToolbox/ |
| Windows: MCP connects but no data | Check `mwinit -s` was run inside WSL (Midway certs are per-environment) |
| Windows: config file not found | Quick config is on Windows filesystem (`C:\Users\<name>\.quickwork\`), not inside WSL. Check both locations. |
| Windows: handoff dir not accessible | Use `\\wsl$\Ubuntu\home\<user>\` to access WSL files from Windows, or create the handoff dir on the Windows filesystem |