# CloudSense DX MCP Server

[![PyPI](https://img.shields.io/pypi/v/cloudsense-dx-mcp.svg)](https://pypi.org/project/cloudsense-dx-mcp/) [![Python](https://img.shields.io/pypi/pyversions/cloudsense-dx-mcp.svg)](https://pypi.org/project/cloudsense-dx-mcp/) [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

An MCP (Model Context Protocol) server for CloudSense DX operations on Salesforce orgs. Provides tools for managing orchestration process templates, running anonymous Apex with savepoint safety, and other CloudSense-specific operations.

## Quick Start

### 1. Install Prerequisites

- **Salesforce CLI** (`sf`) -- [Install Guide](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_install_cli.htm)
- **uv** (Python package runner) -- [Install Guide](https://docs.astral.sh/uv/getting-started/installation/)
- At least one authorized Salesforce org:

```bash
sf org login web --alias my-org
```

- (Optional) Set a default target org for your project:

```bash
sf config set target-org my-org
```

### 2. Configure in Your MCP Client

Add the CloudSense DX MCP server to your client's MCP configuration. The recommended way is via `uvx`, which automatically installs and runs the latest version.

## MCP Client Configurations

### Cursor

Add to your project's `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "CloudSense DX": {
      "command": "uvx",
      "args": ["cloudsense-dx-mcp"]
    }
  }
}
```

### VS Code (Copilot)

Add to `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "CloudSense DX": {
      "command": "uvx",
      "args": ["cloudsense-dx-mcp"]
    }
  }
}
```

### Claude Code

Add to `.mcp.json` in your project:

```json
{
  "mcpServers": {
    "CloudSense DX": {
      "command": "uvx",
      "args": ["cloudsense-dx-mcp"]
    }
  }
}
```

### Cline

Add to your Cline `cline_mcp_settings.json`:

```json
{
  "mcpServers": {
    "CloudSense DX": {
      "command": "uvx",
      "args": ["cloudsense-dx-mcp"]
    }
  }
}
```

### Windsurf

Add to your Windsurf MCP configuration:

```json
{
  "mcpServers": {
    "CloudSense DX": {
      "command": "uvx",
      "args": ["cloudsense-dx-mcp"]
    }
  }
}
```

### Other MCP Clients

For any other MCP client, use the same pattern -- set the command to `uvx` with `cloudsense-dx-mcp` as the argument. Refer to your client's documentation for the exact config file location.

## Alternative Installation Methods

### Using pip

```bash
pip install cloudsense-dx-mcp
```

Then configure your MCP client with:

```json
{
  "command": "cloudsense-dx-mcp"
}
```

### From Source (Development)

```bash
git clone https://github.com/ash-agarwalcs/cloudsense-dx-mcp.git
cd cloudsense-dx-mcp
pip install -e .
```

### Direct CLI

You can also run the server directly from the command line:

```bash
# Via uvx (no install needed)
uvx cloudsense-dx-mcp

# Via pip install
cloudsense-dx-mcp
```

The server communicates via stdio and is designed to be launched by MCP clients.

## Tools

### list_orchestration_templates

List, search, or discover CloudSense orchestration process templates in a Salesforce org.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `org_alias` | string | No | Org alias or partial hint (e.g. `itxdevpro`, `devpro`). Auto-resolved if omitted. |
| `search_term` | string | No | Filter templates by name (case-insensitive substring match). |

**Example prompts:**
- "List all orchestration templates"
- "Search for templates containing 'Internet CPE'"
- "Show me templates from devpro"

### fetch_orchestration_templates

Fetch and save orchestration process templates as JSON files. Templates are saved to `deployment_data/orchestration_templates/<org>/<timestamp>/`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `org_alias` | string | No | Org alias or partial hint. Auto-resolved if omitted. |
| `template_names` | string[] | No | Specific template names to fetch. Fetches ALL if omitted. |
| `max_workers` | integer | No | Parallel workers for concurrent fetching. Default: 5. |

**Example prompts:**
- "Fetch all orchestration templates"
- "Download the Internet CPE Terminate Flow template"
- "Get templates from sit org"

### run_apex

Execute anonymous Apex code on a Salesforce org with automatic savepoint safety.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `apex_code` | string | Yes | The anonymous Apex code to execute. |
| `org_alias` | string | No | Org alias or partial hint. Auto-resolved if omitted. |
| `allow_dml` | boolean | No | Set to `true` to persist data changes. Default: `false` (rolls back). |
| `timeout_seconds` | integer | No | Max execution time. Default: 120. |

**Example prompts:**
- "Run this Apex query on the org"
- "Execute this CloudSense API call"
- "Query all accounts with Apex"

## Prompts

### fetch-orchestration

A guided workflow that walks through template discovery, user confirmation, and parallel fetching. Useful for interactive sessions.

## Org Resolution

The server handles org resolution automatically -- you don't need to specify an org for every request.

**Resolution priority:**

1. **Explicit org** -- If you mention an org (e.g. "from itxdevpro"), it's used directly.
2. **Partial matching** -- Partial hints like "devpro" are fuzzy-matched against your authenticated orgs. If multiple orgs match, you'll be asked to choose.
3. **Session memory** -- Within a chat session, the server remembers the last org used and reuses it for subsequent requests.
4. **Workspace default** -- Falls back to the project's default target-org (`sf config get target-org`).

Every tool response includes `org` and `org_source` fields so you always know which org was used and how it was resolved.

## Prerequisites

| Requirement | Details |
|---|---|
| Python | >= 3.10 |
| Salesforce CLI (`sf`) | [Install](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_install_cli.htm) and authenticate at least one org |
| uv (recommended) | [Install](https://docs.astral.sh/uv/getting-started/installation/) for `uvx` usage |

## Links

- **PyPI:** https://pypi.org/project/cloudsense-dx-mcp/
- **GitHub:** https://github.com/ash-agarwalcs/cloudsense-dx-mcp
