# Running AiMe (aime-local) on Windows

This guide explains how to build, configure, and run **AiMe (aime-local)** on Windows for local MCP tool access with ChatGPT or any MCP client (Claude Desktop, Cursor, etc.).

---

## 1. Prerequisites

- **Windows 10 / 11 x64**
- **Node.js >= 24.0.0**
- **PowerShell 5.1+** (for building native Win32 helpers)
- **MSVC Build Tools / C++ compiler** (included with Visual Studio or Windows SDK for compiling native helper `.exe` files)

---

## 2. Build

Compile all native C++ Win32 security helpers and transpile TypeScript:

```powershell
npm run build
```

This builds:
1. `build/native/aime-safe-fs-win32.exe` (Handle-based containment & SafeFs)
2. `build/native/aime-confirmation-ui-win32.exe` (Native mutation approval dialog)
3. `build/native/aime-process-runner-win32.exe` (Job Object process runner)
4. `build/native/aime-secret-store-win32.exe` (DPAPI protected key storage)
5. `build/native/aime-device-identity-win32.exe` (CNG ECDSA key identity)
6. `build/native/aime-personal-connect-setup-win32.exe` (First-run setup wizard)
7. `build/native/aime-local-modify-launcher-win32.exe` (Unmanaged packaged launcher)
8. All JavaScript runtime files under `dist/`

---

## 3. Configuration Profile

Create a profile JSON file (e.g. `C:\AiMe\profile.json`):

```json
{
  "schemaVersion": 2,
  "profileId": "profile_0123456789abcdef0123456789abcdef",
  "profileRevision": 1,
  "roots": [
    {
      "id": "workspace",
      "path": "C:\\projects\\my-workspace",
      "access": "modify"
    }
  ],
  "capabilities": [
    "get_status",
    "list_directory",
    "read_text_file",
    "search_text_files",
    "create_text_file",
    "replace_text_file",
    "preview_patch",
    "apply_patch",
    "rollback_change"
  ],
  "confirmationPolicy": {
    "filesystemMutation": "always"
  },
  "auditPath": "C:\\AiMe\\audit.jsonl",
  "rollbackDirectory": "C:\\AiMe\\rollback",
  "limits": {
    "maxDirectoryEntries": 100,
    "maxFileBytes": 524288,
    "maxWriteBytes": 524288,
    "maxPatchBytes": 131072,
    "maxPatchHunks": 128,
    "maxPreviewBytes": 131072,
    "maxMutationOperations": 64,
    "maxRollbackBytes": 2097152,
    "rollbackRetentionOperations": 64,
    "maxSearchBytes": 67108864,
    "maxSearchDepth": 32,
    "maxSearchDurationMs": 10000,
    "maxSearchFiles": 10000,
    "maxSearchMatches": 500,
    "maxSearchResultBytes": 131072
  }
}
```

---

## 4. Running Modes

### Mode 0: One-Click Connection for ChatGPT (Recommended) 🚀

The simplest way to connect ChatGPT to your local machine. Automatically initializes configuration, starts the MCP server, connects a secure HTTPS tunnel, and **copies the URL directly to your clipboard**:

```powershell
npm start
```

When run, you get:
```text
========================================================================
🎉 AiMe is READY and CONNECTED!

📋 Server URL (Copied to your Clipboard automatically!):
   👉 https://xxxx.trycloudflare.com/sse

💡 How to connect in ChatGPT:
   1. Open ChatGPT -> Click 'ปลั๊กอินใหม่' (New Plugin)
   2. In 'URL เซิร์ฟเวอร์', Press Ctrl + V to paste
   3. Select Authentication: 'ไม่มีการพิสูจน์ตัวตน' (None)
   4. Check 'ฉันเข้าใจและฉันต้องการดำเนินการต่อ'
   5. Click 'สร้าง' (Create)
========================================================================
```

### Mode A: Stdio MCP Server (Read-only)

Run with standard read-only tool capabilities:
```powershell
npm run start:stdio -- --profile C:\AiMe\profile.json
```

### Mode B: Local Modify Stdio Server (With SafeFs & Native UI Confirmation)

Run with full SafeFs modify, rollback, and native confirmation prompts:
```powershell
npm run start:local-modify:stdio -- --profile C:\AiMe\profile.json
```

### Mode C: Live HTTP/SSE MCP Server (Direct URL for ChatGPT)

Run as an HTTP/SSE server that outputs a URL to copy straight into ChatGPT's **"ปลั๊กอินใหม่"** -> **"URL เซิร์ฟเวอร์"**:

```powershell
npm run start:http -- --config C:\Users\gunnc\AppData\Local\AiMe\profile.json --port 3100
```

When started, it displays:
```text
========================================================================
🚀 AiMe MCP HTTP/SSE Server is LIVE and READY!
📡 Listening on: http://0.0.0.0:3100

👉 Server URL for ChatGPT / MCP Clients:
   http://localhost:3100/sse

💡 In ChatGPT "ปลั๊กอินใหม่":
   1. Paste the URL above in "URL เซิร์ฟเวอร์"
   2. Select Authentication: "ไม่มี" (None)
   3. Check "ฉันเข้าใจ..." and click "สร้าง" (Create)
========================================================================
```

### Mode D: Desktop MCP Client Configuration (Claude Desktop, Cursor, etc.)

In your desktop client's MCP configuration (`claude_desktop_config.json`, etc.):

```json
{
  "mcpServers": {
    "aime": {
      "command": "node",
      "args": [
        "D:\\projects\\GPT@ME\\dist\\src\\windows-local-modify-stdio-main.js",
        "--profile",
        "C:\\Users\\gunnc\\AppData\\Local\\AiMe\\profile.json"
      ]
    }
  }
}
```

---

## 5. Security & Verification

- **FullSessionAuthority**: Grants for generic process execution are gated by TTL, Emergency Stop, and session matching.
- **Rollback & Repair**: In case of interrupted transactions, `OperatorRepairManager` (`src/tools/operator-repair.ts`) non-destructively reconciles pending records back to `ready`.
- **Protected Audit**: All file mutations, approvals, and denials are recorded in the append-only JSONL audit sink.
