Control a Seestar from your AI assistant: point, image, and schedule.

GitHub stars
300

Install

/plugin install seestar@seestar-alp

Run it inside Claude Code after adding the marketplace with /plugin marketplace add smart-underworld/seestar_alp.

Contents

Discovered from source

Skills 4

Building schedules

  1. Inspect. get_schedule to see what already exists. Do not clobber a schedule the user wants to keep; ask first.
  2. Create. create_schedule starts a new empty schedule.
  3. Add items.
    • Generic item: add_schedule_item(action, params) for actions such as wait/park/start-imaging steps. Physical actions (scope_park, scope_move_to_horizon, reboot, shutdown) are refused unless confirm=true; pass it only after the user explicitly confirms that item.
    • Mosaic: schedule_mosaic(target_name, ra, dec, session_time_sec, ra_num, dec_num, panel_overlap_percent=20, gain=80, is_use_lp_filter, is_use_autofocus, is_j2000). ra_num x dec_num is the panel grid; session_time_sec is the total across the grid (the tool converts it to per-panel panel_time_sec).
    • Timing: add_schedule_item("wait_until", {"local_time": "HH:MM"}) holds until a clock time; add_schedule_item("wait_for", {"timer_sec": N}) waits a duration. Use a wait_until as the first item so an early start waits for darkness.
    • start_mosaic runs a single mosaic directly without a stored schedule. It begins an unattended capture that moves the mount, so it requires confirm=true; pass it only after the user confirms.
    • Field gotcha: if you ever build a start_mosaic item by hand via add_schedule_item, put the per-panel time in panel_time_sec, not session_time_sec — the device tolerates the legacy session_time_sec, but the web schedule page only reads panel_time_sec and will error without it. Prefer schedule_mosaic, which handles this for you.
  4. Review. Call get_schedule again and summarise the order and total time for the user.
  5. Fix mistakes. Each item carries a schedule_item_id (from get_schedule). remove_schedule_item(id) deletes one, replace_schedule_item(id, action, params) swaps one out, and insert_schedule_item_before(before_id, action, params) adds one ahead of another — so a mis-ordered append does not mean rebuilding from scratch. replace/insert of a physical action need confirm=true, like add_schedule_item.
  6. Run. start_scheduler launches an unattended run and requires confirm=true; pass it only after the user confirms the reviewed plan. Stop with stop_scheduler.
  7. Steer a running scheduler. pause_scheduler / continue_scheduler suspend and resume; skip_scheduler_cur_item moves past a stuck target (e.g. one lost to cloud or the horizon); reset_scheduler_cur_item restarts the current item from the beginning.
  8. Persist. export_schedule(filepath) saves a schedule to a file; import_schedule(filepath) loads one. Offer export after building a good plan.

Planning a whole night

When the user wants "tonight"/"tomorrow night" across many targets: work out the dark window (astronomical dusk→dawn) and the moon (phase, and when it rises/sets) for the device's location — get_device_state reports location_lon_lat. Schedule moon-tolerant targets (open/globular clusters, bright galaxy cores, and emission nebulae with is_use_lp_filter=true) while the moon is up, and save faint broadband/reflection targets for after moonset. Order targets near their culmination, and anchor the start (and the moonset handover) with wait_until items.

Mind the site's horizon: get_horizon gives the obstruction altitude by azimuth, so place each target in the part of the night when it clears it, not only when it is high. If skip_hidden_targets is true, the scheduler itself skips a mosaic target that is below the horizon plus margin when its turn comes, and moves on to the next item; tell the user when a planned target is at risk of that.

For a large timed plan, building item-by-item is many calls and risks out-of-order appends; it is cleaner to assemble the full schedule JSON (a {"list": [ {action, params, schedule_item_id}, … ]} dict — mosaic items use panel_time_sec) and load it in one import_schedule(filepath) call, then get_schedule to review.

End long unattended schedules with a park step, and confirm with the user before any physical action (see safety).

Safety

Confirmation gate

scope_park, scope_move_to_horizon, reboot, and shutdown refuse unless confirm=true.

  • First call WITHOUT confirm (or just describe the action) and ask the user to approve it explicitly.
  • Pass confirm=true ONLY after the user has said yes in this conversation. Never set it on your own initiative or on a standing assumption.
  • These move hardware or interrupt a session; say what will happen (e.g. "this will stop the current stack").

The same gate applies to the scheduler: add_schedule_item with a physical action requires confirm=true, and start_scheduler (an unattended run) requires confirm=true. Pass them only after explicit user confirmation.

Sun

Never slew (goto_target, scope_goto, mosaics, schedules) toward or near the Sun, and never start imaging in daylight without a solar filter the user has confirmed. If the target's position is near the Sun, refuse and explain.

Mount motion (not hard-gated, but still physical)

polar_align (3PPA) and gotos move the mount. They are not behind the confirm gate, but run them only when the user asked for that action, and only at night / away from the Sun. polar_align drives the mount through its alignment routine — tell the user it will move before starting.

Shutdown order

  1. stop_view / stop_scheduler if active.
  2. scope_park (with confirmation) and wait for completion via get_device_state.
  3. Only then reboot or shutdown (with confirmation). Never shut down an un-parked scope unless the user explicitly insists.

Session planning

Turn "image " into concrete seestar MCP tool calls. Every tool takes telescope_id (default 1); pass it for multi-scope setups.

Startup (when setting up for the night)

The whole startup sequence is drivable via MCP tools. Run the steps the situation needs, in this order, and only when the user is setting up (they move hardware — see safety):

  1. Initialize. startup_sequence(lat, lon) — lat/lon come from get_device_state's location_lon_lat (or ask). Optionally set_heater(state, value) for dew control.
  2. Dark frames. create_dark — have the user cap the lens first. Run this before startup_sequence, or only once startup has fully settled: it needs a free device and will return function conflict (code 524) if another operation is still running.
  3. Polar align / 3PPA. polar_align, then poll get_pa_error until it returns real values (9999.9 = not yet measured). set_3ppa_calibration(enabled) toggles auto-calibration.
  4. Autofocus. start_auto_focus (stop with stop_auto_focus; adjust_focus(steps) / get_focuser_position for manual control).
  5. Filter. set_lp_filter(enabled) for the duo-band/LP filter, or set_wheel_position(n) where a wheel exists (get_wheel_position / get_wheel_state).

One step at a time. The Seestar runs one operation at a time — do not fire these back-to-back. Start a step, then wait for it to finish before the next: poll get_device_state (and get_pa_error for alignment) until the device is idle / reports a result. Firing the next command while one is still running returns function conflict (code 524). A tool call returning {"ok": true}/code 0 only means the command was accepted, not that the motion or routine has completed.

Then proceed to the per-target steps below.

Steps

  1. Readiness. Call get_device_state and get_view_state. Confirm the scope is connected, not already stacking/slewing, and not in an error state. If a view is active and the user wants a new target, call stop_view first.
  2. Resolve coordinates. You need RA/Dec for the target. If the user gave only a name, supply known J2000 coordinates and say so; ask if unsure. Never guess for obscure objects.
  3. Sun check. Do not slew toward the Sun (see the safety skill).
  4. Horizon check. check_target_visibility(ra, dec). If visible is false the target is behind the site's horizon right now (trees, a roof, below the margin): say so, with its altitude and the horizon at that azimuth, and offer another target or a later time instead of slewing. get_horizon shows the whole profile; no points means a flat horizon.
  5. Slew. goto_target(target_name, ra, dec, is_j2000=true). Poll is_goto_completed_ok until true. Use stop_goto_target to abort.
  6. Verify pointing. start_solve, then get_solve_result. If the solve fails, re-check the sky is clear/dark and retry once before reporting.
  7. Stack. start_stack(gain, restart=true) (typical gain 80; use set_gain / set_exposure beforehand to adjust).
  8. Monitor. Use get_view_state periodically and get_last_image to preview. End with stop_view.

For multi-target or timed nights use the building-schedules skill instead.

Settings and firmware compatibility

Firmware versions differ in which settings calls they support. Handle this by detecting, not assuming.

Reading

read_settings tries both read paths (get_setting and get_stack_setting) and merges what it can; any path that failed is reported in errors. Use whatever keys come back rather than assuming a fixed set.

Writing

write_setting(values, variant="auto"):

  • auto (default): one key uses set_stack_setting, several keys use set_stack_settings.
  • Explicit variants: set_setting (nested stack payload), set_stack_setting, set_stack_settings.
  • If a variant is rejected the tool returns {"ok": false, ...}; retry with another variant, starting with auto, then explicit ones.

Rules

  • After writing, call read_settings and verify the values took effect.
  • Prefer feature/payload detection (is the key present in the read result? did the write succeed?) over firmware-version checks.
  • Never claim a setting is unsupported because of a version number; try it and report the actual result.
  • Change only the keys the user asked for.

MCP servers 1

Sponsors

Details

Marketplace
smart-underworld/seestar_alp
Source
mcp/plugin
Category
Community