cloudsense-upgrade-compass 0.8.0

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

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

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

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

Claude CLI (terminal)

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

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.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.
get_customer_json_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_customer_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_package_repo_mapping	Maps installed CS packages to their GitHub source repos. Parses cloudsense.map and .gitmodules from the main cloudsense repo, cross-references with installed packages. Supports local repo path to skip cloning.
clone_package_repos	Clones each mapped CS repo at from-version (installed) and to-version (target). Auto-resolves git tags via multiple strategies (exact, v-prefix, release train, stripped major). Supports selective cloning and force re-clone.

Development

# 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