cloudsense-customer-compass 0.5.0

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

CloudSense Customer Compass

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

Package	cloudsense-customer-compass
Version	0.5.0
Python	>=3.10
License	MIT

Prerequisites

• Python 3.10+
• Salesforce CLI (sf) — install

Installation

# Via uvx (recommended — no install needed, always runs latest)
uvx cloudsense-customer-compass

# Or install globally via pip
pip install cloudsense-customer-compass

MCP Configuration

Cursor IDE

Go to Settings → MCP Servers and add:

{
  "mcpServers": {
    "CloudSense Customer Compass": {
      "command": "uvx",
      "args": ["cloudsense-customer-compass"]
    }
  }
}

Claude Desktop

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "CloudSense Customer Compass": {
      "command": "uvx",
      "args": ["cloudsense-customer-compass"]
    }
  }
}

Claude CLI

claude mcp add "CloudSense Customer Compass" -- uvx cloudsense-customer-compass

Available Tools

Tool	Description
connect_lma	Authorize the CloudSense LMA Salesforce org. First tool to call for any workflow.
find_customer	Search for a customer by name (SOQL LIKE primary, SOSL fallback). Returns matches for confirmation, then provides account_id and account_name for downstream tools.
get_customer_licenses	Retrieve all production and sandbox licenses for a customer. Returns compact package and org summary. Writes full data to customers/<slug>/licenses.json.
get_portfolio_data	Fetch ALL active/trial production licenses enriched with seat utilization and version currency (latest version per package). Groups by customer with health-scoring inputs (renewal risk, release number, seat %, breadth). AI applies composite scoring framework. Writes to portfolio/portfolio-data.json.
save_report	Save AI-generated analysis, insights, or discussion notes as a shareable markdown file. Works across any MCP client (Cursor, Claude Desktop, etc.).

Workflows

Single Customer Analysis

connect_lma              → Authorize the CloudSense LMA org
find_customer            → Search for a customer by name, confirm selection
get_customer_licenses    → License, package, and org summary

Portfolio Analysis

connect_lma              → Authorize the CloudSense LMA org
get_portfolio_data       → Full portfolio snapshot with health-scoring data
                           (seat utilization, version currency, renewal risk)
                           Auto-creates portfolio/scoring-rules.md on first run
AI scoring               → Composite health score per customer (4 dimensions)
                           Uses rules from portfolio/scoring-rules.md
save_report              → Persist ranked insights as shareable markdown

Customising Health Scores

Edit portfolio/scoring-rules.md to change weights, thresholds, core packages, or opportunity detection rules. Changes take effect on the next get_portfolio_data call. You can also override any rule conversationally (e.g. "for this analysis, treat csbb as critical").

Coming Soon

get_installed_packages   → Per-package baseline from customer sandbox
list_metadata            → Discover metadata members by type
retrieve_metadata        → Pull metadata in chunks
get_repo_mapping         → Map packages to GitHub repos
clone_package_repos      → Clone repos for version diff

Workspace Output Structure

Tools write their output to a structured workspace directory:

workspace/
├── assessment.json              # LMA connection info only
├── customers/                   # per-customer data
│   ├── nbn-co-ltd/
│   │   ├── licenses.json
│   │   └── analysis-2026-03-14.md
│   └── starhub/
│       └── licenses.json
├── portfolio/                   # cross-customer analysis
│   ├── scoring-rules.md          # editable health scoring rules
│   ├── portfolio-data.json
│   └── insights-2026-03-14.md
├── packages/                    # per-package artifacts (coming soon)
│   ├── <namespace>/
│   │   ├── package-info.json
│   │   ├── version-map.json
│   │   ├── repo-from/
│   │   └── repo-to/
│   └── _skipped/
└── reference-docs/

Safety

• Read-only against customer Salesforce orgs — never deploys, inserts, updates, or deletes
• Whitelist-enforced — only approved sf CLI subcommands can execute
• LMA queries scoped to Account and sfLma__* objects only
• Customer org queries limited to CloudSense configuration objects
• All sf CLI commands are logged for auditability

Development

python3 -m pip install -e ".[dev]"

# Run server locally
python3 -m cloudsense_customer_compass.server

# Run tests
pytest

# Build & publish
python3 -m build
uv publish dist/*