# cymulate-mcp-tools

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-Model_Context_Protocol-blue)](https://modelcontextprotocol.io/)

Community MCP (Model Context Protocol) server for the **Cymulate** security validation platform. Exposes **100% of the Cymulate REST API** (337 endpoints, OpenAPI v2.0.62) via **100 first-class semantic tools + 1 generic REST fallback + 5 utility tools = 106 total**.

Covers BAS (Breach & Attack Simulation), Exposure Validation, Exposure Analytics, Attack Surface Management, Advanced Scenarios (Purple Team), Findings, Auto Remediation, Environments/Agents, and Platform administration.

---

## Status

> **Unmaintained since 2026-08-07.**
> Last tested against Cymulate API **v2.0.62** (OpenAPI 3.1.1).
> The original author no longer uses the Cymulate platform. Issues will remain open; community PRs are welcome and will be reviewed on a best-effort basis. Fork freely.
>
> This is a **community** MCP — not affiliated with, endorsed by, or supported by Cymulate Ltd. All trademarks belong to their respective owners. Verify your Cymulate Terms of Service permits third-party API clients before use.

---

## Coverage vs official Cymulate MCP

| | This project | Official Cymulate MCP |
|---|---|---|
| Endpoints covered | **337 / 337 (100%)** | ~130 / 337 (39%) |
| First-class tools | 100 | 118 |
| Generic REST fallback | ✅ `cymulate_api_call` | ❌ |
| BAS full coverage (all 11 modules) | ✅ | Partial |
| Auto Remediation | ✅ | ❌ |
| ASM | ✅ | ❌ |
| Advanced Scenarios (Purple Team) | ✅ | Partial |
| HTTP Streamable transport | ✅ | STDIO only |
| Rate-limit awareness in responses | ✅ | ❌ |
| OpenAPI self-inspection tools | ✅ | ❌ |

---

## How it works

```mermaid
sequenceDiagram
    autonumber
    participant U as User
    participant C as Claude/MCP Client
    participant S as cymulate-mcp
    participant V as Zod Validator
    participant X as CymulateClient
    participant A as Cymulate REST API

    U->>C: "Launch BAS assessment on endpoint module"
    C->>S: tools/call: cymulate_bas_launch { module: "endpoint", ... }
    S->>V: validate input schema
    V-->>S: parsed & type-safe args
    S->>X: POST /v1/edr/start (adds x-token header)
    X->>A: HTTPS request
    A-->>X: 200 OK + assessment_id + X-RateLimit-* headers
    X-->>S: mapped response (semantic errors on 4xx/5xx)
    S-->>C: structured result + rate-limit warning if remaining < 10
    C-->>U: renders result
```

---

## When to use which tool

```mermaid
flowchart TD
    Start[Need to call Cymulate API] --> Q1{Common lifecycle<br/>operation?}
    Q1 -->|Yes: launch/stop/status/report| BAS[cymulate_bas_* — 7 unified tools<br/>module enum: endpoint, waf, web_gateway, ...]
    Q1 -->|Yes: EV/EA/ASM/Findings/etc.| FC[Use first-class semantic tool<br/>see CATALOG.md — 100 tools]
    Q1 -->|No — rare/new endpoint| Q2{Know the path?}
    Q2 -->|Yes| GENERIC[cymulate_api_call<br/>generic REST fallback]
    Q2 -->|No — need to discover| INSPECT[cymulate_api_list_endpoints<br/>then cymulate_api_describe_endpoint<br/>then cymulate_api_call]
    BAS --> Done[Response with rate-limit awareness]
    FC --> Done
    GENERIC --> Done
    INSPECT --> Done
```

---

## Setup

### Requirements
- Node.js ≥ 20
- A Cymulate account with API access enabled (generate an API key in the Cymulate console → Settings → API Keys)

### Install

```bash
git clone https://github.com/lyonzin/cymulate-mcp-tools.git
cd cymulate-mcp-tools
npm install
cp .env.example .env
# Edit .env: set CYMULATE_API_KEY
npm run build
```

### Run

```bash
# STDIO (for MCP clients like Claude Code, Cursor, Continue)
npm start

# HTTP Streamable (for remote hosting)
npm run start:http
# Listens on http://127.0.0.1:9494/mcp by default
```

---

## Register with an MCP client

### Claude Code (CLI)

```bash
claude mcp add cymulate node /absolute/path/to/cymulate-mcp-tools/dist/index.js
```

Then set the API key in the shell that spawns Claude, or edit `~/.claude.json`:

```json
{
  "mcpServers": {
    "cymulate": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/cymulate-mcp-tools/dist/index.js"],
      "env": {
        "CYMULATE_API_KEY": "your_key_here",
        "CYMULATE_API_BASE": "https://api.us-app.cymulate.com"
      }
    }
  }
}
```

### Cursor / Continue / other MCP clients

Same JSON shape as above — most MCP clients accept a `mcpServers` map. Point `command` to `node` and `args` to the built `dist/index.js`.

### HTTP mode (remote MCP host)

Start the server in HTTP mode:

```bash
MCP_TRANSPORT=http MCP_HTTP_PORT=9494 npm start
```

Then register the endpoint URL in your MCP client instead of a local command.

---

## Environment variables

| Variable | Default | Required | Purpose |
|---|---|---|---|
| `CYMULATE_API_KEY` | — | ✅ | API key from Cymulate console |
| `CYMULATE_API_BASE` | `https://api.us-app.cymulate.com` | | REST API base URL (change for EU tenant: `https://api.app.cymulate.com`) |
| `MCP_TRANSPORT` | `stdio` | | `stdio` or `http` |
| `MCP_HTTP_HOST` | `127.0.0.1` | | HTTP bind host (only in `http` mode) |
| `MCP_HTTP_PORT` | `9494` | | HTTP bind port |
| `CYMULATE_REQUEST_TIMEOUT_MS` | `60000` | | Per-request timeout |
| `CYMULATE_MAX_RETRIES` | `2` | | Retries on 429/5xx |
| `MCP_LOG_LEVEL` | `info` | | `debug`, `info`, `warn`, `error` |

---

## Tool catalog (18 categories, 106 tools total)

Full list with descriptions in [`CATALOG.md`](./CATALOG.md). Condensed:

| # | Category | Tools | Purpose |
|---|---|---:|---|
| 1 | **BAS Attack Simulation** (unified) | 7 | Launch/stop/status/report across 11 BAS modules via `module` enum |
| 2 | **Immediate Threats** | 5 | Threat catalog, IOCs, MITRE mapping, SIEM detection |
| 3 | **Full Kill-Chain** (FKC) | 4 | FKC scenarios + campaigns, agent selection |
| 4 | **Attack Surface Management** (ASM) | 5 | Scan trigger, history, findings |
| 5 | **Advanced Scenarios** (Purple Team) | 6 | Template CRUD, actions catalog |
| 6 | **EV — Launched Assessments** | 6 | List, create, get, delete, filters |
| 7 | **EV — Scheduled Assessments** | 6 | Schedule CRUD + configurations |
| 8 | **EV — Templates + Smart Templates** | 8 | Template CRUD + smart templates |
| 9 | **EV — Scenarios** | 5 | Scenario CRUD |
| 10 | **EV — Threats** | 5 | Threat listing + auto-run schedules |
| 11 | **EV — Resources** | 4 | Resource CRUD + filters |
| 12 | **EV — Input Configs + Groups + Pre-Reqs + WAF** | 9 | Assessment prerequisites, template grouping |
| 13 | **Exposure Analytics** (EA) | 8 | CVEs, exposures, remediation tasks + export |
| 14 | **Findings + Auto Remediation** | 6 | Findings search + auto-remediation apply |
| 15 | **Environments + Agents** | 8 | Env CRUD, agent listing (connected/all), hashes |
| 16 | **Platform** (SSO/Score/MITRE/Trace/Activity) | 5 | Admin dashboards, MITRE ATT&CK coverage |
| 17 | **General Info** | 3 | Activity center, users, integrations |
| 18 | **Utility & Fallback** | 6 | `cymulate_api_call`, endpoint discovery, health, OpenAPI, debug |

**Naming convention:** `cymulate_<domain>_<action>[_<subject>]`.

---

## Architecture

- **Dual transport in one binary** — STDIO for local MCP clients, HTTP Streamable for remote hosting. Select via `MCP_TRANSPORT`.
- **Zod schemas everywhere** — input validated before touching the API. Type-safe.
- **Rate-limit awareness** — client parses `X-RateLimit-Remaining` on every response; tools return a warning when < 10 remaining.
- **Semantic error mapping** — 401/403/404/429/5xx get MCP-native error codes, not raw HTTP noise.
- **OpenAPI spec cached in memory** — `cymulate_openapi_spec` and `cymulate_api_describe_endpoint` serve from cache after cold start.
- **Idempotency + destructive hints** — every tool declares `readOnlyHint` / `idempotentHint` / `destructiveHint` in MCP annotations for client-side confirmation prompts.

---

## Development

```bash
npm run dev        # tsx watch mode
npm run typecheck  # tsc --noEmit
npm run build      # tsc → dist/
npm run clean      # rimraf dist
```

### Smoke test against real tenant

```bash
node scripts/smoke.mjs   # probes 27 endpoints, reports pass/fail by group
node scripts/mcp-probe.mjs  # boots MCP server, verifies tools/list
```

---

## Contributing

Community PRs welcome. Because the project is unmaintained by the original author:
- Please include a reproducible test case (a `smoke.mjs`-style probe against the changed area is ideal).
- If Cymulate's API drifts (new endpoints, breaking changes), open an issue with the OpenAPI diff — a maintainer from the community can pick it up.
- Fork freely if you need faster iteration.

---

## License

MIT — see [LICENSE](./LICENSE).

## Disclaimer

This is an independent, community project. It is not affiliated with, endorsed by, or supported by Cymulate Ltd. "Cymulate" is a trademark of Cymulate Ltd. Verify your Cymulate Terms of Service permits third-party API clients before using this software.