# pega-mcp-server

Generic TypeScript MCP server for Pega case operations with definition-driven tool registration.

## Purpose

This project provides an MCP tool layer for reading and mutating cases in a flexible way.
Tool wiring is metadata-based, so adding tools does not require editing server registration logic.

## Supported MCP Tools

- `pega.get_cases`
  - Input: optional `limit`
  - Returns: `{ ok: true, data: { cases: [...] } }`
- `pega.get_case`
  - Input: `caseId`, optional `viewType`, `pageName`, `originChannel`
  - Returns: `{ ok: true, data: { case: ... } }`
- `pega.get_case_actions`
  - Input: `caseId`, optional `originChannel`
  - Returns: `{ ok: true, data: { actions: ... } }`
- `pega.get_case_views`
  - Input: `caseId`, `viewId`, optional `originChannel`
  - Returns: `{ ok: true, data: { view: ... } }`
- `pega.attach_document_to_case`
  - Input: `caseId`, `fileName`, `mimeType`, `fileContentBase64`
  - Returns: `{ ok: true, data: ... }`
- `pega.submit_case_action`
  - Input: `caseId`, `action`, optional `content`
  - Returns: `{ ok: true, data: ... }`

All tools return a standard failure format:

```json
{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT | NOT_FOUND_OR_FORBIDDEN | INTERNAL_ERROR",
    "message": "Human-readable explanation",
    "suggestion": "Optional recovery guidance"
  }
}
```

## Environment Variables

Required:

- `PEGA_BASE_URL` (for example `https://your-pega-instance.example.com/prweb`)
- `PEGA_CLIENT_ID`
- `PEGA_CLIENT_SECRET`
- `PEGA_TOKEN_URL` (for example `https://your-pega-instance.example.com/prweb/PRRestService/oauth2/v1/token`)

Optional:

- `PEGA_CASES_API_BASE_PATH` (default: `/api/v1`)
  - Common v2 path when base URL includes `/prweb`: `/api/application/v2`
  - Some deployments use app context: `/PRAuth/app/work-manager/api/application/v2`
- `PEGA_CASES_LIST_DATA_VIEW` (default: `D_pyMyWorkList`)
  - Used as a fallback for `pega.get_cases` when `GET /cases` is not supported (HTTP 405)
  - Endpoint shape: `POST <PEGA_CASES_API_BASE_PATH>/data_views/<dataViewId>`
- `PEGA_ENABLED_TOOLS` comma-separated tool names to allowlist
  - Example: `pega.get_case,pega.get_case_actions`
- `PEGA_DISABLED_TOOLS` comma-separated tool names to blocklist
  - Example: `pega.submit_case_action,pega.attach_document_to_case`

## Run Locally

```bash
npm install
cp .env.example .env
npm run dev
```

## Build

```bash
npm run build
npm start
```

## Test

```bash
npm test
```

## Example Outputs

`pega.get_cases`

```json
{
  "ok": true,
  "data": {
    "cases": [
      {
        "ID": "C-501",
        "caseType": "Insurance Claim",
        "status": "Pending Documents"
      }
    ]
  }
}
```

`pega.get_case`

```json
{
  "ok": true,
  "data": {
    "case": {
      "ID": "C-501",
      "caseType": "Insurance Claim",
      "status": "Pending Documents",
      "uiResources": {
        "root": {
          "type": "page"
        }
      }
    }
  }
}
```

Detailed request/response contracts:
- [docs/tool-contracts.md](./docs/tool-contracts.md)