基于MCP协议构建简历查询API：让AI精准读取非结构化文档

1. 项目概述：当AI能读懂你的简历

最近在折腾AI Agent开发的朋友，可能都绕不开一个核心痛点：如何让AI真正理解并高效利用我们手头那些非结构化的文档数据？比如，一份精心打磨的PDF简历。我们常常希望AI助手能像一位专业的HR一样，快速从简历中提取关键信息，回答诸如“候选人上一份工作的起止时间是？”、“他主导过哪些项目？”这类具体问题。传统的做法，要么是把PDF全文扔给大模型，消耗大量上下文窗口和Token，回答还不一定精准；要么是手动把信息整理成结构化数据，费时费力。

这个项目要解决的，正是这个痛点。它的核心思路是：将一份静态的PDF简历，转化成一个动态的、可查询的“数据服务”，并通过MCP（Model Context Protocol）协议，让各类AI Agent（比如Claude Code、Cursor等）能够像调用一个函数或查询一个数据库那样，按需、精准地从你的简历中获取信息。

简单来说，这就像为你的简历搭建了一个专属的API。AI Agent不需要再去“阅读理解”整个PDF文件，它只需要向这个“简历API”发送一个查询请求，比如“get_work_experience”，就能立刻获得结构化的、清洗过的工作经历列表。这极大地提升了信息检索的效率和准确性，也让AI Agent的能力变得更加模块化和实用。

对于开发者、求职者，或是任何需要频繁向AI提供个人背景信息的人来说，这个项目提供了一个非常优雅的解决方案。它不仅仅是“PDF解析”，更是“PDF服务化”。下面，我就来详细拆解一下我是如何实现这个过程的，其中涉及的思路、技术选型、踩过的坑，都会毫无保留地分享出来。

2. 核心思路与技术选型：为什么是MCP？

在动手之前，明确技术路线至关重要。市面上处理PDF和对接AI的方案很多，我选择MCP协议作为核心桥梁，是经过一番考量的。

2.1 为什么选择MCP协议？

首先，我们需要理解MCP是什么。MCP，即模型上下文协议，是由Anthropic提出的一种开放协议。它的目标是为AI模型（尤其是大语言模型）提供一个标准化的方式来发现、调用外部工具和数据源。你可以把它想象成AI世界的“USB协议”或“插件系统标准”。

对于本项目而言，MCP带来了几个关键优势：

1. 标准化与兼容性：MCP正在成为AI Agent生态中的一个重要标准。通过将简历数据封装成MCP Server，你的“简历查询服务”可以无缝接入任何支持MCP协议的客户端，如Claude Desktop、Cursor、Windsurf等。这意味着你构建一次，就可以多处使用。
2. 结构化工具定义：MCP要求Server明确定义它提供哪些“工具”（Tools）。在我们的场景下，一个工具就是一个查询能力，例如get_basic_info、query_skills_by_keyword、list_all_projects。这种设计迫使我们将模糊的“读取简历”需求，拆解成一系列清晰、具体的原子操作，这本身就是对业务逻辑的很好梳理。
3. 上下文感知与安全：MCP协议下，AI Agent（客户端）是发起请求的一方，它知道自己需要什么，然后通过协议调用Server。Server只负责执行具体的工具并返回结果，不涉及AI的推理过程。这种职责分离更清晰，也避免了将整个PDF文本塞进提示词（Prompt）所带来的上下文浪费和潜在的信息泄露风险。

2.2 PDF解析方案选型

PDF解析是底层的基础。我们的目标是从PDF中准确提取文本、位置和可能的表格信息。我评估了几个主流方案：

• PyPDF2 / pdfminer：老牌、轻量，但对复杂排版和现代PDF格式的支持有时会力不从心，提取的文本顺序可能错乱。
• pdfplumber：在pdfminer基础上做了大量优化，特别擅长保留文本的位置（坐标）信息，对于有栏位结构的简历（比如两栏式）解析效果更好，能较好地还原视觉上的阅读顺序。
• AWS Textract / Google Document AI：云服务，OCR和表单识别能力极强，能处理扫描件，但会产生费用，且依赖网络。
• LayoutParser + 深度学习模型：学术前沿方案，能进行非常精细的版面分析（识别标题、段落、列表等），但环境配置复杂，运行开销大。

我的选择是 pdfplumber。原因在于：对于绝大多数数字生成的简历（非扫描件），pdfplumber在准确性和易用性上取得了很好的平衡。它提供的字符级坐标信息，为我们后续可能需要的“智能字段定位”（比如即使简历模板变了，也能找到“工作经历”这个章节）留下了扩展空间。同时，它是一个纯Python库，离线可用，部署简单。

2.3 文本向量化与语义检索（可选进阶）

基础的解析完成后，我们得到的是纯文本。但AI Agent的查询可能是模糊的、语义化的。例如，“找出所有和机器学习相关的经历”。单纯的关键词匹配（如搜索“机器学习”）可能会漏掉“ML”、“AI模型开发”等表述。

因此，一个进阶的架构是引入嵌入模型（Embedding Model）和向量数据库。我们可以将简历文本按段落或句子切分，转换成向量，存入如ChromaDB、FAISS或Qdrant中。当收到语义查询时，先将查询语句转换成向量，然后在向量数据库中进行相似度搜索，找到最相关的文本片段，再返回给AI Agent。

这是一个“增强模式”。对于初版，我们可以先实现基于规则和关键词的精确工具（如get_skill_list）。在后续迭代中，可以增加一个semantic_search工具，内部调用向量检索来应对开放性问题。我建议分阶段实施，先让核心流程跑通。

2.4 整体架构图（概念性）

基于以上选择，项目的核心架构变得清晰：

[PDF简历文件] -> [pdfplumber解析] -> [结构化信息提取/文本清洗] -> [MCP Server封装] | [可选：向量化索引] -> [向量数据库] | [AI Agent (Claude, Cursor)] <--[MCP协议通信]--> [简历MCP Server] <--[查询]-- [用户/Agent]

Server内部维护着解析后的简历数据（或向量索引），并对外暴露几个定义好的工具函数。AI Agent通过MCP协议调用这些工具。

3. 实战构建：从零搭建简历MCP Server

理论说完了，我们开始动手。我将以一份假设的、格式相对规范的Markdown风格简历（导出为PDF）为例，演示全流程。

3.1 环境准备与依赖安装

首先创建一个新的项目目录，并设置Python虚拟环境（强烈推荐，避免依赖冲突）。

mkdir resume-mcp-server && cd resume-mcp-server python -m venv venv # Windows: venv\Scripts\activate # Mac/Linux: source venv/bin/activate

安装核心依赖：

pip install mcp pdfplumber pydantic # 如果考虑后续向量检索，可以一并安装： # pip install sentence-transformers chromadb

• mcp：Anthropic官方提供的MCP协议Python SDK，用于快速构建Server和Client。
• pdfplumber：我们的PDF解析引擎。
• pydantic：用于数据验证和设置管理，定义工具的参数和返回类型会非常方便。

3.2 PDF解析与信息提取层

我们创建一个pdf_parser.py文件，负责最底层的解析工作。

import pdfplumber import re from typing import Dict, List, Optional, Any class ResumeParser: def __init__(self, pdf_path: str): self.pdf_path = pdf_path self.text = "" self.sections = {} # 用于存储按章节划分的内容 self._raw_pages = [] def extract_text(self): """提取PDF中的所有文本，并尝试按章节进行初步划分""" all_text = [] with pdfplumber.open(self.pdf_path) as pdf: for page in pdf.pages: # 提取页面文本，并保留一些布局线索（如‘\n’） page_text = page.extract_text(layout=True) if page_text: all_text.append(page_text) self._raw_pages.append(page) self.text = "\n".join(all_text) return self.text def identify_sections(self): """一个简单的基于规则和关键词的章节识别方法。 实际应用中，这里可以做得非常复杂，比如利用字体大小、位置信息(pdfplumber提供坐标)。 """ lines = self.text.split('\n') current_section = "Header" section_content = [] # 定义可能的关键词（可根据实际简历调整） section_keywords = { "education": ["教育背景", "学历", "EDUCATION"], "experience": ["工作经历", "工作经验", "EXPERIENCE"], "skills": ["专业技能", "技术栈", "SKILLS"], "projects": ["项目经历", "PROJECTS"], "contact": ["联系方式", "CONTACT"] } for line in lines: line_stripped = line.strip() if not line_stripped: continue # 检查该行是否是新的章节标题 is_section_header = False for sec_name, keywords in section_keywords.items(): for kw in keywords: # 简单匹配：行内容以关键词开头或包含关键词且较短 if line_stripped.startswith(kw) or (kw in line_stripped and len(line_stripped) < 50): # 保存上一个章节的内容 if current_section and section_content: self.sections[current_section] = '\n'.join(section_content).strip() # 开始新章节 current_section = sec_name section_content = [] is_section_header = True break if is_section_header: break if not is_section_header: section_content.append(line_stripped) # 保存最后一个章节 if current_section and section_content: self.sections[current_section] = '\n'.join(section_content).strip() return self.sections def get_basic_info(self) -> Dict[str, str]: """从Header或全文提取基本信息：姓名、电话、邮箱等""" # 这是一个非常简单的正则示例，实际需要更健壮的规则 email_pattern = r'[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}' phone_pattern = r'1[3-9]\d{9}' # 简单匹配中国大陆手机号 # 可以从self.sections[“Header”]或self.text的前几行提取姓名（通常是最醒目的一行） name = “” header_text = self.sections.get(“Header”, self.text[:500]) # 取头部文本 # 假设姓名是Header中非空的第一行（简化逻辑） lines = header_text.split(‘\n’) for line in lines: if line.strip() and len(line.strip()) < 20: # 姓名通常不会太长 name = line.strip() break emails = re.findall(email_pattern, self.text) phones = re.findall(phone_pattern, self.text) return { “name”: name, “email”: emails[0] if emails else “”, “phone”: phones[0] if phones else “”, “raw_header”: header_text[:200] # 返回部分原始文本供参考 } # 示例用法 if __name__ == “__main__”: parser = ResumeParser(“./my_resume.pdf”) parser.extract_text() sections = parser.identify_sections() print(“识别出的章节：”, list(sections.keys())) basic_info = parser.get_basic_info() print(“基本信息：”, basic_info)

注意：identify_sections函数是一个非常基础的基于规则的实现。对于格式千变万化的简历，这可能是最脆弱的部分。在生产环境中，你需要根据你的简历模板定制规则，或者考虑使用更高级的NLP模型（如NER命名实体识别）或基于视觉的版面分析来提升鲁棒性。这里提供的是一个起点。

3.3 构建MCP Server

这是项目的核心。我们创建mcp_server.py文件。我们将使用mcpSDK 的Server类。

import asyncio from mcp import Server, types from pdf_parser import ResumeParser from pydantic import BaseModel, Field from typing import List # 定义工具的参数模型（Pydantic Model） class QuerySkillsArgs(BaseModel): keyword: str = Field(description=“用于筛选技能的关键词，例如 ‘Python’， ‘数据库’。”) class QueryExperienceArgs(BaseModel): company_keyword: str = Field(default=“”, description=“按公司名称关键词过滤工作经历。”) limit: int = Field(default=5, description=“返回经历的最大条数。”) # 初始化我们的简历解析器（假设简历路径固定或通过环境变量配置） RESUME_PATH = “./my_resume.pdf” parser = ResumeParser(RESUME_PATH) parser.extract_text() parser.identify_sections() # 预先解析好 # 创建MCP Server实例 server = Server(“resume-mcp-server”) # 注册工具：获取基本信息 @server.list_tools() async def handle_list_tools() -> List[types.Tool]: “”“声明本Server提供的所有工具。”“” return [ types.Tool( name=“get_basic_info”, description=“获取简历中的个人基本信息，包括姓名、邮箱、电话等。”, inputSchema={ “type”: “object”, “properties”: {}, # 此工具无需参数 }, ), types.Tool( name=“get_skills”, description=“获取简历中列出的所有技能列表。”, inputSchema={ “type”: “object”, “properties”: {}, }, ), types.Tool( name=“query_skills”, description=“根据关键词查询相关的技能。”, inputSchema=QuerySkillsArgs.schema(), ), types.Tool( name=“get_work_experience”, description=“获取详细的工作经历列表。”, inputSchema=QueryExperienceArgs.schema(), ), ] # 实现工具：获取基本信息 @server.call_tool() async def handle_call_tool(name: str, arguments: dict) -> List[types.TextContent]: “”“根据工具名和参数执行具体的工具逻辑。”“” if name == “get_basic_info”: info = parser.get_basic_info() result_text = f”””姓名：{info[‘name’]} 邮箱：{info[‘email’]} 电话：{info[‘phone’]} “”” return [types.TextContent(type=“text”, text=result_text)] elif name == “get_skills”: skills_section = parser.sections.get(“skills”, “”) # 简单按逗号、分号或换行分割技能（需根据简历实际格式调整） import re skill_list = re.split(r‘[,，；;\n]\s*’, skills_section) skill_list = [s.strip() for s in skill_list if s.strip()] result_text = “专业技能列表：\n” + “\n”.join(f”- {skill}” for skill in skill_list) return [types.TextContent(type=“text”, text=result_text)] elif name == “query_skills”: args = QuerySkillsArgs(**arguments) skills_section = parser.sections.get(“skills”, “”) import re skill_list = re.split(r‘[,，；;\n]\s*’, skills_section) filtered_skills = [s.strip() for s in skill_list if args.keyword in s] result_text = f”包含 ‘{args.keyword}’ 的技能：\n” + “\n”.join(f”- {skill}” for skill in filtered_skills) if filtered_skills else f”未找到包含 ‘{args.keyword}’ 的技能。” return [types.TextContent(type=“text”, text=result_text)] elif name == “get_work_experience”: args = QueryExperienceArgs(**arguments) exp_section = parser.sections.get(“experience”, “”) # 这里需要更复杂的解析来分割每一段经历，例如按时间或公司分割。 # 此处为演示，简单按空行分割。 experiences = [exp.strip() for exp in exp_section.split(‘\n\n’) if exp.strip()] if args.company_keyword: experiences = [exp for exp in experiences if args.company_keyword in exp] experiences = experiences[:args.limit] result_text = “工作经历：\n” + “\n”.join(f”{i+1}. {exp}” for i, exp in enumerate(experiences)) return [types.TextContent(type=“text”, text=result_text)] else: raise ValueError(f”未知的工具：{name}”) async def main(): # 启动Server，使用stdio传输（这是与MCP客户端通信的标准方式） async with server.run_stdio() as (read_stream, write_stream): await asyncio.gather( server.run(read_stream, write_stream), # 这里可以添加其他异步任务 ) if __name__ == “__main__”: asyncio.run(main())

这个Server通过标准输入输出（stdio）与客户端通信。它定义了四个工具，并实现了对应的处理函数。当AI Agent（客户端）调用query_skills工具并传入{“keyword”: “Python”}时，Server就会在解析出的技能章节中搜索包含“Python”的项并返回。

3.4 配置AI客户端（以Claude Desktop为例）

要让Claude Desktop能连接到我们的Server，需要创建一个配置文件。

1. 找到Claude Desktop的配置目录：

   • macOS:~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows:%APPDATA%\Claude\claude_desktop_config.json

2. 编辑（或创建）claude_desktop_config.json： 如果文件不存在，就新建一个。如果存在，在”mcpServers”字段中添加我们的Server配置。

{ “mcpServers”: { “resume-server”: { “command”: “python”, “args”: [“/ABSOLUTE/PATH/TO/YOUR/resume-mcp-server/mcp_server.py”], “env”: { “PYTHONPATH”: “/ABSOLUTE/PATH/TO/YOUR/resume-mcp-server” } } } }

关键点：

• command：必须是python。
• args：必须提供你mcp_server.py文件的绝对路径。
• env：设置PYTHONPATH确保Python能找到你的pdf_parser等模块。同样使用绝对路径。
• 配置完成后，重启Claude Desktop。

3. 验证连接： 重启后，在Claude Desktop的聊天框中，你应该能看到一个“螺丝刀”或“工具”图标。点击它，如果能看到get_basic_info、get_skills等工具列表，就说明连接成功了！你可以直接在聊天中让Claude调用这些工具，例如：“请调用get_basic_info工具看看我的基本信息。”

4. 避坑指南与进阶优化

在实际搭建和运行过程中，我遇到了不少问题，这里总结一下，希望能帮你绕开这些坑。

4.1 PDF解析的准确性问题

• 问题：解析出的文本顺序混乱，特别是对于多栏排版、带有图标和表格的简历。
• 解决：
  1. 优先使用pdfplumber的layout=True参数：它能更好地保持文本的视觉顺序。
  2. 利用坐标信息：pdfplumber可以提取每个字符的(x0, top, x1, bottom)坐标。对于复杂的版面，你可以编写算法，根据坐标将文本块重新排序（例如，先按top坐标排序行，再按x0坐标排序行内字符）。
  3. 表格处理：pdfplumber的.extract_tables()方法对简单的表格识别效果不错。对于复杂表格，可能需要结合camelot或tabula-py库。
  4. 备用方案：如果格式过于复杂，可以考虑先将PDF转换为高分辨率图片，再使用OCR（如Tesseract）。但这是最后的手段，因为会损失文本的样式和结构信息。

4.2 MCP Server连接失败

• 问题：Claude Desktop无法识别工具，或提示连接错误。
• 排查步骤：
  1. 检查配置文件路径：args和env中的路径必须是绝对路径，不能使用~或相对路径。
  2. 检查Python环境：确保配置中指定的python命令与你安装依赖的虚拟环境中的是同一个。最稳妥的方式是使用虚拟环境Python解释器的绝对路径作为command。
  3. 检查依赖：确保mcp,pdfplumber等库已安装在Server运行的环境中。
  4. 查看日志：Claude Desktop通常会在其日志文件中输出MCP连接的错误信息。在macOS上，日志可能在~/Library/Logs/Claude/下。通过日志可以定位是协议错误、导入错误还是执行错误。
  5. 手动测试Server：可以先在终端直接运行python mcp_server.py，看是否有明显的Python错误。

4.3 工具设计与Agent体验

• 问题：工具不好用，AI Agent不知道什么时候调用，或者调用后结果不理想。
• 优化建议：
  1. 工具描述要清晰：description字段至关重要。清晰说明工具的用途、输入参数的意义。例如，query_skills的描述可以写“根据关键词在技能列表中模糊匹配”。
  2. 设计原子化工具：不要设计一个“获取所有信息”的巨无霸工具。而是拆分成get_contact、get_education、get_experience_at_company等小工具。这样AI更容易理解和调用。
  3. 返回结构化数据：虽然MCP工具返回的是TextContent，但我们可以返回格式良好的文本，如JSON字符串或Markdown列表。这有助于AI进一步处理。例如，get_work_experience可以返回每个经历的“公司”、“职位”、“时间”、“描述”字段。
  4. 提供示例：在工具描述中，可以加入示例输入。虽然MCP协议本身不支持，但可以在描述文本里写，例如“例如，参数可以是{“keyword”: “Python”}”。

4.4 性能与扩展性

• 问题：每次查询都重新解析PDF，速度慢。
• 解决：在Server初始化时（__init__或启动时）就解析好PDF，将结构化的数据（如sections字典、向量索引）保存在内存中。工具函数直接查询这些内存数据，速度极快。
• 进阶扩展：
  • 多简历支持：可以修改Server，使其能加载指定路径的PDF。甚至可以将工具设计为load_resume和query_current_resume的组合。
  • 向量语义检索：如前所述，集成sentence-transformers和chromadb。在Server启动时，将简历文本分块向量化并存入内存数据库。新增一个semantic_search工具，接收自然语言查询，返回最相关的文本片段。
  • 缓存机制：对于频繁的相同查询，可以添加一个简单的内存缓存（如functools.lru_cache）。

5. 实际应用场景与效果

搭建好这个系统后，我将其应用到了几个实际场景中，效果提升非常明显。

场景一：AI辅助求职沟通在准备面试或撰写求职信时，我直接对Claude说：“根据我的简历，帮我起草一封针对[某公司]后端开发岗位的求职信，突出我的Java和微服务经验。” Claude会先调用get_skills和get_work_experience工具，获取到结构化的技能和项目列表，然后生成的信件就能非常具体地引用我简历中的真实项目和技术栈，而不是凭空编造。

场景二：快速生成个人简介在需要不同长度、不同侧重点的个人简介时（如社交媒体、技术社区、会议演讲），我只需给AI一个指令：“用200字总结我的技术背景，侧重云计算。” AI通过工具查询，能快速抓取到“AWS”、“Docker”、“Kubernetes”等相关技能和经历，组合成一段准确的描述。

场景三：信息核对与提取“我2022年在上一家公司主导的项目叫什么名字？”这类需要精确记忆的问题，AI通过调用工作经历查询工具，能立刻给出答案，避免了手动翻找PDF的麻烦。

效果对比：

• 传统方式：打开PDF，肉眼查找，复制粘贴。容易遗漏，格式错乱，效率低下。
• MCP Server方式：AI在几秒内通过标准化接口获取精准信息，并可直接用于后续的文本生成、分析或决策。整个过程自动化、可编程。

这个项目的价值不仅在于“查简历”，更在于它展示了一种范式：如何将任何有价值的私有文档（论文、手册、报告、笔记）转化为AI可实时、精准调用的知识源。通过MCP协议，我们为自己的数据世界和AI能力之间架起了一座高效、标准的桥梁。你可以举一反三，构建你的“论文查询MCP”、“公司制度问答MCP”、“个人知识库MCP”。