内容
# 奥塞克利斯
**占星学MCP服务器** — 生日图、行星 transit、星盘对比、推进、回归、月相、日食、星辰逆行。所有计算均基于真实星历数据，因此AI代理不会出现天体位置的幻觉。
以拉脱维亚晨星命名。采用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时区（完整的历史DST处理）· 热带和恒星（Lahiri、Fagan/Bradley）黄道 · 全星座、等分、Porphyry和Placidus宫位系统 · 平均月节点和黑月亮 · 幸运点（经典日/夜公式）。
## 安装
### Claude 代码
```bash
claude mcp add auseklis -- npx -y auseklis
```
### Claude Desktop / 任意MCP客户端（stdio）
```json
{
"mcpServers": {
"auseklis": {
"command": "npx",
"args": ["-y", "auseklis"]
}
}
}
```
无需API密钥，无需配置 — 星历数据在本地计算。
### 桌面扩展
从[发布页面](https://github.com/igmizo/auseklis/releases)下载`auseklis.mcpb`，双击安装到Claude Desktop。或者自行构建：`npm run bundle`.
### 远程（自行托管）
相同的服务器作为Cloudflare Worker运行，使用Streamable HTTP通信。将它部署到您自己的账户：
```bash
npm run deploy # wrangler deploy
claude mcp add --transport http auseklis https://auseklis.<your-subdomain>.workers.dev/mcp
```
设置`MCP_SHARED_SECRET`密钥以要求携带者令牌。
## 库的使用
星历核心（`src/ephemeris/`下的所有内容）可以直接导入 — 无需MCP客户端或子进程。这对于无服务器运行时（Vercel、Workers）尤其适用，因为在每个请求上启动`npx auseklis`不是一个可行的选择：
```ts
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`包含图表数学（出生、行星transit、星盘对比、复合、推进、单一位置、角度）以及`resolveInstant`用于本地时间转换为UTC；`…/events`和`…/eclipses`包含时间域搜索。完全类型化，仅支持ESM，无数据文件。
## 示例问题
- *"计算我的出生星盘 — 1990年3月15日出生，15:45，在 Riga."*
- *"这个月有哪些行星在 transit 我的太阳？)*
- *"我的土星回归的确切时刻是什么？"*
- *"我和我的伴侣之间的星盘对比？"* （两个出生日期/时间）
- *"2027年水星逆行的时间和星座是什么？)*
- *"今晚的满月从这里看是否可见为日食？"*
模型处理地名转换为坐标；服务器通过IANA时区数据库处理本地时间转换为UTC。
## 精确度
位置来自[astronomy-engine](https://github.com/cosinekitty/astronomy)（VSOP87 + NOVAS C 3.1）：±1弧分，适用于1700-2200年，远低于1°分辨率的占星解释使用。事件搜索（站立、进入、回归、四分之一月）精确到约1秒。 在CI中与已发布的月食日期、2026年春分、NOVAS太阳位置和独立的Placidus实现进行验证。
## 架构
```
src/
├── ephemeris/ 占星学核心 — 后端无关
│ ├── engine.ts EphemerisBackend 接口 + astronomy-engine 适配器（交换缝）
│ ├── index.ts 星图、相位、星盘对比、复合、推进
│ ├── events.ts 时间搜索：回归、站立、进入、相位时间、月相
│ ├── eclipses.ts 月食/日食搜索，包含占星学背景
│ ├── houses.ts 全星座、等分、Porphyry、Placidus（半弧求解器）
│ ├── points.ts 平均月节点、黑月亮
│ ├── sidereal.ts Ayanamsa（Lahiri、Fagan/Bradley）
│ └── time.ts IANA时区 → UTC转换（无依赖，使用Intl）
├── mcp/ 工具/提示/资源定义在@modelcontextprotocol/sdk
├── stdio.ts 本地入口 — `npx auseklis`
└── index.ts 远程入口 — Cloudflare Worker，通过@hono/mcp实现Streamable HTTP
```
`engine.ts`中的`EphemerisBackend`接口是一个刻意的交换缝：未来的Rust/WASM清洁室星历只需重新实现该接口。
## 开发
```bash
npm install
npm run typecheck # 严格的TS检查
npm test # 23检查套件（星历参考 + MCP端到端）
npm run build # 生成dist/
npm run dev # 本地Cloudflare Worker在:8787
npx @modelcontextprotocol/inspector node dist/stdio.js # 交互式测试工具
```
参见[docs/tools.md](docs/tools.md)获取完整的工具参考，[docs/architecture.md](docs/architecture.md)获取设计说明。
## 许可
MIT。本项目故意避免使用Swiss Ephemeris（`.se1`/`.se2`数据文件和`sweph`绑定）：这些是AGPL许可的，这将对使用它们构建的任何网络服务施加AGPL义务。这里所有内容都使用MIT许可的代码计算，无外部数据文件 — 可以安全地嵌入、fork和商业部署。详情参见[NOTICE](NOTICE)。
权衡：没有Chiron或小行星（它们需要星历数据文件）。它们在通过公共领域JPL数据在路线图中可用。
## 路线图
- v1：Rust/WASM清洁室星历后端，位于同一`EphemerisBackend`缝隙后
- 通过公共领域JPL数据添加Chiron + 主要小行星
- Koch宫位系统，赤纬/平行相位
