cloudsense-customer-compass 0.3.1

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.

Prerequisites

• Python 3.10+
• Salesforce CLI (sf) — install
• GitHub CLI (gh) or SSH keys for GitHub access (needed for repo cloning steps)

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 customer inquiry.
find_customer	Search for a customer by name using SOSL fuzzy search with SOQL LIKE fallback. Returns matches for confirmation, then saves the selected customer to state.
get_customer_licenses	Retrieve all production and sandbox licenses for a customer. Returns license summary, org summary, and recommended sandbox. Writes to customer/licenses.json.

More tools are being added incrementally. See the Workflow section below for the planned pipeline.

Workflow

connect_lma              → Authorize the CloudSense LMA org
find_customer            → Search for a customer by name
get_customer_licenses    → License and org summary
get_installed_packages   → Per-package baseline (coming soon)
list_metadata            → Discover metadata members (coming soon)
retrieve_metadata        → Pull metadata in chunks (coming soon)
get_repo_mapping         → Map packages to GitHub repos (coming soon)
clone_package_repos      → Clone repos for version diff (coming soon)

Workspace Output Structure

Tools write their output to a structured workspace directory:

workspace/
├── assessment.json              # active customer pointer + connection info
├── customers/                   # per-customer data (never overwritten on switch)
│   ├── nbn-co/
│   │   ├── licenses.json
│   │   └── metadata/
│   ├── telstra/
│   │   └── licenses.json
│   └── ...
├── packages/                    # per-package artifacts
│   ├── <namespace>/
│   │   ├── package-info.json
│   │   ├── version-map.json
│   │   ├── repo-from/
│   │   └── repo-to/
│   └── _skipped/
├── reference-docs/
└── cloudsense-meta/

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