jobstack-mcp

jobstack-mcp

一个面向 JobStack 的远程 **MCP（Model Context Protocol）**连接器。JobStack 是统一的职位搜索 API（jobs-api），可整合官方招聘平台的数据源和公共 ATS 平台（USAJOBS、Adzuna、Jooble、The Muse、Reed，以及由一个 ats 引擎统一接入的 Greenhouse/Lever/Ashby/Workable/SmartRecruiters），并将结果转换为统一的 Job 数据结构。

在线服务： https://jobstack-mcp.vercel.app/mcp — 提供 2 个工具，通过 MCP 可流式传输的 HTTP 传输协议公开。由于上游 jobs-api 部署按用量计费（RapidAPI/Apify），且其 /v1/* 路由受 RapidAPI 代理密钥保护，此连接器使用同一密钥（JOBSTACK_MCP_PROXY_SECRET，通过 X-RapidAPI-Proxy-Secret 标头发送）对外发起的调用进行身份验证，并应用软性 IP 速率限制（JOBSTACK_MCP_RATE_LIMIT，默认为每小时 30 次工具调用，基于内存），确保免费的 MCP 层用于发现，而非绕过付费职位列表的无限制通道 — 参见 lib/ratelimit.js。

项目简介

JobStack 是一个纯 REST API。本仓库是一个轻量适配器，将每个端点作为可发现的、类型化的 MCP 工具公开，让 MCP 客户端（Claude、ChatGPT 及任何支持 MCP 的 Agent）能够直接调用，并通过单个 /mcp 端点使用 MCP 可流式传输的 HTTP 传输协议。它本身不包含业务逻辑 — 每次工具调用都会直接 fetch jobs-api，并将 JSON 响应原样作为工具结果返回。

工具

工具	JobStack 端点	描述
search_jobs	GET /v1/jobs/search	搜索并合并所有引擎（或 sources= 指定的引擎子集）的职位信息，按最新发布优先排序，并支持分页。
get_job	GET /v1/jobs/{source}/{id}	根据来源引擎和原生 ID 获取单个职位（ats 使用组合 ID：board:company:nativeId）。

两个工具均为只读工具，标注为 { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }。

search_jobs 输入

• keywords（字符串，可选）— 自由文本搜索词。
• location（字符串，可选）— 自由文本地点筛选条件。
• remote（布尔值，可选）— 在数据源提供相关标记时，筛选远程职位。
• sources（字符串，可选）— 引擎键组成的逗号分隔列表：usajobs, adzuna, jooble, themuse, reed, ats。省略时搜索全部六个引擎。
• limit（整数，范围 1-100，可选，默认值 20）。
• offset（整数，≥0，可选，默认值 0）。

get_job 输入

• source（枚举：usajobs | adzuna | jooble | themuse | reed | ats）。
• id（字符串）— 搜索结果中的上游原生 ID；对于 ats，则为组合字符串 board:company:nativeId。

配置

• JOBSTACK_MCP_API_BASE_URL — 上游基础 URL。默认值为 https://jobs-api-gamma.vercel.app。
• JOBSTACK_MCP_PROXY_SECRET — 随对外调用转发为 X-RapidAPI-Proxy-Secret 的 RapidAPI 代理密钥（生产环境源站会对 /v1/* 进行保护，因此必须提供）。
• JOBSTACK_MCP_RATE_LIMIT — 每个 IP 每小时的工具调用软性上限。默认值为 30。

本地开发

npm install
npm run dev          # starts local-server.js on http://localhost:3900
npm run smoke        # in another terminal — real HTTP/JSON-RPC smoke test

test/smoke.mjs 会通过真实 HTTP/JSON-RPC 与运行中的服务交互，并验证 GET /health、initialize（serverInfo.name === "jobstack"）以及 tools/list（包含 2 个工具及其从 zod 导出的架构），随后尝试执行一次实时的 search_jobs 工具调用。在本地未设置 JOBSTACK_MCP_PROXY_SECRET 时，上游源站会返回 403（受 RapidAPI 保护）——这是预期的上游身份验证情况。冒烟测试会将其报告为软警告，同时仍验证完整的协议功能。

部署

cd /Users/isaiahdupree/Software/jobstack-mcp
npx vercel --yes --prod

部署完成后，可在 Claude、ChatGPT 或任何 MCP 客户端中注册此 MCP 连接器，URL 为 https://<deployment-domain>/mcp。