joblet-mcp-grok

独立的 MCP 服务器，向 Grok 及任何其他符合标准的 MCP 主机提供只读的 joblet.ai 职位搜索。独立部署——与 Joblet 的其他连接器不共享任何基础设施、分支或发布流程。

两个工具，均为只读（readOnlyHint: true）：

• search_jobs — 关键词搜索，带有真实的上游位置过滤器、MCP 层相关性过滤（标题/类别/行业/职位 token 匹配；仅描述匹配被拒绝）、expVer/近似重复去重，以及 8 条结果的硬上限。提供 text + structuredContent，以及一个 MCP Apps 职位卡片小部件，供支持渲染的主机使用。

• get_job_details — 按职位 ID 获取完整发布信息（描述、要求、职责、薪资和工作地点（如已知）、申请链接）。

申请 URL 按字节精确传递（保留 Joveo 跟踪，无代理或重定向）。就业类型有意不展示或过滤：上游搜索不提供权威字段。

要求

• Node.js 18+（在 Node 24 上开发和测试）

• 无需 API 密钥或机密——上游 joblet.ai API 是公开的

本地设置

npm ci
npm run build        # bundles the widget to dist/mcp-app.html (required before start)
PORT=3010 npm start  # MCP endpoint at http://localhost:3010/mcp

健康检查：

# GET /health  ->  {"status":"ok","version":"1.1.0"}

MCP 端点：POST /mcp — Streamable HTTP，JSON 响应，无状态（无会话 ID）。需要规范标准的 Accept: application/json, text/event-stream 请求头。GET / 返回服务横幅。

本地验证 MCP 契约

MCP_URL="http://localhost:3010/mcp" node test_client.mjs
MCP_URL="http://localhost:3010/mcp" node test_widget.mjs

或以交互方式：npm run inspect（MCP Inspector → Streamable HTTP → /mcp URL）。

开发

npm run typecheck    # server + widget/tests configs
npm test             # vitest suites (server pipeline, widget, a11y, logging)
npm run build        # production widget bundle

配置

参见 .env.example。所有内容均为可选；默认值适合生产环境。MCP_REQUEST_LOG=1 启用经过清理的逐调用日志记录（仅哈希/长度/计数——绝不记录原始查询文本、位置、申请 URL 或凭据）。

小部件说明

职位卡片小部件通过 MCP Apps 的 sendSizeChanged 通知向主机报告其固有高度（仅高度，在 requestAnimationFrame 之后测量，带变化门控以避免调整大小循环），并在声明了固定主机容器高度时遵循该高度。主机是否相应地调整 iframe 大小属于主机行为。View & Apply CTA 使用符合标准的 ui/open-link 请求，并在主机拒绝或不支持时提供可见、可访问的卡片内回退（链接 + 复制操作）——它绝不会静默失败。