# CloudSense Upgrade Compass

MCP server for CloudSense package upgrade assessment, analysis, and impact verification.

## What it does

Given a Salesforce org with CloudSense packages installed, this MCP server:

1. Discovers installed packages and their versions
2. Pulls customer metadata (Apex, LWC, Aura, objects, flows, etc.)
3. Clones CloudSense package repos for from-version and to-version
4. Runs package diff analysis (breaking changes, new features, bug fixes)
5. Analyzes customer codebase impact (which customer files reference changed APIs)
6. Verifies API compatibility (signature-level SAFE/BREAKING verdicts)
7. Maps test coverage gaps (which impacted files lack test coverage)
8. Generates a comprehensive upgrade report with phasing, effort, and risk

## Prerequisites

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

## 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"]
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `init_assessment` | Initialize upgrade assessment project. Creates SFDX project, validates prerequisites (sf CLI, GitHub access), checks org authorization, detects production vs sandbox. |
| `get_installed_packages` | Discover all installed packages in the org. Identifies CloudSense packages, flags cloud service dependencies (CSPOFA, cscfga, csslm), writes `installed-packages.json`. |
| `get_customer_metadata` | Pull customer metadata (Apex, LWC, Aura, VF, objects, flows, validation rules, static resources, permissions) from the org. Adaptive batching handles 10K file limit via binary split. |
| `get_managed_package_objects` | Retrieve CS managed package objects (__c, __mdt) that wildcard retrieval misses. Discovers via `sf sobject list`, excludes ChangeEvent/History/Share/Feed, retrieves in adaptive batches. |

## 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
```
