# jobs-winterchill-mcp

An [MCP](https://modelcontextprotocol.io) server over the **winterchill** UK tech-jobs catalog
([jobs.winterchill.xyz](https://jobs.winterchill.xyz)). It's a thin, read-only client over the
public catalog API — no secrets, nothing stored — that lets an MCP client (Claude Desktop, the
Claude CLI, etc.) search jobs, inspect companies, and match/tailor a CV.

## Tools

| Tool | What it does |
|------|--------------|
| `search_jobs` | Search the live board (free-text + filters: city, salary, sponsorship, discipline, tech, level, source, sort). |
| `get_job` | Fetch one job by `source` + `id`, with the full description. |
| `get_company` | Company facts (rating, size, industry, Levels.fyi comp) + its current live roles. |
| `match_cv` | Rank the live board against a pasted CV (semantic retrieve → rerank → comp-weighted). |
| `tailor_cv` | ATS-tailor a CV to one job — returns applyable `before → after` edits + advice. |
| `list_filters` | The accepted filter values (cities, disciplines, levels, sources, technologies). |

`match_cv` / `tailor_cv` are stateless and anonymous (nothing is stored); they're rate-limited
per IP. `tailor_cv` returns up to 5 edits on the free/anonymous tier.

## Install / configure

Requires Python ≥ 3.10. The server speaks MCP over **stdio**.

Add it to your MCP client config (Claude Desktop `claude_desktop_config.json`, or the Claude CLI):

```json
{
  "mcpServers": {
    "winterchill": {
      "command": "uvx",
      "args": ["jobs-winterchill-mcp"]
    }
  }
}
```

Or run from a local checkout:

```bash
uv run jobs-winterchill-mcp
# or
pip install -e . && jobs-winterchill-mcp
```

### Configuration

| Env var | Default | Purpose |
|---------|---------|---------|
| `WINTERCHILL_API_BASE` | `https://jobs.winterchill.xyz` | Override the catalog API base URL (e.g. for local dev). |

## How it works

Every tool maps to a public endpoint:

- `search_jobs` → `GET /api/v1/jobs`
- `get_job` → `GET /api/v1/jobs/{source}/{id}`
- `get_company` → `GET /api/v1/companies/{key}`
- `match_cv` → `POST /api/cv/match`
- `tailor_cv` → `POST /api/cv/job-match` (`mode: tailor`)

No API key is needed. The catalog data is the same already-public board; this server just makes
it available to LLM agents over MCP.

## Releasing

Publishing to PyPI is automated via GitHub Actions + **PyPI Trusted Publishing** (OIDC, no token
stored). In short: bump `version` in `pyproject.toml`, then publish a GitHub Release — the
`publish` workflow builds and uploads. Full steps (incl. the one-time PyPI pending-publisher
setup) are in **[RELEASING.md](RELEASING.md)**.

## License

MIT © Valerii Iatsko