Protein MCP Server

Instructions

Implementation Reference

• src/protein_mcp/tools.py:679-715 (handler)

  MCP tool handler for 'download_structure_tool'. Registers the tool with @mcp.tool() decorator and delegates execution to the download_structure helper function.
  @mcp.tool() async def download_structure_tool( pdb_id: str, file_format: str = "pdb", save_local: bool = False, ctx: Context | None = None, ) -> dict[str, Any]: """ 结构文件工具 - 下载和管理蛋白质结构文件 这个工具处理所有文件相关的操作，从下载到格式说明。 Args: pdb_id: PDB ID (例如: "5G53") file_format: 文件格式 - "pdb": 标准PDB格式 (推荐，人类可读) - "mmcif": 大分子晶体信息文件格式 (现代标准) - "cif": 晶体信息文件格式 - "mmtf": 大分子传输格式 (二进制，速度快) save_local: 是否保存到本地文件 (默认False返回内容) ctx: FastMCP Context，用于进度反馈和日志记录 Returns: 文件内容或下载信息 + 格式说明和使用指南 Examples: # 获取PDB文件内容 download_structure("1A3N") # 下载mmCIF格式并保存到本地 download_structure("2HHB", "mmcif", True) # 获取快速MMTF格式 download_structure("6VSB", "mmtf") """ return await download_structure(pdb_id, file_format, save_local, ctx)
• src/protein_mcp/tools.py:420-586 (helper)

  Core helper function implementing the download logic: validates PDB ID and format, downloads from RCSB, handles local save or content preview, provides format info, and formats MCP response.
  async def download_structure( pdb_id: str, file_format: str = "pdb", save_local: bool = False, ctx: Context | None = None ) -> dict[str, Any]: """ 结构文件工具 - 下载和管理蛋白质结构文件 这个工具处理所有文件相关的操作，从下载到格式说明。 Args: pdb_id: PDB ID (例如: "5G53") file_format: 文件格式 - "pdb": 标准PDB格式 (推荐，人类可读) - "mmcif": 大分子晶体信息文件格式 (现代标准) - "cif": 晶体信息文件格式 - "mmtf": 大分子传输格式 (二进制，速度快) save_local: 是否保存到本地文件 (默认False返回内容) ctx: FastMCP Context，用于进度反馈和日志记录 Returns: 文件内容或下载信息 + 格式说明和使用指南 """ try: if ctx: await ctx.info(f"📁 开始下载结构文件: {pdb_id}.{file_format}") await ctx.report_progress(0, 100, "初始化下载...") if not validate_pdb_id(pdb_id): return format_error_response( "无效的PDB ID格式", f"期望格式: 4位字符 (首位数字，后三位可数字可字母)，实际: {pdb_id}", ) # 验证PDB ID存在性 if not _validate_pdb_exists(pdb_id): if ctx: await ctx.error(f"❌ PDB ID {pdb_id} 不存在") return format_error_response("PDB ID不存在", f"PDB ID {pdb_id} 在RCSB数据库中未找到") # 验证文件格式 supported_formats = get_supported_formats() if file_format not in supported_formats: if ctx: await ctx.error(f"❌ 不支持的文件格式: {file_format}") return format_error_response( "不支持的文件格式", f"支持格式: {', '.join(supported_formats)}" ) # 构建下载URL download_url = f"{RCSB_DOWNLOAD_URL}/{pdb_id}.{file_format}" local_filename = f"{pdb_id}.{file_format}" if ctx: await ctx.report_progress(50, 100, f"下载 {file_format.upper()} 格式文件...") # 下载文件 if save_local: if ctx: await ctx.info(f"💾 保存到本地: {local_filename}") success = download_file(download_url, local_filename) if success: result_data = { "pdb_id": pdb_id, "file_format": file_format, "file_path": local_filename, "download_method": "saved_local", "file_size": None, # 可以添加文件大小信息 } if ctx: await ctx.info(f"✅ 文件保存成功: {local_filename}") else: if ctx: await ctx.error(f"❌ 文件下载失败: {local_filename}") return format_error_response( "文件下载失败", f"无法下载 {pdb_id}.{file_format} 文件" ) else: # 返回文件内容（对于小文件） try: if ctx: await ctx.info("🌐 从远程获取文件内容预览...") import requests response = requests.get(download_url, timeout=30) if response.status_code == 200: result_data = { "pdb_id": pdb_id, "file_format": file_format, "file_path": download_url, "download_method": "url_provided", "file_content": ( response.text[:1000] + "..." if len(response.text) > 1000 else response.text ), "content_preview": True, } if ctx: await ctx.info(f"✅ 文件内容获取成功 (预览: {len(response.text)} 字符)") else: if ctx: await ctx.error(f"❌ HTTP错误: {response.status_code}") return format_error_response( "文件下载失败", f"HTTP {response.status_code}: 无法访问文件" ) except Exception as e: if ctx: await ctx.error(f"❌ 网络错误: {str(e)}") return format_error_response("网络错误", f"下载失败: {str(e)}") # 添加格式信息 format_info = { "pdb": { "name": "Protein Data Bank (PDB) 格式", "description": "经典的文本格式，人类可读", "recommended": True, "use_case": "一般用途，化学演示，小分子结构", "advantages": ["人类可读", "广泛支持", "适合编辑"], }, "mmcif": { "name": "大分子晶体信息文件格式", "description": "现代的XML风格格式，更灵活", "recommended": True, "use_case": "复杂结构，大批量数据，现代软件", "advantages": ["更详细", "支持复杂数据", "现代标准"], }, "cif": { "name": "晶体信息文件格式", "description": "标准化格式， mmcif的简化版", "recommended": False, "use_case": "基本晶体学数据", "advantages": ["标准化", "简洁"], }, "mmtf": { "name": "大分子传输格式", "description": "二进制格式，压缩高效", "recommended": True, "use_case": "大批量传输，高性能应用", "advantages": ["文件小", "加载快", "压缩效率高"], }, } result_data["format_info"] = format_info.get( file_format, { "name": f"{file_format.upper()} 格式", "description": "支持的文件格式", "recommended": False, "use_case": "通用格式", "advantages": ["标准支持"], }, ) if ctx: await ctx.report_progress(100, 100, "完成") await ctx.info(f"✅ 成功获取 {pdb_id} 的 {file_format} 格式文件") return format_success_response( result_data, f"成功获取 {pdb_id} 的 {file_format} 格式文件。{format_info.get(file_format, {}).get('description', '')}", ) except Exception as e: if ctx: await ctx.error(f"❌ 文件操作失败: {str(e)}") return format_error_response("文件操作错误", f"download_structure 执行失败: {str(e)}")
• src/protein_mcp/server.py:17-18 (registration)

  Invocation of register_all_tools(mcp) in server creation, which defines and registers the download_structure_tool using @mcp.tool().
  # 注册所有工具 register_all_tools(mcp)
• src/protein_mcp/tools.py:588-715 (registration)

  The register_all_tools function where the download_structure_tool is defined and registered via @mcp.tool() decorator.
  def register_all_tools(mcp) -> None: """ 注册3个核心整合工具到FastMCP服务器 优化后的工具设计： 1. find_protein_structures - 蛋白质结构发现工具 2. get_protein_data - 蛋白质综合数据工具 3. download_structure - 结构文件工具 Args: mcp: FastMCP服务器实例 """ # 工具1: 蛋白质结构发现工具 - 整合搜索、示例、验证功能 @mcp.tool() async def find_protein_structures_tool( keywords: str | None = None, category: str | None = None, pdb_id: str | None = None, max_results: int = 10, ctx: Context | None = None, ) -> dict[str, Any]: """ 蛋白质结构发现工具 - 搜索、示例、验证的统一入口 这是蛋白质研究的起点，帮助你发现和验证PDB结构。 Args: keywords: 搜索关键词 (如: "hemoglobin", "kinase", "DNA") category: 预设类别 ("癌症靶点", "病毒蛋白", "酶类", "抗体", "膜蛋白", "核糖体") pdb_id: 直接验证或查看特定PDB ID (如: "1A3N") max_results: 搜索结果最大数量 (默认10，最大100) ctx: FastMCP Context，用于进度反馈和日志记录 Returns: 包含PDB结构列表、验证结果、示例数据的综合响应 Examples: # 搜索血红蛋白相关结构 find_protein_structures(keywords="hemoglobin") # 获取癌症靶点示例 find_protein_structures(category="癌症靶点") # 验证PDB ID find_protein_structures(pdb_id="1A3N") """ return await find_protein_structures(keywords, category, pdb_id, max_results, ctx) # 工具2: 蛋白质综合数据工具 - 一次获取所有蛋白质信息 @mcp.tool() async def get_protein_data_tool( pdb_id: str, data_types: list[str] | None = None, chain_id: str | None = None, ctx: Context | None = None, ) -> dict[str, Any]: """ 蛋白质综合数据工具 - 获取完整蛋白质信息包 这个工具是蛋白质数据获取的核心，一次性获取你需要的所有信息。 Args: pdb_id: PDB ID (例如: "5G53") data_types: 需要的数据类型列表 - "basic": 基本信息 (标题、方法、分辨率等) - "sequence": 氨基酸序列信息 - "structure": 二级结构分析 - "all": 获取所有数据 chain_id: 特定链ID (例如: "A"，可选) ctx: FastMCP Context，用于进度反馈和日志记录 Returns: 完整的蛋白质数据包，包含请求的所有数据类型 Examples: # 获取所有数据 get_protein_data("5G53", ["all"]) # 只获取基本信息和序列 get_protein_data("1A3N", ["basic", "sequence"]) # 获取特定链的数据 get_protein_data("2HHB", ["all"], "A") """ # 如果没有指定数据类型，默认获取基本数据 if data_types is None: data_types = ["basic", "sequence", "structure"] return await get_protein_data(pdb_id, data_types, chain_id, ctx) # 工具3: 结构文件工具 - 下载和管理蛋白质结构文件 @mcp.tool() async def download_structure_tool( pdb_id: str, file_format: str = "pdb", save_local: bool = False, ctx: Context | None = None, ) -> dict[str, Any]: """ 结构文件工具 - 下载和管理蛋白质结构文件 这个工具处理所有文件相关的操作，从下载到格式说明。 Args: pdb_id: PDB ID (例如: "5G53") file_format: 文件格式 - "pdb": 标准PDB格式 (推荐，人类可读) - "mmcif": 大分子晶体信息文件格式 (现代标准) - "cif": 晶体信息文件格式 - "mmtf": 大分子传输格式 (二进制，速度快) save_local: 是否保存到本地文件 (默认False返回内容) ctx: FastMCP Context，用于进度反馈和日志记录 Returns: 文件内容或下载信息 + 格式说明和使用指南 Examples: # 获取PDB文件内容 download_structure("1A3N") # 下载mmCIF格式并保存到本地 download_structure("2HHB", "mmcif", True) # 获取快速MMTF格式 download_structure("6VSB", "mmtf") """ return await download_structure(pdb_id, file_format, save_local, ctx)