# complyeah-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server for
[complyeah](https://complyeah.com). It lets an MCP-compatible AI assistant
(Claude Desktop, IDE assistants, and others) use your complyeah account: list
domains and scans, read findings, and start an external penetration test.

It is a thin client of the complyeah REST API — the same API documented at
<https://complyeah.com/api>. Reads are free; starting a comprehensive scan spends
one scan credit, exactly as in the web app.

## Setup

1. Create an API key on your account's **API** page and copy it (it's shown
   once). Keys look like `cmply_live_…`.
2. Add the server to your MCP client. For Claude Desktop, in
   `claude_desktop_config.json`:

   ```json
   {
     "mcpServers": {
       "complyeah": {
         "command": "npx",
         "args": ["-y", "complyeah-mcp"],
         "env": { "COMPLYEAH_API_KEY": "cmply_live_your_key_here" }
       }
     }
   }
   ```

3. Restart the client. The `complyeah` tools appear automatically.

The key is read from the `COMPLYEAH_API_KEY` environment variable — it is never
passed through the model. To point at a non-default API host, set
`COMPLYEAH_API_URL` (defaults to `https://api.complyeah.com`).

## Tools

| Tool | What it does |
|---|---|
| `whoami` | Confirm your key and show the account it belongs to. |
| `list_domains` | List your domains and verification status. |
| `list_scans` | List your scans. |
| `get_scan` | Get one scan and its status. |
| `get_findings` | List a scan's findings (severity, CVSS, remediation, fingerprint). |
| `trigger_scan` | Start a scan on a verified domain. Comprehensive spends one credit. |

`trigger_scan` is marked as a non-read-only action, so a well-behaved host asks
for your confirmation before it runs. It accepts an optional `idempotency_key`
so a retried request never starts (or charges for) a second scan.

## Develop

```bash
npm install
npm run build          # compiles src/ -> dist/
COMPLYEAH_API_KEY=cmply_live_… npm start
```

## License

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