[BETA] AI-Powered Group Permissions Automation for PPlus

git clone https://github.com/MasterteamSA/PPlus-Agent.git
cd PPlus-Agent
npm install && npm run build

git clone https://github.com/MasterteamSA/pplus-knowledge.git

{
  "mcpServers": {
    "pplus-knowledge": {
      "command": "node",
      "args": ["/full/path/to/PPlus-Agent/dist/index.js"],
      "env": {
        "PPLUS_KNOWLEDGE_PATH": "/full/path/to/pplus-knowledge/knowledge"
      }
    }
  }
}

I need you to automate PPlus user group permissions using an Excel accessibility matrix.

**Inputs:**
- Excel file: `{{PATH_TO_YOUR_EXCEL_FILE}}`
- Target instance: `{{YOUR_INSTANCE_URL}}` (e.g., https://g-pmo.masterteam.sa)
- Knowledge repo: https://github.com/MasterteamSA/pplus-knowledge

**What to do:**

1. **Read the Excel file** using pandas/openpyxl. Each sheet represents a level type (Portfolio, Program, Project). Row 3 contains role names as column headers. Below that, module headers (no checkmarks) alternate with action rows (with checkmarks). Parse this into a structured mapping: `{level -> module -> action -> [role names]}`.

2. **Connect to the PPlus instance** via the browser (Chrome MCP). Navigate to the admin groups page at `{{YOUR_INSTANCE_URL}}/admin/user-group/main/groups`. Log in if needed.

3. **Extract the auth token** from `localStorage.getItem('currentUser')` — the token is at `JSON.parse(currentUser).data.token`.

4. **Fetch all groups** via `GET /service/api/identity/Groups` with Bearer token. Map each group name from the Excel to its numeric group ID.

5. **Fetch the permission structure** via `GET /service/api/identity/Groups/{groupId}/Permissions` for any group. This returns the full permission tree with claim IDs:
   ```
   data[] -> levelName -> logs[] -> name (module) -> actions[] -> { id (claimId), name, isSelected }
   ```

6. **Build the claim mapping**: For each Excel entry (level + module + action + roles), find the matching `claimId` from the API permission structure. Use fuzzy matching for action names that may differ slightly (e.g., trailing spaces, "Update Milestone Progress" vs "Update Milestone Progress ").

7. **Apply permissions for each group**: For each group ID, determine which claimIds should be enabled (from Excel) and which should be disabled (not in Excel). Send individual PUT requests:
   ```
   PUT /service/api/identity/Groups/{groupId}/Permissions
   Content-Type: application/json
   Authorization: Bearer {token}
   Body: {"claimId": <id>, "isSelected": true/false}
   ```
   Each PUT updates ONE permission. Loop through all permissions for all groups.

8. **Verify**: After all updates, re-fetch permissions for each group and confirm the actual state matches the desired state from the Excel. Report any mismatches.

**Key API details (from the knowledge base):**
- Base URL pattern: `/service/api/` (not `/api/`)
- Auth: Bearer token from localStorage `currentUser.data.token`
- Groups endpoint: `GET /service/api/identity/Groups`
- Permissions endpoint: `GET|PUT /service/api/identity/Groups/{id}/Permissions`
- PUT payload: `{"claimId": <number>, "isSelected": <boolean>}` — one permission per call
- The permission tree has 4 levels: Portfolio, Program, Project, and optionally Strategic Project or Department

**Important notes:**
- Do NOT send arrays or the full permission tree as PUT body — it will return 500
- Each permission must be updated individually via separate PUT calls
- The API level name may have trailing spaces (e.g., "Project " vs "Project") — trim when matching
- Some modules in the Excel may not exist on the target instance — skip them gracefully
- Always disable permissions NOT in the Excel matrix (clean slate per group)

Excel Sheet                    API Response
-----------                    ------------
Level: "Portfolio"       -->   levelName: "Portfolio"
Module: "Tasks"          -->   logs[].name: "Tasks"
Action: "Add"            -->   actions[].name: "Add"
Roles: ["Admin", ...]         actions[].id: 785  <-- claimId

For each role in Excel:
  groupNameToId["Admin"] = 1
  PUT /Groups/1/Permissions { claimId: 785, isSelected: true }

Summary:
- Total permissions mapped from Excel: 125
- Skipped (not on instance): 4
- Total API updates: 315
- Success: 315, Failed: 0

Group Results:
  Admin:                    124 permissions enabled
  Technical Project Manager: 23 permissions enabled
  Portfolio Manager:         42 permissions enabled
  Program Owner:             31 permissions enabled
  Program Manager:           31 permissions enabled
  Director of Supervision:   62 permissions enabled
  Director General:          49 permissions enabled
  Quality & Compliance:       8 permissions enabled

Verification: 0 mismatches across all groups