AI candidate scoring via MCP. Score resumes against job descriptions with Claude — returns dimension scores, strengths, and gaps.

hrmcp-server

一个用于 HR 和招聘工作流的源码可用 MCP 服务。使用 Claude 根据职位描述为候选人评分，并返回结构化的维度分数、优势和不足。任何支持 MCP 的 Agent 框架都可以直接调用它。

托管 API — 无需运行任何内容即可使用：recruitapi.app 自托管 — 不到 15 分钟即可部署到 Railway（见下文）

---

端点

POST /score-candidate

根据职位描述为候选人的简历评分。

请求

{
  "resume_text": "...",
  "job_description": "...",
  "weights": {
    "skills_match": 0.40,
    "experience": 0.30,
    "industry_background": 0.20,
    "education": 0.10
  },
  "recency_window_years": 10
}

字段	类型	必填	默认值
resume_text	string	是	—
job_description	string	是	—
weights	object	否	{skills_match: 0.40, experience: 0.30, industry_background: 0.20, education: 0.10}
recency_window_years	integer > 0	否	10

权重之和必须为 1.0。每个值必须介于 0.0 和 1.0 之间。 两个文本字段的长度上限均为 15,000 个字符。简历至少须有 50 个单词。

响应 — 200

{
  "overall_score": 82,
  "dimension_scores": {
    "skills_match": 88,
    "experience": 85,
    "industry_background": 74,
    "education": 70
  },
  "strengths": [
    "Five years of hands-on Python in production ML pipelines",
    "Led cross-functional team during platform migration"
  ],
  "gaps": [
    "No experience with Kubernetes",
    "MBA preferred; candidate holds a BS"
  ],
  "recency_window_used": 10,
  "model": "claude-sonnet-4-20250514",
  "warnings": []
}

所有分数均为 0–100 的整数。strengths 和 gaps 各包含 2–4 条字符串，且内容须基于简历和职位描述，而非泛泛而谈。

幂等性

传入 Idempotency-Key 标头，可将响应缓存 24 小时。使用相同键重试时会返回缓存的响应，不会调用模型，也不会扣除额度。

Idempotency-Key: req_01J8XYZ

---

GET /health

{ "status": "ok", "model": "claude-sonnet-4-20250514" }

---

身份验证

每次请求 /score-candidate 都需要 API 密钥。可通过以下任一方式传入：

X-API-Key: hrmcp_sk_...

Authorization: Bearer hrmcp_sk_...

购买额度后会发放密钥。请前往 hrmcp-server-production.up.railway.app/billing 获取。

---

速率限制

限制按 API 密钥在滚动时间窗口内计算，而非按固定时钟边界计算。

限制	默认值
每分钟	30 个请求
每天	500 个请求
并发	5 个进行中的请求

每个响应都包含当前限制状态：

X-RateLimit-Limit-Minute: 30
X-RateLimit-Remaining-Minute: 28
X-RateLimit-Reset-Minute: 1712000060
X-RateLimit-Limit-Day: 500
X-RateLimit-Remaining-Day: 497
X-RateLimit-Reset-Day: 1712041234

自托管部署可通过 RATE_LIMIT_ENABLED=false 完全禁用速率限制。

---

额度

每次成功调用 /score-candidate 都会扣除一个额度。额度按 100 个一组购买，每组 $5，有效期为 180 天。

状态	代码	含义
402	credits_exhausted	余额为零
402	credits_expired	尚有额度，但该组额度已过期

---

错误格式

所有错误都使用相同的封装格式：

{
  "error": {
    "code": "missing_required_field",
    "message": "One or more required fields are missing.",
    "detail": { "missing_fields": ["resume_text"] }
  }
}

代码	状态	描述
unauthorized	401	API 密钥缺失、无效或已撤销
rate_limit_exceeded	429	超出滚动窗口限制；请查看 Retry-After 标头
credits_exhausted	402	没有剩余额度
credits_expired	402	额度已过期
missing_required_field	400	缺少 resume_text 或 job_description
resume_too_short	400	简历少于 50 个单词
payload_too_large	400	输入超过 15,000 个字符
weights_invalid_sum	400	权重之和不为 1.0
weights_missing_keys	400	缺少一个或多个权重键
weights_negative_value	400	权重值不在 0.0–1.0 范围内
recency_window_invalid	400	recency_window_years 不是正整数
idempotency_key_invalid	400	Idempotency-Key 标头值无效
model_unavailable	503	Anthropic API 超时或发生故障
response_parse_failure	500	模型返回了无法解析的输出

警告不会导致请求失败，并会随 200 响应一同返回：

代码	触发条件
non_english_detected	简历或 JD 中含有非拉丁字符
job_description_thin	JD 少于 30 个单词

---

自托管

部署到 Railway

1. 点击上方按钮 — Railway 会克隆代码仓库并配置一个 Postgres 服务
2. 添加 5 个必需的环境变量（见下文）
3. 在 Stripe 控制面板中注册 POST /webhooks/stripe；将签名密钥粘贴到 STRIPE_WEBHOOK_SECRET
4. 查看部署日志，确认出现 db_migrated 和 server_started
5. 访问 /health 进行确认

在本地运行

git clone https://github.com/Spaceghost99/hrmcp-server.git
cd hrmcp-server
npm install
cp .env.example .env
# Fill in ANTHROPIC_API_KEY at minimum
npm run dev

无需设置 DATABASE_URL 即可进行评分。身份验证和计费需要 Postgres。

---

环境变量

以下 5 个变量为必需项，缺少时服务器会在启动时崩溃。

变量	必需	默认值	描述
ANTHROPIC_API_KEY	是	—	Anthropic API 密钥
DATABASE_URL	仅生产环境	—	PostgreSQL 连接字符串（Railway 会提供此值）
STRIPE_SECRET_KEY	仅生产环境	—	Stripe 密钥（sk_test_... 或 sk_live_...）
STRIPE_WEBHOOK_SECRET	仅生产环境	—	Stripe Webhook 签名密钥（whsec_...）
PORT	否	3000	Railway 会自动设置此值
NODE_ENV	否	development	在 Railway 上设置为 production
ANTHROPIC_MODEL	否	claude-sonnet-4-20250514	用于评分的模型
ANTHROPIC_TIMEOUT_MS	否	25000	Anthropic API 超时时间，单位为毫秒
BCRYPT_ROUNDS	否	10	用于密钥哈希的 bcrypt 成本因子
RATE_LIMIT_ENABLED	否	true	设置为 false 可禁用速率限制
RATE_LIMIT_PER_MINUTE	否	30	每个密钥按滚动分钟计算的限制
RATE_LIMIT_PER_DAY	否	500	每个密钥按滚动天数计算的限制
RATE_LIMIT_CONCURRENT	否	5	每个密钥允许的最大并发请求数
MAX_RESUME_CHARS	否	15000	简历字符数上限
MAX_JD_CHARS	否	15000	职位描述字符数上限
STRIPE_PRICE_LOOKUP_KEY	否	credits_100	Stripe 价格查询键
CREDITS_BUNDLE_SIZE	否	100	每次购买获得的点数
CREDITS_EXPIRY_DAYS	否	180	点数过期天数
LOG_LEVEL	否	info	info 或 error
IDEMPOTENCY_TTL_SECONDS	否	86400	幂等缓存的存活时间，单位为秒
APP_URL	否	http://localhost:3000	公共基础 URL；用于计费链接

每个变量的描述请参阅 .env.example。

---

架构

src/
  index.ts                  — HTTP server, request routing, middleware wiring
  config.ts                 — Environment variable loading
  middleware/
    auth.ts                 — API key extraction and validation
    rateLimit.ts            — Rolling window rate limiter (in-memory)
    logger.ts               — Structured JSON logging
  billing/
    keys.ts                 — Key generation, hashing, verification (pure functions)
    db.ts                   — PostgreSQL pool, schema migration, all queries
    stripe.ts               — Checkout sessions, webhook handler, credit lifecycle
  tools/
    score-candidate/
      handler.ts            — Input validation, orchestration
      scorer.ts             — Anthropic API call, response parsing
      schema.ts             — Zod schemas and default weights
      prompt.ts             — System prompt and user prompt builder
  errors/
    codes.ts                — Error code constants
    envelope.ts             — createError / createWarning helpers

POST /score-candidate 的请求流程：

1. 身份验证 — 提取密钥、通过 SHA-256 查找、使用 bcrypt 验证
2. 速率限制 — 检查滚动分钟／天数／并发窗口
3. 解析并验证请求正文
4. 幂等处理 — 如果密钥匹配，则返回缓存的响应
5. 扣除点数 — 在 Postgres 中原子执行 SELECT FOR UPDATE
6. 评分 — 调用 Anthropic，解析并验证响应
7. 如果存在幂等键，则缓存响应
8. 添加 X-RateLimit-* 标头并发送响应
9. 释放并发槽位并写入请求日志行

---

替代方案

还有其他托管候选人评分方案。hrmcp-server 源码可用、可自托管，并原生支持 MCP — 对于支持该协议的 Agent 框架，无需使用包装器。

---

许可证

本软件基于 Elastic License 2.0 授权。可免费使用、自托管和修改。不得将本软件作为托管或管理式服务提供给第三方。如需商业托管，请联系 [email protected]。