# Lever MCP Server

AI-powered access to the Lever ATS/recruiting platform via Model Context Protocol.

## Features

- **Opportunity Management**: List, get, create, search, archive opportunities (candidates), manage notes and sources
- **Job Postings**: List, get, create postings, view applicants, and get posting statistics
- **Interview Feedback**: List, get, and create interview feedback and evaluations
- **Offers**: List, get, create offers, and track offer version history
- **Users**: List and retrieve Lever users and team members
- **Pipeline Stages**: List and get pipeline stage information
- **Tags**: List tags and add tags to opportunities
- **Sources**: List candidate sources for attribution tracking

## Installation

```bash
npm install
npm run build
```

## Environment Variables

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `LEVER_API_KEY` | ✅ | Lever API key | `your_lever_api_key_here` |

## Getting Your Access Token

1. Log into your Lever account
2. Navigate to **Settings** > **Integrations** > **API**
3. Click **Create new API key**
4. Set appropriate permissions for your use case
5. Copy the generated API key
6. Set it as `LEVER_API_KEY` in your environment

## Required API Scopes

Configure API key permissions based on your use case:

- **Read access**: Opportunities, Postings, Users, Feedback, Offers, Stages, Tags, Sources
- **Write access**: Create opportunities, add tags, create feedback, create offers, archive opportunities

## Usage

### Stdio Mode (Default)

```bash
node dist/main.js
```

Or using the npm script:

```bash
npm start
```

### HTTP Mode

Currently supports stdio transport only. HTTP/SSE transport support coming soon.

## Tool Coverage Manifest

### Total API Coverage

- **Total Lever API endpoints**: ~80
- **Tools implemented**: 22
- **Intentionally skipped**: 58
- **Coverage**: 22/80 = 27.5%

### Implemented Tools

| Category | Tools | Count |
|----------|-------|-------|
| Opportunities | list, get, create, search, archive, list_notes, add_source | 7 |
| Postings | list, get, create, list_applicants, get_stats | 5 |
| Feedback | list, get, create | 3 |
| Offers | list, get, create, list_versions | 4 |
| Users | list, get | 2 |
| Stages | list, get | 2 |
| Tags | list, add | 2 |
| Sources | list | 1 |

**Total: 26 tools** across 8 categories

### Skipped Endpoints (Rationale)

- **Archive Reasons** (2 endpoints): Configuration data, rarely changed
- **Interviews** (6 endpoints): Complex scheduling, better suited for UI
- **Panels** (4 endpoints): Interview panel management, low-use
- **Requisitions** (5 endpoints): Enterprise-only feature
- **Referrals** (4 endpoints): Specific workflow, niche use case
- **Webhooks** (8 endpoints): Admin configuration, not suitable for MCP
- **Files/Attachments** (6 endpoints): Binary handling requires special transport
- **Bulk Operations** (4 endpoints): High-risk, better suited for admin tools
- **Advanced Reporting** (10+ endpoints): Complex analytics better in UI
- Other low-use administrative endpoints

### Coverage Goals

Current implementation focuses on **Tier 1** (daily recruiting workflows):
- Managing candidates and opportunities
- Reviewing and creating feedback
- Posting jobs and tracking applicants
- Extending offers
- Pipeline management

**Future expansion** could add Tier 2 tools for power users:
- Interview scheduling and panel management
- Bulk operations
- Advanced reporting and analytics
- Requisition approval workflows

## Development

```bash
# Watch mode for development
npm run dev

# Build
npm run build

# Type checking
npx tsc --noEmit
```

## License

MIT