Genesys Cloud Function Data Actions MCP

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

Requirements

• Node.js 20+

• npm

Related MCP server: Gravitee APIM MCP Server

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/ into your repository, or create a folder with the same layout:

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

2. Configure credentials

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

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

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/):

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

Or run gc-function doctor manually:

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 to .cursor/mcp.json in your workspace (or use the copy in examples/starter-workspace/.cursor/mcp.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:

npm ci
npm run check

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

CLI quick start

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)

npm run start:mcp

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

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

Architecture

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.