hiringcafe-cli 0.1.4__tar.gz → 0.2.0__tar.gz

hiringcafe_cli-0.2.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: hiringcafe-cli
+Version: 0.2.0
+Summary: Spec-driven Python CLI for Hiring Cafe job search and saved-job tracking
+Author: chen-gdp
+Author-email: chen-gdp <146709874+chen-gdp@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/chen-gdp/hiringcafe-cli
+Project-URL: Repository, https://github.com/chen-gdp/hiringcafe-cli
+Project-URL: Issues, https://github.com/chen-gdp/hiringcafe-cli/issues
+Project-URL: Changelog, https://github.com/chen-gdp/hiringcafe-cli/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# HiringCafe CLI
+
+Give your AI agent Hiring Cafe superpowers: search jobs, inspect postings, and keep your real Hiring Cafe saved-job board in sync without a browser.
+
+[![PyPI](https://img.shields.io/pypi/v/hiringcafe-cli.svg)](https://pypi.org/project/hiringcafe-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/hiringcafe-cli.svg)](https://pypi.org/project/hiringcafe-cli/)
+[![CI](https://github.com/chen-gdp/hiringcafe-cli/actions/workflows/ci.yaml/badge.svg)](https://github.com/chen-gdp/hiringcafe-cli/actions/workflows/ci.yaml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+```bash
+hiringcafe search "python developer" --jsonl
+```
+
+The CLI gives your agent structured access to public jobs and, when authenticated, selected actions on your real Hiring Cafe account. Public search and job details use Hiring Cafe's [documented read-only MCP connector](https://hiringcafe.com/documentation/hiringcafe-claude-connector): each search returns at most 10 jobs, with at most one job per company and no pagination or filters yet. Requests are rate-limited; avoid high-frequency automated polling.
+
+> **Unofficial client.** This project is not affiliated with, endorsed by, or supported by Hiring Cafe. Use your own account, respect the service, and expect upstream APIs to change.
+
+## Contents
+
+- [Install](#install)
+- [For agents](#for-agents)
+- [Commands](#commands)
+- [Authentication](#authentication)
+- [Saved jobs](#saved-jobs)
+- [Caching and local data](#caching-and-local-data)
+- [Exit codes](#exit-codes)
+- [Development](#development)
+- [Project status](#project-status)
+
+## Install
+
+HiringCafe CLI is published on PyPI and supports Python 3.11–3.14 with no runtime dependencies.
+
+Install it as a persistent CLI tool:
+
+```bash
+uv tool install hiringcafe-cli
+```
+
+Or, if you prefer pipx:
+
+```bash
+pipx install hiringcafe-cli
+```
+
+Run it once without installing anything:
+
+```bash
+uvx --from hiringcafe-cli hiringcafe --version
+```
+
+Verify the installed version:
+
+```bash
+hiringcafe --version
+```
+
+## For agents
+
+The smallest useful loop is install, search, and consume machine-readable output:
+
+```bash
+uv tool install hiringcafe-cli
+hiringcafe search "python developer" --page 0 --json
+```
+
+For a fresh result, bypass the anonymous-read cache:
+
+```bash
+hiringcafe search "python developer" --no-cache --json
+```
+
+Stream the returned jobs as one JSON object per line (up to 10 results):
+
+```bash
+hiringcafe search "python developer" --jsonl
+```
+
+Extract the normalized jobs from one JSON page:
+
+```bash
+hiringcafe search "python developer" --page 0 --json | jq -c '.result.jobs[]'
+```
+
+Ask only for the result count:
+
+```bash
+hiringcafe count "python developer" --json
+```
+
+Import an existing Firebase refresh token without an interactive password prompt:
+
+```bash
+printf '%s\n' "$HIRINGCAFE_REFRESH_TOKEN" | hiringcafe auth import
+hiringcafe saved-jobs list --json
+```
+
+Agent automation contract:
+
+- JSON success output goes to stdout; diagnostics and cache notices go to stderr.
+- Stable exit codes describe transport, input, rate-limit, auth, and conflict outcomes.
+- Provider passwords and Firebase ID tokens are never written to disk.
+- Authenticated mutations are never retried or cached.
+- Anonymous search/count responses use a 15-minute cache; job details use 24 hours.
+- Search returns at most 10 jobs, one per company; pagination and filters are not supported by the current upstream interface.
+- Invalid arguments fail before a network request is made.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `hiringcafe search "query" --json` | Search jobs and print structured JSON |
+| `hiringcafe search "query" --jsonl` | Stream up to 10 search results as JSON Lines |
+| `hiringcafe count "query" --json` | Print only the result count |
+| `hiringcafe job show <objectID> --json` | Inspect one job posting |
+| `hiringcafe auth login --email you@example.com` | Authenticate interactively |
+| `hiringcafe auth import` | Import an existing Firebase refresh token |
+| `hiringcafe auth status` | Check whether a local session exists |
+| `hiringcafe auth logout` | Remove the local session |
+| `hiringcafe saved-jobs list --json` | List saved jobs |
+| `hiringcafe saved-jobs save <objectID>` | Save a job |
+| `hiringcafe saved-jobs stage <objectID> --stage applied` | Change a job stage |
+| `hiringcafe saved-jobs remove <objectID> --yes` | Remove a saved job |
+| `hiringcafe cache purge` | Remove cached anonymous reads |
+
+Every command supports `--help`, for example:
+
+```bash
+hiringcafe search --help
+hiringcafe saved-jobs save --help
+```
+
+## Authentication
+
+For human use, log in with your Hiring Cafe email:
+
+```bash
+hiringcafe auth login --email you@example.com
+hiringcafe auth status
+```
+
+The password is read from hidden input (or `HIRINGCAFE_PASSWORD` for automation), exchanged once for Firebase credentials, and only the refresh token is stored.
+
+For automation, import a refresh token that you already hold:
+
+```bash
+printf '%s\n' "$HIRINGCAFE_REFRESH_TOKEN" | hiringcafe auth import
+```
+
+The CLI stores only the refresh token in an owner-only local session file. It does not store your password or short-lived Firebase ID token. Browser OAuth login is intentionally deferred until its real provider and loopback callback behavior can be verified.
+
+## Saved jobs
+
+These commands modify your real Hiring Cafe account. Review object IDs and confirmation prompts before changing data.
+
+`saved-jobs save` currently depends on an older raw job-hydration endpoint that is returning a Cloudflare challenge from the CLI host. It may fail before saving; the read-only MCP connector does not support saved-job writes or provide the raw object needed by this command. Listing, staging, and removing saved jobs use separate authenticated flows.
+
+```bash
+hiringcafe saved-jobs save <objectID> --stage saved
+hiringcafe saved-jobs stage <objectID> --stage interviewing
+hiringcafe saved-jobs remove <objectID> --yes
+```
+
+Valid stages are `saved`, `applied`, `interviewing`, `offer`, `rejected`, `ghosted`, and `hidden`.
+
+## Caching and local data
+
+| Data | Location | Notes |
+|---:|---|---|
+| Refresh token | `~/.config/hiringcafe-cli/session.json` | Owner-only file; removed by logout |
+| Anonymous cache | `~/.cache/hiringcafe-cli/cache/v1/` | Public search and job data only |
+
+Set `HIRINGCAFE_CONFIG_HOME` or `HIRINGCAFE_CACHE_HOME` to use different roots.
+
+```bash
+hiringcafe search "python developer" --no-cache
+hiringcafe search "python developer" --cache-ttl 3600
+hiringcafe cache purge
+```
+
+Authenticated saved-job operations are never cached.
+
+## Exit codes
+
+| Code | Agent action |
+|---:|---|
+| `0` | Success |
+| `1` | Transport, HTTP, parsing, or API error; inspect stderr |
+| `2` | Invalid arguments or search state; fix the request |
+| `3` | Rate limited; wait and retry |
+| `4` | No stored credential; authenticate first |
+| `5` | Stored credential rejected; re-authenticate |
+| `6` | Write conflict or prerequisite missing; refresh state |
+
+## Development
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/chen-gdp/hiringcafe-cli.git
+cd hiringcafe-cli
+uv sync
+uv run pytest
+uv run hiringcafe --help
+uv run pre-commit run --all-files
+```
+
+Normal tests do not access the network. The verified anonymous endpoint probe is opt-in:
+
+```bash
+LIVE=1 uv run hiringcafe probe
+```
+
+Every implementation change traces to `specs/pr-*/spec.md` and the roadmap. Never commit credentials, Firebase tokens, cookies, real UIDs, emails, or private account data.
+
+## Project status
+
+Public search, job details, authentication, saved-job listing/staging/removal, retries, caching, Python 3.11–3.14 CI, and tagged PyPI releases are implemented. Saved-job save is currently blocked by the challenged raw hydration route. Filters/facets, tracker search, saved-job pagination, and browser OAuth login remain deferred until their upstream contracts are verified.
+
+See [`roadmap.md`](roadmap.md) and [`specs/`](specs/) for the complete implementation status and PR specifications.

hiringcafe_cli-0.2.0/README.md

@@ -0,0 +1,220 @@
+# HiringCafe CLI
+
+Give your AI agent Hiring Cafe superpowers: search jobs, inspect postings, and keep your real Hiring Cafe saved-job board in sync without a browser.
+
+[![PyPI](https://img.shields.io/pypi/v/hiringcafe-cli.svg)](https://pypi.org/project/hiringcafe-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/hiringcafe-cli.svg)](https://pypi.org/project/hiringcafe-cli/)
+[![CI](https://github.com/chen-gdp/hiringcafe-cli/actions/workflows/ci.yaml/badge.svg)](https://github.com/chen-gdp/hiringcafe-cli/actions/workflows/ci.yaml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+```bash
+hiringcafe search "python developer" --jsonl
+```
+
+The CLI gives your agent structured access to public jobs and, when authenticated, selected actions on your real Hiring Cafe account. Public search and job details use Hiring Cafe's [documented read-only MCP connector](https://hiringcafe.com/documentation/hiringcafe-claude-connector): each search returns at most 10 jobs, with at most one job per company and no pagination or filters yet. Requests are rate-limited; avoid high-frequency automated polling.
+
+> **Unofficial client.** This project is not affiliated with, endorsed by, or supported by Hiring Cafe. Use your own account, respect the service, and expect upstream APIs to change.
+
+## Contents
+
+- [Install](#install)
+- [For agents](#for-agents)
+- [Commands](#commands)
+- [Authentication](#authentication)
+- [Saved jobs](#saved-jobs)
+- [Caching and local data](#caching-and-local-data)
+- [Exit codes](#exit-codes)
+- [Development](#development)
+- [Project status](#project-status)
+
+## Install
+
+HiringCafe CLI is published on PyPI and supports Python 3.11–3.14 with no runtime dependencies.
+
+Install it as a persistent CLI tool:
+
+```bash
+uv tool install hiringcafe-cli
+```
+
+Or, if you prefer pipx:
+
+```bash
+pipx install hiringcafe-cli
+```
+
+Run it once without installing anything:
+
+```bash
+uvx --from hiringcafe-cli hiringcafe --version
+```
+
+Verify the installed version:
+
+```bash
+hiringcafe --version
+```
+
+## For agents
+
+The smallest useful loop is install, search, and consume machine-readable output:
+
+```bash
+uv tool install hiringcafe-cli
+hiringcafe search "python developer" --page 0 --json
+```
+
+For a fresh result, bypass the anonymous-read cache:
+
+```bash
+hiringcafe search "python developer" --no-cache --json
+```
+
+Stream the returned jobs as one JSON object per line (up to 10 results):
+
+```bash
+hiringcafe search "python developer" --jsonl
+```
+
+Extract the normalized jobs from one JSON page:
+
+```bash
+hiringcafe search "python developer" --page 0 --json | jq -c '.result.jobs[]'
+```
+
+Ask only for the result count:
+
+```bash
+hiringcafe count "python developer" --json
+```
+
+Import an existing Firebase refresh token without an interactive password prompt:
+
+```bash
+printf '%s\n' "$HIRINGCAFE_REFRESH_TOKEN" | hiringcafe auth import
+hiringcafe saved-jobs list --json
+```
+
+Agent automation contract:
+
+- JSON success output goes to stdout; diagnostics and cache notices go to stderr.
+- Stable exit codes describe transport, input, rate-limit, auth, and conflict outcomes.
+- Provider passwords and Firebase ID tokens are never written to disk.
+- Authenticated mutations are never retried or cached.
+- Anonymous search/count responses use a 15-minute cache; job details use 24 hours.
+- Search returns at most 10 jobs, one per company; pagination and filters are not supported by the current upstream interface.
+- Invalid arguments fail before a network request is made.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `hiringcafe search "query" --json` | Search jobs and print structured JSON |
+| `hiringcafe search "query" --jsonl` | Stream up to 10 search results as JSON Lines |
+| `hiringcafe count "query" --json` | Print only the result count |
+| `hiringcafe job show <objectID> --json` | Inspect one job posting |
+| `hiringcafe auth login --email you@example.com` | Authenticate interactively |
+| `hiringcafe auth import` | Import an existing Firebase refresh token |
+| `hiringcafe auth status` | Check whether a local session exists |
+| `hiringcafe auth logout` | Remove the local session |
+| `hiringcafe saved-jobs list --json` | List saved jobs |
+| `hiringcafe saved-jobs save <objectID>` | Save a job |
+| `hiringcafe saved-jobs stage <objectID> --stage applied` | Change a job stage |
+| `hiringcafe saved-jobs remove <objectID> --yes` | Remove a saved job |
+| `hiringcafe cache purge` | Remove cached anonymous reads |
+
+Every command supports `--help`, for example:
+
+```bash
+hiringcafe search --help
+hiringcafe saved-jobs save --help
+```
+
+## Authentication
+
+For human use, log in with your Hiring Cafe email:
+
+```bash
+hiringcafe auth login --email you@example.com
+hiringcafe auth status
+```
+
+The password is read from hidden input (or `HIRINGCAFE_PASSWORD` for automation), exchanged once for Firebase credentials, and only the refresh token is stored.
+
+For automation, import a refresh token that you already hold:
+
+```bash
+printf '%s\n' "$HIRINGCAFE_REFRESH_TOKEN" | hiringcafe auth import
+```
+
+The CLI stores only the refresh token in an owner-only local session file. It does not store your password or short-lived Firebase ID token. Browser OAuth login is intentionally deferred until its real provider and loopback callback behavior can be verified.
+
+## Saved jobs
+
+These commands modify your real Hiring Cafe account. Review object IDs and confirmation prompts before changing data.
+
+`saved-jobs save` currently depends on an older raw job-hydration endpoint that is returning a Cloudflare challenge from the CLI host. It may fail before saving; the read-only MCP connector does not support saved-job writes or provide the raw object needed by this command. Listing, staging, and removing saved jobs use separate authenticated flows.
+
+```bash
+hiringcafe saved-jobs save <objectID> --stage saved
+hiringcafe saved-jobs stage <objectID> --stage interviewing
+hiringcafe saved-jobs remove <objectID> --yes
+```
+
+Valid stages are `saved`, `applied`, `interviewing`, `offer`, `rejected`, `ghosted`, and `hidden`.
+
+## Caching and local data
+
+| Data | Location | Notes |
+|---:|---|---|
+| Refresh token | `~/.config/hiringcafe-cli/session.json` | Owner-only file; removed by logout |
+| Anonymous cache | `~/.cache/hiringcafe-cli/cache/v1/` | Public search and job data only |
+
+Set `HIRINGCAFE_CONFIG_HOME` or `HIRINGCAFE_CACHE_HOME` to use different roots.
+
+```bash
+hiringcafe search "python developer" --no-cache
+hiringcafe search "python developer" --cache-ttl 3600
+hiringcafe cache purge
+```
+
+Authenticated saved-job operations are never cached.
+
+## Exit codes
+
+| Code | Agent action |
+|---:|---|
+| `0` | Success |
+| `1` | Transport, HTTP, parsing, or API error; inspect stderr |
+| `2` | Invalid arguments or search state; fix the request |
+| `3` | Rate limited; wait and retry |
+| `4` | No stored credential; authenticate first |
+| `5` | Stored credential rejected; re-authenticate |
+| `6` | Write conflict or prerequisite missing; refresh state |
+
+## Development
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/chen-gdp/hiringcafe-cli.git
+cd hiringcafe-cli
+uv sync
+uv run pytest
+uv run hiringcafe --help
+uv run pre-commit run --all-files
+```
+
+Normal tests do not access the network. The verified anonymous endpoint probe is opt-in:
+
+```bash
+LIVE=1 uv run hiringcafe probe
+```
+
+Every implementation change traces to `specs/pr-*/spec.md` and the roadmap. Never commit credentials, Firebase tokens, cookies, real UIDs, emails, or private account data.
+
+## Project status
+
+Public search, job details, authentication, saved-job listing/staging/removal, retries, caching, Python 3.11–3.14 CI, and tagged PyPI releases are implemented. Saved-job save is currently blocked by the challenged raw hydration route. Filters/facets, tracker search, saved-job pagination, and browser OAuth login remain deferred until their upstream contracts are verified.
+
+See [`roadmap.md`](roadmap.md) and [`specs/`](specs/) for the complete implementation status and PR specifications.

{hiringcafe_cli-0.1.4 → hiringcafe_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hiringcafe-cli"
-version = "0.1.4"
+version = "0.2.0"
 description = "Spec-driven Python CLI for Hiring Cafe job search and saved-job tracking"
 readme = "README.md"
 license = "MIT"

{hiringcafe_cli-0.1.4 → hiringcafe_cli-0.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "hiringcafe-cli"
-version = "0.1.4"
+version = "0.2.0"
 description = "Spec-driven Python CLI for Hiring Cafe job search and saved-job tracking"
 readme = "README.md"
 license = "MIT"

{hiringcafe_cli-0.1.4 → hiringcafe_cli-0.2.0}/src/hiringcafe_cli/__init__.py

@@ -2,6 +2,7 @@
 
 import argparse
 import sys
+from importlib.metadata import PackageNotFoundError, version
 
 from hiringcafe_cli import (
     auth,
@@ -21,7 +22,10 @@ from hiringcafe_cli.saved_jobs import VALID_STAGES
 from hiringcafe_cli.saved_jobs_list import FirestoreError
 from hiringcafe_cli.search_state import InvalidSearchState
 
-__version__ = "0.1.0"
+try:
+    __version__ = version("hiringcafe-cli")
+except PackageNotFoundError:  # pragma: no cover - source-tree fallback
+    __version__ = "0.0.0+unknown"
 
 EXIT_CONTRACT = """\
 Exit codes:

{hiringcafe_cli-0.1.4 → hiringcafe_cli-0.2.0}/src/hiringcafe_cli/count.py

@@ -8,7 +8,7 @@ from hiringcafe_cli.search import search
 def count(
     query: str, raw_search_state: str | None = None, no_cache: bool = False, cache_ttl: int | None = None
 ) -> dict:
-    """Count results by requesting page zero.
+    """Count results using the supported public search response.
 
     Args:
         query: Query-text mode.

{hiringcafe_cli-0.1.4 → hiringcafe_cli-0.2.0}/src/hiringcafe_cli/http_client.py

@@ -18,8 +18,9 @@ BROWSER_HEADERS = {
         "(KHTML, like Gecko) Chrome/128.0 Safari/537.36 hiringcafe-cli/0.1"
     ),
 }
-REQUIRED_SSR_KEYS = ("ssrHits", "ssrPage", "ssrTotalCount", "ssrPageSize", "ssrIsLastPage")
 RETRYABLE_STATUSES = {408, 429, *range(500, 600)}
+MCP_URL_PATH = "/api/mcp"
+MCP_TOOLS = {"search_jobs", "get_job_details"}
 
 
 class HireCafeHTTPError(RuntimeError):
@@ -88,41 +89,6 @@ class RetryPolicy:
         return random.uniform(0, self.base * (2**attempt))
 
 
-def parse_ssr_page(html: str) -> dict:
-    """Parse and validate pageProps from a HiringCafe SSR response.
-
-    Args:
-        html: Complete SSR HTML document.
-
-    Returns:
-        The validated pageProps object.
-
-    Raises:
-        ValueError: If __NEXT_DATA__ is missing, malformed, or incomplete.
-    """
-    marker_start = '<script id="__NEXT_DATA__" type="application/json">'
-    fallback_start = '<script id="__NEXT_DATA__">'
-    starts = [index for index in (html.find(marker_start), html.find(fallback_start)) if index >= 0]
-    if not starts:
-        raise ValueError("missing __NEXT_DATA__")
-    start = min(starts)
-    content_start = html.index(">", start) + 1
-    end = html.find("</script>", content_start)
-    if end < 0:
-        raise ValueError("unterminated __NEXT_DATA__")
-    try:
-        payload = json.loads(html[content_start:end])
-    except json.JSONDecodeError as error:
-        raise ValueError("invalid __NEXT_DATA__ JSON") from error
-    properties = payload.get("props", {}).get("pageProps", {})
-    if not isinstance(properties, dict):
-        raise ValueError("__NEXT_DATA__ pageProps is not an object")
-    for key in REQUIRED_SSR_KEYS:
-        if key not in properties:
-            raise ValueError(f"missing SSR key: {key}")
-    return properties
-
-
 class WebClient:
     """Client that owns every anonymous HiringCafe web URL."""
 
@@ -139,18 +105,69 @@ class WebClient:
         self.timeout = timeout
         self.retry_policy = RetryPolicy(timeout=timeout)
 
-    def search_page(self, search_state: dict, page: int) -> dict:
-        """Fetch one SSR search page.
+    def call_mcp_tool(self, name: str, arguments: dict[str, str | int]) -> str:
+        """Call a documented read-only HiringCafe MCP tool and return its text content.
 
         Args:
-            search_state: Complete search state object.
-            page: Nonnegative page number.
+            name: Supported public tool name.
+            arguments: Tool arguments encoded as JSON.
 
         Returns:
-            Validated ``props.pageProps``.
+            Joined textual content from the MCP result.
+
+        Raises:
+            ValueError: If the tool name or JSON-RPC response is invalid.
+            HireCafeHTTPError: If HiringCafe returns an HTTP error.
+            HireCafeTransportError: If the request cannot complete.
         """
-        query = urllib.parse.urlencode({"searchState": json.dumps(search_state), "page": page})
-        return parse_ssr_page(self._get(f"{self.base_url}/?{query}", "search"))
+        if name not in MCP_TOOLS:
+            raise ValueError("unsupported HiringCafe MCP tool")
+        body = json.dumps(
+            {
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "tools/call",
+                "params": {"name": name, "arguments": arguments},
+            },
+            separators=(",", ":"),
+        ).encode()
+        request = Request(
+            f"{self.base_url}{MCP_URL_PATH}",
+            data=body,
+            headers={
+                "Accept": "application/json, text/event-stream",
+                "Content-Type": "application/json",
+                "User-Agent": "hiringcafe-cli",
+            },
+            method="POST",
+        )
+        try:
+            with self.urlopen(request, timeout=self.timeout) as response:
+                response_body = read_limited(response, "mcp").decode("utf-8")
+        except HTTPError as error:
+            raise HireCafeHTTPError("mcp", error.code, error.reason) from error
+        except (URLError, TimeoutError, OSError) as error:
+            raise HireCafeTransportError("mcp", error) from error
+        payload = self._json(response_body)
+        if payload.get("jsonrpc") != "2.0" or type(payload.get("id")) is not int or payload["id"] != 1:
+            raise ValueError("invalid HiringCafe MCP response")
+        result = payload.get("result")
+        if "error" in payload or not isinstance(result, dict) or result.get("isError"):
+            raise ValueError("HiringCafe MCP tool call failed")
+        content = result.get("content")
+        if not isinstance(content, list):
+            raise ValueError("HiringCafe MCP response has no text content")
+        texts = []
+        for item in content:
+            if not isinstance(item, dict) or item.get("type") != "text":
+                continue
+            text = item.get("text")
+            if not isinstance(text, str):
+                raise ValueError("HiringCafe MCP response has invalid text content")
+            texts.append(text)
+        if not texts:
+            raise ValueError("HiringCafe MCP response has no text content")
+        return "\n".join(texts)
 
     def job_description(self, object_id: str) -> dict:
         """Fetch a job-description JSON object.