内容
# freehire MCP 服务器
[MCP](https://modelcontextprotocol.io) 服务器，基于 [freehire](https://freehire.dev) 工作职位 API。它允许任何 MCP 主机 — Claude Desktop、Claude Code 或兼容的代理 —
**搜索、筛选和申请 IT 工作**，无需浏览器，使用个人 API 密钥进行身份验证。它镜像 [freehire CLI](https://github.com/strelov1/freehire-cli)：相同的 API，相同的凭证，以 MCP 工具的形式暴露，而不是 shell 命令。
## 安装
无需全局安装 — 主机通过 `npx` 运行它。将它添加到主机的 MCP 配置中（Claude Desktop → **设置 → 开发者 → 编辑配置**，或
`~/.claude.json` for Claude Code）：
```json
{
"mcpServers": {
"freehire": {
"command": "npx",
"args": ["-y", "freehire-mcp"],
"env": { "FREEHIRE_TOKEN": "fhk_xxxxxxxx" }
}
}
}
```
在网页应用中创建 `fhk_…` 密钥（freehire.dev → 账户菜单 → **API 密钥**）。
如果您已经使用 freehire CLI (`freehire auth login`)，可以 **省略 `env`** —
服务器读取相同的 `~/.freehire/creds.json`。
## 身份验证
令牌和 API 基地址按优先级解析
**环境变量 → `~/.freehire/creds.json` → 默认 `https://freehire.dev`**：
| 内容 | 来源 |
|------|---------|
| 令牌 | `FREEHIRE_TOKEN` → 凭证文件 |
| API 基地址 | `FREEHIRE_API_URL` → 凭证文件 → `https://freehire.dev` |
服务器只读取凭证文件（它从不写入凭证文件 — 登录仍然是 CLI 的任务）。
如果没有配置令牌，工具会返回一个明确的“未身份验证”错误，而不是服务器启动失败。
## 工具
| 工具 | 用途 |
|------|---------|
| `whoami` | 身份验证用户（验证密钥）。 |
| `facets` | 筛选器/技能词汇表：每个筛选器的实时值和计数。 **先调用此工具。** |
| `search` | 关键词 + 筛选器工作搜索；返回工作和总匹配计数。 |
| `market_fit` | 根据实时市场需求（覆盖范围 + 缺口）评估技能列表。 |
| `job` | 通过 slug 获取单个工作的完整内容。 |
| `company` | 通过 slug 获取公司和其开放工作。 |
| `apply` | 标记工作已申请。 |
| `save` / `unsave` | 书签 / 取消书签。 |
| `stage` | 设置申请阶段（服务器验证）。 |
| `note` | 附加一个自由文本备注。 |
| `my` | 调用者的跟踪工作（全部/已查看/已保存/已申请）以及阶段 + 备注。 |
| `submit` | 提交职位待审核。 |
| `my_submissions` | 调用者的提交内容以及状态。 |
| `jobs_add` / `jobs_edit` | 管理员：作者 / 编辑工作（403 无管理员角色）。 |
| `submissions_pending` | 管理员：审核队列。 |
| `submission_approve` / `submission_reject` | 管理员：决定提交内容。 |
**筛选器。** `search`、`market_fit` 和 `facets` 共享相同的市场筛选器参数：
`remote`、`region`、`country`、`city`、`company`、`category`、`role`、
`seniority`、`employment_type`、`english_level`、`salary_min`、`visa`，以及一个通用的
`facets` 映射（`{"source": "greenhouse"}`）用于词汇表中的其他筛选器。
使用 `facets` 工具发现有效值 — 不要创造它们。在 `search` 中，`skills` 是一个筛选器；在 `market_fit` 中，`skills` 是被测量的集合。
每个工具返回原始 API `data` 作为 JSON 文本；API 错误成为一个带有 HTTP 状态码的 `isError` 结果（401 添加身份验证提示）。
## 开发
```bash
npm install
npm test # vitest: 配置、客户端（模拟服务器）、筛选器、工具调度
npm run build # tsc → dist/
```
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。freehire 后端和 CLI 也是 MIT 许可证。
