mcp-server-104

台湾104人力銀行のMCPサーバー。Claude（または任意のMCPクライアント）が104のリアルタイム求人を直接検索できるようにします。

このツールはあなたに適していますか？

Related MCP server: job-source-mcp

⚠️ 免責事項（先にお読みください）

• 104には公開された公式APIはありません。本プロジェクトはWebフロントエンドの非公式内部エンドポイントを使用しており、104の仕様変更によりいつでも使えなくなる可能性があります。

• 自動化アクセスは104の利用規約に違反する可能性があります。本プロジェクトは個人・低頻度・学習目的にのみ使用してください。

• 高頻度の取得、大量クロール、公開サービスとしての提供はしないでください —— ブロックされやすく、法的リスクもあります。

• 本プロジェクトには礼儀としてのスロットリング（各リクエスト間隔をランダムに1.5〜3.5秒）が組み込まれています。削除したり短縮したりしないでください。

• 本プロジェクトの使用によって生じたいかなる結果も、利用者の自己責任です。

データ取得の方法

104の検索APIはCloudflareのbot対策の背後に隠されています。curlやNodeのfetch（Referer / User-Agentを付けても）ではブロックされます —— 403またはCloudflareの"Just a moment..."チャレンジページが返されます。

重要なのはヘッダーではなく、TLSフィンガープリントです。 CloudflareはTLSハンドシェイクのフィンガープリント（JA3）を検査します。一般的なプログラムのフィンガープリントはブラウザと明らかに異なるため、即座にブロックされます。

本プロジェクトは**cycletlsを使用してChromeのTLSフィンガープリントを偽装し、Cloudflareにリクエストが本物のブラウザからのものだと思わせて通過させます。これによりブラウザを起動する必要がなく**（Playwright / Seleniumより一桁軽量・高速・デプロイが容易）、純粋なHTTPで実際のJSONを取得できます。

cycletlsの内部はGoで書かれたTLSクライアントのサブプロセスで、サーバー起動時に一度起動し、全体で共有します。

現在の機能

search_jobs パラメータ

フィルターパラメータの実装の細かい点（すべて104公式サイトUIの実際のリクエスト＋metadata.totalの実測から得たもの）：

1. salaryMinはscmin＋sctp=M＋scstrict=1を同時に送る必要があります。scstrictがないと給与フィルターは完全に無視されます。

2. 「面談」の給与値は0で、104はデフォルトで保持します（面談は高額の可能性があるため）。excludeNegotiableで除外できます。

3. 給与上限9,999,999は104の「上限なし」センチネル値で、サーバー側で「N元以上」に正規化されています。

4. remoteWork=1完全/2部分、ro=1フルタイム/2パートタイム、jobexp=1/3/5/10/99（排他的な年功区分）。

5. 地域・職種はツリー状コード表＋枝刈りを使用：親ノード（例：「新竹県市」）にヒットしたら親コードを使用し、子コードに展開しない —— 展開しすぎると104が400を返します。

6. 広告検出：104は結果の先頭に広告を挿入します（元のフィールドjobType=1）。これはキーワードを無視します（例：看護師の検索で「COACH 精品銷售」が出る）。各レコードにfeaturedフラグを付けてマークし、excludeFeatured=trueで一括除外できます。jobType=2（有料優先枠）はキーワードに一致するため、有効な結果としてマークしません。検索リストには意図的に完全なJDを含めていません（簡潔にし、モデルがリストを整理する際にURLを別のレコードに誤って対応付けるのを防ぐため）。完全な内容はget_job_detailを使用します。

フィールド命名は3つのツール間で一貫（すべて104の元のフィールドの意味に対応し、同名異物を避ける）：

概念	search_jobs	get_job_detail	get_company_jobs
求人コード（slug、get_job_detailに渡せる）	jobId	jobId	jobId
求人URL	url	url	url
地域（区レベル）	area	area	area
完全な住所（区＋通り）	—	location	—
必要経験年数	—	experience	experience
得意なツール・言語（C++、Linux）	skills	skills	—
職務スキル（職種レベル、例：「ソフトウェアシステム開発」）	—	jobSkills	—
会社ページURL（get_company_jobsに渡す）	companyUrl	companyUrl	—
広告枠かどうか（jobType=1）	featured	—	—

jobIdは常にslug（例：7uqyj）で、104の内部番号ではありません —— slugのみget_job_detailに渡せます。skillsはどこでも「具体的な技術」を指します。

get_job_detail パラメータ

get_company_jobs パラメータ

3つのツールの連携方法：

• search_jobs / get_job_detailは各レコードでurl（求人）とcompanyUrl（会社）の2つのURLを返します。

• 特定の求人の完全な内容を見たい場合 → そのurlをget_job_detailに渡します。

• 「この会社には他にどんな求人があるか」を見たい場合 → companyUrlをget_company_jobsに渡します（これは指定した会社の求人リストであり、キーワード検索ではありません）。

search_jobs ─ url ──────→ get_job_detail
      │                        │
      └─ companyUrl ───────────┴──→ get_company_jobs

104内部APIリファレンス

主要エンドポイント：

GET https://www.104.com.tw/jobs/search/api/jobs

必要なヘッダー：Referer: https://www.104.com.tw/jobs/search/、Accept-Language: zh-TW

よく使うクエリパラメータ（本プロジェクトでは現在一部のみ使用、残りは将来の拡張用）：

地域・職種コード表（static.104.com.twに配置、Cloudflareのブロックなし、通常のfetchで取得可能）：

https://static.104.com.tw/category-tool/json/Area.json
https://static.104.com.tw/category-tool/json/JobCat.json

その他のエンドポイント：

• 求人詳細：GET https://www.104.com.tw/job/ajax/content/{slug}（Refererは/job/{slug}を指す）

• 会社の求人：GET https://www.104.com.tw/api/companies/{code}/jobs?page=1&pageSize=20（list.topJobs＋list.normalJobsを返す）

ファイル構成

src/
  index.ts            進入點：建 server、掛 tool、接 stdio、處理關閉
  config.ts           所有設定 / 魔術數字（JA3 指紋、endpoint、節流區間…）
  types.ts            乾淨型別 + normalizeJob / JobDetail / CompanyJob（防腐層）
  query.ts            純函式：組查詢網址、解析 slug/公司碼、client 端過濾、enum 對照
  codes.ts            地區/職類「名稱→官方代碼」解析（樹狀比對+剪枝，快取代碼表）
  api/
    httpClient.ts     cycletls 單例（TLS 指紋偽裝）
    throttle.ts       禮貌性隨機節流 1.5~3.5s
    job104.ts         104 抓取層：組 URL → 打 API → 重試 → 正規化
  tools/
    searchJobs.ts     search_jobs
    getJobDetail.ts   get_job_detail
    getCompanyJobs.ts get_company_jobs
scripts/
  smoke-test.mjs      手動發 JSON-RPC 驗證，不用開 Claude 也能測
test/
  types.test.mjs      normalize 邏輯（薪資格式、面議、哨兵值…）
  query.test.mjs      組網址 / slug / 公司碼 / 過濾 / enum 對照
  codes.test.mjs      代碼表樹狀比對 + 剪枝

開発

npm run build                 # 編譯 src → dist
npm test                      # 跑單元測試（先 build 再 node --test，零額外依賴）
node scripts/smoke-test.mjs   # 煙霧測試（連真實 104）
npm run inspect               # 開 MCP Inspector GUI 除錯

テスト戦略：純粋なロジック（正規化、URL組み立て、フィルタリング）はすべてtypes.ts / query.tsに抽出し、Node組み込みのnode --testでテスト。高速でネットワーク不要 —— 壊したらすぐにわかります。ネットワークに触れる部分（job104.ts / httpClient.ts）はスモークテストで実際の104に対して検証します。

Claude Codeへの接続

claude mcp add job104 -- node /Users/marshall.wang/tomtom/my/app/104-mcp-server/dist/index.js

コードを変更したらnpm run buildを実行し、その後Claude Codeを再起動（または/mcpでreconnect）して反映させます。

必ず覚えておくべき2つの落とし穴

1. stdoutはプロトコル専用パイプラインです。 stdioモードでconsole.logを使うとJSON-RPCメッセージを汚染し、即座に切断されます。ログは常にstderrに出力してください。

2. descriptionはモデルが判断する唯一の根拠です。 モデルはこれを見てツールを呼ぶかどうかを決定します。きれいに書くことより、明確に書くことが重要です。