cloudsense-upgrade-compass 0.11.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_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

# 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