# Greenhouse MCP Server

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

## Features

- **Candidate Management**: List, get, create, update candidates, and add candidate notes
- **Application Tracking**: Browse applications, advance through pipeline stages, reject applications
- **Job Management**: List, get, create, and update job postings and requisitions
- **Interviews**: List all interviews, get interview details, list scheduled interviews
- **Scorecards**: Browse interview feedback, get scorecard details, create new scorecards
- **Offers**: List and retrieve offer details and compensation information
- **Organization Data**: Access departments, offices, sources, rejection reasons, job stages, and custom fields
- **User Management**: List and retrieve Greenhouse users and team members

## Installation

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

## Environment Variables

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `GREENHOUSE_API_KEY` | ✅ | Greenhouse Harvest API key | `your_harvest_api_key_here` |

## Getting Your Access Token

1. Log into your Greenhouse account
2. Navigate to **Configure** > **Dev Center** > **API Credential Management**
3. Click **Create New API Key**
4. Select **Harvest API** (for production data access)
5. Set appropriate permissions for your use case
6. Copy the generated API key
7. Set it as `GREENHOUSE_API_KEY` in your environment

## Required API Scopes

The Harvest API key requires permissions based on your use case:

- **Read access**: Candidates, Applications, Jobs, Interviews, Scorecards, Offers, Users, Departments, Offices
- **Write access**: Create/update candidates, create scorecards, advance applications, reject applications, create/update jobs

Configure permissions when creating the API key in Greenhouse.

## 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 Greenhouse Harvest API endpoints**: ~150
- **Tools implemented**: 20
- **Intentionally skipped**: 130
- **Coverage**: 20/150 = 13%

### Implemented Tools

| Category | Tools | Count |
|----------|-------|-------|
| Candidates | list, get, create, update, create_note | 5 |
| Applications | list, get, advance, reject | 4 |
| Jobs | list, get, create, update | 4 |
| Interviews | list, get, list_scheduled | 3 |
| Scorecards | list, get, create | 3 |
| Offers | list, get | 2 |
| Organization | list_departments, list_offices, list_sources, list_rejection_reasons, list_job_stages, list_custom_fields | 6 |
| Users | list, get | 2 |

**Total: 29 tools** across 8 categories

### Skipped Endpoints (Rationale)

- **Job Posts** (6 endpoints): Covered by job management tools, posts are auto-created with jobs
- **Email Templates** (4 endpoints): Admin configuration, rarely needed in AI workflows
- **Approvals** (5 endpoints): Complex approval flow management better suited for UI
- **EEOC** (3 endpoints): Compliance data requiring special handling
- **Activity Feed** (10+ endpoints): Duplicates data available in primary resources
- **Webhooks** (8 endpoints): Admin configuration, not suitable for MCP tool calls
- **Attachments** (4 endpoints): Complex binary handling, requires special transport
- **Tags** (4 endpoints): Low-value metadata, rarely used
- Other low-use administrative endpoints

### Coverage Goals

Current implementation focuses on **Tier 1** (daily recruiting workflows):
- Reviewing candidates and applications
- Advancing candidates through pipeline
- Scheduling and evaluating interviews
- Managing job postings
- Accessing organizational data

**Future expansion** could add Tier 2 tools for power users:
- Bulk operations
- Advanced reporting
- Candidate pool management
- Offer approval workflows

## Development

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

# Build
npm run build

# Type checking
npx tsc --noEmit
```

## License

MIT