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:

Discovers installed packages and their versions (cross-referenced with LMA production data)
Pulls customer metadata (Apex, LWC, Aura, objects, flows, etc.)
Retrieves managed package objects and customer customizations
Exports custom settings and configuration values
Maps packages to GitHub repos with version-ref resolution
Clones repos for from-version and to-version comparison
(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

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

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

# 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/*

Metadata

Release files for cloudsense-upgrade-compass 0.12.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cloudsense-upgrade-compass 0.12.3
File	Size	Uploaded	Provenance
cloudsense_upgrade_compass-0.12.3.tar.gz	66.7 kB	Mar 13, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for cloudsense-upgrade-compass 0.12.3
File	Interpreter	ABI	Platform	Reset
cloudsense_upgrade_compass-0.12.3-py3-none-any.whl 83.9 kB Mar 13, 2026 Without provenance	Python 3	none	any	Details

Total release size: 150.6 kB

Release files / cloudsense_upgrade_compass-0.12.3.tar.gz

Download URL	cloudsense_upgrade_compass-0.12.3.tar.gz
Size	66.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`ca6b23b14473d92827e444cf4918d8fbf8ae0c3d0cc113761239087381a64898`
BLAKE2b-256 checksum How to use checksums	`452cf71f76c808ba620ae77ce51141dc9b333b8aeea115de6e89c2082375aa49`
Upload date	Mar 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.7.18`

Release files / cloudsense_upgrade_compass-0.12.3-py3-none-any.whl

Download URL	cloudsense_upgrade_compass-0.12.3-py3-none-any.whl
Size	83.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`363d8840c7bbd79f13e9d5dd80b949482a43a6306f5d62c66e3c88e42b2c161e`
BLAKE2b-256 checksum How to use checksums	`69b1c1988741629ce30f206bad2383702118c3be315bc3aa630de80eba5f536a`
Upload date	Mar 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.7.18`

Security for cloudsense-upgrade-compass 0.12.3

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.