AstroNest — Vedic Astrology & Ephemeris

AstroNest：为应用和 AI Agent 提供吠陀占星服务

AstroNest 是一款吠陀占星（Jyotiṣa）引擎，可通过 REST API 调用，也可通过 MCP 连接到 AI Agent。它基于自己的 JPL DE440 星历进行计算，解读结果是确定性的：相同的出生数据始终会得到相同的答案，并附上解读依据和所依据的古典典籍。

此仓库包含两部分内容：将 AstroNest 连接到 AI Agent 的方法，以及使用 REST API 的 Next.js 快速入门。

• 文档：https://www.astronest.ai/developers
• OpenAPI 3.1 规范：https://www.astronest.ai/openapi/astronest-v1.json
• Postman：AstroNest Developer API 工作区
• 密钥：https://www.astronest.ai/developer。Sandbox 密钥免费，并会返回固定样例。

将其连接到 AI Agent（MCP）

端点（Streamable HTTP）：https://www.astronest.ai/api/developer/mcp

Claude Code

claude mcp add --transport http astronest https://www.astronest.ai/api/developer/mcp \
  --header "Authorization: Bearer YOUR_ASTRONEST_KEY"

mcp.json（Cursor、VS Code 和其他读取此格式的客户端）

{
  "mcpServers": {
    "astronest": {
      "url": "https://www.astronest.ai/api/developer/mcp",
      "headers": { "Authorization": "Bearer YOUR_ASTRONEST_KEY" }
    }
  }
}

也可通过 Smithery 和 MCP Registry 使用，名称为 io.github.onedotlinks/astronest。

Agent 可以向它询问什么

每个工具回答一个问题。解读类工具会像占星师一样解读星盘，并返回依据，而不只是行星位置：

工具	回答的问题
get_life_reading	我的人生整体如何——哪些领域（婚姻、子女、事业、金钱、房产……）会在何时成为焦点，包括过去和未来？
get_domain_timeline	婚姻、事业或其他领域何时会成为焦点？未来几年在这方面会如何？
get_relationship_reading	两个人作为商业伙伴、兄弟姐妹、亲子或朋友，相处得如何？
get_venture_timing	我应该何时启动项目、签约或借款？我的星盘支持从事哪类业务？
assess_gemstone	我应该佩戴这种宝石（蓝宝石、pukhraj、祖母绿……）吗？为什么？
get_compatibility、get_guna_milan	Kundli 配对：36 分制 Aṣṭakūṭa 评分、基于上升点、月亮和金星的 Manglik 分析，以及完整的双方解读
interpret_domain、get_guidance	我的星盘对某个人生领域有何提示？当前运行周期对我有何要求？
find_muhurta	在某个日期范围内，哪些日子和时间段适合举办活动？
get_chart、get_dasha、星历工具	星盘（含 16 张分盘）、从 Vimśottarī daśā 到 pratyantar 的大运周期，以及原始 JPL DE440 位置数据

解读会说明星盘显示了什么以及原因。这些是象征性解读，并非预测，也不是医疗、法律、财务或心理建议；每条回复都带有此免责声明。

Next.js 快速入门

一个基于 AstroNest Developer API 的小型 Next.js 应用。输入出生日期、时间和地点，即可获取：

• 星盘：上升点、九大 graha 的星座、宫位、nakṣatra 和尊贵状态，以及当前运行的 daśā（1 个积分）
• 当前指引：以通俗语言呈现当前运行的 mahādaśā / antardaśā / pratyantardaśā（3 个积分）
• 领域解读：事业、婚姻、财务及其他 12 个领域，包含支持因素、注意事项、时间窗口，以及相互印证的方法数量（5 个积分）
• 可选：使用你自己的大模型进行 “用通俗语言解释”（不消耗 AstroNest 积分）

这三个 AstroNest 调用都不使用语言模型。它们是确定性的，因此几秒内即可返回结果，且相同的输入始终会得到相同的答案。

五分钟内运行

1. 获取密钥。 在 https://www.astronest.ai/developer 登录并创建密钥。每个账户可一次性获得 100 个免费实时额度，自首次创建实时密钥起 60 天内有效（不会续期）：足够进行约 20 次领域解读或绘制 100 张星盘。 沙盒密钥免费且没有时间限制，并会返回固定的示例响应。免费额度用完或 60 天期限结束后，实时调用会返回 402 credits_exhausted，直到你购买额度包；沙盒密钥仍可继续使用。
2. 安装并配置。

   npm install
   cp .env.example .env.local
   # put your key in ASTRONEST_API_KEY
   

3. 运行。

   npm run dev
   

   打开 http://localhost:3000。

工作原理

browser ──► /api/astronest/{chart|guidance|interpret} ──► AstroNest API   (your key, server-side)
        └─► /api/explain ──────────────────────────────► your LLM         (optional)

• lib/astronest.ts 是一个类型化客户端。你可以将这个文件复制到自己的应用中。
• app/api/astronest/[op]/route.ts 仅转发这三个操作，因此无法通过该路由调用密钥允许的所有端点。
• app/api/explain/route.ts 会将 AstroNest 计算出的解读发送到任意兼容 OpenAI 的 chat-completions 端点（OpenAI、Vercel AI Gateway、OpenRouter、本地 Ollama），并指示模型只使用提供给它的事实。模型负责撰写内容；AstroNest 负责占星计算。

部署前须知

• 密钥属于机密信息。 它只存储在服务器环境变量中。切勿为其添加 NEXT_PUBLIC_ 前缀，也切勿从浏览器调用 API。API 不会发送 CORS 标头，因此浏览器调用无论如何都会失败。
• 任何调用演示路由的人都会消耗你的额度。 默认情况下，这些路由只会响应来自 localhost 的请求。在将 ALLOW_PUBLIC_DEMO=true 设为启用之前，请先在路由前添加自己的登录验证（最好也设置速率限制）。本地检查会读取请求主机，因此如果代理重写了 Host，请勿依赖此检查。
• 出生数据属于个人数据。 此应用不会存储任何数据，API 也不会存储。如果你添加存储功能，就需要承担相应的数据保护责任。
• **请展示每次响应附带的免责声明：**内容为象征性解读，不构成医疗、法律、财务或心理建议。

深入探索

端点	点数	说明
POST /v1/chart	1	添加 location，用于占星地图和迁移后的星盘
POST /v1/dasha	1	完整的 Vimśottarī 时间线
POST /v1/guidance	3	使用 referenceDate 指定其他任意时刻
POST /v1/interpret	5	15 个领域
POST /v1/timing/resolve	7	由大模型生成解读；请预留 90 秒
POST /v1/forecast	8	由大模型生成解读；请预留 90 秒
POST /v1/muhurta	10	指定日期范围内的吉时
POST /v1/compatibility	12	合并解读两张星盘
POST /v1/guna-milan	2	两人配对的 36 分制 Aṣṭakūṭa 匹配度 + Manglik（上升点、月亮、金星）
POST /v1/life-reading	10	全人生解读：人生章节和 11 个生活领域，涵盖过去与未来（areas 可缩小范围）
POST /v1/domain-timeline	3	纵观一生的某个生活领域：列出影响该领域的所有时期，也可指定日期范围
POST /v1/relationship	8	商业伙伴、兄弟姐妹、父母与子女、朋友：关系宫位、星盘间联系、关系指标
POST /v1/venture-timing	10	何时投入、建设、守护或暂缓；根据星盘为你描述的企业排序
POST /v1/gem-assessment	5	这张星盘是否适合佩戴这颗宝石：给出结论、支持和反对的所有依据，以及依据的有效时长
POST /v1/ephemeris/positions	0.1	某一时刻的原始位置（JPL DE440）；无需出生数据
POST /v1/ephemeris/angles	0.1	某一时刻和地点的上升点、MC 和宫位宫头
POST /v1/ephemeris/ayanamsa	0.1	Lahiri、Raman、Krishnamurti、Fagan–Bradley
POST /v1/ephemeris/sunrise	0.1	当地日期的日出、日落和次日日出时间
POST /v1/ephemeris/series	1	每开始 100 个点计 1 点，最多 1,000 个

四种单时刻 Ephemeris 调用各收费 0.1 点：每开始 10 次调用计 1 点，按账户跨这些调用合并计算（开启新计费区间的调用会报告 units_charged: 1，之后九次报告 0）。 仅对成功的（2xx）调用收费。点数用完后，API 会返回 402 credits_exhausted；请在开发者门户购买点数包。付费点数不会过期。

• OpenAPI 3.1 规范：https://www.astronest.ai/openapi/astronest-v1.json（导入 Postman，或用任意语言生成客户端）
• 参考资料：开发者门户 https://www.astronest.ai/developer