npm package: @haviq/mcp
Description: HAV-IQ MCP Server — deploy Salesforce metadata in plain English from Claude Code, Cursor, or Windsurf
Author: HAV-IQ
Latest version: 1.1.0

# HAV-IQ MCP Server

Deploy Salesforce metadata in plain English from **Claude Code**, **Cursor**, **Windsurf**, or any MCP-compatible AI IDE.

```
"What's ready to deploy in the Acme pipeline?"
"Show me branches with high risk scores"
"Deploy AccountService and ContactTrigger from DEV to QA"
"What changed between DEV and QA?"
"Retry the failed deployment"
```

## Prerequisites

- HAV-IQ package installed in your Salesforce org
- A Salesforce Connected App configured for JWT Bearer auth
- Node.js 18+

---

## Quick Start

```bash
npm install -g @haviq/mcp
haviq-mcp --setup
```

The setup wizard walks you through connecting to your Salesforce org — no manual config files needed.

## Manual Configuration

If you prefer, create `.haviq.json` in your project root (or `~/.haviq.json` for global config):

```json
{
  "instanceUrl": "https://myorg.my.salesforce.com",
  "clientId":    "3MVG9...",
  "username":    "admin@myorg.com",
  "privateKey":  "/path/to/server.key"
}
```

For **quick testing**, you can use a session token instead:

```json
{
  "instanceUrl": "https://myorg.my.salesforce.com",
  "accessToken": "00D..."
}
```

Environment variables are also supported (useful for CI):

| Variable              | Description                        |
|-----------------------|------------------------------------|
| `HAVIQ_INSTANCE_URL`  | Your org's My Domain URL           |
| `HAVIQ_CLIENT_ID`     | Connected App client ID            |
| `HAVIQ_USERNAME`      | Salesforce username                |
| `HAVIQ_PRIVATE_KEY`   | RSA private key (PEM string)       |
| `HAVIQ_LOGIN_URL`     | Login URL (default: login.salesforce.com) |
| `HAVIQ_ACCESS_TOKEN`  | Direct access token (testing only) |

---

## Salesforce Setup

### 1. Create a Connected App

1. Setup → App Manager → New Connected App
2. Enable OAuth Settings
3. Callback URL: `http://localhost` (not used for JWT)
4. Selected OAuth Scopes: **Full access (full)** or **API (api) + Manage user data via APIs (api)**
5. Enable **Use Digital Signatures**
6. Upload your RSA certificate (`.crt` file)

### 2. Generate RSA Key Pair

```bash
openssl genrsa -out server.key 2048
openssl req -new -x509 -days 3650 -key server.key -out server.crt
```

Upload `server.crt` to the Connected App. Keep `server.key` secure — this goes in your `.haviq.json`.

### 3. Approve the Connected App

Setup → Manage Connected Apps → HAV-IQ MCP → Edit Policies → **Permitted Users: Admin approved users are pre-authorized** → Save

Then: Setup → Permission Sets → assign the Connected App to the user's permission set.

---

## Add to Claude Code

In your Claude Code MCP settings (`.claude/mcp.json` or global settings):

```json
{
  "mcpServers": {
    "haviq": {
      "command": "haviq-mcp"
    }
  }
}
```

Or with environment variable auth (no config file):

```json
{
  "mcpServers": {
    "haviq": {
      "command": "haviq-mcp",
      "env": {
        "HAVIQ_INSTANCE_URL":  "https://myorg.my.salesforce.com",
        "HAVIQ_CLIENT_ID":     "3MVG9...",
        "HAVIQ_USERNAME":      "admin@myorg.com",
        "HAVIQ_PRIVATE_KEY":   "-----BEGIN RSA PRIVATE KEY-----\n..."
      }
    }
  }
}
```

## Add to Cursor

Settings → MCP → Add Server:

```json
{
  "name":    "haviq",
  "command": "haviq-mcp"
}
```

---

## Available Tools

| Tool | What it does |
|------|-------------|
| `get_pipelines` | List all HAV-IQ pipelines with IDs |
| `get_stages` | List stages (DEV, QA, UAT, PROD) for a pipeline |
| `list_deployments` | Recent deployments with status and AI review summary |
| `get_branches` | Feature branches with AI risk scores (0–100) |
| `get_delta_manifest` | Compute changed components between two stages |
| `create_deployment` | Deploy specific components from source to target |
| `create_delta_deployment` | Deploy all changed components (AI-computed delta) |
| `retry_deployment` | Re-trigger a failed deployment |
| `override_deployment` | Override a stuck deployment status |

---

## Typical Workflow

```
You:     "What pipelines do we have?"
Claude:  [calls get_pipelines] → "Acme Pipeline (active) — ID: a0B..."

You:     "Show me the stages"
Claude:  [calls get_stages] → "DEV → QA → UAT → PROD (all authenticated)"

You:     "What's changed between DEV and QA?"
Claude:  [calls get_delta_manifest] → "3 components changed: AccountService, ContactTrigger, OpportunityHelper"

You:     "Deploy all of them to QA"
Claude:  [calls create_delta_deployment] → "✅ Delta deployment created. Deployment ID: a1C..."

You:     "Check the status"
Claude:  [calls list_deployments] → "🔄 DEV → QA | running | Apr 3, 2:14 PM"
```

---

## Security

Git provider tokens are transmitted to your Salesforce org via HTTPS and stored as EncryptedText fields. They are never stored locally by the MCP server. The server holds no state — all data lives in your Salesforce org.

## License

MIT