# CloudSense Customer Compass

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

## Prerequisites

- Python 3.10+
- Salesforce CLI (`sf`) — [install](https://developer.salesforce.com/tools/salesforcecli)
- GitHub CLI (`gh`) or SSH keys for GitHub access (needed for repo cloning steps)

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

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