Constellation Composition MCP Server

Instructions

Implementation Reference

• src/constellation_composition_mcp/server.py:1319-1392 (handler)

  The handler function `search_constellations` iterates through the `CONSTELLATIONS` dictionary, applying filters for query, shape, and brightness to return matching constellation metadata.

  @mcp.tool(
      name="search_constellations",
      annotations={
          "title": "Search Constellations by Theme or Characteristics",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": False
      }
  )
  async def search_constellations(params: ConstellationSearchInput) -> str:
      """
      Search for constellations by name, theme, visual characteristics, or shape.
      
      Useful for discovering which constellations match specific compositional needs
      or thematic requirements. Returns constellation details including mythology,
      visual characteristics, and shape patterns.
      
      Args:
          params (ConstellationSearchInput): Search parameters including:
              - query: Text search for name/theme/characteristic
              - shape_type: Filter by geometric shape
              - brightness: Filter by brightness pattern
              - response_format: Output format (markdown or json)
      
      Returns:
          str: List of matching constellations with their characteristics
      """
      
      results = []
      
      for name, data in CONSTELLATIONS.items():
          match = True
          
          # Text query matching
          if params.query:
              query_lower = params.query.lower()
              searchable = f"{name} {data.get('story', '')} {data.get('theme', '')} {data.get('visual_character', '')}".lower()
              if query_lower not in searchable:
                  match = False
          
          # Shape filter
          if params.shape_type and match:
              shape = data.get('shape', '')
              if params.shape_type.lower() not in shape.lower():
                  match = False
          
          # Brightness filter
          if params.brightness and match:
              brightness = data.get('brightness_profile', '')
              if params.brightness.lower() not in brightness.lower():
                  match = False
          
          if match:
              result = {
                  'name': name,
                  'abbr': data.get('abbr'),
                  'story': data.get('story'),
                  'theme': data.get('theme'),
                  'visual_character': data.get('visual_character'),
                  'shape': data.get('shape'),
                  'brightness_profile': data.get('brightness_profile'),
                  'star_count': data.get('star_count_visual')
              }
              results.append(result)
      
      if not results:
          return "No constellations found matching your criteria. Try broader search terms."
      
      if params.response_format == ResponseFormat.JSON:
          return json.dumps({'constellations': results, 'count': len(results)}, indent=2)
      else:
          return format_search_results_markdown(results)