Unified Reading

unified-reading

面向公共 Unified Reading API 的 SDK、CLI 和 stdio MCP 服务。提供出生日期，即可返回生命灵数、西方太阳星座和中国生肖。还包含 1924—2044 年的农历新年表。无需 API 密钥，也不会存储任何数据。

请只发送出生日期，不要发送姓名、出生时间或地点。完整的个人解读请访问 unifiedreading.com。

CLI

npx unified-reading profile 1990-07-14

1990-07-14
Life Path   4  The Builder
Sun sign    ♋ Cancer, decan 3 (Water, Cardinal, ruled by Moon)
Chinese     Yang Metal Horse

命令	功能
unified-reading profile <YYYY-MM-DD>	查询一个日期对应的生命灵数、太阳星座和中国生肖
unified-reading batch <YYYY-MM-DD>...	查询最多 20 个日期的相同信息
unified-reading year <YYYY>	查询一个中国生肖年份及其农历新年起止日期
unified-reading years [--limit N] [--cursor YYYY] [--all]	分页浏览年份表
unified-reading mcp	作为 stdio MCP 服务运行

任何命令都可以添加 --json，以获取原始 API 响应。--base-url 用于将 CLI 指向其他源站。

MCP 服务

unified-reading mcp 会运行一个 stdio MCP 服务，将请求转发到 https://unifiedreading.com/mcp 上的远程服务。它适用于只能启动本地命令的 MCP 客户端：

{ "mcpServers": { "unified-reading": { "command": "npx", "args": ["-y", "unified-reading", "mcp"] } } }

该服务提供用于查询选项、出生日期资料（附带 MCP Apps 卡片）和中国生肖年份的工具。它已在官方 MCP 注册表中登记，名称为 com.unifiedreading/unified-reading。

SDK

需要 Node 18 或更高版本，或任何支持 fetch 的运行时。

import { UnifiedReading, UnifiedReadingError } from "unified-reading";

const client = new UnifiedReading();

const profile = await client.profile("1990-07-14");
console.log(profile.lifePath.number, profile.sunSign.sign, profile.chineseZodiac.animal); // 4 Cancer Horse

const results = await client.profiles(["1990-07-14", "1990-01-20"], { idempotencyKey: crypto.randomUUID() });

for await (const year of client.allChineseZodiacYears()) {
  console.log(year.year, year.animal, year.starts, year.ends);
}

try {
  await client.profile("1990-02-30");
} catch (error) {
  if (error instanceof UnifiedReadingError) console.log(error.code, error.hint); // invalid_date ...
}

方法	端点
profile(date)	GET /api/v1/profile?date=
profiles(dates, { idempotencyKey })	POST /api/v1/profiles/batch
chineseZodiacYears({ limit, cursor })	GET /api/v1/chinese-zodiac/years（单页）
allChineseZodiacYears()	通过异步迭代器获取所有页面
chineseZodiacYear(year)	查询某一年；若年份不在 1924—2044 年范围内，则返回 null

日期可以是 YYYY-MM-DD 字符串或 Date 对象；传入 Date 时，会按其本地日历日期发送。发生错误时会抛出 UnifiedReadingError，其中包含 status、code、hint 和 retryAfter。该 API 对每个 IP 的请求速率限制为每分钟 10 次。

链接

• API 指南：https://unifiedreading.com/docs
• OpenAPI 规范：https://unifiedreading.com/openapi.json
• MCP 服务（为 AI Agent 提供相同的计算）：https://unifiedreading.com/mcp
• 源码：https://github.com/emrecolako/unified-reading/tree/main/sdk
• 问题反馈：https://github.com/emrecolako/unified-reading/issues（请勿提供个人数据），或发送邮件至 [email protected]