Metadata-Version: 2.4
Name: cloudsense-dx-mcp
Version: 0.6.1
Summary: MCP server for CloudSense DX operations (orchestration templates, etc.)
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: certifi
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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 `cloudsense-dx-exports/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. Required unless `fetch_all` is true.         |
| `fetch_all`      | boolean  | No\*     | Set to `true` to fetch all templates. Required if `template_names` is omitted. |
| `max_workers`    | integer  | No       | Parallel workers for concurrent fetching. Default: 5.                          |

\*You must provide either `template_names` or `fetch_all: true`. Omitting both returns an error.

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

## Environment Variables

| Variable                           | Default                   | Description                                |
| ---------------------------------- | ------------------------- | ------------------------------------------ |
| `CLOUDSENSE_DX_EXPORT_ROOT`        | Current working directory | Root directory for template export output. |
| `CLOUDSENSE_DX_MAX_SF_CONCURRENCY` | `8`                       | Max concurrent `sf` CLI subprocesses.      |

## Links

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