Constellation Composition MCP Server

Instructions

Implementation Reference

• src/constellation_composition_mcp/server.py:1603-1697 (handler)

  The tool 'get_constellation_coordinates' retrieves 5D parameter coordinates for a constellation or canonical state. It handles both direct canonical state lookups and constellation lookups (which are then mapped to the nearest canonical state or inferred).

  async def get_constellation_coordinates(
      name: str,
      response_format: ResponseFormat = ResponseFormat.JSON
  ) -> str:
      """
      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)
      """
      # Direct canonical state lookup
      if name in CONSTELLATION_CANONICAL_STATES:
          state = CONSTELLATION_CANONICAL_STATES[name]
          coords = {p: state[p] for p in CONSTELLATION_PARAMETER_NAMES}
          result = {
              "state_name": name,
              "source_constellation": state.get("source_constellation", ""),
              "description": state.get("description", ""),
              "coordinates": coords,
              "parameter_names": CONSTELLATION_PARAMETER_NAMES,
              "match_type": "exact_canonical"
          }
      else:
          # Try to match constellation name to nearest canonical state
          target_name = None
          for cname in CONSTELLATIONS:
              if name.lower() == cname.lower():
                  target_name = cname
                  break
              if name.lower() == CONSTELLATIONS[cname]['abbr'].lower():
                  target_name = cname
                  break
  
          if not target_name:
              available_states = ", ".join(sorted(CONSTELLATION_CANONICAL_STATES.keys()))
              available_const = ", ".join(sorted(CONSTELLATIONS.keys()))
              return json.dumps({
                  "error": f"'{name}' not found",
                  "available_canonical_states": available_states,
                  "available_constellations": available_const
              }, indent=2)
  
          # Find canonical state sourced from this constellation
          exact_match = None
          for sname, sdata in CONSTELLATION_CANONICAL_STATES.items():
              if sdata.get("source_constellation", "").lower() == target_name.lower():
                  exact_match = sname
                  break
  
          if exact_match:
              state = CONSTELLATION_CANONICAL_STATES[exact_match]
              coords = {p: state[p] for p in CONSTELLATION_PARAMETER_NAMES}
              result = {
                  "state_name": exact_match,
                  "source_constellation": target_name,
                  "description": state.get("description", ""),
                  "coordinates": coords,
                  "parameter_names": CONSTELLATION_PARAMETER_NAMES,
                  "match_type": "constellation_to_canonical"
              }
          else:
              # Infer coordinates from constellation metadata
              meta = CONSTELLATIONS[target_name]
              coords = _infer_coordinates_from_metadata(meta)
              result = {
                  "state_name": None,
                  "source_constellation": target_name,
                  "description": f"Inferred from {target_name} metadata (no canonical state)",
                  "coordinates": coords,
                  "parameter_names": CONSTELLATION_PARAMETER_NAMES,
                  "match_type": "inferred"
              }
  
      if response_format == ResponseFormat.JSON:
          return json.dumps(result, indent=2)
      else:
          md = f"# Coordinates: {result.get('state_name') or result['source_constellation']}\n\n"
          md += f"**Match type:** {result['match_type']}\n\n"
          md += f"**Description:** {result['description']}\n\n"
          for p in CONSTELLATION_PARAMETER_NAMES:
              val = result['coordinates'][p]
              bar = "█" * int(val * 20)
              md += f"- `{p}`: {val:.2f} {bar}\n"
          return md