# Genesys Cloud Function Data Actions MCP

Development toolkit and MCP server for Genesys Cloud Function Data Actions.

## Requirements

- Node.js 20+
- npm

## Using the MCP server (recommended)

You do **not** need to clone this repository to use the MCP server in Cursor. Use a Function workspace (your own repo) and install the server via GitHub.

### 1. Create a workspace

Copy [`examples/starter-workspace/`](examples/starter-workspace/) into your repository, or create a folder with the same layout:

```text
your-workspace/
├── .cursor/mcp.json
├── .env
├── genesys-environments.yaml
└── functions/
```

### 2. Configure credentials

```bash
cp .env.example .env
cp genesys-environments.yaml.example genesys-environments.yaml
```

Set Genesys credentials in `.env` (never commit this file):

```text
GENESYSCLOUD_CLIENT_ID=...
GENESYSCLOUD_CLIENT_SECRET=...
GENESYSCLOUD_API_BASE_URL=https://api.mypurecloud.com.au
GENESYSCLOUD_ORG_ID=...
GENESYS_FUNCTION_MCP_MODE=read-only
```

Alternatively, set `GENESYSCLOUD_ACCESS_TOKEN` (it takes precedence over client credentials).

### 3. Pre-install the toolkit (recommended)

From your **workspace root** (the folder that contains `.env`, not `functions/`):

```bash
chmod +x setup.sh   # if you copied examples/starter-workspace/
./setup.sh
```

Or run `gc-function doctor` manually:

```bash
export GENESYS_FUNCTION_WORKSPACE_ROOT="$PWD"
npx --yes --package=github:darbyje/genesys-function-data-actions-mcp#v0.1.2 gc-function doctor --format json
```

The first run downloads and compiles the package (~1–2 minutes). This caches the install so Cursor’s first MCP connect is fast. Expect `genesysAuthentication: "READY"` when `.env` is configured.

### 4. Wire Cursor to the MCP server

Copy [`mcp.json.example`](mcp.json.example) to `.cursor/mcp.json` in your workspace (or use the copy in [`examples/starter-workspace/.cursor/mcp.json`](examples/starter-workspace/.cursor/mcp.json)):

```json
{
  "mcpServers": {
    "genesys-function-data-actions": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "--yes",
        "--package=github:darbyje/genesys-function-data-actions-mcp#v0.1.2",
        "genesys-function-mcp"
      ],
      "env": {
        "GENESYS_FUNCTION_WORKSPACE_ROOT": "${workspaceFolder}",
        "GENESYS_FUNCTION_MCP_MODE": "read-only"
      },
      "envFile": "${workspaceFolder}/.env"
    }
  }
}
```

Open your workspace in Cursor and confirm the MCP server connects. Local tools work without Genesys credentials; remote tools require authentication.

### Alpha limitations (v0.1.0)

- Read-only remote MCP tools are supported.
- Plan/apply deployment writes exist but are **not verified end-to-end** in non-production yet.
- First `npx` run compiles TypeScript via the package `prepare` script (~30 seconds).

## Developing this repository

For contributors working on the toolkit itself:

```bash
npm ci
npm run check
```

Use [`mcp.json.dev.example`](mcp.json.dev.example) for local MCP development (points at `./dist/mcp/server.js`).

### CLI quick start

```bash
npm run cli -- init normalize-customer-data --display-name "Normalize Customer Data"
npm run cli -- validate --project normalize-customer-data
npm run cli -- build --project normalize-customer-data
npm run cli -- inventory --env dev --format json
npm run cli -- plan --project normalize-customer-data --env dev --publish
npm run cli -- apply --plan <plan-id>
```

### MCP server (local)

```bash
npm run start:mcp
```

### Phase 0 spike scripts (opt-in, non-production)

```bash
export GENESYS_LIVE_TESTS=true
export GENESYSCLOUD_ENVIRONMENT_CLASS=non-production
npm run spike:discover
npm run spike:lifecycle
npm run spike:cleanup
```

## Architecture

```text
CLI / MCP  ->  application services  ->  domain ports  <-  adapters
                                              |
                         +--------------------+--------------------+
                         |                    |                    |
                   filesystem            Genesys SDK           npm/zip
```

Genesys SDK types stay inside `src/genesys/`. Deployment uses immutable plan/apply semantics.

## Safety controls

- No raw Genesys API MCP tools
- Plan before apply; apply requires plan ID
- Published contract changes block in-place deployment
- Tokens and upload URLs are redacted from logs
- Read-only mode blocks remote writes

## Publishing releases

Maintainer workflow:

1. Push to `github.com/darbyje/genesys-function-data-actions-mcp`.
2. Run `npm run check` on CI (included in `.github/workflows/ci.yml`).
3. Tag a release (e.g. `v0.1.0`) after the verification gate passes.
4. Customers install via `npx --yes --package=github:darbyje/genesys-function-data-actions-mcp#v0.1.2 genesys-function-mcp` (pinned in `mcp.json.example`).

Bump the tag in customer-facing `mcp.json` examples when shipping a new version.

See `docs/adr/` for recorded decisions.