Constellation Composition MCP Server

Instructions

Implementation Reference

• src/constellation_composition_mcp/server.py:1404-1469 (handler)

  The 'generate_constellation_composition' tool handler function. It validates the constellation input, optionally fetches geometry data, performs the core deterministic composition mapping, and formats the output.

  async def generate_constellation_composition(params: ConstellationCompositionInput) -> str:
      """
      Generate detailed composition parameters mapped from a constellation's geometry and mythology.
      
      Translates astronomical star patterns into practical compositional guidance for image
      generation, including focal point placement, visual flow, balance characteristics,
      and thematic elements derived from constellation mythology.
      
      This uses a deterministic zero-LLM-cost approach for geometric translation,
      making it highly efficient for batch processing and consistent results.
      
      Args:
          params (ConstellationCompositionInput): Configuration including:
              - constellation_name: Name or abbreviation of constellation
              - canvas_width: Target canvas width in pixels (512-4096)
              - canvas_height: Target canvas height in pixels (512-4096)
              - include_mythology: Include mythological themes (boolean)
              - response_format: Output format (json or markdown)
      
      Returns:
          str: Structured composition parameters in requested format, including:
              - focal_points: List of primary visual anchors with positions and weights
              - visual_flow: Directional movement and rhythm patterns
              - balance: Visual balance type and center of mass
              - spatial_distribution: How elements spread across frame
              - mythology_themes: Key thematic elements from constellation story
              - suggested_elements: Concrete suggestions for subjects, lighting, atmosphere, colors
      """
      
      # Find constellation in database
      constellation_name = params.constellation_name
      if constellation_name not in CONSTELLATIONS:
          available = ', '.join(sorted(CONSTELLATIONS.keys()))
          return f"Error: Constellation '{constellation_name}' not found. Available constellations: {available}"
      
      metadata = CONSTELLATIONS[constellation_name]
      abbr = metadata['abbr']
      
      # Attempt to fetch real geometry data (optional enhancement)
      geometry_data = await fetch_constellation_data(abbr)
      
      # Generate composition parameters (deterministic, zero-LLM-cost)
      composition = map_constellation_to_composition(
          constellation_name=constellation_name,
          metadata=metadata,
          geometry_data=geometry_data,
          canvas_width=params.canvas_width,
          canvas_height=params.canvas_height,
          include_mythology=params.include_mythology
      )
      
      # Format response
      if params.response_format == ResponseFormat.JSON:
          result = {
              'constellation': constellation_name,
              'abbreviation': abbr,
              'canvas': {
                  'width': params.canvas_width,
                  'height': params.canvas_height
              },
              'composition': composition.model_dump()
          }
          return json.dumps(result, indent=2)
      else:
          return format_composition_markdown(constellation_name, metadata, composition)