jobs-scrape-mcp

MCP (Model Context Protocol) server exposing the jobs-scrape corpus to an AI.

Once connected, Claude can directly query the collected job postings: “what skills are requested in the canton of Vaud?”, “how many part-time job postings in healthcare in August?”, “summarize this posting”.

Installation

uv pip install git+https://github.com/XavierBeheydt/jobs-scrape-mcp.git
claude mcp add jobs-scrape -- uv run jobs-scrape-mcp

The server reads the same database as the CLI:

Related MCP server: mcp-jobs

Exposed tools

Resources: jobs://summary and jobs://sources.

The volume of responses is the real challenge

An MCP tool returns its result in the model's context. Returning twenty complete postings -- several tens of thousands of characters -- would saturate that context for zero benefit: you don't read twenty full descriptions to answer “what skills are requested in Geneva”.

This server therefore applies a simple rule:

• list tools return excerpts (320 characters) and the structured fields used to judge relevance;

• get_job returns the full text of a single posting;

• limit is capped at 50, whatever the requested value;

• each response distinguishes total (matches) from returned (items returned), so the model knows it only sees a part.

No search logic here

BM25 ranking, facets, and aggregations live in jobs_scrape.search, at the heart of the project. This module merely exposes them. Search remains defined in a single place — the web interface and the MCP server inherit it, and an improvement to ranking benefits both.

Tool descriptions: the trigger, not just the function

The model chooses its tools based on their description. A description that only says what a tool does leaves the model to guess when to use it. Each tool therefore states its trigger — “call this tool as soon as a question concerns available job postings” — and a test verifies that no description remains sparse.

Development

uv venv
uv pip install git+https://github.com/XavierBeheydt/jobs-scrape.git
uv pip install -e ".[dev]"
uv run pytest -q      # hors ligne, base temporaire