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

hrmcp-server

HR および採用ワークフロー向けのソース公開型 MCP サーバーです。Claude を使用して候補者を職務内容と照合してスコアリングし、各評価項目のスコア、強み、ギャップを構造化して返します。MCP に対応するエージェントフレームワークであれば、ネイティブに呼び出せます。

ホステッド 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_...

API キーはクレジット購入後に発行されます。hrmcp-server-production.up.railway.app/billing で取得してください。

---

レート制限

制限は固定の時刻境界ではなく、ローリングウィンドウで API キーごとに適用されます。

制限	デフォルト
1 分あたり	30 リクエスト
1 日あたり	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 の呼び出しが成功するたびに、クレジットが 1 つ差し引かれます。クレジットは 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	1 つ以上の重みキーがありません
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 ウェブフック署名シークレット（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	キーごとの1分間のローリング制限
RATE_LIMIT_PER_DAY	いいえ	500	キーごとの1日間のローリング制限
RATE_LIMIT_CONCURRENT	いいえ	5	キーごとの同時処理リクエストの最大数
MAX_RESUME_CHARS	いいえ	15000	履歴書の文字数上限
MAX_JD_CHARS	いいえ	15000	求人情報の文字数上限
STRIPE_PRICE_LOOKUP_KEY	いいえ	credits_100	Stripe の価格検索キー
CREDITS_BUNDLE_SIZE	いいえ	100	1回の購入で付与されるクレジット数
CREDITS_EXPIRY_DAYS	いいえ	180	クレジットの有効期限（日数）
LOG_LEVEL	いいえ	info	info または error
IDEMPOTENCY_TTL_SECONDS	いいえ	86400	冪等性キャッシュの TTL（秒）
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 にネイティブ対応しているため、このプロトコルをサポートするエージェントフレームワーク用のラッパーは不要です。

---

ライセンス

Elastic License 2.0 の下でライセンスされています。無料で使用、セルフホスト、変更できます。このソフトウェアをホスト型またはマネージドサービスとして第三者に提供することはできません。商用ホスティングに関するお問い合わせは [email protected] までご連絡ください。