cloudsense-upgrade-compass 0.12.0

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

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:

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