auseklis: Instructions file for Codex

AGENTS.md

Astrology MCP server. TypeScript ESM, official MCP SDK, dual transport (stdio bin + Cloudflare Worker).

Commands

• npm run typecheck — strict TS, no emit
• npm test — 20-check smoke suite (esbuild-bundles test/smoke.ts, runs on Node)
• npm run build — tsc -p tsconfig.build.json → dist/
• npm run dev — wrangler dev server on :8787
• node dist/stdio.js — run the built stdio server

Architecture (load-bearing facts)

• src/ephemeris/engine.ts defines EphemerisBackend — the ONLY place astronomy-engine may be imported for runtime use. Everything else derives from its primitives so the backend can be swapped (planned Rust/WASM v1).
• src/mcp/server.ts exports createServer(); both entries (src/stdio.ts, src/index.ts) attach transports to it. The Worker creates a fresh server per request (stateless).
• Tool pattern: Zod raw-shape inputSchema + outputSchema, READONLY annotations, handlers wrap pure functions in run() from src/mcp/schemas.ts (errors → isError text).
• SERVER_VERSION in src/mcp/server.ts must match package.json, server.json, manifest.json.

Gotchas

• astronomy-engine's Ecliptic() ALREADY rotates EQJ→ecliptic-of-date. Never pre-rotate with Rotation_EQJ_ECT — that double-rotates (~50″/yr drift; was a real 0.1.0 bug).
• astronomy-engine ships broken ESM packaging; engine.ts imports it via namespace + default-interop fallback. Don't "simplify" to named imports — plain Node ESM breaks.
• Timezone conversion (src/ephemeris/time.ts) uses Intl only — no tz dependency. Works on Node and Workers.
• LICENSING: never add sweph/swisseph deps or .se1/.se2 files (AGPL contamination — see NOTICE).

Testing philosophy

Reference facts over shape checks: published eclipse dates, the 2026 equinox, NOVAS SunPosition agreement, an independent Placidus fixture (CircularNatalHoroscopeJS, LA 2019-07-20 17:10Z). When adding astronomy, find an external anchor.