Metadata-Version: 2.4
Name: cloudsense-upgrade-compass
Version: 0.10.8
Summary: MCP server for CloudSense package upgrade assessment, analysis, and impact verification.
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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_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. |
| `get_cs_settings` | Discovers CS custom settings from retrieved metadata, describes fields via `sf sobject describe`, exports all setting values via SOQL queries. Writes per-setting JSON files. |
| `get_object_customizations` | Post-processes CS managed objects to find customer-added fields, validation rules, record types. Compares field namespaces against object namespaces to identify customizations. |
| `get_repo_mapping` | Maps installed CS packages to GitHub repos using cloudsense.map, .gitmodules, AND apex-packages/README.md. Enriches with branches, deprecation, R38 status, customer usage, migration complexity, cloud service links. Produces `version-ref-map.json` with pre-resolved from/to git refs and editable overrides. Falls back to GitHub search for unmapped packages. Copies 2nd Brain reference docs for Phase C. |
| `clone_package_repos` | Reads version-ref-map and clones repos at from/to refs. Respects manual overrides. Skips deprecated/identical/empty-code packages. Discovers new dependencies from target version sfdx-project.json. Updates ref-map with verified status. |

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