Calculate the altitude and azimuth angles of a celestial object.

Use when: you need one named object's position at a specified place and instant. Do not use when: you need an all-night target list or a complete observing decision. Requires: object name, observer coordinates, observation time, and its IANA timezone. Follow-up: get_celestial_rise_set for events; get_nightly_forecast for night targets; plan_stargazing_session for a complete observing decision.

Args: celestial_object: Name of object (e.g. "sun", "moon", "andromeda") lon: Observer longitude in degrees lat: Observer latitude in degrees time: Observation time string "YYYY-MM-DD HH:MM:SS" time_zone: IANA timezone string

Returns: Dict with keys "data", "_meta". "data" contains "altitude" and "azimuth" (degrees).

Calculate the rise and set times of a celestial object.

Use when: you need one object's rise/set events. Choose calendar_day for the local date containing time, or next_events for the next rise and next set after time. Do not use when: you need a continuous observing window or a complete night plan. Requires: object name, observer coordinates, time, timezone, and the intended event scope. Follow-up: get_celestial_pos for position; plan_stargazing_session for observing windows.

Args: celestial_object: Name of object (e.g. "sun", "moon", "andromeda") lon: Observer longitude in degrees lat: Observer latitude in degrees time: Date string "YYYY-MM-DD HH:MM:SS" time_zone: IANA timezone string event_scope: "calendar_day" (default) finds the events in the local calendar day containing time. "next_events" finds the next rise and next set independently, rolling into following days when needed.

Returns: Dict with keys "data", "_meta". "data" contains "rise_time" and "set_time".

Get detailed information about the Moon's phase and position.

Use when: you need lunar phase or illumination facts, with optional observer-local events. Do not use when: you need to rank observing sites or assess a target's overall suitability. Requires: time and timezone; supply both lat and lon for local position and rise/set. Follow-up: get_telescope_targets for equipment-aware targets; plan_stargazing_session for the combined effect of moonlight, weather, place, and observing goals.

When lat and lon are provided, also returns the Moon's local altitude, azimuth, moonrise, and moonset relative to the observer.

Args: time: Date string "YYYY-MM-DD HH:MM:SS" time_zone: IANA timezone string lat: Observer latitude in degrees (optional, for local position) lon: Observer longitude in degrees (optional, for local position)

Returns: Dict with keys "data", "_meta". "data" contains illumination, phase_name, age_days, elongation, earth_distance, and optionally altitude/azimuth plus moonrise/moonset (UTC unix timestamps).

Get a list of solar system planets currently visible (above horizon).

Use when: you need planets above the observer's horizon at a specified instant. Do not use when: you need all-night visibility, darkness guarantees, or equipment ranking. Requires: observer coordinates, time, and timezone; above-horizon visibility alone does not establish dark-sky or telescope observing conditions. Follow-up: get_celestial_pos or get_celestial_rise_set for a selected planet; plan_stargazing_session for a planetary observing decision.

Args: lon: Observer longitude in degrees lat: Observer latitude in degrees time: Observation time string "YYYY-MM-DD HH:MM:SS" time_zone: IANA timezone string

Returns: Dict with keys "data", "_meta". "data" is a list of planet dicts (name, altitude, azimuth).

Get the position (altitude/azimuth) of the center of a constellation.

Use when: you need a named constellation's center position at a place and instant. Do not use when: you need to identify which constellation contains arbitrary coordinates, or to choose individual observing targets. Requires: constellation name, observer coordinates, time, and timezone. Follow-up: get_nightly_forecast for individual night targets; plan_stargazing_session for a complete observing decision.

Args: constellation_name: Name of constellation (e.g. "Orion", "Ursa Major") lon: Observer longitude in degrees lat: Observer latitude in degrees time: Observation time string "YYYY-MM-DD HH:MM:SS" time_zone: IANA timezone string

Returns: Dict with keys "data", "_meta". "data" contains name, altitude, azimuth.

Get a curated list of best objects to view for the night.

Use when: place and night are known and you need general night targets and a night window. Do not use when: you need telescope-specific target matching or regional site selection. Requires: observer coordinates, time within the intended night, timezone, and optional limit. Interpretation: this is an astronomy forecast, not a weather forecast. Deep-sky altitude and score are evaluated at the supplied time; deep_sky.score sorts lower first and must not be compared with telescope suitability_score (higher first). The legacy transit_alt is an altitude estimate at that scoring time, not a separately solved meridian transit. night_window is civil darkness (Sun below -6 degrees), not astronomical darkness (-18 degrees) or guaranteed exposure time. Follow-up: get_telescope_targets for known optics; get_shooting_plan for an imaging schedule; plan_stargazing_session when place or night still needs comparison.

Args: lon: Observer longitude in degrees lat: Observer latitude in degrees time: Observation time "YYYY-MM-DD HH:MM:SS" inside the intended night. A bare date means local midnight and can belong to the previous evening's night. time_zone: IANA timezone string limit: Max number of deep-sky objects to return (default 20)

Returns: Standard envelope; data contains: - moon_phase: Moon details - planets: List of visible planets - deep_sky: Sorted list of deep sky objects (Messier/NGC) - night_window: Civil-dark window for the requested night

Get metadata for all registered MCP tools.

Use when: you need the wrapped catalog with full documentation and parameter summaries. Do not use when: your client only needs standard MCP tools/list discovery or a business result. Requires: no inputs; this call discovers tools and does not perform observing analysis. Follow-up: choose a tool from its use/do-not-use guidance; plan_stargazing_session is the primary entry for complete observing decisions.

Returns: Dict with keys "data", "_meta". "data.tools" contains tool metadata objects.

Get light pollution data for a specific area.

Use when: you need a bounding-box grid of light pollution measurements for a map or analysis. Do not use when: you need ranked places or a complete observing decision. Requires: south/west/north/east bounds and optional grid zoom. Returns: data.grid points with brightness, Bortle class, and SQM, plus bounds and zoom. Follow-up: analysis_area for synchronous place candidates; submit_area_analysis for background place analysis; plan_stargazing_session for an observing decision.

Returns a grid of light pollution data points including brightness, Bortle class, and SQM.

Args: south, west, north, east: Bounding box coordinates. zoom: Grid resolution zoom level (default: 10). Higher = more detailed.

Analyze a geographic area for suitable stargazing locations.

Use when: you need synchronous place candidates or cached pages for a fixed regional query. Do not use when: the search needs background polling/cancellation or a complete night plan. Requires: south/west/north/east bounds; keep search parameters fixed while changing pages. Follow-up: analysis_area with the same query for other pages; submit_area_analysis for background work; plan_stargazing_session for dates, weather, and target decisions.

This tool searches for dark, accessible locations with good viewing conditions. Results are cached based on search parameters.

Fast mode: Set road_radius_km=0 to skip road connectivity checks. This avoids OSMnx network downloads from Overpass API and is much faster — use it when you only need candidate locations with light pollution and elevation data, without road distance analysis.

Args: south, west, north, east: Bounding box coordinates. max_locations: Maximum number of candidate locations to find (before pagination). min_height_diff: Minimum elevation difference for prominence. road_radius_km: Search radius for road access. Set to 0 to skip road checks. network_type: Type of road network ('drive', 'walk', etc.). avoid_popular_spots: Penalize heuristically popular locations when ranking results. prefer_quiet_at_night: Favor locations that are likelier to quiet down at night. popularity_radius_km: Preference horizon for the popularity heuristics. db_config_path: Optional path to database config. page: Page number (1-based). page_size: Number of results per page.

Returns: Dict with keys "data", "_meta". "data" contains: - items: List of location results for the current page. - total: Total number of locations found. - page: Current page number. - page_size: Current page size. - resource_id: Cache key for the non-pagination search parameters.

Submit bounded background place analysis and return its task identifier.

Use when: a geographic place search may outlive one tool call and needs background control. Do not use when: you need a complete observing decision or only want to poll an existing task. Requires: request.bounds and optional place-search preferences; max_locations must be from 1 to 100. Returns: task snapshot with task_id, resource_id, state, and normalized request. Active duplicate queries share a task. Completed retries may use cached data. Follow-up: get_area_analysis_task to poll; get_area_analysis_result after success; cancel_area_analysis_task if no longer needed; plan_stargazing_session for decisions.

Poll an area task's state, deadline, failure, and normalized request.

Use when: you have a task_id and need execution state, failure, or remaining physical work. Do not use when: you need result pages; do not submit a new job merely to poll. Requires: task_id returned by submit_area_analysis in the same server runtime. Returns: task snapshot with state, failure, request, and execution_pending. Running progress is unknown; success does not guarantee the separate result cache still exists. Follow-up: get_area_analysis_result after success; cancel_area_analysis_task if unwanted. On TASK_RUNTIME_CHANGED, resubmit the original request rather than polling the old ID.

Logically cancel queued/running area work and discard its late results.

Use when: a submitted area task is no longer needed and its late result must not publish. Do not use when: you want to delete cached data or interrupt another domain's operation. Requires: task_id returned by submit_area_analysis in the same server runtime. Returns: idempotent cancellation snapshot; an existing terminal state stays unchanged. A running provider call keeps its execution slot until it actually finishes. Follow-up: get_area_analysis_task to confirm state and execution_pending; wait for physical work to drain before considering resubmission.

Page a successful area task's existing cached result without recomputing.

Use when: get_area_analysis_task reports succeeded and you need its original result pages. Do not use when: the task is queued/running and you only need to poll its state. Requires: the successful task_id, page >= 1, and page_size >= 1. Returns: cached items, pagination metadata, and resource_id with the task's publication version checked; this call never silently recomputes missing data. Follow-up: get_area_analysis_result with the same task_id for other pages; get_area_analysis_task for state; resubmit the normalized request on TASK_RESULT_EXPIRED.

Recommend astrophotography targets for a telescope setup.

Use when: place, time, and optics are known and you need ranked deep-sky imaging targets. Do not use when: you only need naked-eye targets, a timed schedule, or a choice of sites. Requires: focal length, observer coordinates, time, and timezone; supply known sensor and optical details for matching. For equipment presets use plan_stargazing_session. Follow-up: get_shooting_plan for timed imaging slots; plan_stargazing_session if the observing place or night still needs comparison; get_celestial_pos for altitude at a specific clock time (the target altitude field is at civil dusk).

Given a telescope/camera configuration and observing location+time, returns a ranked list of deep-sky objects best suited for imaging. Interpretation: altitude is at civil dusk, not at the requested clock time; azimuth is at civil midnight. Use altitude_curve or get_celestial_pos for another time. transit_alt is the sampled peak within the civil-night window, in degrees; transit_time and curve time values are UTC Unix seconds. Null rise/set values mean no crossing was found inside that window, not that an object can never rise/set. suitability_score is a heuristic (higher is better), not a probability or weather clearance. Missing photometry is unknown; do not infer a seasonal visibility error from missing magnitude or from the civil-dusk altitude alone.

Args: focal_length_mm: Telescope focal length in mm (e.g. 250 for RedCat51) lon: Observer longitude in degrees lat: Observer latitude in degrees time: Observation time string "YYYY-MM-DD HH:MM:SS" time_zone: IANA timezone string (e.g. "Asia/Shanghai", "UTC") aperture_mm: Telescope aperture in mm (optional, for limiting magnitude) sensor_width_mm: Camera sensor width in mm (optional) sensor_height_mm: Camera sensor height in mm (optional) sensor_pixel_size_um: Camera pixel size in microns (optional) central_obstruction_pct: Central obstruction percentage (0-50) reducer_factor: Focal reducer factor (default 1.0) barlow_factor: Barlow/extender factor (default 1.0) mount_type: "equatorial" or "altaz" (default "equatorial") filter_type: Filter type — "Hα", "OIII", "SII", or None for LRGB limit: Maximum number of targets to return (default 20)

Returns: data.targets[] — ranked list, best first. Each target has: name, type, magnitude, catalog altitude (civil dusk, degrees), azimuth (civil midnight, degrees), dawn_altitude angular_size_arcmin, angular_size_min_arcmin, angular_size_pa_deg surface_brightness (mag/arcmin²), fov_fit_score, fov_fill_ratio suitability_score (0-100), mosaic_recommended, optimal_rotation_deg rise_time, set_time, transit_time (UTC unix timestamps), transit_alt (degrees) altitude_curve[{time, alt}] civil_dusk, civil_dawn, observation_time data.moon — {illumination, phase, altitude_curve, always_down, always_up, dark_fraction, moonrise, moonset} data.config — the TelescopeConfig used data.total — number of targets returned

Generate a single-night astrophotography shooting plan.

Use when: optics, place, and night are fixed and you need matched targets in timed slots. Do not use when: you still need to choose a site or compare nights, or only need target ranks. Requires: focal length, observer coordinates, time, and the observing timezone (defaults to UTC); optional sensor, optical, and minimum-altitude settings. Follow-up: get_telescope_targets for target details; plan_stargazing_session to reconsider place, date, equipment preset, or observing constraints.

Runs match_telescope_targets then generate_shooting_schedule, returning targets + moon + timed shooting slots in one response. Interpretation: target altitude is at civil dusk, not the requested clock time; use altitude_curve or get_celestial_pos for another time. The schedule uses a civil-dark window (Sun below -6 degrees), not astronomical darkness (-18 degrees), and does not validate weather, access, obstructions or achieved integration time. Empty/null slots or exposure values are not an all-night imaging commitment.

Returns: data.targets[] — same structure as get_telescope_targets data.moon — {illumination, phase, moonrise, moonset, always_down, always_up, dark_fraction, altitude_curve} data.plan — {date, slots[{start_time, end_time, target_name}], total_exposure_min, moon_phase, moon_illumination, moon_delay_min} data.config — the TelescopeConfig used data.total — number of matched targets

通过地点名称获取综合天气（当前 + 小时预报 + 日预报）。

Use when: you have a place name and need weather facts for that resolved location. Do not use when: you already have exact coordinates or need a complete observing decision. Requires: an unambiguous place name; use full administrative names for Chinese locations. Provider selection can remain at the server's default aggregation policy. Follow-up: get_weather_by_position for precise coordinates; plan_stargazing_session to combine weather with darkness, targets, and alternative observing sites.

Geocoding uses offline China gazetteer (CJK) → Photon → Nominatim cascade. Weather data is aggregated from multiple providers with graceful fallback. Open-Meteo needs no API key; network/provider failures can still occur. Atmospheric fields: summary.current.atmosphere and summary.hourly[*].atmosphere contain optional model estimates with their own valid time and per-field provenance. Inspect summary.atmosphere_sources for source failures and resolution. Missing/null means unknown. CAMS global is approximately 45 km and natively 3-hourly; hourly output may be interpolated. AOD is column extinction, not surface visibility. Boundary-layer height is above local model ground, not a pollution ceiling. No AQI or pollution attribution is inferred. Interpretation: summary.current is current weather, summary.daily is calendar-day aggregation, and summary.hourly contains timestamped forecasts. For a future observing night select the actual hourly timestamps across local midnight and inspect providers and source for failures/provenance. Missing/null or out-of-horizon hours are unknown, not clear weather. Forecasts are predictions, not observations of future conditions; do not assume all providers or fields cover the same dates.

中文地名提示：建议使用完整行政区划名称，如 "浙江安吉"、"杭州西湖区"。 内置离线行政区划数据会正确解析到对应的行政区（如安吉县），而非 POI 商铺。 需要精确定位时优先使用 get_weather_by_position(lat, lon)。

Args: place_name: 地点名称。中文请使用完整行政区划（如 "浙江省安吉县"），避免仅用2-3字短名。 provider: provider 模式，可选 all/qweather/open-meteo/wttr。

Returns: Dict，包含 keys: "data", "_meta"（成功时）或 "error", "_meta"（失败时）。

通过经纬度获取综合天气（当前 + 小时预报 + 日预报）。

Use when: you have precise coordinates and need current and forecast weather facts. Do not use when: you only have a place name or need ranked observing sites or night targets. Requires: latitude and longitude; provider selection can remain at the default policy. Follow-up: get_weather_by_name for place-name input; plan_stargazing_session to compare observing places and nights using weather and other evidence.

Weather data is aggregated from multiple providers with graceful fallback. Open-Meteo needs no API key; network/provider failures can still occur. Atmospheric fields: summary.current.atmosphere and summary.hourly[*].atmosphere contain optional model estimates with their own valid time and per-field provenance. Inspect summary.atmosphere_sources for source failures and resolution. Missing/null means unknown. CAMS global is approximately 45 km and natively 3-hourly; hourly output may be interpolated. AOD is column extinction, not surface visibility. Boundary-layer height is above local model ground, not a pollution ceiling. No AQI or pollution attribution is inferred. Interpretation: summary.current is current weather, summary.daily is calendar-day aggregation, and summary.hourly contains timestamped forecasts. For a future observing night select the actual hourly timestamps across local midnight and inspect providers and source for failures/provenance. Missing/null or out-of-horizon hours are unknown, not clear weather. Forecasts are predictions, not observations of future conditions; do not assume all providers or fields cover the same dates.

Args: lat: 纬度 lon: 经度 provider: provider 模式，可选 all/qweather/open-meteo/wttr。

Returns: Dict，包含 keys: "data", "_meta"（成功时）或 "error", "_meta"（失败时）。

Create a composite stargazing plan for a region and time.

Use when: an existing bbox-first integration needs ranked regional places for one night. Do not use when: starting a new intent-based integration, providing a place name, comparing several nights, or only requesting weather facts. Requires: south/west/north/east bounds, observation time, and timezone. Returns: data.query, ranked data.candidates with scores, windows, weather and targets, and data.summary; all within the standard response envelope. recommendation_score is a relative ranking, not a probability or go/no-go threshold. _meta.status=success can still contain summary.warnings and candidate notes. Only candidates with dated weather and a usable window can be recommended. Missing-weather references retain their place weight without renormalization; weather base score/contribution/weight are zero compatibility placeholders, not bad-weather facts. summary.recommended_location_name is null when none qualify. Missing night-hour weather is unknown, not clear; a null best_observation_window is not an all-night opening. night_window is civil darkness (Sun below -6 degrees), not astronomical darkness (-18 degrees) or guaranteed exposure time. Inspect the returned candidate coordinates; a regional result is not a fixed-site plan. Follow-up: plan_stargazing_session is preferred for new integrations; get_multiday_stargazing_plan preserves bbox-first comparison across nights.

Compare one to seven consecutive nights and recommend the best night and place.

Use when: an existing bbox-first integration compares one to seven consecutive nights. Do not use when: starting a new intent-based integration, querying nonconsecutive dates, more than seven nights, or checking background task status. Requires: south/west/north/east bounds, local start_date, timezone, and optional night count. Returns: normalized data.query, per-night plans, the best night, and summary; each night uses its own civil-dark window. recommendation_score is a relative ranking, not a probability or go/no-go threshold. _meta.status=success can still contain per-night errors, warnings and candidate notes. Compare the dated forecast hours for each night; do not reuse summary.current or summary.daily as night weather. Missing night-hour coverage is unknown, not clear. Civil darkness (Sun below -6 degrees) is not astronomical darkness (-18 degrees) or guaranteed exposure time; a null best_observation_window is not an all-night opening. Follow-up: plan_stargazing_session is preferred for new integrations; get_best_stargazing_plan for the compatible single-night regional detail.

Preferred end-to-end planning entry point for choosing when, where, and what to observe across one to seven nights.

Use when: you need a complete observing decision or comparisons of places and nights. Do not use when: you only need raw weather, celestial facts, or task status. Requires: request.location (place name, center/radius, or exact bounds) and start_date; timezone, one-to-seven nights, observing goal, equipment preset/overrides, and supported preference fields have explicit defaults or are optional. A center/radius is a regional search, not a plan locked to the center point. The radius becomes an approximate search box, not a strict circular distance filter. Quietness/popularity adjustments require the corresponding preference flags. Pass request as a JSON object, not a JSON string; inspect resolved_location before describing a candidate as the exact user-specified site. Returns: normalized request, decision, alternatives, evidence, uncertainties, missing inputs, ranking-change conditions, and next actions in the standard envelope. Weather evidence uses dated night-hour forecasts. Missing weather or no usable window excludes a candidate from decision and alternatives; unranked_planning_reference evidence retains known location/sky facts with weather_unknown or no_usable_window status. If none qualify, decision=null. Partial coverage remains provisional. The night_window remains civil darkness. For deep_sky, observation windows require at least two continuous astronomical-dark hours, cloud <=25%, rain probability <=20%, and wind <=20 km/h, with known rain/wind fields. These are heuristic screening limits, not verified imaging success probabilities. Interpretation: recommendation_score is a relative ranking, not a probability or an absolute go/no-go threshold. _meta.status=success means execution succeeded; decision=null means no selected session. A null observation_window means no usable window was established, not an all-night opening. Inspect evidence, uncertainties, missing_inputs and next_actions even on success. nightly_weather_unavailable and no_usable_observation_window are high-uncertainty warnings; long_range_forecast requires a forecast recheck near departure. Never replace missing night hours with summary.current or summary.daily, or infer a provider from weather wording. Civil darkness means Sun below -6 degrees, not astronomical darkness at -18 degrees; its duration is not guaranteed exposure time. Popularity/quiet scores are heuristics, not measured noise or calibrated crowd probabilities. When equipment is supplied, decision.targets already contains equipment-matched targets; use that list to answer the selected session's target question without a second lookup. Read selected_target_window_check evidence before claiming shootability: complete equipment curves with no 25-degree, 30-minute model slot in the selected weather window are excluded. Missing or partial curves and generic targets remain unknown references. Altitude-only checks have unknown Moon constraints; independent slots may overlap and do not verify per-slot Moon separation, tracking or actual exposure. Keep the returned target order; do not compare scores across generic and equipment rankings. This is a synchronous call and can exceed a client default deadline; a timeout does not establish that a background planning task exists. Follow-up: get_shooting_plan for an imaging schedule at the selected place/night; get_weather_by_position for updated weather facts. Inspect missing inputs and next actions before treating a degraded decision as final.

Retrieve the current datetime and timezone.

Use when: you need the server environment's current time and local timezone. Do not use when: you need time at a remote observing site or already have its timezone. Requires: no inputs; local means the server environment, not the user's observing site. Follow-up: use the observing site's explicit time_zone in celestial and plan_stargazing_session requests; do not infer it from the server timezone.

Returns: Dict with keys "data", "_meta". "data" contains "current_time" (ISO string).