# CloudSense Customer Compass

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

| | |
|---|---|
| **Package** | `cloudsense-customer-compass` |
| **Version** | `0.7.0` |
| **Python** | `>=3.10` |
| **License** | MIT |

## Prerequisites

- Python 3.10+
- Salesforce CLI (`sf`) — [install](https://developer.salesforce.com/tools/salesforcecli)

## Installation

```bash
# 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:

```json
{
  "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`

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

### Claude CLI

```bash
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 with region and industry for disambiguation. On confirmation, returns full account profile (industry, region, parent company, description, website, LinkedIn) for AI context. |
| `get_customer_licenses` | Retrieve all production and sandbox licenses for a customer. Searches both Account links and Company name to ensure complete coverage. 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, version currency, account context (region, industry, parent company), and corporate group analysis. Saves timestamped snapshots for change detection. AI applies composite scoring framework from editable `portfolio/scoring-rules.md`. |
| `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 by name, confirm (returns full account profile)
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
                           (seats, versions, region, industry, parent groups)
                           Auto-creates portfolio/scoring-rules.md on first run
                           Saves timestamped snapshot + detects changes
AI scoring               → Composite health score per customer (4 dimensions)
                           Corporate group analysis, opportunity flags
                           Uses rules from portfolio/scoring-rules.md
save_report              → Persist ranked insights as shareable markdown
                           Supports persona-based reports (exec, sales, tech, CS)
```

### Customising Health Scores

Edit `portfolio/scoring-rules.md` to change weights, thresholds, core
packages, opportunity detection rules, or report persona templates.
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") or run what-if scenarios ("what if we drop R35 support?").

### 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
│   ├── history/                  # timestamped snapshots for trend analysis
│   │   ├── portfolio-data-2026-03-01.json
│   │   └── portfolio-data-2026-03-14.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

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