Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@job-hunting-mcp 幫我找台北的後端工程師職缺，月薪四萬以上，優先看最近更新的"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🌐 繁體中文 | English
job-hunting-mcp 是一個協助個人查詢工作的唯讀 Model Context Protocol（MCP）server。AI agent 可以依自然語言同時搜尋 104 與 Cake 的公開職缺，逐筆顯示資料來源、公司、職稱、工作內容、薪資、地點和原始連結。
Related MCP server: JobSpy MCP Server
唯讀公開職缺搜尋與詳情查詢
自動查詢 104 與 Cake，不要求使用者輸入來源
每個來源預設 10 筆，可指定 10–20 筆
每筆結果使用來源限定的 job_ref，例如 104:8ue17、cake:site-reliability-engineer-sre-71702b
不登入、不使用使用者 Cookie、不投遞、不收藏、不追蹤、不讀取求職者資料
目前必須先從 GitHub 取得專案，再安裝相依套件與建置：
git clone https://github.com/YutangShi/job-hunting-mcp.git
cd job-hunting-mcp
node --version
npm ci
npm run build需求：Node.js 22 LTS、npm，以及可連線至 104／Cake 的網路。impers 使用原生 curl-impersonate 相容 library；若啟動時無法載入，請依錯誤訊息設定原生 runtime。
在專案根目錄執行：
NODE_BIN="$(command -v node)"
PROJECT_DIR="$(pwd -P)"
codex mcp add job-hunting-mcp -- "$NODE_BIN" "$PROJECT_DIR/dist/index.js"
codex mcp get job-hunting-mcp重新建置程式後重新啟動 Codex 即可。只有專案路徑或啟動命令改變時才需重新註冊。
把以下內容加入 Claude Desktop 的 MCP 設定，並將兩個路徑換成絕對路徑：
{
"mcpServers": {
"job-hunting-mcp": {
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/job-hunting-mcp/dist/index.js"]
}
}
}macOS/Linux 可用 command -v node，Windows 可用 where node 查詢 Node.js。儲存後重新啟動 Claude Desktop。
目前版本是本機 stdio server。Codex CLI 和 Claude Desktop 可以直接啟動本機程序；ChatGPT 網頁版或其他託管型 agent 通常需要遠端可連線的 MCP server、HTTPS endpoint、驗證和該平台的 connector 設定，因此不能直接使用本機 dist/index.js 路徑。這些 client 的遠端部署尚未包含在本版本。
使用者問題
↓
AI agent 呼叫 search_jobs
↓
job-hunting-mcp 分別查詢 104 與 Cake
↓
合併正規化結果，保留每筆來源與來源狀態
↓
AI agent 使用回傳的 job_ref 呼叫 get_job_details本機 client 透過 stdio MCP frame 溝通。來源查詢有節流與大小限制；某個來源失敗時，其他來源的成功結果仍會保留，並在回應中顯示失敗來源與錯誤類別。
目前程式實際註冊的 MCP tools 只有以下兩個。smoke:104、smoke:cake、test:e2e 是測試／驗證命令，不是 MCP tools。
Tool | 用途 | 主要輸入 | 回傳內容 |
| 同時搜尋所有啟用來源的公開職缺 |
| 公司、職稱、工作內容描述、薪資、地點、來源、原始連結、 |
| 讀取搜尋結果對應的完整公開職缺內容 |
| 公司、職稱、完整工作內容、條件、薪資、地點、來源、原始連結 |
search_jobs 不接受 source 欄位；使用者不需要知道職缺來自哪個平台。get_job_details 不接受任意 URL，只接受來源限定的 job_ref。
npm test
npm run typecheck
npm run build
npm run test:e2e
npm run smoke:104
npm run smoke:cakenpm test：執行 unit、adapter、transport 和 MCP in-memory 測試
npm run typecheck：執行 TypeScript 型別檢查
npm run build：建立 dist/index.js
npm run test:e2e：啟動建置後的 stdio MCP server，列出全部 tools，實際呼叫搜尋與詳情
npm run smoke:104：即時驗證台北 SRE 多筆搜尋與詳情
npm run smoke:cake：即時驗證 Cake SRE 搜尋與詳情；來源回傳 403、429、challenge 或 schema 變更時會明確失敗
本專案採用 MIT License，詳見 LICENSE。第三方地區／職類代碼表的授權說明見 THIRD_PARTY_NOTICES.md。
讀取職缺完整內容。job_ref 必須來自 search_jobs 結果；目前 V1 只支援來源 104。
| Name | Required | Description | Default |
|---|---|---|---|
| job_ref | Yes | search_jobs 結果中的 job_ref，例如 104:8ue17 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds real context beyond them: the source-coverage limitation for V1 and the provenance requirement for job_ref. It does not describe error behavior for invalid or out-of-scope refs, but the safety profile is fully covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero waste; the core purpose is front-loaded and the constraint follows. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no output schema, the description conveys that the full job record is returned and bounds which sources are supported. A note on what 'full content' includes would close the remaining gap, but nothing needed to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the job_ref property already documents its origin and an example format (104:8ue17), so the schema does the heavy lifting. The description reinforces the provenance constraint but adds no syntax or format detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (讀取職缺完整內容) and frames it relative to the sibling search_jobs by requiring job_ref to originate there, so the search-then-detail split is clear. It does not explicitly say 'use this instead of search_jobs for details', but the routing is inferable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete precondition (job_ref must come from search_jobs results) and a hard scoping constraint (V1 only supports source 104), which tells the agent when this tool will and won't work. No explicit statement of when to avoid it beyond that source limitation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
自動搜尋已啟用的 104 與 Cake 公開職缺。直接輸入職務條件即可，不需指定來源；例如 keyword='SRE'。每個來源預設回傳 10 筆，可指定 10–20 筆；來源符合條件的職缺不足時會回傳實際筆數。每筆結果包含公司、職稱、工作內容描述、薪資、原始職缺連結、來源和可供 get_job_details 使用的來源限定 job_ref。
| Name | Required | Description | Default |
|---|---|---|---|
| edu | No | 104 學歷代碼 | |
| area | No | 104 地區名稱，例如 台北市、新竹市 | |
| page | No | ||
| sort | No | ||
| is_new | No | 是否限定近期刊登職缺 | |
| jobcat | No | 104 職類名稱，例如 系統工程師 | |
| remote | No | ||
| keyword | No | 職務關鍵字，例如 SRE、DevOps、資料工程師 | |
| job_type | No | ||
| exp_years | No | ||
| page_size | No | 每個來源預設搜尋 10 筆；可指定 10 至 20 筆 | |
| salary_min | No | 薪資下限；104 端點的薪資條件可能是排序而非硬性篩選 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations only covering read-only/open-world, the description carries real behavioral load: it discloses the two-source fan-out, per-source default of 10 and the 10–20 range, and the important partial-result rule (fewer matches returns the actual count). It also enumerates the per-result fields, so the agent knows what comes back despite no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with the core action and example, then result counts and return fields. Every sentence carries distinct information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter, no-output-schema search tool it covers the essentials: source behavior, count semantics, partial results, and return fields. The main gap is that most of the domain-specific filter parameters (edu, jobcat, area, sort) get no orientation in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 58% across 12 parameters, so the schema documents roughly half. The description adds meaningful semantics for keyword (example) and page_size (per-source, not total), but leaves edu, area, sort, is_new, jobcat, remote, job_type, exp_years, and page entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (自動搜尋 104 與 Cake 公開職缺) and scopes it to enabled/public sources. The final sentence explicitly links the returned job_ref to the sibling get_job_details, so an agent can distinguish the two tools without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tells the agent to pass conditions directly and that source need not be specified, with a concrete example (keyword='SRE'). It also seeds the handoff to get_job_details, but never states when to prefer the sibling or what conditions are unsupported.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_job_detailssearch_jobsScored across 2 tools
The two tools are cleanly separated: search_jobs performs discovery across sources, while get_job_details retrieves full content for a specific job_ref produced by search. There is no plausible scenario where an agent would confuse one for the other, and the dependency between them is stated explicitly.
Both names follow the same snake_case verb_noun convention (search_jobs, get_job_details) with a shared '_jobs'/'job' noun stem. The pattern is entirely predictable and would extend naturally to future tools.
Two tools is on the thin side even for a narrowly scoped server; a search-plus-detail pair is the minimum useful surface rather than a well-rounded one. It is defensible for a focused job-search use case but leaves little room for anything beyond the single browse workflow.
Search plus full-detail retrieval covers the core discovery workflow, but get_job_details only supports 104, so Cake results returned by search_jobs are a dead end for detail retrieval. There is also no filtering, sorting, pagination beyond 20 results, or any save/apply/track operation that a 'job hunting' domain would normally imply.
Job search over employers' own hiring systems. Search with no key; a free key opens every read tool.
Search AI-native jobs, inspect application forms, and fetch free interview-prep resources.
searchnapply connects your AI agent to 500K+ open jobs taken straight from company career sites, kept up to date as companies add and close them. Search in your own words with the site's filters (role, location, remote, salary, experience, department), read postings in full, and tailor a resume or cover letter from your searchnapply profile. Save a search as a monitor to collect new postings and track what you applied to or skipped. It never invents a job or a salary, and it does not apply for you: you apply on the company's own page. Free plan included, within a daily call limit.
Search job postings across Indeed, LinkedIn, and more from one request - titles, companies
