# Lever MCP Server

A Model Context Protocol (MCP) server implementation for the Lever ATS (Applicant Tracking System) platform. This server enables AI assistants to interact with Lever's recruiting and hiring workflows through a standardized interface.

## Features

- **Complete API Coverage**: 19 tools covering all major Lever workflows
- **Rate Limiting**: Built-in rate limiting (10 req/sec steady state, 20 req/sec burst)
- **Error Handling**: Comprehensive error handling with descriptive messages
- **Type Safety**: Full TypeScript implementation with detailed type definitions
- **Pagination Support**: All list endpoints support pagination with `has_more` indicators
- **Authentication**: Secure Basic Auth using API keys

## Installation

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

## Configuration

Set your Lever API key as an environment variable:

```bash
export LEVER_API_KEY="your_api_key_here"
```

You can create API keys from the [Integrations and API page](https://hire.lever.co/settings/integrations) in your Lever account settings.

## Usage

### As an MCP Server

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "lever": {
      "command": "node",
      "args": ["/path/to/lever/dist/index.js"],
      "env": {
        "LEVER_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Standalone

```bash
npm start
```

## Available Tools

### Opportunities (Candidates) - 6 tools

1. **list_opportunities** - List all candidates with filtering by stage, tags, posting, owner, archive status. Supports pagination.

2. **get_opportunity** - Get detailed information about a specific candidate including contact info, stage, tags, applications, and history.

3. **create_opportunity** - Add a new candidate to the pipeline with contact details, stage assignment, tags, and posting application.

4. **update_opportunity** - Modify candidate information, change stage, update tags, assign owner, or archive/unarchive.

5. **add_opportunity_note** - Record notes, interactions, or feedback on a candidate. Supports secret/confidential notes.

6. **add_opportunity_tag** - Add categorization tags to candidates for filtering and organization.

### Postings (Job Openings) - 4 tools

7. **list_postings** - List all job postings with filtering by state, department, location, commitment level.

8. **get_posting** - Get full job posting details including description, requirements, hiring manager, and application questions.

9. **create_posting** - Create a new job posting with title, description, department, location, and distribution settings.

10. **update_posting** - Modify job posting details, change status (open/close), update description, or reassign ownership.

### Pipeline Stages - 1 tool

11. **list_stages** - Get all pipeline stages to understand hiring workflow and obtain stage IDs for moving candidates.

### Users - 2 tools

12. **list_users** - List all team members with roles and permissions. Use for assigning ownership or followers.

13. **get_user** - Get detailed user information including role, permissions, and contact details.

### Offers - 3 tools

14. **list_offers** - View all offers for a candidate including status (draft, sent, signed).

15. **get_offer** - Get detailed offer information including compensation, start date, and documents.

16. **create_offer** - Generate a new employment offer with compensation details and terms.

### Feedback & Forms - 3 tools

17. **list_feedback** - View all interview feedback and scorecards for a candidate.

18. **submit_feedback** - Submit or update interview feedback and scorecards.

19. **list_feedback_templates** - Get available feedback templates (interview scorecards) and their structure.

## Tool Naming Conventions

All tools follow consistent naming patterns:

- `list_*` - Paginated collection endpoints (support offset/limit)
- `get_*` - Single resource retrieval by ID
- `create_*` - Resource creation
- `update_*` - Resource modification
- `add_*` - Add sub-resources (tags, notes, etc.)
- `submit_*` - Submit forms/feedback

All tool names use `snake_case` for consistency.

## Pagination

All `list_*` tools support pagination:

**Request Parameters:**
- `limit` (number, optional): Number of results per page (1-100, default 100)
- `offset` (string, optional): Pagination token from previous response

**Response Format:**
```json
{
  "data": [...],
  "has_more": true,
  "next_offset": "0.1414895548650.a6070140-33db"
}
```

To get the next page, pass the `next_offset` value as the `offset` parameter in your next request.

## Error Handling

The server provides detailed error messages for common scenarios:

- **400 Invalid Request**: Malformed parameters or missing required fields
- **401 Unauthorized**: Invalid API key
- **403 Forbidden**: Insufficient permissions for the requested operation
- **404 Not Found**: Resource does not exist
- **429 Rate Limit**: Too many requests (retry with exponential backoff)
- **500 Server Error**: Lever service error
- **503 Service Unavailable**: Lever is temporarily down

## API Coverage Manifest

### Total Lever API Endpoints
Based on Lever API documentation (https://hire.lever.co/developer/documentation):

| Category | Total Endpoints | Covered | Coverage |
|----------|----------------|---------|----------|
| Opportunities | 15+ | 6 | 40% |
| Applications | 3 | 0* | 0% |
| Postings | 10+ | 4 | 40% |
| Stages | 2 | 1 | 50% |
| Users | 5 | 2 | 40% |
| Offers | 5 | 3 | 60% |
| Feedback/Forms | 8+ | 3 | 38% |
| Archive Reasons | 2 | 0 | 0% |
| Files | 4 | 0 | 0% |
| Interviews | 6 | 0 | 0% |
| Panels | 4 | 0 | 0% |
| Requisitions | 4 | 0 | 0% |
| Sources | 2 | 0 | 0% |
| Tags | 2 | 0** | 0% |
| Webhooks | 4 | 0 | 0% |
| Referrals | 3 | 0 | 0% |
| Audit Events | 2 | 0 | 0% |
| Resumes | 2 | 0 | 0% |

**Total Estimated Endpoints:** ~80+  
**Tools Implemented:** 19  
**Coverage:** ~24%

\* Applications are created via `create_opportunity` with posting_id  
\*\* Tags are managed via `add_opportunity_tag` and opportunity update operations

### Intentionally Skipped

The following endpoints were not implemented in this initial version:

1. **Archive Reasons** (list, get) - Read-only reference data, lower priority
2. **Applications** (list, get, create) - Covered via opportunity workflows
3. **Files** (upload, list, delete) - File handling requires multipart form support
4. **Interviews** (create, update, list, delete) - Advanced scheduling features
5. **Panels** (create, update, list) - Interview panel management
6. **Requisitions** (list, create, update) - Headcount/budget tracking
7. **Sources** (list) - Reference data
8. **Tags** (list) - Covered via opportunity operations
9. **Webhooks** (create, list, update, delete) - Integration configuration
10. **Referrals** (create, list) - Specialized candidate source
11. **Audit Events** (list) - Security/compliance logging
12. **Resumes** (list, parse) - Document processing

### Coverage Rationale

This implementation focuses on the **core recruiting workflow (Tier 1)**:

✅ **Covered:**
- Candidate management (search, create, update, track)
- Job posting management (create, update, publish)
- Pipeline movement (stages)
- Team collaboration (users, notes)
- Offer generation and tracking
- Interview feedback collection

❌ **Not Yet Covered:**
- Advanced integrations (webhooks)
- File/document management
- Compliance/audit logging
- Requisition/budget tracking
- Complex interview scheduling

### Future Enhancements

Potential additions for future versions:

1. **Archive operations** - Archive/unarchive with reasons
2. **Interview scheduling** - Create and manage interviews
3. **File uploads** - Resume and document handling
4. **Requisitions** - Headcount tracking and approvals
5. **Webhooks** - Event subscriptions for real-time updates
6. **Bulk operations** - Batch candidate updates
7. **Advanced search** - Full-text search across candidates
8. **Analytics** - Pipeline metrics and reporting

## Rate Limits

Lever enforces rate limits using token bucket:
- **Steady state:** 10 requests/second
- **Burst capacity:** Up to 20 requests/second
- **Per:** API key

This server automatically handles rate limiting with the Bottleneck library.

## Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode
npm run watch

# Type checking
npx tsc --noEmit
```

## Project Structure

```
lever/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── client/
│   │   └── lever-client.ts   # API client with rate limiting
│   ├── tools/
│   │   ├── opportunities-tools.ts  # Candidate tools
│   │   ├── postings-tools.ts       # Job posting tools
│   │   ├── stages-tools.ts         # Pipeline stage tools
│   │   ├── users-tools.ts          # Team member tools
│   │   ├── offers-tools.ts         # Offer tools
│   │   └── feedback-tools.ts       # Feedback/forms tools
│   └── types/
│       └── index.ts          # TypeScript type definitions
├── package.json
├── tsconfig.json
└── README.md
```

## License

MIT

## Resources

- [Lever API Documentation](https://hire.lever.co/developer/documentation)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)

## Support

For issues or questions:
1. Check the [Lever API docs](https://hire.lever.co/developer/documentation)
2. Review API key permissions in Lever settings
3. Verify rate limits and retry with exponential backoff
4. Check server logs for detailed error messages