工作匹配 MCP 服务器

一个提供智能工作匹配能力的模型上下文协议（MCP）服务器。从工作描述中提取结构化的职位要求，并从LlamaCloud简历索引中查找/排序候选人。

🚀 功能

核心工作匹配功能

1. extract_job_requirements - 从工作描述文本中提取结构化数据
2. find_matching_candidates - 从LlamaCloud索引中查找并排序候选人
3. search_candidates_by_skills - 按特定技能搜索候选人
4. score_candidate_qualifications - 对候选人的资格进行评分

额外功能

• add / subtract / multiply - 基本数学函数（向后兼容）

📋 可用的 MCP 工具

工作描述处理

• extract_job_requirements(job_description_text: str) - 从文本中提取结构化的职位要求

候选人管理

• find_matching_candidates(required_qualifications: str, preferred_qualifications: str, top_k: int, enable_reranking: bool) - 查找符合职位资格的候选人
• search_candidates_by_skills(skills: str, top_k: int) - 按特定技能搜索候选人
• score_candidate_qualifications(candidate_resume: str, required_qualifications: str, preferred_qualifications: str, job_title: str, job_description: str) - 对候选人的资格进行评分

📋 函数详情

1. 提取职位要求

extract_job_requirements(jd_text: str) -> str

输入： 工作描述文本（从职位发布中复制）

输出： 包含以下内容的 JSON 字符串：

• title: 职位名称
• company: 公司名称
• location: 工作地点
• required_qualifications: 必要资格条件数组
• preferred_qualifications: 优先资格条件数组
• description: 工作概述
• experience_level: 经验水平（初级/中级/高级）
• employment_type: 就业类型（全职/合同等）

2. 从 LlamaCloud 中查找并排序候选人

find_matching_candidates(required_qualifications: str, preferred_qualifications: str, top_k: int, enable_reranking: bool) -> str

输入：

• required_qualifications: 逗号分隔的必要资格条件
• preferred_qualifications: 逗号分隔的优先资格条件
• top_k: 最多检索的候选人数量（默认：1
• enable_reranking: 是否启用重新排名（默认：True）

输出： 包含以下内容的 JSON 字符串：

• candidates: 带有分数和分析的候选人数组
• total_candidates: 找到的候选人总数
• search_parameters: 关于搜索配置的详细信息

关键特性：

• 使用语义搜索从 LlamaCloud 索引中检索候选人
• 加权评分：必要资格条件权重更高
• 匹配百分比：整体兼容性得分
• 详细解释：每个资格评估的详细解释

3. 按技能搜索候选人

search_candidates_by_skills(skills: str, top_k: int) -> str

输入：

• skills: 逗号分隔的技能或关键词列表
• top_k: 检索的顶级候选人数量（默认：10）

输出： 包含匹配候选人及其分数的 JSON

4. 对候选人资格进行评分

score_candidate_qualifications(candidate_resume: str, required_qualifications: str, preferred_qualifications: str, job_title: str, job_description: str) -> str

输入：

• candidate_resume: 候选人的简历文本
• required_qualifications: 逗号分隔的必要资格条件
• preferred_qualifications: 逗号分隔的优先资格条件
• job_title: 用于上下文的职位名称（可选）
• job_description: 用于上下文的职位描述（可选）

输出： 包含以下内容的综合分析：

• 优势和劣势
• 详细的评分分解
• 招聘建议
• 角色适应性评估

🛠️ 设置与配置

1. 配置 API 密钥及设置

您有两个配置选项：

选项 A：环境变量（推荐用于生产）

# 必需：OpenAI API 密钥
export OPENAI_API_KEY="your-openai-api-key"

# 必需：LlamaCloud 配置
export LLAMA_CLOUD_API_KEY="your-llamacloud-api-key"
export LLAMA_CLOUD_INDEX_NAME="your-resume-index-name"
export LLAMA_CLOUD_PROJECT_NAME="your-project-name"
export LLAMA_CLOUD_ORGANIZATION_ID="your-organization-id"

# 可选：服务器配置
export PORT="8080"
export HOST="0.0.0.0"
export REQUEST_TIMEOUT="30.0"
export OPENAI_TEMPERATURE="0.1"

选项 B：直接在 config.py 中配置（适用于本地开发）

1. 打开 config.py 并替换占位符值：

   # 替换这些占位符值为您的实际 API 密钥：
   OPENAI_API_KEY = "your-actual-openai-api-key-here"
   LLAMA_CLOUD_API_KEY = "your-actual-llamacloud-api-key-here"
   LLAMA_CLOUD_ORGANIZATION_ID = "your-actual-org-id-here"
   LLAMA_CLOUD_INDEX_NAME = "your-actual-index-name"
   

2. ⚠️ 安全警告：如果您直接编辑 config.py，切勿将 API 密钥提交到版本控制！

获取您的 API 密钥：

• OpenAI API 密钥：从 OpenAI 平台 获取
• LlamaCloud API 密钥：从 LlamaCloud 控制台 获取
• LlamaCloud 组织 ID：在您的 LlamaCloud 项目设置中找到
• LlamaCloud 索引名称：您在 LlamaCloud 中的简历索引名称

没有 LlamaCloud 凭据时，服务器会使用模拟候选人数据进行测试。

2. 保护您的 API 密钥（重要！）

如果您计划将此代码提交到版本控制，请创建一个 .gitignore 文件以保护您的敏感信息：

# 创建 .gitignore 文件
cat > .gitignore << EOF
# 环境变量和敏感文件
.env
.env.local
.env.production
config_local.py

# Python
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
.venv/
venv/

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db
EOF

替代方案：您也可以创建一个单独的 config_local.py 文件，其中包含您的实际密钥，并在 config.py 中导入它，然后将 config_local.py 添加到 .gitignore。

3. 安装依赖项

# 使用 uv 安装（推荐）
uv install

# 或者使用 pip
pip install fastmcp httpx

4. 运行服务器

python server.py

服务器将在 http://localhost:8080/mcp 启动（或 PORT 环境变量指定的端口）

🧪 测试

运行全面的测试套件：

# 先启动服务器
python server.py

# 在另一个终端中运行测试
python test_server.py

测试套件将：

• ✅ 从样本 JD 中提取职位要求
• ✅ 从 LlamaCloud 中检索并排序候选人（或模拟数据）
• ✅ 对顶级候选人进行详细分析
• ✅ 测试向后兼容性函数

📊 工作原理

架构概述

1. 工作描述处理

   • 使用 OpenAI 从自由形式的 JD 文本中提取结构化要求
   • 分离必要资格条件与优先资格条件
   • 提取元数据（职位名称、公司名称、地点等）

2. 候选人检索

   • 使用语义搜索查询 LlamaCloud 索引
   • 根据职位要求构建搜索查询
   • 检索具有相似度分数的顶级候选人

3. 智能评分

   • 使用 OpenAI 对每个候选人进行评分（0-2 分）
   • 0: 未达到, 1: 部分达到, 2: 强烈达到
   • 必要资格条件在最终评分中加权两倍
   • 提供每个评分的解释

4. 匹配计算

   加权评分 = (必要总分 × 2) + 优先总分
   匹配百分比 = (加权评分 / 最大可能评分) × 100
   

数据流

graph TD
    A[工作描述文本] --> B[extract_job_requirements]
    B --> C[结构化要求 JSON]
    C --> D[find_matching_candidates]
    E[LlamaCloud 索引] --> D
    D --> F[带有分数的排名候选人]
    C --> G[score_candidate_qualifications]
    H[个人简历] --> G
    G --> I[详细分析及建议]

🎯 使用案例

1. 自动简历筛选

# 从职位发布中提取要求
job_reqs = extract_job_requirements(job_posting_text)

# 从您的简历数据库中查找顶级候选人
top_candidates = find_matching_candidates("Python, JavaScript, React", "AWS, Docker", 10, True)

# 获取有希望候选人的详细分析
for candidate in top_5:
    analysis = score_candidate_qualifications(candidate['resume'], job_reqs, candidate['name'])

2. 招聘流程集成

• ATS 集成：自动评分收到的应用
• 招聘工具：提供基于数据的候选人排名
• 面试准备：生成针对候选人的面试问题

3. 职场分析

• 需求趋势：跟踪职位发布中的常见资格条件
• 候选人缺口分析：识别候选人池中的缺失技能
• 薪酬基准：关联资格条件与薪酬数据

🚀 部署

前提条件

确保您已设置以下内容：

• Python 3.10+
• UV 包管理器
• Google Cloud SDK (gcloud)
• 配置项目 ID：export PROJECT_ID=<your-project-id>
• 创建 Artifact Registry 存储库：remote-mcp-servers

本地开发

# 1. 安装依赖项
uv install

# 2. 配置 API 密钥（选择一种方法）：

# 方法 A：设置环境变量
export OPENAI_API_KEY="your-openai-api-key"
export LLAMA_CLOUD_API_KEY="your-llamacloud-api-key"
export LLAMA_CLOUD_INDEX_NAME="your-index-name"
export LLAMA_CLOUD_ORGANIZATION_ID="your-org-id"

# 方法 B：直接编辑 config.py（参见配置部分）

# 3. 运行服务器
python server.py

服务器将在 http://localhost:8080/mcp 启动，并记录其使用的配置：

[INFO]: LlamaCloudService 初始化，索引：your-index-name
[INFO]: MCP 服务器正在 0.0.0.0:8080 启动

快速配置测试：

您可以通过运行以下命令来验证您的配置是否正常工作：

python -c "from config import OPENAI_API_KEY, LLAMA_CLOUD_API_KEY, LLAMA_CLOUD_INDEX_NAME; print(f'OpenAI: {OPENAI_API_KEY[:10]}..., LlamaCloud: {LLAMA_CLOUD_API_KEY[:10]}..., Index: {LLAMA_CLOUD_INDEX_NAME}')"

如果看到类似 "your-openai-api-key-here" 的占位符值，则需要更新您的配置。

Docker 部署

# 构建镜像
docker build -t job-matching-mcp .

# 运行容器
docker run -p 8080:8080 \
  -e OPENAI_API_KEY="your-key" \
  -e LLAMA_CLOUD_API_KEY="your-key" \
  job-matching-mcp

Google Cloud Run 部署

📚 参考文档：在不到 10 分钟内将远程 MCP 服务器部署到 Google Cloud Run

初始部署

# 构建并推送到 Artifact Registry
gcloud builds submit --region=us-central1 \
  --tag us-central1-docker.pkg.dev/$PROJECT_ID/remote-mcp-servers/mcp-server:latest

# 部署到 Cloud Run
gcloud run deploy mcp-server \
  --image us-central1-docker.pkg.dev/$PROJECT_ID/remote-mcp-servers/mcp-server:latest \
  --region=us-central1 \
  --no-allow-unauthenticated \
  --set-env-vars OPENAI_API_KEY="your-key",LLAMA_CLOUD_API_KEY="your-key"

再次部署步骤

在对您的 MCP 服务器进行了代码更改后，按照以下步骤重新部署：

步骤 1：重建容器并推送到 Artifact Registry

gcloud builds submit --region=us-central1 \
  --tag us-central1-docker.pkg.dev/$PROJECT_ID/remote-mcp-servers/mcp-server:latest

步骤 2：将更新的容器重新部署到 Cloud Run

gcloud run deploy mcp-server \
  --image us-central1-docker.pkg.dev/$PROJECT_ID/remote-mcp-servers/mcp-server:latest \
  --region=us-central1 \
  --no-allow-unauthenticated

步骤 3：测试部署（可选）

启动 Cloud Run 代理以测试您的更新服务器：

gcloud run services proxy mcp-server --region=us-central1

然后运行您的测试脚本：

uv run test_server.py

📁 项目结构

mcp-on-cloudrun/
├── config.py                 # 配置常量
├── models.py                 # 数据结构
├── server.py                 # 主 MCP 服务器
├── Dockerfile               # 容器配置
├── pyproject.toml           # Python 依赖项
├── services/
│   ├── openai_service.py    # OpenAI API 集成
│   └── llamacloud_service.py # LlamaCloud 集成
├── tools/
│   ├── math_tools.py        # 数学运算（加法、减法、乘法）
│   ├── job_tools.py         # 工作描述提取
│   └── candidate_tools.py   # 候选人搜索和评分
└── test_server.py           # 测试客户端

🔧 自定义

评分标准

修改 services/openai_service.py 中的评分提示以调整评估标准：

• 更改评分尺度（例如从 0-2 改为 0-5）
• 调整必要资格条件与优先资格条件之间的权重
• 添加领域特定的评估标准

LlamaCloud 集成

对于使用真实候选人数据的生产部署：

1. 设置 LlamaCloud 账户并创建简历索引
2. 在 config.py 中配置环境变量
3. 用实际的 LlamaCloud API 调用替换模拟候选人数据

OpenAI 模型选择

在 config.py 中更改模型：

OPENAI_MODEL = "gpt-4o-mini"  # 快速且成本效益高
# OPENAI_MODEL = "gpt-4o"     # 质量更高，但更昂贵

📈 性能与扩展

• 并发请求：FastMCP 处理多个同时的工作匹配请求
• 缓存：考虑实现 Redis 来频繁地提取工作要求
• 速率限制：OpenAI API 有速率限制；对于大量使用，实施排队
• 成本优化：大多数操作使用 gpt-4o-mini，关键分析使用 gpt-4o

🔐 安全注意事项

安全说明

• 始终使用 --no-allow-unauthenticated 要求 Cloud Run 认证
• 确保用户具有 roles/run.invoker IAM 角色以访问服务器
• 使用 Cloud Run 代理进行本地测试时需要认证
• API 密钥：切勿将 API 密钥提交到版本控制
• 输入验证：服务器验证所有输入并处理错误数据
• 错误处理：外部服务不可用时优雅降级
• 数据隐私：简历数据通过 OpenAI 处理；考虑数据保留策略

🔍 故障排除

常见问题：

配置问题：

1. “无效 API 密钥” 错误：

   • 检查您的 API 密钥是否正确设置在 config.py 或环境变量中
   • 验证 API 密钥有效并具有适当的权限
   • 对于 OpenAI：确保您有信用/账单设置

2. “LlamaCloud 索引未找到”：

   • 验证 LLAMA_CLOUD_INDEX_NAME 与您的实际索引名称匹配
   • 检查 LLAMA_CLOUD_ORGANIZATION_ID 是否正确
   • 确保您的 LlamaCloud API 密钥有权访问指定的索引

3. 服务器显示占位符值：

   • 如果您在日志