genome-mcp

Instructions

Implementation Reference

• src/genome_mcp/core/tools.py:499-549 (handler)

  MCP tool registration and handler for 'analyze_gene_evolution'. Performs input validation and calls the core internal implementation.
  @mcp.tool() async def analyze_gene_evolution( gene_symbol: str, target_species: list[str] = None, analysis_level: str = "Eukaryota", include_sequence_info: bool = True, ) -> EvolutionResult: """ 基因进化分析工具 - MCP接口包装 Args: gene_symbol: 基因符号（如 TP53, BRCA1） target_species: 目标物种列表（如 ["mouse", "rat", "zebrafish"]） analysis_level: 分析层级（如 Eukaryota, Metazoa, Vertebrata） include_sequence_info: 是否包含序列信息 Returns: 进化分析结果 Examples: # 分析 TP53 在哺乳动物中的进化 analyze_gene_evolution("TP53", ["human", "mouse", "rat", "dog"]) """ try: # 验证基因分析参数 ( validated_gene_symbol, validated_target_species, validated_analysis_level, ) = validate_gene_params( gene_symbol=gene_symbol, target_species=target_species, analysis_level=analysis_level, ) return await _analyze_gene_evolution_internal( validated_gene_symbol, validated_target_species, validated_analysis_level, include_sequence_info, _query_executor, ) except ValidationError as e: return format_simple_error( e, query=gene_symbol, operation="analyze_gene_evolution" ) except Exception as e: return format_simple_error( e, query=gene_symbol, operation="analyze_gene_evolution" )
• src/genome_mcp/core/evolution_tools.py:186-318 (handler)

  Core implementation executing the gene evolution analysis: queries orthologs, computes conservation scores, evolutionary insights, and phylogenetic distribution.
  async def analyze_gene_evolution( gene_symbol: str, target_species: list[str] = None, analysis_level: str = "Eukaryota", include_sequence_info: bool = True, query_executor: QueryExecutor = None, ) -> dict[str, Any]: """ 基因进化分析 - 分析基因在跨物种间的进化关系 功能包括： - 同源基因识别和检索 - 系统发育关系分析 - 物种分布统计 - 进化保守性评估 Args: gene_symbol: 基因符号（如 TP53, BRCA1） target_species: 目标物种列表（如 ["mouse", "rat", "zebrafish"]） analysis_level: 分析层级（如 Eukaryota, Metazoa, Vertebrata） include_sequence_info: 是否包含序列信息 query_executor: 查询执行器实例 Returns: 进化分析结果，包含同源基因信息、系统发育数据和统计信息 Examples: # 分析 TP53 在哺乳动物中的进化 analyze_gene_evolution("TP53", ["human", "mouse", "rat", "dog"]) # 分析基因在所有真核生物中的进化 analyze_gene_evolution("BRCA1", analysis_level="Eukaryota") """ if query_executor is None: query_executor = QueryExecutor() try: # 验证输入参数 if not gene_symbol or not gene_symbol.strip(): return { "error": "基因符号不能为空", "gene_symbol": gene_symbol, "error_type": "validation_error", "suggestions": ["提供有效的基因符号，如 TP53, BRCA1"], } gene_symbol = gene_symbol.strip() # 构建查询 if target_species: query = f"{gene_symbol} across species {' '.join(target_species)}" else: query = f"{gene_symbol} evolution conservation" # 执行同源基因查询 parsed = QueryParser._parse_ortholog(query) if target_species: parsed.params["target_species"] = target_species parsed.params["gene_symbol"] = gene_symbol result = await query_executor.execute(parsed) # 检查查询结果 if not result.get("success") and result.get("error"): return { "error": f"同源基因查询失败: {result.get('error', '未知错误')}", "gene_symbol": gene_symbol, "status": "service_unavailable", "message": "Ensembl API服务暂时不可用，无法进行同源基因分析", "suggestions": [ "稍后重试", "检查网络连接", "确认基因符号正确", "尝试使用其他基因符号（如大写格式）", ], "alternative_resources": [ { "name": "Ensembl Web界面", "url": f"https://www.ensembl.org/Homo_sapiens/Search?q={gene_symbol}", "description": "在Ensembl网站手动搜索基因", }, { "name": "NCBI Gene", "url": f"https://www.ncbi.nlm.nih.gov/gene?term={gene_symbol}", "description": "NCBI基因数据库", }, ], "debug_info": { "parsed_query": query, "query_params": parsed.params, "original_error": result.get("error"), }, } # 检查是否有同源基因数据 orthologs = result.get("result", {}).get("orthologs", []) if not orthologs: return { "error": f"未找到基因 '{gene_symbol}' 的同源基因", "gene_symbol": gene_symbol, "status": "no_orthologs_found", "message": "该基因可能不存在于Ensembl数据库中，或者没有同源基因记录", "suggestions": [ "检查基因符号拼写是否正确", "尝试使用该基因的其他名称或别名", "确认该基因在参考基因组中存在", ], "query_result": result, } # 添加进化分析信息 evolution_analysis = { "gene_symbol": gene_symbol, "analysis_level": analysis_level, "target_species": target_species, "include_sequence_info": include_sequence_info, "evolutionary_insights": _generate_evolutionary_insights(result), "conservation_score": _calculate_conservation_score(result), "phylogenetic_distribution": _analyze_phylogenetic_distribution(result), "data_quality": { "orthologs_count": len(orthologs), "species_count": len({o.get("organism_name") for o in orthologs}), "high_confidence_count": len( [o for o in orthologs if o.get("confidence") == "high"] ), }, } result["evolution_analysis"] = evolution_analysis result["success"] = True # 明确标记成功 return result
• src/genome_mcp/core/types.py:77-84 (schema)

  Type definition for the return type EvolutionResult of the analyze_gene_evolution tool.
  class EvolutionResult(TypedDict): """进化分析结果类型""" target_gene: str orthologs: list[dict[str, Any]] analysis_info: dict[str, Any] conservation_scores: dict[str, float] | None
• src/genome_mcp/core/evolution_tools.py:14-39 (helper)

  Helper function generating evolutionary insights (conservation level, functional constraints) based on ortholog count.
  def _generate_evolutionary_insights(result: dict[str, Any]) -> dict[str, Any]: """生成进化洞察""" insights = { "conservation_level": "unknown", "evolutionary_rate": "unknown", "functional_constraints": [], } # 基于同源基因数量评估保守性 orthologs_data = result.get("result", {}).get("orthologs", []) orthologs_count = len(orthologs_data) if orthologs_count > 100: insights["conservation_level"] = "highly_conserved" insights["functional_constraints"].append("Strong purifying selection") elif orthologs_count > 20: insights["conservation_level"] = "moderately_conserved" insights["functional_constraints"].append("Moderate functional constraints") else: insights["conservation_level"] = "lineage_specific" insights["functional_constraints"].append( "Potential lineage-specific adaptation" ) return insights
• src/genome_mcp/core/__init__.py:10-25 (registration)

  Re-export of analyze_gene_evolution from evolution_tools.py for module-level access.
  from .evolution_tools import analyze_gene_evolution, build_phylogenetic_profile from .query_executor import QueryExecutor from .query_parser import ParsedQuery, QueryParser, QueryType __all__ = [ # 客户端 "NCBIClient", "UniProtClient", "EnsemblClient", # 查询相关 "QueryParser", "QueryType", "ParsedQuery", "QueryExecutor", # 进化分析工具 "analyze_gene_evolution",