# job104-mcp

An MCP server for searching [104 人力銀行](https://www.104.com.tw) job listings with
natural-language filters. Works with any MCP client — Claude, Cursor, Windsurf, Cline,
Zed, VS Code, and others.

> **Disclaimer:** This is an unofficial, educational/personal-use tool. It is **not
> affiliated with, endorsed by, or sponsored by 104 Corporation**. It calls 104's
> public web endpoints; please respect 104's Terms of Service and use it at a
> reasonable, low frequency. No scraped job data is distributed with this project.

## How it works

104 sits behind Cloudflare bot protection — a plain HTTP request to its JSON API
returns 403. This server uses [`curl_cffi`](https://github.com/lexiforest/curl_cffi)
with `impersonate="chrome"` to match a real browser's TLS fingerprint, so the same
public endpoints return their normal JSON. The AI sees clean structured results; the
104 category/area codes are resolved from Chinese names automatically.

## Prerequisite: install uv

Every install path runs the server through [uv](https://docs.astral.sh/uv/), so it must
be installed first (`uvx` ships with uv):

    # macOS / Linux
    curl -LsSf https://astral.sh/uv/install.sh | sh
    # Windows (PowerShell)
    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

## Install in any MCP client (Cursor, Windsurf, Cline, Zed, VS Code, …)

MCP is an open protocol, so any MCP-capable client works — not just Claude. Add this to
the client's MCP config (e.g. Cursor's `~/.cursor/mcp.json`); the `command`/`args` form is
what most clients accept:

    {
      "mcpServers": {
        "job104": { "command": "uvx", "args": ["job104-mcp@latest"] }
      }
    }

## Install in Claude Code (User scope)

    claude mcp add job104 -s user -- uvx job104-mcp@latest

Or from a local clone (no PyPI required):

    claude mcp add job104 -- uv run --project /absolute/path/to/job104-mcp -m job104_mcp

## Install in Claude Desktop (.mcpb bundle)

The `.mcpb` bundle is a Claude-Desktop-only convenience (other clients use the JSON config
above). Download `job104-mcp-vX.Y.Z.mcpb` from the
[Releases](https://github.com/mozzan/job104-mcp/releases) page and double-click it (or drag
it into Claude Desktop → Settings → Extensions).

To build the bundle yourself:

    npx @anthropic-ai/mcpb pack .   # produces job104-mcp.mcpb

## Run manually (stdio)

    uv run job104-mcp
    # or
    uv run python -m job104_mcp

## Tools

- `search_jobs` — search with keyword, area, job category, salary floor, remote,
  recency, experience, education, sort, paging. Use Chinese names for `area`/`jobcat`
  (e.g. `["台北市大安區"]`, `["軟體工程師"]`); they resolve to 104 codes automatically.
  Each result carries a `detail_id`.
- `get_job_detail` — full posting for a `detail_id` from `search_jobs`.
- `lookup_code` — resolve a job-category or area name to its 104 code.

## Refresh code tables

The bundled `jobcat.json` / `area.json` come from 104's public category tool. Regenerate:

    uv run python scripts/fetch_codes.py

## Tests

    uv run pytest            # fast unit tests
    uv run pytest -m live    # hits the real 104 site

## Releasing (maintainer)

Releases are automated by `.github/workflows/release.yml`, triggered when the
version in `pyproject.toml` changes on `main`. It publishes to PyPI, builds the
`.mcpb` bundle, and attaches it to a GitHub Release.

One-time PyPI setup (uses [Trusted Publishing](https://docs.pypi.org/trusted-publishers/),
no API token stored): on <https://pypi.org/manage/account/publishing/> add a pending
publisher with project `job104-mcp`, owner `mozzan`, repo `job104-mcp`, workflow
`release.yml`.

To cut a release: bump `version` in `pyproject.toml`, commit to `main`.

## License

MIT — see [LICENSE](LICENSE). Provided as-is, without warranty.