genome-mcp

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

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

  MCP tool handler for 'analyze_gene_evolution'. Decorated with @mcp.tool(), validates inputs using validate_gene_params, and delegates to the internal _analyze_gene_evolution_internal function. Includes schema via type hints and docstring.
  @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-347 (helper)

  Core helper implementation performing the actual gene evolution analysis: queries orthologs via Ensembl, generates evolutionary insights, calculates conservation scores, analyzes phylogenetic distribution, and handles errors.
  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 except Exception as e: import traceback error_trace = traceback.format_exc() return { "error": f"基因进化分析异常: {str(e)}", "gene_symbol": gene_symbol, "error_type": "gene_evolution_error", "suggestions": [ "检查基因符号是否正确", "确认网络连接正常", "稍后重试", "联系技术支持", ], "troubleshooting": { "target_species": target_species, "analysis_level": analysis_level, "possible_causes": [ "基因符号不存在", "Ensembl API不可用", "网络连接问题", "服务器内部错误", ], "error_trace": error_trace, }, }
• src/genome_mcp/core/tools.py:14-14 (registration)

  Import of the internal analyze_gene_evolution function aliased as _analyze_gene_evolution_internal, used by the MCP handler.
  from .evolution_tools import analyze_gene_evolution as _analyze_gene_evolution_internal
• src/genome_mcp/core/tools.py:500-505 (schema)

  Function signature defining the input schema (parameters with types and defaults) and output type (EvolutionResult) for the 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: