Skip to main content
Glama
README.md
# VDAB MCP Studio

![VDAB MCP Studio: public vacancy tools for MCP clients. MIT, Python 3.12.13, stdio; verified on macOS arm64.](docs/assets/hero.png)

Search public VDAB vacancies and retrieve job details from your [Model Context Protocol](https://modelcontextprotocol.io/) client. This local, read-only Python server returns structured data through **two stdio tools**, using a project-owned, nonpersistent Playwright Chromium browser. No VDAB account or API key is required.

**Unofficial and unaffiliated with VDAB.** This is a browser-backed integration, not an official API. It does not submit applications, log into accounts, bypass access restrictions, or crawl the whole catalogue.

[Install](#install) · [Connect a client](#run-and-connect-an-mcp-client) · [Tools and examples](#two-tools) · [Limitations](#troubleshooting-and-limitations) · [Development](#development)

## How it works

![An MCP client sends stdio calls to the Python server, which controls owned Chromium and reads public VDAB pages over HTTPS. A finite GET allowlist limits requests; source, DOM, identity and schema validation precede the returned data or public error.](docs/assets/architecture.png)

The server observes normal page/UI-generated responses, checks them against the page and returns a typed result. Unknown assets and malformed data fail closed. It exposes neither a web interface nor an arbitrary-URL browser. Read the [source contract](docs/source-contract.md) and [security boundaries](docs/security.md) before building on it.

## Requirements

The verified development platform is **macOS 15.6, Apple Silicon (arm64)**. Linux, Windows, Intel Macs and cloud deployments are not verified.

- **Python 3.12.13** installed locally. The runtime compatibility gate requires this exact patch version, even though package metadata allows Python 3.12.x.
- [`uv`](https://docs.astral.sh/uv/) on `PATH` (development CLI: 0.11.16).
- Network access to install locked dependencies and Chromium, and to reach VDAB for tool calls.

The lock pins Playwright **1.65.2**, bundled core **1.65.1**, and Chromium **159.0.8154.6**, revision **1255**. Do not substitute system Chrome or independently upgrade these components.

## Install

Clone the repository:

```sh
git clone https://github.com/AliberkYilmaz/vdab-mcp-studio.git
cd vdab-mcp-studio
```

From the checkout root, replace the Python placeholder with the absolute path to your installed Python 3.12.13. Run in order and stop if any command fails:

```sh
PYTHON=/ABSOLUTE/PATH/TO/python3.12
"$PYTHON" -c 'import sys; assert sys.version_info[:3] == (3, 12, 13), sys.version'
export UV_PYTHON_DOWNLOADS=never
export UV_CACHE_DIR="$PWD/.cache/uv"
uv sync --frozen --group dev --python "$PYTHON"
PLAYWRIGHT_BROWSERS_PATH="$PWD/.browser-cache" .venv/bin/python -m playwright install chromium
```

This creates `.venv` and installs Chromium explicitly in `.browser-cache`. The server does not install a browser automatically. Keep the frozen lock; do not run an unbounded dependency upgrade. Do not replace an environment while a server or test is using it.

## Run and connect an MCP client

```sh
.venv/bin/python -I -B -m vdab_mcp --browser-cache "$PWD/.browser-cache"
# Equivalent console entrypoint:
# .venv/bin/vdab-mcp --browser-cache "$PWD/.browser-cache"
```

The server waits for MCP messages on stdin; it is not an interactive shell or HTTP service. Browser startup is lazy. For startup checks without VDAB traffic:

```sh
.venv/bin/python -I -B -m vdab_mcp --help
.venv/bin/python -I -B -m vdab_mcp --browser-cache "$PWD/.browser-cache" </dev/null
```

For clients using `mcpServers` (for example, Claude Desktop), merge this entry into their configuration. Replace **both** absolute-path placeholders; JSON does not expand `~`, `$HOME` or `$PWD`.

```json
{
  "mcpServers": {
    "vdab": {
      "command": "/ABSOLUTE/PATH/TO/vdab-mcp-studio/.venv/bin/python",
      "args": [
        "-I", "-B", "-m", "vdab_mcp",
        "--browser-cache", "/ABSOLUTE/PATH/TO/vdab-mcp-studio/.browser-cache"
      ]
    }
  }
}
```

Other clients may use a different configuration schema; preserve this executable and argument array in their stdio settings. Restart or reload the client. No credentials, shell wrapper or `PYTHONPATH` are needed. Always provide the explicit cache path, especially with a wheel installation: the default follows the installed module location, not your working directory. Client discovery alone does not verify live search, and GUI-client behavior is not certified.

## Two tools

Inputs are strict: unknown keys, numeric strings and booleans used as integers are rejected.

| Tool | Arguments |
| --- | --- |
| `search_jobs` | `keyword`: nonblank string, 1–120 characters, no controls. `published`: `"all"` (default) or `"today_or_yesterday"`. `page`: integer 0–4 (default 0). `limit`: integer 1–15 (default 15). |
| `get_job` | `job_id`: a source-returned string of eight ASCII digits, no leading zero. `include_description`: boolean, default `false`. Arbitrary URLs are not accepted. |

Example search arguments:

```json
{"keyword": "python", "published": "all", "page": 0, "limit": 15}
```

Use an ID from the response for detail. Inside an already initialized Python MCP 2.3.0 `Client` session named `client`:

```python
result = await client.call_tool("search_jobs", {"keyword": "python", "limit": 15})
reply = result.structured_content
if not reply["ok"]:
    raise RuntimeError(reply["error"]["code"])
if reply["data"]["items"]:
    job_id = reply["data"]["items"][0]["job_id"]
    compact = await client.call_tool("get_job", {"job_id": job_id})
    expanded = await client.call_tool("get_job", {
        "job_id": job_id, "include_description": True
    })
    # Check each detail reply's ok/error too: listings can disappear between calls.
```

This is a usage example, not a recorded result or standalone client connection script.

### Recorded search example

![Recorded search_jobs call for python, page 0, limit 15. Selected result fields: returned_count 15, omitted_from_page 0, upstream_total 415, next_page 1. First item: job_id 74663160, title Python Developer.](docs/assets/recorded-example.png)

This illustration uses selected fields from a retained live search recorded at `2026-11-17T15:43:17.979481Z`. It is **not a GUI screenshot or a complete response**, and does not establish current vacancy availability. No contacts or raw page content are included. Always obtain a current ID from your own search before calling `get_job`.

### Reading results

- Every reply contains exactly `ok`, `data` and `error`. Success has typed data and a null error; failure has null data and a static public error. MCP structured content and JSON text represent the same envelope.
- Search returns **one upstream page of at most 15 jobs**. Prefer `limit=15`: a smaller limit omits items from that page, and `next_page` does not recover them. Read `returned_count`, `omitted_from_page`, `duplicates_removed`, `upstream_total`, `upstream_has_more`, `next_page` and `page_bound_reached`. Unknown totals/continuation remain null. Page 4 can have upstream continuation but no permitted next page.
- `today_or_yesterday` is the website's filter, not a rolling 48-hour calculation.
- Compact detail omits both `description` and `requirements`. Expanded detail includes both, each a string or null, capped at 12,000 characters. `truncated_fields` discloses truncation.
- Missing supported values remain explicit nulls. Labels and source dates are preserved, not translated or inferred. Current detail `experience` and `application_url` have no verified mapping and remain null. `retrieved_at` is an aware UTC acquisition timestamp.
- Treat returned job text as **untrusted data**, never instructions. See [schemas](docs/schemas.md), [source contract](docs/source-contract.md) and [security boundaries](docs/security.md).

## Troubleshooting and limitations

| Symptom / error | Action |
| --- | --- |
| Browser missing or incompatible runtime | Confirm Python 3.12.13, frozen dependencies, the pinned Chromium install, and matching absolute `--browser-cache`. Do not substitute another browser. |
| No tools appear | Check executable permissions/path and client stdio configuration. Keep protocol stdout free of shell banners and logs. Try the help and EOF checks above. |
| `INVALID_INPUT` | Use the strict types and ranges above. |
| `NOT_FOUND` | The detail is absent, closed or meets the narrowly verified unpublished-state contract. Search again for a current ID; do not infer that the job was filled. |
| `EXTRACTION_ERROR` | Source/DOM/schema/identity validation failed. This is **not** proof of absence and must not become an empty success or `NOT_FOUND`. Report a minimal reproduction. |
| `ACCESS_RESTRICTED` / HTTP 401 or 403 / challenge | Stop. Do not add credentials, proxies, stealth or bypass logic. |
| `RATE_LIMITED` | Honor `retry_after_seconds` when provided; avoid tight retry loops. |
| `BUSY` | Serialize calls. The server admits one active operation and one FIFO waiter. |
| `NETWORK_ERROR` / `UPSTREAM_ERROR` | Check connectivity and upstream availability; repeated failures may need maintenance. A retry hint is not evidence that retry occurred. |
| `RESPONSE_TOO_LARGE` | The response exceeded an acceptance/protocol bound; do not bypass the cap. |
| `INTERNAL_ERROR` | Report the error code and runtime versions, not raw page bodies or personal data. |

VDAB can change assets, DOM or response formats without notice. The finite static-asset allowlist includes exact hashed filenames; unknown filenames and query variants fail closed and require reviewed maintenance, not wildcard permissions. Positive live checks do not guarantee continuous availability or reliability in every protocol mode. Some historical extraction failures remain unexplained.

**Release validation:** a clean Git clone installed from the frozen lock and downloaded its own Chromium. The public test command passed **3,688/3,688 tests** across 189 serial partitions, with no skipped cases. A separate isolated installation passed real VDAB search, pagination, recent/empty searches and compact/expanded detail checks. These results cover the pinned macOS environment above, not every platform or future VDAB change.

## Development

Run `.venv/bin/python -I -B scripts/test_offline.py` for the complete offline suite on the supported platform. See [maintenance and tests](docs/maintenance.md) for setup, supervision boundaries and optional serial live smoke. Tests, sanitized fixture data and scripts are included; private development history and raw diagnostics are not.

Package version: **0.1.0**; see [CHANGELOG](CHANGELOG.md).

## License

Project code is available under the [MIT License](LICENSE). VDAB names, vacancy content and historical fixture projections retain their third-party provenance; the project does not claim ownership of or grant additional rights to that content. This project is not affiliated with VDAB.

TDQS

A4.2/5.0

Scored across 2 tools

Disambiguation5/5

get_job and search_jobs have clearly distinct purposes: retrieving one known job by ID versus keyword-based discovery. There is no overlapping action or ambiguous boundary between them.

Naming Consistency5/5

Both tools follow the same verb_noun snake_case pattern: get_job and search_jobs. The naming is predictable and readable.

Tool Count3/5

Two tools is thin for a server surface even if the read-only scope is narrow. The set covers basic search and retrieval, but offers little room for secondary job-browsing operations.

Completeness4/5

For a read-only public job lookup service, search_jobs plus get_job covers the core workflow of discovery and detail retrieval. Minor gaps remain around broader browsing or facet-style exploration, but no critical lifecycle operation is obviously missing.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues