# Salesforce Support MCP

MCP UI app that renders an interactive support form and creates Salesforce `Case` records through the Salesforce REST API.

## Transport (Streamable HTTP by default)

This server speaks **MCP over Streamable HTTP** on **`/mcp`** using `@modelcontextprotocol/sdk`’s `StreamableHTTPServerTransport`. That is the default when you run `node dist/main.js`, `npm run start`, `npm run dev`, or `npm run serve` (no `--stdio` flag).

- **Base URL:** `http://localhost:3001/mcp` (override port with `PORT` in `.env` or the environment).
- **CORS:** enabled so browser-based MCP hosts (for example MCP Apps basic-host) can call the endpoint.

Point any MCP client that supports **Streamable HTTP** at that URL. Example shape (exact keys depend on your client):

```json
{
  "mcpServers": {
    "salesforce-support": {
      "url": "http://localhost:3001/mcp"
    }
  }
}
```

**Stdio** is optional: run with `--stdio` (see [Alternative: stdio](#alternative-stdio-for-desktop-hosts)) for hosts that only support process-based transports.

## Tools Exposed

- `open_support_form` (model-visible): opens the iframe UI form.
- `get_support_form_options` (app-only): loads Case picklist options (`Priority`, `Type`, `Origin`, `Status`).
- `submit_support_case` (app-only): validates and submits Case data.

## Scripts

- `npm run dev`: watch UI bundle and run the MCP server (**Streamable HTTP**, default).
- `npm run build`: build UI and compile server code.
- `npm run start`: production build then run **Streamable HTTP** (`node dist/main.js`).
- `npm run serve` / `npm run serve:stdio`: `tsx watch` variants (HTTP default; add `--stdio` for stdio).
- `npm run start:stdio`: same as `start` but **stdio** transport (`--stdio`).
- `npm run check-auth`: smoke-test auth strategy resolution.

## Environment

Copy `.env.example` to `.env` and configure at least one auth strategy.

Auth fallback order:

1. Static token (`SF_ACCESS_TOKEN` + `SF_INSTANCE_URL`)
2. OAuth username/password (`SF_CLIENT_ID`, `SF_CLIENT_SECRET`, `SF_USERNAME`, `SF_PASSWORD`)
3. Salesforce CLI (`sf org display --json`)

If none is configured, the form still opens but submitting fails with an auth error.

## Local Verification (basic-host)

### 1) Build and start this MCP server

From the repository root:

```bash
npm install
npm run build
node dist/main.js
```

Expected log:

```text
MCP server listening on http://localhost:3001/mcp
```

### 2) Start the MCP Apps basic host

From `ext-apps-main/examples/basic-host`:

```bash
npm install --ignore-scripts
npm run build
npx tsx serve.ts
```

Expected log:

```text
Host server:    http://localhost:8080
Sandbox server: http://localhost:8081
```

### 3) Browser smoke test

1. Open `http://localhost:8080`.
2. Select the local MCP server endpoint (`http://localhost:3001/mcp`).
3. Select tool `open_support_form`.
4. Click **Call Tool**.
5. Confirm form title appears: `Submit Salesforce Support Request`.
6. Fill required fields (`Subject`, `Description`) and click **Submit Support Case**.
7. Verify success banner with `CaseNumber` or `Case Id`.

## Current Validation Notes

- UI rendering path is verified (host connects, tool renders iframe form).
- If Salesforce auth is not configured, submit path returns a clear runtime error message.
- Server-side validation maps Salesforce/API errors back to field-level UI errors where possible.

## Alternative: stdio for desktop hosts

If your MCP host only supports stdio, build once then run Node with `--stdio`:

```json
{
  "mcpServers": {
    "salesforce-support": {
      "command": "node",
      "args": ["<ABSOLUTE_PATH_TO_REPO>/dist/main.js", "--stdio"]
    }
  }
}
```