npm package: @klevercv/mcp-server
Description: MCP server for KlevrCV — resume generation via AI agents
Latest version: 1.0.1

# @klevercv/mcp-server

MCP server for [KlevrCV](https://klevercv.com) — generate tailored resumes via AI agents without browser automation.

## Requirements

- Node.js >= 18
- A KlevrCV API key ([get one at klevercv.com/settings](https://klevercv.com/settings))

## Quick Start

Set your API key, then run:

```bash
KLEVERCV_API_KEY=kv_live_... npx -y @klevercv/mcp-server
```

On startup the server is silent. If `KLEVERCV_API_KEY` is missing it exits with an error message on stderr.

## Installation

Add to your MCP client config. All clients use the same JSON structure.

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "klevercv": {
      "command": "npx",
      "args": ["-y", "@klevercv/mcp-server"],
      "env": {
        "KLEVERCV_API_KEY": "kv_live_your_key_here"
      }
    }
  }
}
```

### Cursor

Edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "klevercv": {
      "command": "npx",
      "args": ["-y", "@klevercv/mcp-server"],
      "env": {
        "KLEVERCV_API_KEY": "kv_live_your_key_here"
      }
    }
  }
}
```

### Cline

Open the Cline sidebar → MCP Servers → Configure, then add to `cline_mcp_settings.json`:

```json
{
  "mcpServers": {
    "klevercv": {
      "command": "npx",
      "args": ["-y", "@klevercv/mcp-server"],
      "env": {
        "KLEVERCV_API_KEY": "kv_live_your_key_here"
      }
    }
  }
}
```

### Other MCP clients

Any client that supports stdio MCP servers with env vars uses the same shape. Set `KLEVERCV_API_KEY` in the `env` block and use `npx -y @klevercv/mcp-server` as the command.

## Tools

### `klevercv_generate_resume`

Submit a resume generation job. Returns immediately with a `generation_id` — does not block while the PDF is generated.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_description` | string | Yes | Full job description text |
| `job_title` | string | Yes | Job title (e.g. "Senior Engineer") |
| `company_name` | string | Yes | Company name (e.g. "Acme Corp") |
| `template_id` | string | No | Template ID from `klevercv_list_templates` |

Example response:
```
generation_id: abc123
Use klevercv_get_generation_status to poll for completion.
```

---

### `klevercv_get_generation_status`

Poll a generation job. Waits up to `timeout_seconds` for completion, then returns a signed download URL.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `generation_id` | string | Yes | ID from `klevercv_generate_resume` |
| `timeout_seconds` | number | No | Max wait time (default: 120) |

Example response (complete):
```
status: complete
download_url: https://...r2.cloudflarestorage.com/...?X-Amz-Expires=3600
```

Example response (timeout):
```
isError: true
GENERATION_TIMEOUT: Generation did not complete within 120 seconds. Try polling again.
```

---

### `klevercv_list_templates`

List available resume templates with stable IDs.

No parameters.

Example response:
```
Templates (3):
- classic: Classic — Clean single-column format
- modern: Modern — Two-column with accent color
- minimal: Minimal — Compact single-page layout
```

---

### `klevercv_list_resumes`

List past generated resumes with pagination.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | number | No | Results per page (default: 10) |
| `offset` | number | No | Pagination offset (default: 0) |

---

### `klevercv_get_account_info`

Return credits remaining, email, and account plan.

No parameters.

Example response:
```
Email: user@example.com
Plan: starter
Credits remaining: 8
Total generations: 12
```

## Error Handling

All business errors return `isError: true` with an error code so the agent can take action without crashing.

| Error code | Meaning | Agent action |
|------------|---------|--------------|
| `AUTH_FAILED` | API key invalid, expired, or missing | Stop and ask user to check their API key |
| `INSUFFICIENT_CREDITS` | No credits left | Call `klevercv_get_account_info` and inform user |
| `RATE_LIMITED` | Too many requests; includes `retry_after` seconds | Wait and retry |
| `INVALID_TEMPLATE_ID` | Template ID not recognized | Call `klevercv_list_templates` to get valid IDs |
| `GENERATION_TIMEOUT` | PDF not ready within `timeout_seconds` | Retry `klevercv_get_generation_status` with the same `generation_id` |
| `RESUME_NOT_FOUND` | Resume ID doesn't exist or belongs to another user | Verify ID with `klevercv_list_resumes` |
| `GENERATION_NOT_FOUND` | `generation_id` not found | Verify ID from `klevercv_generate_resume` response |
| `NETWORK_ERROR` | Network or API connectivity issue | Retry after a short delay |

## License

MIT