Skip to main content
Glama
Resume Preview MCP Server

Resume Preview MCP Server

by studyllm

Resume Preview MCP Server

简体中文 | English

MCP server,把结构化的简历内容渲染到浏览器里的实时 A4 页面 —— 你反复打磨措辞的同时,页面跟着刷新,不用导出再重来。

MIT 许可证,兼容任何 MCP 客户端。

✨ 功能特性

  • 🔄 实时刷新 - 内容一改,已打开的标签页就自己刷新

  • 📐 A4 版式 - 简历在浏览器和 PDF 里都是真实的 A4 页面

  • 📤 两种导出格式 - 导出 PDF,或导出成独立 HTML 文档

  • 🧩 结构化内容模型 - 你没写的板块会直接从页面上消失

  • 🔤 始终是纯文本 - 内容被转义,里面的 HTML 标签和脚本永远不会被解释

  • 🗂️ 多份简历 - 每份简历一个 resume_id,各有各的标签页和 slug

  • 💾 持久化的工作文件 - 简历存放在 ~/.config/resume-preview/resumes

  • 🖥️ 独立画廊 - resume-preview --serve 打开浏览器画廊,列出所有已存简历,支持搜索和删除

  • 🌍 两套彼此独立的语言 - 页面框架跟随浏览器语言;简历自身的语言按份设置,决定分节标题和导出的文档

  • 🔎 审阅工具 - 在预览页里缩放、平移、导出,附带连接状态指示和"最后更新"时间戳

  • 🤖 内置技能 - 插件自带 resume 技能,包含内容模型和措辞建议

Related MCP server: Resume MCP Agent

架构

架构图:分层模块与调用关系

两条链路共用同一套代码路径:

  • 预览 — resume_preview → 逐层处理 → 渲染结果落进 resumes/ → live-server.ts 监听到变化,用 WebSocket 推 reload

  • 导出 — resume_export → 走同一套渲染 → 落盘到 save_path

模块与接口清单见 docs/api-list.md。

🚀 快速开始

发布状态:npm 包 @studyllm/resume-preview 尚未发布(npm view @studyllm/resume-preview 返回 404), 因此 npm install -g @studyllm/resume-preview 与插件的 npx 启动方式暂时都不可用。GitHub 仓库 studyllm/resume-preview 已创建,请克隆源码后执行 npm install && npm run build, 再按下面的 .mcp.json 接入 MCP 客户端。

插件安装(推荐)

在 Claude Code 中输入 —— 下面两条是斜杠命令,不是 shell 命令。

/plugin marketplace add studyllm/resume-preview
/plugin install resume-preview@resume-preview

然后重启 Claude Code 以激活插件。

从源码安装

git clone https://github.com/studyllm/resume-preview.git
cd resume-preview
npm install && npm run build && npm install -g .

本地检出后,用这样一份 .mcp.json 接入 MCP 客户端:

{
  "mcpServers": {
    "resume-preview": {
      "command": "node",
      "args": ["build/index.js"]
    }
  }
}

验证安装

插件安装:MCP 服务会自动配置好,只需在 Claude Code 中运行 /mcp,确认服务列表里出现 resume-preview。

从源码安装:需要手动注册并核对:

claude mcp add --scope user resume-preview resume-preview
claude mcp list

你应当看到 resume-preview: resume-preview - ✓ Connected

💡 使用

直接开口要简历就行。装成插件后,内置的 resume 技能会把内容模型、"预览—迭代—导出"的工作流,以及该避开的坑都告诉 AI 客户端。

"帮我写一份后端工程师的简历并预览"      // 浏览器打开 A4 页面
"把自我评价写得更短、更具体一些"          // 同一个标签页原地刷新
"把简历导出成 PDF 到 ./docs/resume.pdf"  // 同一份简历的另一条出口

同一份简历的每次修改都复用同一个 resume_id:已打开的标签页会被刷新,而不是新开一个。不同简历用不同的 resume_id(比如每个目标岗位一份)。

内容模型

简历是一个 JSON 对象。只有 basics.name 是必填的 —— 其余板块你没写就直接从页面上省略:

{
  "basics": {
    "name": "张小明",
    "title": "高级后端工程师",
    "email": "zhang@example.com",
    "phone": "138-0000-0000",
    "location": "上海",
    "links": [{ "label": "GitHub", "url": "https://github.com/example" }]
  },
  "summary": "六年后端经验,专注于高并发服务与数据管道建设。",
  "experience": [
    {
      "company": "某某科技有限公司",
      "title": "高级后端工程师",
      "start": "2023.07",
      "end": "至今",
      "location": "上海",
      "highlights": [
        "主导订单系统重构,接口 P99 延迟从 800ms 降到 180ms",
        "搭建单元化发布流程,回滚时间从 20 分钟缩短到 2 分钟"
      ]
    }
  ],
  "projects": [
    {
      "name": "实时数据平台",
      "role": "技术负责人",
      "period": "2024.01 - 2024.09",
      "highlights": ["设计流式 ETL 链路,支撑日均 20 亿条事件"]
    }
  ],
  "education": [
    {
      "school": "某某大学",
      "degree": "计算机科学与技术 学士",
      "period": "2016.09 - 2020.06",
      "highlights": ["GPA 3.7 / 4.0"]
    }
  ],
  "skills": [
    { "category": "后端", "items": ["Go", "Java", "PostgreSQL", "Kafka"] },
    { "category": "基础设施", "items": ["Kubernetes", "Terraform"] }
  ],
  "extras": [{ "label": "证书", "items": ["PMP"] }]
}

content 参数既可以直接接受这个对象,也可以接受装着同样对象的 JSON 字符串。 start 和 end 是自由格式的字符串("2023.07"、"至今"),页面用一个短横线把它们连起来。

分节顺序与标题

分节的顺序是固定的:

自我评价 → 工作经历 → 项目经历 → 教育经历 → 专业技能 → 其他

内容里没有的板块会从页面上省略 —— 绝不会渲染出一个空板块。

标题跟随简历自身的 locale,而不是浏览器的:zh-CN 就是上面这些标题,en 则是 Summary → Experience → Projects → Education → Skills → Extras。导出的文档始终是你设定的那个语言,与谁打开它无关。

🔌 其他 MCP 客户端配置

这个服务是为 Claude Code 优化的,但任何兼容 MCP 的客户端都能用。

配置内容对所有客户端都是一样的 —— 把下面这段加进客户端的 MCP 配置文件:

客户端的 MCP 配置

{
  "mcpServers": {
    "resume-preview": {
      "command": "resume-preview"
    }
  }
}
  • Codex — ~/.codex/mcp_settings.json

  • Cursor — .cursor/mcp.json,或设置界面(Cmd/Ctrl + ,)→ MCP Servers

  • VSCode + Cline 插件 — 设置(Cmd/Ctrl + ,)→ 搜索 "Cline MCP" → MCP Settings JSON

  • Windsurf — macOS ~/Library/Application Support/Windsurf/mcp.json;Linux ~/.config/windsurf/mcp.json;Windows %APPDATA%\Windsurf\mcp.json

  • Gemini CLI — ~/.gemini/mcp.json

其余兼容 MCP 的客户端也用上面那份标准配置。

有两个客户端可以直接用命令行配置:

codex mcp add resume-preview resume-preview
gemini config mcp add resume-preview --command resume-preview

安装之后,resume-preview 命令应当已经在你的 PATH 里。

注意: 有些客户端要的是可执行文件的完整路径:

  • 查路径:which resume-preview(Unix/macOS)或 where resume-preview(Windows)

  • 在配置里用绝对路径:"command": "/path/to/resume-preview"

🎯 实时刷新

  1. 首次渲染: 在浏览器打开 http://localhost:3737/resume/<slug>

  2. 做出修改: AI 客户端更新内容,并用同一个 resume_id 调用 resume_preview

  3. 自动刷新: 浏览器通过 WebSocket 感知变化并重新加载

  4. 状态指示: 绿点 = 已连接,红点 = 正在重连

实时服务使用 3737-3747 端口,并自动挑一个可用端口。页面工具栏上还提供缩放、平移,以及直接下载 PDF / HTML 的按钮。

服务只绑定 127.0.0.1,且没有任何鉴权。简历含个人信息,绝不要把端口暴露到局域网或公网。

🖥️ 独立服务模式

用 --serve 参数可以不起 AI agent,只启动预览服务:

resume-preview --serve

它会在浏览器里打开简历画廊,列出此前渲染过的所有简历。画廊会显示每份简历的最后更新时间和文件大小,可以按 ID 搜索,也能删除不再需要的。

🛠️ 开发

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

# 开发监听模式
npm run dev

# 直接启动 MCP 服务
npm start

❓ 常见问题

简历存放在哪里? 在 ~/.config/resume-preview/resumes/<slug>/ 下 —— 目录名是由 resume_id 推导出的 slug,所以像 小王的简历 这样的中文 ID 会变成类似 r-3f9a2b 的东西。

支持哪些语言? 两种,而且彼此独立。页面框架 —— 画廊、工具栏、对话框 —— 跟随请求:?lang=en 优先,其次浏览器的 Accept-Language,最后 zh-CN。简历本身 —— 分节标题和导出的文档 —— 跟随你传给 resume_preview 的 locale,它与简历一起存储,默认 zh-CN。导出语言永远不依赖浏览器,所以同一份简历每次导出都一样。

内容支持 HTML 吗? 不支持,而且是刻意的。每个值都会被转义后按文本打印。写纯文本就好;内容里的标记会原样显示 —— 这是本产品最大的 XSS 面,它会一直关着。

还有别的模板或主题吗? 目前没有 —— default 是唯一实现的模板,也是唯一实现的主题。两者都是 src/constants.ts 里的白名单(RESUME_TEMPLATES / RESUME_THEMES),所以新增一个只需要扩展这两个列表并加上对应的资源文件。

📝 故障排查

服务连不上:

# 确认服务已安装
resume-preview -v

# 需要的话重装
npm install -g @studyllm/resume-preview

# 核对 MCP 配置
claude mcp list

权限不足报错:

# 确保可执行文件有执行权限
chmod +x $(which resume-preview)

端口被占用:

服务使用 3737-3747 端口,会自动找一个可用端口。看看是不是别的进程占着:

lsof -i :3737-3747

简历没渲染出来,或实时刷新不工作:

服务日志在 ~/.config/resume-preview/logs/ —— mcp.log 记录工具调用与简历渲染,web.log 记录 HTTP/WebSocket 连接与实时刷新。

日志级别由环境变量 CLAUDE_MERMAID_LOG_LEVEL 控制,可选 DEBUG、INFO(默认)、WARN、ERROR、OFF —— 变量名是历史遗留,保持不变。设成 DEBUG 可以看更细的日志:

tail -f ~/.config/resume-preview/logs/mcp.log
tail -f ~/.config/resume-preview/logs/web.log

报 Cannot find package 'puppeteer': 多半是安装时没带上 Chromium。重新 npm install -g @studyllm/resume-preview,或先在本机跑一次 npx puppeteer browsers install chrome 把浏览器下载下来。

🤝 参与贡献

欢迎贡献!请尽管提交 Pull Request。

🔗 相关链接

上游项目

本仓库从 claude-mermaid 改名而来,现在只专注简历。上游项目(claude-mermaid)在 Fronteir AI 上有托管部署。本仓库是改名后的 fork,不在它的服务范围内。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers