104.com.tw Jobs Search MCP

104 Job Hunter MCP 🏹

透過 MCP (Model Context Protocol) 讓 AI 直接接管 104 人力銀行的繁瑣操作。
專注於精準過濾、深度調研、競爭者情報反推與客製自薦信代填，拒絕無意義的亂槍打鳥。

---

🎯 實戰淬鍊的真實故事

這套工具不是寫來展示技術的 Demo。我自己轉職 AI 工程師時，就是靠著這套流程，精準拿到面試並成功落地。

在 104 上找工作，大家一定都體會過這種無力感：

• 雜訊太多：職缺標題寫著「AI 工程師」，點進去才發現工作內容只是資料標註，或者混雜了一堆與關鍵字無關的付費廣告（例如搜工程師跑出精品專櫃）。
• 競爭模糊：104 只給籠統的人數區間（如「6~10 人」或「30 人以上」），你根本不知道對手是誰、具備什麼學歷與技能背景。
• 精力有限：認真研究公司背景、核對職缺條件、手寫客製化自薦信，一天頂多投 3 家，腦袋就乾了。
• 罐頭履歷無效：市面上許多標榜「自動求職」的工具，本質只是狂按送出的垃圾信發報機，充滿 ChatGPT 套話，HR 一看就直接丟垃圾桶。

因此我寫了這套 MCP 工具，把 AI 當作自己的「求職特助」：
它清楚我的技能樹、職涯目標與地雷紅線；在背景幫我擋掉 95% 不合適與廣告職缺；調閱對手背景與確切應徵人數進行勝率診斷；接著調出我原本存在 104 的自薦信語氣，針對職位痛點微調，並把推薦信填妥在應徵視窗裡，最後交給我親自把關確認。

這套人機協作流程幫我拿到了滿意的工作。現在我把這套系統完整開源出來。

---

🧭 設計原則：四道防線

flowchart TD
    subgraph Input["1. 輸入設定"]
        A["求職宣言 (MY_PROFILE.md)"] --> B["AI Agent (大腦)"]
        A2["帳號內既有推薦信範本<br>(保持真實語氣)"] --> B
    end

    subgraph Core["2. 篩選與競爭調研 (MCP)"]
        B -->|攔截 API 搜尋| C["104 職缺庫"]
        C -->|背景自動比對| D{"條件/紅線/廣告過濾"}
        D -- 排除不符條件與廣告 --> X["捨棄"]
        D -- 挑選 Top 3 --> E["深度調研職缺與企業"]
        E -->|反推確切人數與對手背景| E2["📊 競爭態勢分析 (apply_analysis)"]
        E2 --> F["撰寫客製自薦信<br>(突圍優勢 + 去 AI 腔調)"]
    end

    subgraph HITL["3. Hit-in-the-Loop 安全邊界"]
        F --> G["自動代填至 104 應徵視窗<br>(job104_prepare_application)"]
        G --> H{"人類最終肉眼審查"}
        H -->|滿意| I["👤 人類手動點擊確認送出"]
        H -->|需修改| F
    end

    classDef accent fill:#f96,stroke:#333,stroke-width:2px;
    class H,I accent;

1. 精準狙擊，不搞亂槍打鳥

AI 抓回搜尋結果後，不會一股腦把十幾頁列表倒給你。它會對照你的 MY_PROFILE.md，自動濾掉薪資不符、踩到地雷或技術棧差太遠的職缺，並能一鍵過濾 104 付費廣告（excludeFeatured），只整理出 3 到 5 筆真正值得看的選擇。

2. 競爭者情報逆向分析（知己知彼）

104 網站只提供粗略的應徵人數區間（如「11~30 人」），且 API 的 total 常態為 0。本專案透過兩位小數的百分比數值，利用數學解題器精準反推確切應徵總人數，並還原出對手的學歷、年資、擅長技能與證照分布，讓你在投遞前就知道自己贏在哪裡。

3. 說人話，拔除機器臭味

工具會直接讀取你 104 帳號現有的推薦信範本（job104_get_cover_letters），以你平常講話的習慣為底稿，針對該職缺的需求微調。徹底拿掉「深感榮幸、為貴司賦能」這種浮誇套話，把重點放在實際做過的專案邊界與解題過程。

4. Hit-in-the-loop：安全邊界不退讓

這套工具絕不替你按最後的「確認送出」。
job104_prepare_application 會打開投遞彈窗、選定推薦信範本、填入客製化推薦信，然後停下來。投哪家、怎麼投，是你的個人職涯，最後的送出鍵必須由你親眼看過、親手按下。

---

✨ 核心功能與工程細節

• 🔍 進階 API 攔截搜尋：監聽 104 後端 JSON API，支援薪資下限 (salaryMin 搭配 scstrict=1)、排除面議、排除廣告職缺 (excludeFeatured)、最新排序 (sort: 'newest') 與遠端工作篩選，並內建台灣縣市 Area Code 自動解析。
• 📊 競爭情報精算：獨創 job104_get_apply_analysis，透過百分比反推與互斥維度總和約束 ($\sum k_i = N$) 精準算出不重複應徵人數，並掌握學歷（碩博/大學）、年資階層、對手 Top 10 技能與證照。
• 🏢 企業深層調研與 JD 內文搜尋：除提取企業福利與公司簡介外，支援以 keyword 直接在該公司所有職缺的 JD 內文中全文比對，挖掘職稱沒寫但內文要求的寶藏職缺。
• 🔗 代碼/網址雙格式無縫串接：所有職缺與公司工具皆內建智慧正規化（normalizeJobUrl），無論傳入完整 104 網址或純代碼（如 6lots）皆可直接調用。
• 🔒 本地優先 (Local-First)：
  • 100% 在你本機運作，不對外傳輸帳號密碼或個人資料。
  • 登入使用獨立的本機 Chrome Profile，完全由你在官方頁面操作，免除重複登入困擾。
• 🚦 併發互斥與生命週期防護：內建 runExclusive 佇列互斥鎖、導航監聽器防洩漏保護（waitForJsonResponseDuringGoto）、統一錯誤邊界（executeToolSafely），並在 MCP 斷線時自動釋放 Chrome Profile 鎖定，杜絕殭屍進程。

---

📋 前置準備清單 (Prerequisites)

開始使用前，請確認你的電腦已安裝好以下基礎工具：

項目	建議版本	必要性	說明與用途	下載來源
Node.js	>= 18.0.0 (推薦 20+ LTS)	必備	執行 MCP 伺服器、編譯 TypeScript 與套件管理	官方下載
Google Chrome	官方穩定版本	必備	本專案借用本機 Chrome 儲存 Profile，免除爬蟲驗證並維持登入	官方下載
Git	任意版本	必備	用於下載專案及日後 git pull 更新代碼	官方下載
MCP Client	支援 MCP 之客戶端	必備	載入並調用本工具的 AI 環境 (如 Antigravity, Claude Desktop, Cursor)	-
104 會員帳號	個人正常帳號	必備	請先在 104 網站完成基本履歷填寫與自薦信範本儲存	104 官網

[!TIP] 一鍵環境診斷：安裝完套件後，可在終端機執行 npm run check，系統會自動檢測 Node.js 版本、Chrome 執行檔路徑、編譯狀態與登入 Profile，若有缺少會給出具體提示。

---

🚀 快速上手

[!IMPORTANT]

🤖 給正在協助人類的 AI Agent (System Directive)

如果你是被人類指派來協助設定或操作本專案的 AI 代理（如 Antigravity, Claude Desktop, Cursor 等）：

1. 立即讀取操作手冊：請優先研讀專案根目錄的 AGENTS.md，內含完整的決策狀態機與去 AI 化推薦信規格。
2. 主動引導建立分身：檢查根目錄是否存在 MY_PROFILE.md。若尚無此檔，請暫停搜尋，主動向人類提問索取簡歷/專案經歷，並參考 MY_PROFILE.example.md 協助生成專屬 Profile。
3. 遵守安全防線：嚴格落實 Hit-in-the-Loop 規範，代填表單後將視窗交還人類，絕不替人類代按最終送出鍵。

1. 安裝與建置

git clone https://github.com/YuJunWang/104-job-hunter-mcp.git
cd 104-job-hunter-mcp
npm install
npm run check    # 💡 檢查本機環境與 Chrome 是否就緒
npm test         # 🧪 執行 6 組單元測試套件
npm run build

2. 登入 104 帳號（只需一次）

npx tsx src/login.ts

執行後會跳出 Chrome 視窗，請在 104 官方頁面登入。登入成功後腳本會自動儲存 Cookie 並安全關閉。

3. 掛載 MCP 伺服器

將設定加入你的 MCP 用戶端設定檔（例如 Antigravity 的 mcp_config.json 或 Claude Desktop 的 claude_desktop_config.json）：

{
  "mcpServers": {
    "104-job-hunter": {
      "command": "node",
      "args": ["D:\\your-path\\104-job-hunter-mcp\\build\\index.js"]
    }
  }
}

4. 設定 AI 腦袋

1. 複製根目錄的 MY_PROFILE.example.md，命名為 MY_PROFILE.md。
2. 填入你的專案經驗、技能樹、薪資期望、地點與絕對紅線。
3. 直接告訴你的 AI：

   「請閱讀專案裡的 MY_PROFILE.md 與 AGENTS.md，照著標準劇本幫我找工作。」

---

🛠️ MCP 工具列表 (共 11 組)

工具名稱	用途說明	運作機制
job104_check_session	檢查登入是否有效	支援新版 signin.104.com.tw 跳轉判斷，避免中途卡住
job104_search	搜尋職缺	支援關鍵字、地點代碼轉換、薪資下限、排除面議、排除廣告職缺、遠端型態與最新排序
job104_get_details	讀取職缺完整內容	支援傳入職缺網址或代碼，取得詳細 JD、薪資條件、加分技能與 HR 聯絡人資訊
job104_get_apply_analysis	應徵者競爭情報分析	數學反推確切應徵總人數（含維度加總約束），並回傳學歷、年資、年齡、語言、Top 10 技能與證照分布
job104_get_cover_letters	取得現有自薦信範本	支援傳入職缺網址或代碼，讀取帳號內的預設與自訂推薦信標題與全文，保留個人原始口吻
job104_prepare_application	代填應徵表單 (HITL)	支援傳入職缺網址或代碼，開啟彈窗、選定範本並填入微調後的推薦信，支援 Dry Run 截圖，不替你送出
job104_search_companies	搜尋企業資訊	查詢公司代碼、規模、產業類別與現有職缺數
job104_get_company_detail	公司深度分析	支援傳入公司網址或代碼，提取企業福利文化與開放職缺，並可以 keyword 比對該公司職缺 JD 全文
job104_save_job	收藏職缺	支援傳入職缺網址或代碼，解析所屬公司並加入我的收藏名單
job104_save_company	追蹤公司	支援傳入公司網址或代碼，帶入完整規格 Payload 追蹤心儀企業
job104_reload_server	優雅重載 MCP	伺服器更新代碼後安全關閉瀏覽器並發送重啟信號，不中斷 stdio 通道

---

📁 專案架構

104-job-hunter-mcp/
├── src/
│   ├── index.ts          # MCP 入口，註冊 11 組工具、統一錯誤邊界與優雅退場機制
│   ├── browser.ts        # Playwright 瀏覽器單例、fetchIn104 與防洩漏導航攔截封裝
│   ├── login.ts          # 互動登入與 Cookie 本地持久化腳本
│   ├── check-env.ts      # 環境健康檢查工具 (npm run check)
│   ├── utils/
│   │   ├── url.ts        # 職缺/公司 URL 正規化、API 路徑比對與登入網址判斷
│   │   ├── area.ts       # 104 官方台灣縣市 Area Code 雙向對照工具
│   │   └── applyAnalysis.ts # 應徵者人數精算反推（含維度總和約束）與多維度正規化
│   ├── tools/            # 8 個工具模組（共提供 10 組核心業務工具）
│   └── __tests__/        # 6 組單元測試套件與 runAllTests.ts 測試運行器
├── AGENTS.md             # AI 操作手冊（含去 AI 寫作原則、競爭情報分析與 4 步投遞 SOP）
├── MY_PROFILE.example.md # 求職分身設定檔範本
└── package.json          # v1.2.1

---

寫在最後

求職不該是求職者與企業人資之間的「垃圾信轟炸攻防」。
善用 AI 替你過濾雜訊、診斷競爭態勢、填寫繁瑣表單，把時間和精力省下來，留給真正與未來主管、團隊交流的關鍵時刻。

希望這個專案能幫你少走一點冤枉路，順利找到合適的位置。