Skip to main content
Glama
Sign In
Constellation Composition MCP Server

Constellation Composition MCP Server

by dmarsters
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Constellation Composition MCP Server

MCP server that translates astronomical constellation patterns into compositional parameters for AI image generation.

Features

  • 22 major constellations with geometric and mythological metadata

  • Zero-LLM-cost deterministic mapping from star patterns to focal points

  • Mythology integration for thematic guidance

  • Multiple output formats (JSON and Markdown)

  • Canvas scaling from 512x512 to 4096x4096 pixels

Related MCP server: Astro MCP Server

Installation

pip install -e ".[dev]"

Usage

As MCP Server

Add to Claude Desktop configuration:

{
  "mcpServers": {
    "constellation-composition": {
      "command": "constellation-composition-mcp"
    }
  }
}

Programmatically

from constellation_composition_mcp.server import (
    generate_constellation_composition,
    search_constellations
)

# Search for constellations
results = await search_constellations(query="hunting")

# Generate composition
composition = await generate_constellation_composition(
    constellation_name="Orion",
    canvas_width=1920,
    canvas_height=1080
)

Available Tools

  1. search_constellations - Search by theme, shape, or brightness

  2. generate_constellation_composition - Map constellation to composition parameters

  3. list_all_constellations - Browse all available constellations

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
./tests/run_tests.sh

# Format code
black src/ tests/
ruff check src/ tests/

Documentation

See docs/ directory for detailed documentation:

  • Architecture overview

  • Integration examples

  • Constellation database reference

License

MIT License - See LICENSE file for details

Author

Dal Marsters - Lushy.app

Available Tools

11 tools
apply_constellation_presetApply Rhythmic Preset — Generate Oscillation SequenceA
Read-onlyIdempotent

Apply a Phase 2.6 rhythmic preset, generating a complete oscillation sequence over one full period.

Layer 2: Deterministic sequence generation (0 tokens).

Returns a trajectory of 5D coordinate states tracing one complete cycle of the preset oscillation. This output is directly usable by:

  • Tier 4D integrate_forced_limit_cycle for single-domain orbits

  • Tier 4D integrate_forced_limit_cycle_multi_domain for composition

  • Phase 2.7 generate_constellation_attractor_prompt for keyframe prompts

Inputs: params (required). Returns: result

compute_constellation_trajectoryCompute Smooth Trajectory Between Two Constellation StatesA
Read-onlyIdempotent

Compute smooth interpolation trajectory between two canonical states.

Layer 2: Deterministic interpolation (0 tokens).

Uses cosine ease-in-out for perceptually smooth transitions. Each step includes full 5D coordinates suitable for attractor prompt generation or multi-domain composition input.

Inputs: params (required). Returns: result

generate_constellation_attractor_promptGenerate Image Prompt from Attractor Coordinates (Phase 2.7)A
Read-onlyIdempotent

Generate image-generation-ready prompts from 5D constellation coordinates.

Layer 2: Deterministic vocabulary extraction (0 tokens).

Translates abstract parameter coordinates into concrete visual vocabulary suitable for Stable Diffusion, ComfyUI, DALL-E, or Midjourney. Three output modes are available:

  • composite: Single prompt string combining keywords and geometric specs. Best for direct image generation.

  • split_keywords: Categorized keyword lists (visual type, specifications, parameter descriptors). Best for ComfyUI prompt engineering.

  • descriptive: Narrative paragraph prompt. Best for DALL-E / Midjourney.

Coordinates can be provided directly, or derived from a canonical state name.

Inputs: params (required). Returns: result

generate_constellation_compositionGenerate Composition Parameters from ConstellationA
Read-onlyIdempotent

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

Inputs: params (required). Returns: result

get_constellation_coordinatesExtract 5D Parameter Coordinates for a Constellation or StateA
Read-onlyIdempotent

Extract normalized 5D parameter coordinates for a canonical state or constellation name.

Layer 1: Pure taxonomy lookup (0 tokens).

If a canonical state name is given (e.g. 'orion_grandeur'), returns its exact coordinates. If a constellation name is given (e.g. 'Orion'), returns the nearest canonical state's coordinates with distance metric.

Coordinates are suitable for:

  • Trajectory computation (Phase 1A)

  • Rhythmic composition input (Phase 2.6)

  • Attractor visualization (Phase 2.7)

  • Multi-domain composition (Tier 4D)

Inputs: name (required), response_format. Returns: result

get_constellation_domain_registry_configGet Tier 4D Domain Registry ConfigurationA
Read-onlyIdempotent

Return Tier 4D integration configuration for compositional limit cycles.

Layer 2: Pure lookup (0 tokens).

Returns the domain signature for registering with aesthetic-dynamics-core multi-domain composition. Includes domain_id, parameter names, preset periods, and canonical state coordinates — everything needed for integrate_forced_limit_cycle_multi_domain.

Inputs: no named parameters. Returns: result

get_constellation_visual_typesList Visual Types and Keywords (Phase 2.7)A
Read-onlyIdempotent

List all constellation visual types with their coordinates and keywords.

Layer 1: Pure taxonomy lookup (0 tokens).

Returns the complete visual vocabulary catalog used by the attractor prompt generator. Each visual type represents a region of the 5D constellation parameter space with associated image-generation keywords.

Inputs: no named parameters. Returns: result

get_server_infoGet Server Info and CapabilitiesA
Read-onlyIdempotent

Get server metadata, capabilities, and Phase 2.6/2.7 status.

Layer 1: Pure reference (0 tokens).

Returns comprehensive information about the constellation composition server including available tools, parameter space dimensions, canonical states, rhythmic presets, and visual vocabulary types.

Inputs: no named parameters. Returns: result

list_all_constellationsList All Available ConstellationsA
Read-onlyIdempotent

List all available constellations with basic information.

Provides a quick overview of all 22 major constellations available in the system, including their abbreviations and primary themes. Useful for browsing options or understanding the full scope of available compositional patterns.

Args: response_format: Output format ('markdown' or 'json')

Returns: str: Complete list of constellations with basic metadata

Inputs: response_format. Returns: result

list_constellation_presetsList Phase 2.6 Rhythmic PresetsA
Read-onlyIdempotent

List all available Phase 2.6 rhythmic presets with their parameters.

Layer 1: Pure taxonomy lookup (0 tokens).

Returns preset names, periods, oscillation patterns, state pairs, and descriptions. Presets define temporal oscillation patterns between canonical constellation states for rhythmic composition and Tier 4D multi-domain limit cycle discovery.

Inputs: response_format. Returns: result

search_constellationsSearch Constellations by Theme or CharacteristicsA
Read-onlyIdempotent

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

Inputs: params (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.1/5.0

    Scored across 11 tools

    Disambiguation4/5

    Most tools have distinct purposes with clear boundaries, such as apply_constellation_preset for generating oscillation sequences, generate_constellation_attractor_prompt for creating image prompts, and get_constellation_coordinates for coordinate extraction. However, some tools like get_constellation_visual_types and list_all_constellations might overlap slightly in providing catalog-like information, but their descriptions help differentiate them by focusing on visual vocabulary versus basic constellation metadata.

    Naming Consistency3/5

    The naming follows a mixed convention with some tools using verb_noun patterns like apply_constellation_preset and generate_constellation_attractor_prompt, while others use noun-based names like get_constellation_coordinates and list_all_constellations. This inconsistency is noticeable but still readable, as most names are descriptive and follow a general structure related to constellation operations.

    Tool Count5/5

    With 11 tools, the count is well-scoped for the server's purpose of constellation composition and image generation. Each tool serves a specific role in the workflow, from listing and searching constellations to generating prompts and computing trajectories, ensuring comprehensive coverage without unnecessary bloat.

    Completeness5/5

    The tool set provides complete coverage for the domain of constellation-based composition, including listing and searching constellations, extracting coordinates, generating trajectories, creating image prompts, and integrating with multi-domain systems. There are no obvious gaps; tools support the full lifecycle from discovery to application in image generation and rhythmic composition.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • astronomy-oracle

      gregario
      A
      license
      A
      quality
      B
      maintenance
      Accurate astronomical catalog data and observing session planner for LLM assistants. Stops hallucinated magnitudes, coordinates, and visibility.
      3
      123 npm
      3
      MIT

    • Astro MCP Server

      aryaminus
      F
      license
      Not graded
      quality
      C
      maintenance
      Multi-tradition astrology engine that computes real birth charts, transits, and synastry for AI agents via MCP tools.
      15
      -