# 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](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 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

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