Guide for AI agents

Cosmic Weather Mesh is machine-readable. Every panel in the UI is backed by a plain JSON GET endpoint — no auth, no API key, no scraping required. This page (and the identical AGENTS-GUIDE.md at the repo root) is the canonical reference.

What this app does

Given a date/time and a latitude/longitude, it returns (1) real geocentric ecliptic positions of the Sun, Moon, and eight planets computed from ephemeris data (via astronomy-engine, a real astronomical library — not a lookup table), (2) live or historical weather for that place from Open-Meteo (free, no key), and (3) a short generated "interpretation" pairing the two.

HTTP endpoints

GET /api/profile?date=ISO8601&lat=NN&lon=NN

One-shot combined endpoint. Returns astro, weather, and interpretation. This is what the UI calls and the recommended entry point for agents.

GET /api/astro?date=ISO8601&lat=NN&lon=NN

Astro-only. Returns Sun/Moon/planet ecliptic longitudes, zodiac signs, degree-in-sign, retrograde flags, Moon phase, and an approximate Ascendant (needs accurate lat/lon and time — treat as indicative, not birth-chart-precise).

GET /api/weather?lat=NN&lon=NN&date=ISO8601

Weather-only. Uses live forecast for dates within ~15 days of now, and the Open-Meteo historical archive for dates outside that window (e.g. birth dates in the past).

GET /api/geocode?q=CityName

Free-text place search → array of {name, country, latitude, longitude}. Use this before calling the endpoints above if you only have a place name.

MCP server

The same logic is also exposed as a standalone MCP (Model Context Protocol) server over stdio JSON-RPC, in /mcp-server of the repo. It exposes two tools:

get_astro_profile(date, lat, lon) — same payload as /api/astro
get_weather(lat, lon, date?) — same payload as /api/weather

Run it with node mcp-server/index.js and point any MCP-compatible client (Claude Desktop, Claude Code, etc.) at it as a stdio server. See mcp-server/README.md for the exact client config block.

Data honesty notes

Planetary positions are real ephemeris output, tropical zodiac convention.
The Ascendant uses a standard formula with a constant mean obliquity (23.4367°) — accurate to a fraction of a degree for any date in the last few centuries, but sensitive to exact birth time.
Weather is real Open-Meteo data, not simulated.
The "interpretation" text is a lightweight, deterministic template — playful commentary, not a claim of predictive accuracy.

Example

curl "https://<deployment>/api/profile?date=2026-07-31T18:00:00Z&lat=40.7128&lon=-74.0060"