jobhunt

jobhunt

jobhunt 是一个小型本地桥接工具，用于连接托管的 Jobven MCP 服务。该服务从公司招聘网站收集职位信息和雇主 资料。你可以通过它使用一系列丰富的筛选条件搜索职位，包括职位名称和 描述中的短语、远程类型、经验水平、 雇佣类型、技能、行业、语言、地点、 薪资范围、签证担保和发布日期；选择一个 职位以阅读全文；按名称查找雇主； 打开某位雇主的资料；或获取一个示例 webhook 投递，用于测试接收端。

此软件包本身不执行任何搜索。它会在本地返回工具 列表，内容与从在线端点捕获的内容完全一致，并将每次工具调用转发至上游， 原样返回收到的内容。根据捕获的说明，搜索返回的职位以及 单个职位或公司查询都会计入你自己的 Jobven 账户月度额度，而 公司搜索免费。此软件包中的任何功能都无法 申请职位、提交申请、发送消息、 开始结账或创建密钥：它只会通过以下五个调用读取数据， 此外还有一个示例 webhook，不会发送任何内容，也不会生成任何真实签名。

工具

• search_jobs — 使用 GET /v1/public/jobs 的筛选条件搜索 Jobven 职位信息。默认返回 10 个职位（最多 25 个），每个职位描述附带纯文本摘要；get_job 可获取完整文本。使用相同筛选条件将 nextCursor 作为 cursor 传回，即可获取下一页。每个返回的职位都会计入月度配额。所有参数均为可选：q（职位名称关键词；按任意顺序进行 AND 匹配，使用 "double quotes" 精确匹配短语，使用 OR 匹配任一词项，使用前导 - 排除；不区分大小写；不搜索职位描述）、descriptionQuery（职位描述中的完整词语短语，按字面匹配；不区分大小写；速度较慢，建议与 postedAfter 搭配使用）、remoteType（onsite、remote、hybrid、flexible）、experienceLevel（entry、mid、senior、lead、executive）、employmentType（full_time、part_time、contract、internship、seasonal、volunteer、temporary、per_diem、other）、skills、industry、language（ISO 639-1 代码）、location、country（ISO 3166-1 alpha-2；XX 可匹配没有地点信息的职位）、state、city、minSalary、maxSalary、salaryCurrency（ISO 4217 代码）、hasVisaSponsorship、hasRelocation、status（active 为默认值，或 closed）、postedAfter、postedBefore、listedAfter（Unix 秒）、sortBy（postedAt、listedAt、title、company）、order（ASC 或 DESC，默认值为 DESC）、includeTotal、cursor 和 limit（1-25，默认值为 10）。
• get_job — 根据 id 获取一条 Jobven 职位信息及完整描述（GET /v1/public/jobs/{id}）。必填：id（来自 search_jobs 的职位 ID，UUID 格式）。可选：descriptionFormat（plain 为默认值，或 markdown）。每条职位计入月度配额。
• search_companies — 按名称查找 Jobven 收录职位的雇主（GET /v1/public/companies）。返回 id、name 和 website；get_company 可获取公司资料。免费：公司搜索不计入配额。所有参数均为可选：search（名称包含此文本）、status（active 或 inactive；未设置时两者均包含）、isVerified、sortBy（name、foundedYear、totalJobsPosted、activeJobsCount、createdAt）、sortOrder（ASC 或 DESC）、page（从 1 开始）和 limit（1-25，默认值为 10）。
• get_company — 根据 id 获取一位雇主的资料（GET /v1/public/company-profiles/{id}）：业务内容、行业、规模、成立年份、总部和社交链接。必填：id（来自 search_companies 的公司 ID）。每条计入月度配额。
• webhook_example — 一个 Jobven webhook 事件的示例投递：接收方实际收到的原始请求正文和标头，使用示例密钥签名，并附带 webhook 文档中的 TypeScript、Python 或 Go 签名验证器。验证器可接受该示例，因此可以端到端测试接收方。不调用 API，无需密钥，免费。必填：event（job.created、job.updated、job.closed、job.deleted）和 language（typescript、python、go）。

配置

• JOBVEN_MCP_URL（可选）— 覆盖上游端点。默认值为 https://api.jobven.com/mcp。（此覆盖钩子是本次重建自行标注的还原内容。）
• JOBVEN_API_KEY（可选）— 设置后，每个上游请求都会携带 X-API-Key: <value> 标头，其中包含调用方自己的 Jobven API 密钥。未设置时，不会发送密钥标头。（原始注册记录指定了必需的 X-API-Key 密钥标头，因此标头名称是确定的；该记录未指定包的环境变量名称，因此从此环境变量转发密钥是经过标注的还原内容——原始接口是在不提供密钥的情况下捕获的。）

转发机制

首次调用工具时，客户端会在上游打开一个可流式传输的 HTTP 会话：先发送 JSON-RPC initialize 请求（protocolVersion 为 2025-03-26，clientInfo 名称为 jobhunt），然后发送 notifications/initialized 通知，最后发送携带调用方参数且保持不变的 tools/call 请求。当上游在 initialize 的响应中返回 Mcp-Session-Id 标头后，该值会附加到此会话的每个后续请求中；此会话会在进程运行期间一直复用。 响应可能是普通 JSON，也可能是服务器发送的事件；两种格式都会读取。

上游的成功结果会原样传递，包括上游设置的任何 isError 标志。 失败情况——JSON-RPC 错误、非 2xx 状态、无法读取响应，或无法完成的请求——会作为 isError 结果返回，其文本以 jobhunt error: 开头（此呈现方式是本次重建中特意标注的内容）。

命令行界面

每个工具也可作为子命令使用，并接受一个 JSON 参数字符串：

npx @reneturcios/jobhunt search_jobs '{"q":"typescript","remoteType":["remote"]}'
npx @reneturcios/jobhunt get_job '{"id":"00000000-0000-0000-0000-000000000000"}'
npx @reneturcios/jobhunt search_companies '{"search":"acme"}'
npx @reneturcios/jobhunt get_company '{"id":42}'
npx @reneturcios/jobhunt webhook_example '{"event":"job.created","language":"python"}'
npx @reneturcios/jobhunt --version

退出代码：成功时为 0，结果为 isError 时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/jobhunt mcp

MCP 客户端配置：

{
  "mcpServers": {
    "jobhunt": {
      "command": "npx",
      "args": ["-y", "@reneturcios/jobhunt", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/jobhunt
docker run --rm ghcr.io/cloudcorprecords/jobhunt --version

容器的默认命令是 mcp，因此第一种形式是 stdio MCP 服务；其他参数则会正常传递给命令行界面。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全使用存根 JSON-RPC 上游运行，不会发起实时网络调用。

许可证

MIT——请参阅 LICENSE。