willo-mcp-server/README.md

MCP server for Willo API integration - list interviews, participants, and get detailed participant information

# Willo MCP Server

An MCP (Model Context Protocol) server that integrates with the Willo API to manage interviews and participants. This server provides three main tools for listing interviews, listing participants, and getting detailed participant information.

## Installation

Install via npm:

```bash
npm install -g willo-mcp-server
```

Or install locally:

```bash
npm install willo-mcp-server
```

## Setup

1. Get your Willo API key from your Willo account
2. Set the API key as an environment variable:

```bash
export WILLO_API_KEY="your-api-key-here"
```

## Usage

The server provides three tools:

### `list_interviews`

Lists interviews from the Willo API with optional filters.

**Parameters:**
- `department` (optional): Key of the department to filter by
- `owner` (optional): Key of the owner to filter by  
- `search` (optional): Search by title, owner email, department name
- `ordering` (optional): Comma separated list of fields to order by
- `page_size` (optional): Number of results per page (1-30)
- `api_key` (optional): API key if not set in environment

**Example response:**
```json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "key": "1e2048a686804049b128f1357c559cbf",
      "title": "Researcher",
      "owner": {
        "key": "d62a87cd963f46a0b6d020947fd1dcf5",
        "email": "mariecurie@example.com",
        "full_name": "Marie Curie"
      },
      "organisation": {
        "key": "78d0380bb05f40fe9b5103437ef3284d",
        "name": "Willo"
      },
      "department": {
        "key": "b323b3e3bf424da3ac0b08bd534c91e2",
        "name": "HR"
      },
      "invite_link": "https://willotalent.com/invite/fhf3v/"
    }
  ]
}
```

### `list_participants`

Lists participants with optional filters.

**Parameters:**
- `interview` (optional): Key of the interview to filter by
- `department` (optional): Key of the department to filter by
- `owner` (optional): Key of the owner to filter by
- `search` (optional): Search by name, email, interview title
- `page_size` (optional): Number of results per page (1-30)
- `api_key` (optional): API key if not set in environment

### `get_participant`

Gets detailed information for a specific participant including answers and transcripts.

**Parameters:**
- `participant_id` (required): Key of the participant to get details for
- `api_key` (optional): API key if not set in environment

### `find_participants_by_status`

Finds all participants with a specific status across all interviews. This function combines multiple API calls to search through all participants and filter by their exact status.

**Parameters:**
- `status` (required): Exact Willo status to filter by
- `department` (optional): Key of the department to filter by
- `owner` (optional): Key of the owner to filter by
- `interview` (optional): Key of specific interview to search within
- `delay_ms` (optional): Delay between API calls in milliseconds (default: 200ms, min: 100ms)
- `api_key` (optional): API key if not set in environment

**Valid Status Values:**
- `"Default"` - New registrations, haven't started interview
- `"Received"` - Completed interview, pending evaluation
- `"Accepted"` - Passed evaluation, approved candidate
- `"Rejected"` - Failed evaluation, declined candidate

**Example Usage:**
```javascript
// Find all candidates pending evaluation
find_participants_by_status({ status: "Received" })

// Find all accepted candidates
find_participants_by_status({ status: "Accepted" })

// Find all rejected candidates  
find_participants_by_status({ status: "Rejected" })

// Find new/incomplete interviews
find_participants_by_status({ status: "Default" })

// Find received candidates in specific department
find_participants_by_status({ 
  status: "Received", 
  department: "dept_key_123" 
})

// Find accepted candidates with longer delay to avoid rate limiting
find_participants_by_status({ 
  status: "Accepted", 
  delay_ms: 500 
})
```

**Rate Limiting Protection:**
This function includes built-in rate limiting protection:
- Automatic retry with exponential backoff for 429 errors
- Configurable delays between API calls
- Batch processing to avoid overwhelming the API
- Graceful error handling that continues processing other participants

## Configuration

### Claude Desktop

Add to your Claude Desktop MCP settings (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "willow": {
      "command": "npx",
      "args": ["willo-mcp-server"],
      "env": {
        "WILLO_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Local Development

If you're running from source:

```json
{
  "mcpServers": {
    "willow": {
      "command": "node",
      "args": ["/path/to/willo-mcp-server/dist/index.js"],
      "env": {
        "WILLO_API_KEY": "your-api-key"
      }
    }
  }
}
```

## API Reference

This server integrates with the Willo API v2. For more information about the API endpoints and responses, refer to the [Willo API documentation](https://documenter.getpostman.com/view/7798010/VUjSEiSn).

## Requirements

- Node.js 18.0.0 or higher
- Valid Willo API key

## License

MIT