# CloudSense Upgrade Compass

MCP server for CloudSense package upgrade assessment, customer license intelligence, and portfolio insights.

## What it does

This MCP server provides two main capabilities:

### 1. Customer & Portfolio Intelligence (LMA-first)

Connect to the CloudSense License Management App (LMA) org to:

- **Find customers** by name (fuzzy search via SOSL)
- **Retrieve license details** -- production and sandbox orgs, installed packages, versions, expiry, health score
- **Identify opportunities** -- upgrades, upsells, renewals based on deterministic scoring
- **Portfolio insights** -- bulk analysis across all customers with priority heatmap and tiered categorization

### 2. Upgrade Assessment

Given a customer's Salesforce sandbox with CloudSense packages installed:

1. Discovers installed packages and their versions (cross-referenced with LMA production data)
2. Pulls customer metadata (Apex, LWC, Aura, objects, flows, etc.)
3. Retrieves managed package objects and customer customizations
4. Exports custom settings and configuration values
5. Maps packages to GitHub repos with version-ref resolution
6. Clones repos for from-version and to-version comparison
7. *(Coming soon)* Package diff analysis, customer impact analysis, API compatibility verification, and comprehensive upgrade report

## Prerequisites

- Python 3.10+
- Salesforce CLI (`sf`) installed and authenticated
- GitHub CLI (`gh`) installed or SSH keys configured for GitHub access

## Installation

```bash
# Via uvx (recommended)
uvx cloudsense-upgrade-compass

# Or install locally for development
uv pip install -e ".[dev]"
```

## Configuration

### Cursor IDE

Go to **Settings > MCP Servers** and add:

```json
{
  "mcpServers": {
    "cloudsense-upgrade-compass": {
      "command": "uvx",
      "args": ["cloudsense-upgrade-compass"]
    }
  }
}
```

### Claude CLI (terminal)

```bash
claude mcp add cloudsense-upgrade-compass -- uvx cloudsense-upgrade-compass
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cloudsense-upgrade-compass": {
      "command": "uvx",
      "args": ["cloudsense-upgrade-compass"]
    }
  }
}
```

## Workflow

### LMA-First Flow (recommended starting point)

```
connect_lma              → Authorize the CloudSense LMA org
find_customer            → Search for a customer by name (fuzzy)
get_customer_licenses    → Full license intelligence + health score
```

After LMA discovery, the AI can provide upgrade/upsell/renewal insights. To proceed with a full upgrade assessment:

```
init_assessment          → Set up the assessment project (reads customer from state)
get_installed_packages   → Discover packages in the customer's sandbox
get_customer_metadata    → Pull customer code from the sandbox
get_managed_objects      → Retrieve CS managed package objects
get_cs_settings          → Export custom setting values
get_object_customizations→ Find customer-added fields on CS objects
get_repo_mapping         → Map packages to GitHub repos
clone_package_repos      → Clone repos for version comparison
```

### Standalone Tools

These work independently without a full assessment:

```
get_portfolio_insights   → Bulk cross-customer analysis with scoring and heatmap
```

## Available Tools

| Tool | Description |
|------|-------------|
| `connect_lma` | Authorize the CloudSense LMA Salesforce org. First tool to call for any customer inquiry. Discovers sfLma field model (best-effort). Creates state file automatically. |
| `find_customer` | Search for a customer by name in the LMA org. Uses SOSL fuzzy search with SOQL LIKE fallback. Excludes prospect accounts. |
| `get_customer_licenses` | Retrieve all licenses, org summary, and package info for a customer. Produces Customer Health Score (0-100), upgrade opportunities, and recommends the best sandbox for metadata retrieval. |
| `get_portfolio_insights` | Analyze the entire CloudSense customer portfolio. Computes renewal urgency, license utilization, version currency, and customer size scores. Generates ranked report with heatmap and tiered categories. |
| `init_assessment` | Initialize upgrade assessment project. Validates prerequisites, creates SFDX project structure. Supports `skip_sandbox` for LMA-only mode. Reads customer info from state. |
| `get_installed_packages` | Discover all installed packages in the org. Identifies CloudSense packages, flags cloud service dependencies (CSPOFA, cscfga, csslm). |
| `get_customer_metadata` | Pull customer metadata from the org. Adaptive batching handles the 10K file retrieval limit via binary split. |
| `get_managed_objects` | Retrieve CS managed package objects (__c, __mdt) that wildcard retrieval misses. Discovers via `sf sobject list`, retrieves in adaptive batches. |
| `get_cs_settings` | Export CS custom setting values. Discovers settings from metadata, describes fields, queries values. Writes per-setting JSON files. |
| `get_object_customizations` | Find customer-added fields, validation rules, and record types on CS managed objects by comparing namespaces. |
| `get_repo_mapping` | Map installed CS packages to GitHub repos using cloudsense.map, .gitmodules, and README metadata. Produces verifiable `version-ref-map.json` with editable overrides. |
| `clone_package_repos` | Clone repos at from/to version refs. Skips deprecated/identical packages. Discovers new dependencies from target version. |

## State Management

All tools share a single `upgrade-assessment-state.json` file in the working directory. The state file is:

- **Created automatically** by the first tool call (`connect_lma`)
- **Progressively enriched** by each subsequent tool
- **Resumable** -- tools check for completed steps and skip them
- **Editable** -- users can modify the state file to correct values

All tools accept an optional `working_directory` parameter. The AI automatically passes the current workspace path on every call -- users are never asked for it.

## Safety

- **Read-only** against customer Salesforce orgs -- never deploys, inserts, updates, or deletes
- **Sandbox-only** for customer metadata retrieval -- hard-blocks production orgs
- **LMA queries** are scoped to `Account` and `sfLma__*` objects only
- **Customer org queries** are limited to CloudSense configuration objects
- All external commands (sf, git) are logged for auditability

## Development

```bash
# Clone and install
git clone <repo-url>
cd cloudsense-upgrade-compass
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# Run tests
pytest

# Run server locally
python -m cloudsense_upgrade_compass.server

# Build
python3 -m build

# Publish
uv publish dist/*
```
