willow-mcp-server/README.md

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

# Willow MCP Server

An MCP (Model Context Protocol) server that integrates with the Willow 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 willow-mcp-server
```

Or install locally:

```bash
npm install willow-mcp-server
```

## Setup

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

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

## Usage

The server provides three tools:

### `list_interviews`

Lists interviews from the Willow 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

## Configuration

### Claude Desktop

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

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

### Local Development

If you're running from source:

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

## API Reference

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

## Requirements

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

## License

MIT