内容
# 简历 MCP 服务器
> 由 **模型上下文协议（MCP）** 、 **TypeScript** 、 **Express** 和 **官方 MCP SDK** 构建的 AI 驱动的简历 MCP 服务器。
>
> 通过 **stdio** 和 **HTTP** 传输协议，以结构化 AI 工具的形式公开简历信息，实现与兼容 MCP 的 AI 客户端的无缝集成。
---
## 🌐 线上部署
| 端点 | URL |
|---|---|
| **MCP 端点** | `https://resume-mcp-server-z04b.onrender.com/mcp` |
| **健康检查** | `https://resume-mcp-server-z04b.onrender.com/health` |
| **部署平台** | [Render](https://render.com) （免费套餐） |
---
## 💡 为什么有这个项目？
尽管简历可以轻松地以 PDF 形式上传，但该项目演示了如何使用 **模型上下文协议** 将 **结构化信息暴露给 AI 应用程序**。
与将简历视为非结构化文档不同，AI 客户端可以通过 **专用工具** 以结构化、预测的响应检索特定信息 — 技能、项目、教育、经验、关键词搜索和简历量身定制。
相同的架构可以扩展到企业系统，如 **人力资源平台、CRM、医院数据库、ERP 系统和内部业务应用程序**。
> 这就是为什么 MCP 存在 — 为了给 AI 代理提供结构化、程序化的访问数据源，而不是依赖原始文档解析。
---
## ✅ 项目亮点
| | |
|---|---|
| ✔ | 使用 **官方 MCP SDK** 构建 |
| ✔ | 支持 **stdio** 和 **HTTP/Streamable** 传输协议 |
| ✔ | **部署在 Render** 上，带有公开的公共端点 |
| ✔ | **与 Claude Desktop 集成** （stdio） |
| ✔ | **与 Cursor AI 集成** （HTTP） |
| ✔ | **8 个功能齐全的 AI 工具** |
| ✔ | 完整的 **TypeScript** 实现，带有 Zod 验证 |
| ✔ | **自动测试套件** — 16/16 stdio + 6/6 HTTP 测试通过 |
---
## 🏗️ 架构
### 本地（stdio 传输）
```
Claude Desktop
│
│ stdin / stdout (stdio)
│
简历 MCP 服务器 （node dist/stdioMain.js）
│
│ 读取
│
resume.json
```
### 远程（HTTP 传输）
```
Cursor AI / Claude Desktop / 任意 MCP 客户端
│
│ POST /mcp （HTTP + Streamable）
│
Render.com
│
简历 MCP 服务器 （node dist/httpMain.js）
│
│ 读取
│
resume.json
```
---
## 🧪 已测试的 AI 客户端
| 客户端 | 传输 | 状态 |
|---|---|---|
| **Claude Desktop** | stdio | ✅ 已测试并正常工作 |
| **Cursor AI** | HTTP | ✅ 已测试并正常工作 |
| **Render 部署** | HTTP/Streamable | ✅ 已测试并正常工作 |
| **MCP Inspector** | stdio | ✅ 已测试并正常工作 |
| Claude Web | — | ⚠️ 目前不支持任意自定义 MCP 服务器 |
| ChatGPT | — | ⚠️ 目前不支持连接到自定义 MCP 服务器 |
---
## 🌍 可能的商业用例
该架构可以适应远不止于个人简历：
| 用例 | 描述 |
|---|---|
| **员工数据库 MCP** | HR 团队通过 AI 查询员工技能、角色和历史 |
| **医院记录 MCP** | AI 检索患者记录、预约或处方 |
| **CRM 助手** | AI 查询客户数据、线索和交易历史 |
| **HR 招募助手** | AI 筛选候选人并将 JD 匹配到个人资料 |
| **ERP 系统** | AI 获取库存、订单和财务记录 |
| **知识库** | AI 搜索内部公司文档 |
| **公司文档** | AI 回答政策和流程问题 |
| **GitHub 仓库助手** | AI 查询代码库结构、贡献者和问题 |
> 该项目中的 MCP 架构是 **与所有这些企业场景中使用的相同模式**。
---
## ✨ 功能
| 功能 | 描述 |
|---|---|
| **8 个 MCP 工具** | 查询摘要、经验、技能、项目、教育、搜索、按 ID 获取和根据 JD 量身定制简历 |
| **两种传输模式** | **stdio** （本地，零配置）和 **HTTP/Streamable** （远程，可部署） |
| **简历量身定制** | 基于规则的关键词重叠分析 — 将您的简历与任何职位描述进行匹配 |
| **全文搜索** | 在所有简历部分中搜索，带有用于深入研究的稳定 ID |
| **可选 API 密钥身份验证** | 使用 `x-api-key` 头验证保护您的 HTTP 端点 |
| **健康检查端点** | `GET /health` 用于在线监测和部署健康检查 |
| **类型安全** | 使用严格的 TypeScript 和 Zod 模式验证编写 |
---
## 🛠️ 可用工具
### `getSummary`
返回候选人的姓名、职业职称、摘要和联系信息。
- **参数：** 无
- **示例提示：** *"这个候选人的职业摘要是什么？"*
### `getExperience`
返回工作经验历史。可选地按公司名称过滤（不区分大小写，部分匹配）。
- **参数：** `company` *(可选字符串)* — 例如 `"RBrickks"`
- **示例提示：** *"这个人曾经在哪些公司工作过？"*
### `getSkills`
按类别返回技能。可选地过滤到特定类别。
- **参数：** `category` *(可选枚举)* — `"languages"` | `"frameworks"` | `"tools"` | `"soft"`
- **示例提示：** *"这个候选人知道哪些编程语言？"*
### `getProjects`
返回候选人构建的项目。可选地按技术栈标签过滤。
- **参数：** `tag` *(可选字符串)* — 例如 `"Angular"` 、 `"Spring Boot"`
- **示例提示：** *"展示使用 Angular 的项目"*
### `getEducation`
返回学术教育历史，包括学位、机构和成绩。
- **参数：** 无
- **示例提示：** *"这个候选人在哪里学习过？"*
### `search`
在所有简历部分进行全文搜索 — 摘要、经验要点、技能、项目描述和教育。返回可以传递给 `fetch` 以获取详细信息的稳定 ID。
- **参数：** `query` *(必填字符串)* — 例如 `"Spring Boot"` 、 `"automation"`
- **示例提示：** *"搜索简历中与安全相关的任何内容"*
### `fetch`
通过其稳定 ID（由 `search` 返回）获取特定简历部分的完整详细信息。
- **参数：** `id` *(必填字符串)* — 例如 `"summary"` 、 `"experience-0"` 、 `"projects-1"` 、 `"skills"` 、 `"education-2"`
- **示例提示：** *"获取 experience-0 的完整详细信息"*
### `tailorResume`
分析职位描述并对最相关的技能、经验要点和项目进行排名，通过关键词重叠。纯粹基于规则 — 无外部 AI 依赖。
- **参数：** `jobDescription` *(必填字符串)* — 职位发布的全文
- **示例提示：** *"这里有一个谷歌公司 Java 后端职位的职位描述：[粘贴 JD]。这个简历的匹配度如何？*
---
## 📦 先决条件
- [Node.js](https://nodejs.org/) **v18 或更高版本**
- npm（随 Node.js 包含）
---
## 🚀 安装
```bash
# 克隆仓库
git clone https://github.com/Adarshcharjan/resume-mcp-server.git
cd resume-mcp-server
# 安装依赖
npm install
# 将 TypeScript 编译为 JavaScript
npm run build
```
---
## ▶️ 运行服务器
### 选项 1：stdio 传输（本地）
设计用于与运行在同一台机器上的 AI 客户端直接集成（例如 Claude Desktop）。客户端启动服务器进程并通过标准输入/输出进行通信。
```bash
npm run dev:stdio
```
### 选项 2：HTTP 传输（本地或远程）
作为标准 Web 服务器运行。使用此选项进行远程部署或当 AI 客户端通过 HTTP 连接时。
```bash
npm run dev:http
```
服务器在 `http://localhost:3000` 启动，包含：
- **MCP 端点：** `POST http://localhost:3000/mcp`
- **健康检查：** `GET http://localhost:3000/health`
---
## 🔐 API 密钥身份验证
HTTP 服务器支持 **可选的 API 密钥身份验证**。
如果在环境变量中设置了 `RESUME_MCP_API_KEY`，则 `/mcp` 的每个请求都必须包含头部：
```
x-api-key: 您的密钥
```
否则，服务器以 **公共模式** 运行（不需要身份验证）。
**设置：**
```bash
# 复制示例 env 文件
cp .env.example .env
```
编辑 `.env`:
```env
PORT=3000
RESUME_MCP_API_KEY=您的自定义密钥
```
当激活 API 密钥时，Claude Desktop 配置必须包含它：
```json
{
"mcpServers": {
"resume": {
"type": "streamable-http",
"url": "https://您的服务器.onrender.com/mcp",
"headers": {
"x-api-key": "您的自定义密钥"
}
}
}
}
```
---
## 🔌 与 MCP 兼容的 AI 客户端集成
### Claude Desktop
Claude Desktop 原生支持 MCP。您可以使用任一传输模式连接。
#### stdio（推荐用于本地使用）
1. 打开您的 Claude Desktop 配置文件：
- **Windows：** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS：** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux：** `~/.config/Claude/claude_desktop_config.json`
2. 添加 `mcpServers` 条目（如果文件不存在，请创建）：
```json
{
"mcpServers": {
"resume": {
"command": "node",
"args": ["/绝对路径/到/resume-mcp-server/dist/stdioMain.js"]
}
}
```
> ⚠️ **Windows 用户：** 在路径中使用双反斜杠：
> `"D:\\Study\\Resume _MCP_server\\dist\\stdioMain.js"`
3. **完全重启** Claude Desktop（从系统托盘退出，然后重新打开）。
4. 启动新的聊天。锤子 🔨 工具图标在聊天输入附近将显示所有 8 个简历工具。
#### HTTP / Streamable（远程服务器）
```json
{
"mcpServers": {
"resume": {
"type": "streamable-http",
"url": "https://resume-mcp-server-z04b.onrender.com/mcp"
}
}
}
```
---
### Cursor AI
1. 打开 **Cursor 设置** → **MCP**（或 `Ctrl+Shift+P` → "MCP：添加服务器"）。
2. 添加新服务器：
**stdio：**
```json
{
"resume": {
"command": "node",
"args": ["/绝对路径/到/resume-mcp-server/dist/stdioMain.js"]
}
}
```
**HTTP（推荐 - 使用实时 Render 部署）：**
```json
{
"resume": {
"type": "streamable-http",
"url": "https://resume-mcp-server-z04b.onrender.com/mcp"
}
}
```
3. 简历工具将立即在 Cursor 的 AI 聊天中可用。
---
### VS Code + GitHub Copilot
1. 在您的工作区中创建或编辑 `.vscode/mcp.json`:
```json
{
"servers": {
"resume": {
"command": "node",
"args": ["/绝对路径/到/resume-mcp-server/dist/stdioMain.js"]
}
}
```
2. 在 Agent 模式下打开 GitHub Copilot Chat - 简历工具将可用。
---
### Windsurf
1. 打开 **Windsurf 设置** → **MCP**。
2. 添加新服务器：
```json
{
"resume": {
"type": "streamable-http",
"url": "https://resume-mcp-server-z04b.onrender.com/mcp"
}
}
```
---
### MCP Inspector（测试和调试）
[ MCP Inspector](https://github.com/modelcontextprotocol/inspector) 是一个用于测试 MCP 服务器而无需任何 AI 客户端的视觉工具。
```bash
npx @modelcontextprotocol/inspector
```
当 Inspector UI 在您的浏览器中打开时：
1. 设置 **传输类型** → `STDIO`
2. 设置 **命令** → `node`
3. 设置 **参数** → `dist/stdioMain.js`
4. 点击 **连接**
所有 8 个工具将出现。点击任意工具，填写参数并点击 **运行** 以查看实时 JSON 响应。
---
## ☁️ Render 部署
该项目在 Render 上使用 HTTP Streamable 传输进行部署。
### 配置
| 设置 | 值 |
|---|---|
| **运行时** | Node |
| **构建命令** | `npm install && npm run build` |
| **启动命令** | `npm start` |
| **计划** | 免费 |
### Render 上的环境变量
| 变量 | 值 |
|---|---|
| `PORT` | `3000` |
| `RESUME_MCP_API_KEY` | *(您的密钥 - 可选)* |
> **注意：** Render 的免费套餐在 15 分钟不活动后会关闭。冷启动后的第一个请求可能需要 ~30 秒才能响应。
---
## 🧪 测试
### 自动测试套件 - stdio（16 个测试用例）
```bash
npm run build
node test-all-tools.mjs
```
预期输出：
```
✓ PASS 1. getSummary - 姓名：Adarsh Charjan | 标题：Junior Software Developer
✓ PASS 2. getExperience - 返回的职位：3
✓ PASS 3. getExperience - 过滤 "RBrickks" → 2 个职位
✓ PASS 4. getSkills - 语言：Java、SQL、HTML、CSS
✓ PASS 5. getSkills - 过滤 "frameworks" → Spring Boot、Spring MVC、Hibernate、Angular、REST APIs
✓ PASS 6. getProjects - 返回 2 个项目
✓ PASS 7. getProjects - 过滤 "Angular" → WELLCARE Hospital Management System
✓ PASS 8. getEducation - B.Tech、HSC、SSC
✓ PASS 9. search "Spring Boot" - 4 个匹配
✓ PASS 10. search "automation" - 2 个匹配
✓ PASS 11. fetch "summary" - 专业总结
✓ PASS 12. fetch "experience-0" - RBrickks 的 Junior Software Developer
✓ PASS 13. fetch "projects-1" - WELLCARE Hospital Management System
✓ PASS 14. fetch "skills" - 技能和技术
✓ PASS 15. tailorResume - 匹配语言：[Java, SQL] | 最高分数：7
✓ PASS 16. fetch 无效 ID - 正常错误处理
结果：16 通过 0 失败 / 16 总数 🎉### 自动测试套件 - HTTP（6 个测试用例）
```bash
# 终端 1
npm run dev:http
# 终端 2
node test-http.mjs
```
预期输出：
```
✓ PASS 1. initialize - 服务器：resume-mcp-server v1.0.0
✓ PASS 2. getSummary - 姓名：Adarsh Charjan
✓ PASS 3. getExperience - 过滤 "AutomationEdge" → RPA Intern
✓ PASS 4. search "RBAC" - 3 个匹配
✓ PASS 5. tailorResume - 匹配框架：[Spring Boot, Angular, REST APIs]
✓ PASS 6. GET /health - 状态：ok
结果：6 通过 0 失败 / 6 总数 ️
```
