# telivy-mcp

An MCP server for [Telivy](https://www.telivy.com/)'s Security API, built to be
deployed from the [MCP Gateway](https://github.com/shaank0/mcp-gateway) catalog.
Written against the published OpenAPI spec:
<https://api-v1.telivy.com/api-docs/security-json>.

**Purpose:** turn a Telivy risk assessment into a client-facing presentation and
hand-over document that opens a sales conversation. `get-assessment-briefing`
gathers everything one call: client profile, headline grade, per-area scorecard,
top findings with risk and remediation, dark-web exposure counts, M365 /
Google Workspace MFA coverage, sensitive-data exposure, talking points and
next steps.

## Run

```bash
TELIVY_API_KEY=... npm run dev        # http://localhost:8080/mcp
docker build -t telivy-mcp . && docker run -p 8080:8080 -e TELIVY_API_KEY=... telivy-mcp
```

| Variable | Default | Purpose |
|---|---|---|
| `TELIVY_API_KEY` | required | Telivy Portal → Account → Integrations |
| `TELIVY_API_BASE` | `https://api-v1.telivy.com` | override for testing |
| `TELIVY_MAX_REPORT_BYTES` | `15728640` | refuse report downloads over this size |
| `PORT` | `8080` | listen port |

Streamable HTTP at `POST /mcp` (stateless), health at `GET /healthz`.

## Tools

Read (`get-` / `list-`): `list-risk-assessments`, `get-risk-assessment`,
`list-external-scans`, `get-external-scan`, `get-external-scan-findings`,
`get-finding-details`, `get-breach-data`, `get-devices`, `get-device`,
`get-scan-status`, `get-agent-versions`, `get-m365-users`, `get-gws-users`,
`get-pii-summary`, `get-risk-progress`, `get-assessment-briefing`,
`get-report`, `get-external-scan-report`.

Write: `create-external-scan`, `create-risk-assessment`,
`convert-to-risk-assessment`, `update-monitoring-settings`, `rescan-device`.

No delete / archive / uninstall tools, by design.

## Secrets never returned

Telivy's breach data carries leaked plaintext and hashed passwords. They are
replaced with `plaintextPasswordExposed` / `hashedPasswordExposed` booleans
before any tool returns, every success payload is key-scrubbed
(`password`, `hashedPassword`, `telivyKey`, `apiKey`, `secret`), and upstream
error text mentioning a credential field is withheld.

## Develop

```bash
npm ci
npm run verify   # tsc + vitest
```

Pushing to `main` builds the image, smoke-tests it (healthz + MCP
initialize + tools/list = 23 tools) and publishes
`ghcr.io/shaank0/telivy-mcp:latest`.