genome-mcp

Instructions

Implementation Reference

• src/genome_mcp/core/tools.py:427-498 (handler)

  Core handler implementation for the 'smart_search' tool. Handles natural language queries, applies validation, filters, parsing, and execution via QueryExecutor. Adds smart_search_info to results.

  @mcp.tool()
  async def smart_search(
      description: str,
      context: str = "genomics",
      filters: dict[str, Any] = None,
      max_results: int = 20,
  ) -> SearchResult:
      """
      智能语义搜索 - 理解自然语言描述并执行相应查询
  
      语义理解示例：
      - "breast cancer genes on chromosome 17" → 查找17号染色体上的乳腺癌基因
      - "TP53 protein interactions" → 查找TP53蛋白相互作用
      - "tumor suppressor genes" → 查找肿瘤抑制基因
      - "genes related to DNA repair" → 查找DNA修复相关基因
  
      Args:
          description: 自然语言描述
          context: 搜索上下文（genomics/proteomics/pathway）
          filters: 过滤条件
          max_results: 最大结果数
  
      Returns:
          智能搜索结果
  
      Examples:
          smart_search("breast cancer genes on chromosome 17")
          smart_search("TP53 protein interactions", context="proteomics")
          smart_search("DNA repair genes", filters={"species": "human"})
      """
      try:
          # 验证搜索参数
          validated_description, validated_context, validated_max_results = (
              validate_search_params(
                  description=description, context=context, max_results=max_results
              )
          )
  
          # 智能解析查询意图
          query = _apply_filters(validated_description, filters)
  
          # 根据上下文调整查询
          if validated_context == "proteomics":
              query_type = "protein"
          elif validated_context == "pathway":
              query_type = "search"
          else:
              query_type = "auto"
  
          # 解析查询意图
          parsed = QueryParser.parse(query, query_type)
  
          # 执行查询（直接使用查询执行器，避免MCP工具间调用）
          result = await _query_executor.execute(
              parsed, max_results=validated_max_results
          )
  
          # 添加智能解析信息
          result["smart_search_info"] = {
              "description": validated_description,
              "context": validated_context,
              "parsed_query": query,
              "filters_applied": filters is not None,
          }
  
          return result
  
      except ValidationError as e:
          return format_simple_error(e, query=description, operation="smart_search")
      except Exception as e:
          return format_simple_error(e, query=description, operation="smart_search")

• src/genome_mcp/core/validation.py:184-217 (schema)

  Input schema validation function specifically for smart_search parameters: description (required str), context (genomics/proteomics/pathway), max_results (1-50).

  def validate_search_params(
      description: str, context: str = "genomics", max_results: int = 20
  ) -> tuple[str, str, int]:
      """
      验证搜索参数
  
      Args:
          description: 搜索描述
          context: 搜索上下文
          max_results: 最大结果数
  
      Returns:
          验证后的参数元组
  
      Raises:
          ValidationError: 搜索描述验证失败
      """
      if not description or not description.strip():
          raise ValidationError("Search description cannot be empty")
  
      description = description.strip()
  
      # 验证context
      valid_contexts = {"genomics", "proteomics", "pathway"}
      if context not in valid_contexts:
          context = "genomics"
  
      # 验证max_results
      if not isinstance(max_results, int) or max_results < 1:
          max_results = 20
      elif max_results > 50:
          max_results = 50
  
      return description, context, max_results

• src/genome_mcp/core/types.py:42-49 (schema)

  Output type definition (TypedDict) for smart_search results, including query, results list, total_count, and metadata.

  class SearchResult(TypedDict):
      """搜索结果类型"""
  
      query: str
      results: list[dict[str, Any]]
      total_count: int
      search_metadata: dict[str, Any]

• src/genome_mcp/main.py:34-41 (registration)

  Registration point where create_mcp_tools(mcp) is called, which defines and registers the smart_search tool using FastMCP's @mcp.tool() decorator.

  from .core.tools import create_mcp_resources, create_mcp_tools
  
  # 创建MCP实例
  mcp = FastMCP("Genome MCP", version="0.2.5")
  
  # 注册所有资源和工具
  create_mcp_resources(mcp)
  create_mcp_tools(mcp)