Auseklis Astrology

auseklis

占星术 MCP 服务——本命盘、行运、比较盘、推运、回归、日月食、逆行、月相。基于真实星历计算，让 AI Agent 不再臆造行星位置。

名称源自拉脱维亚的晨星。采用 MIT 许可证，不含 AGPL 星历数据——请参阅许可。

工具

工具	功能
get_planet_position	某一时刻一个星体／点的位置（星座、度数、速度、逆行状态）
compute_natal_chart	完整本命盘：13 个点、宫位、轴点、福点、相位
compute_transits	当前（或任意）星空与本命盘之间的相位
compute_progressions	次限推运（一日对应一年）
compute_synastry	两个人之间的跨盘相位
compute_composite_chart	关系的中点合盘
find_returns	太阳／月亮／行星回归（精确时刻）
get_moon_phase	月相、照明度、月亮星座、接下来的四个盈亏时点
find_eclipses	日食／月食及其星座，包括当地可见性
find_retrograde_periods	任意行星开始逆行／恢复顺行的时刻
find_sign_ingresses	星体换座的时刻（春分点、土星入座等）
find_aspect_times	行运形成精确相位的时刻（“土星什么时候与我的太阳形成刑相？”）

此外还提供两个提示词（natal_chart_reading、current_sky_report）和一个术语表资源（auseklis://glossary）。

功能： 支持使用 IANA 时区的当地出生时间（完整处理历史夏令时）· 回归黄道和恒星黄道（Lahiri、Fagan/Bradley）· 整宫制、等宫制、Porphyry 和 Placidus 宫位制· 平均月交点和黑月莉莉丝· 福点（古典昼夜公式）。

安装

Claude Code

claude mcp add auseklis -- npx -y auseklis

Claude Desktop／任意 MCP 客户端（stdio）

{
  "mcpServers": {
    "auseklis": {
      "command": "npx",
      "args": ["-y", "auseklis"]
    }
  }
}

无需 API 密钥或配置——星历在本地计算。

桌面扩展

从发布页面下载 auseklis.mcpb，然后双击即可在 Claude Desktop 中安装。也可以自行构建：npm run bundle。

远程（可自托管）

同一服务也可以作为通过 Streamable HTTP 通信的 Cloudflare Worker 运行。将其部署到自己的账户：

npm run deploy   # wrangler deploy
claude mcp add --transport http auseklis https://auseklis.<your-subdomain>.workers.dev/mcp

设置 MCP_SHARED_SECRET 密钥以要求使用 bearer token。

库用法

星历核心（src/ephemeris/ 下的所有内容）可直接导入——无需 MCP 客户端或子进程。这种方式适用于无服务器运行时（Vercel、Workers），因为无法为每个请求启动 npx auseklis：

import { computeNatalChart } from "auseklis/ephemeris";
import { findRetrogradePeriods } from "auseklis/ephemeris/events";
import { findEclipses } from "auseklis/ephemeris/eclipses";

const chart = computeNatalChart({
  utc: "1990-03-15T13:45:00Z",
  location: { latitude: 56.95, longitude: 24.11 }, // Riga
  houseSystem: "placidus",
});

auseklis/ephemeris 包含星盘计算（本命盘、行运、比较盘、合盘、推运、单点位置、轴点），以及用于当地时间 → UTC 转换的 resolveInstant；…/events 和 …/eclipses 则包含时域搜索功能。类型完整，仅支持 ESM，无数据文件。

可询问的示例问题

• “计算我的本命盘——出生于 1990 年 3 月 15 日 15:45，地点是 Riga。”
• “这个月有哪些行星正在行运我的太阳？”
• “我的土星回归具体是什么时候？”
• “我和伴侣的比较盘如何？”（提供两人的出生日期／时间）
• “2027 年水星什么时候逆行，分别在哪些星座？”
• “今晚的满月在这里能以月食的形式看到吗？”

模型负责将地名转换为坐标；服务通过 IANA 时区数据库负责将当地时间转换为 UTC。

精度

位置数据来自 astronomy-engine（VSOP87 + NOVAS C 3.1）：在 1700–2200 年间精度为 ±1 角分，远高于占星解读使用的 1° 分辨率。事件搜索（留逆、入座、回归、盈亏时点）的时间精确到约 1 秒。已在 CI 中通过已公布的日食日期、2026 年春分、NOVAS 太阳位置以及独立的 Placidus 实现进行验证。

架构

src/
├── ephemeris/        Astrology core — backend-agnostic
│   ├── engine.ts     EphemerisBackend interface + astronomy-engine adapter (the swap seam)
│   ├── index.ts      Charts, aspects, synastry, composite, progressions
│   ├── events.ts     Time searches: returns, stations, ingresses, aspect times, moon phases
│   ├── eclipses.ts   Eclipse searches with astrological context
│   ├── houses.ts     Whole-sign, equal, Porphyry, Placidus (semi-arc solver)
│   ├── points.ts     Mean lunar nodes, Black Moon Lilith
│   ├── sidereal.ts   Ayanamsa (Lahiri, Fagan/Bradley)
│   └── time.ts       IANA timezone → UTC conversion (no dependencies, uses Intl)
├── mcp/              Tool/prompt/resource definitions on @modelcontextprotocol/sdk
├── stdio.ts          Local entry — `npx auseklis`
└── index.ts          Remote entry — Cloudflare Worker, Streamable HTTP via @hono/mcp

engine.ts 中的 EphemerisBackend 接口是有意预留的替换接口：未来只需重新实现该接口，即可接入采用清洁室方式开发的 Rust/WASM 星历。

开发

npm install
npm run typecheck   # strict TS
npm test            # 23-check smoke suite (ephemeris references + MCP end-to-end)
npm run build       # emit dist/
npm run dev         # local Cloudflare Worker on :8787
npx @modelcontextprotocol/inspector node dist/stdio.js   # poke tools interactively

完整的工具参考请参阅 docs/tools.md，设计说明请参阅 docs/architecture.md。

许可

MIT。本项目有意避开 Swiss Ephemeris（.se1/.se2 数据文件和 sweph 绑定）：它们采用 AGPL 许可，这会使基于它们构建的任何网络服务都负有遵守 AGPL 的义务。此处的所有内容均由 MIT 许可的代码计算得出，不依赖外部数据文件，可放心嵌入、分叉并用于商业部署。详情请参阅 NOTICE。

取舍是：不支持 Chiron 或小行星（它们需要星历数据文件）。已将其列入路线图，计划通过公有领域的 JPL 衍生数据实现。

路线图

• v1：在相同的 EphemerisBackend 接口后，提供 Rust/WASM 洁净室星历后端
• 使用公有领域的 JPL 数据支持 Chiron + 主要小行星
• Koch 宫位制、赤纬／平行相位