Skip to main content
Glama
xiaoyu312

fateclear-solar-time

by xiaoyu312
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

fateclear-solar-time

CI License: MIT

中文 | English

真太阳时、二十四节气精确时刻、中国 1986–1991 年夏令时，一个小 TypeScript 库，附带 MCP 服务，AI 助手可以直接调用。由 拨云 FateClear 维护。

在线演示： 拨云 FateClear 八字排盘，填出生时间和地点，会显示换算后的真太阳时。

能做什么

  • 真太阳时：钟表时间 + 经度 → 当地真太阳时。包含经度修正（每度 4 分钟）和均时差（太阳实际位置和平均位置的差，一年里在 −14 到 +16 分钟之间）。

  • 二十四节气：任意公历年份 24 个节气的交节时刻，精确到秒，给出 UTC 和北京时间。按太阳视黄经计算。

  • 中国夏令时：1986–1991 年每年的起止时间。出生时间落在夏令时里会自动减 1 小时，也标出“不存在”（拨快跳过的那 1 小时）和“有歧义”（拨回重复的那 1 小时）的时刻。

Related MCP server: Chinese Fortune Analysis System (BaZi)

安装

npm install github:a18565517703-ctrl/fateclear-solar-time

目前直接从 GitHub 安装，安装时会自动编译。npm 包稍后发布。

用法

import { trueSolarTime, solarTerms, solarTerm, chinaDstStatus } from "fateclear-solar-time";

// 1990-03-12 23:30 出生在北京（东经 116.4°）
const r = trueSolarTime({ year: 1990, month: 3, day: 12, hour: 23, minute: 30, longitude: 116.4 });
r.trueSolarText;              // "1990-03-12 23:05:50"
r.longitudeCorrectionMinutes; // -14.4
r.equationOfTimeMinutes;      // 约 -9.8

// 1988 年夏天的钟表时间会自动扣掉夏令时
trueSolarTime({ year: 1988, month: 7, day: 1, hour: 12, minute: 0, longitude: 120 }).dstCorrectionMinutes; // -60

// 2026 年的 24 节气
solarTerms(2026).map((t) => `${t.zh} ${t.beijing}`);
solarTerm(1990, "立春").beijing; // "1990-02-04 10:13:58"

参数说明：

参数

说明

longitude

东经为正，西经为负

utcOffset

钟表所在时区，默认 8（北京时间）

dst

"auto"（默认，按 1986–1991 年表自动判断）、true（强制减 1 小时）、false（不处理）

eot

"precise"（默认，按天文位置算）或 "simple"（三项近似公式，和精确值差 2 分钟以内）

MCP 服务

{
  "mcpServers": {
    "fateclear-solar-time": { "command": "npx", "args": ["-y", "github:a18565517703-ctrl/fateclear-solar-time"] }
  }
}

提供三个工具：true_solar_time、solar_terms、china_dst。

精度

  • 节气时刻用 astronomy-engine 算太阳视黄经，1900–2100 年抽样和 tyme4ts 对比，差不到 2 分钟。

  • 夏令时表在测试里和 IANA 时区库逐条核对。

  • 真太阳时只做时间换算，不涉及任何命理判断。

协议

MIT。依赖见 THIRD_PARTY_NOTICES.md。配套数据集：fateclear-calendar-data（1900–2100 年节气、干支、农历）。

English

A small TypeScript library for true (apparent) solar time, exact moments of the 24 Chinese solar terms, and China's 1986–1991 daylight saving time, with an MCP server so AI assistants can call it directly. Maintained by 拨云 FateClear.

Live demo: FateClear BaZi chart shows the converted true solar time for any birth time and place.

Features

  • True solar time: clock time + longitude → local apparent solar time, with longitude correction (4 min per degree) and the equation of time (−14 to +16 min over the year).

  • 24 solar terms: exact moments (to the second) for any Gregorian year, in UTC and Beijing time, from the Sun's apparent ecliptic longitude.

  • China DST 1986–1991: start/end of each year's DST; clock times inside DST are corrected by −1 hour, and skipped or repeated hours are flagged as nonexistent / ambiguous.

Install & use

npm install github:a18565517703-ctrl/fateclear-solar-time

Installs straight from GitHub and builds on install. An npm package will follow later.

import { trueSolarTime, solarTerms } from "fateclear-solar-time";

trueSolarTime({ year: 1990, month: 3, day: 12, hour: 23, minute: 30, longitude: 116.4 }).trueSolarText;
// "1990-03-12 23:05:50"
solarTerms(2026); // 24 terms with utc and beijing times

Options: longitude (east positive), utcOffset (hours, default 8), dst ("auto" | true | false), eot ("precise" | "simple").

MCP server

Add the config above to your MCP client (runs straight from GitHub, no npm package needed). Tools: true_solar_time, solar_terms, china_dst.

Accuracy

Solar terms are computed with astronomy-engine and agree with tyme4ts within 2 minutes across a 1900–2100 sample. The DST table is verified against the IANA tz database in tests.

License

MIT. See THIRD_PARTY_NOTICES.md. Companion dataset: fateclear-calendar-data.

Available Tools

3 tools
china_dstB

China daylight saving time 1986–1991: the full table, or the status of one clock time.

ParametersJSON Schema
NameRequiredDescriptionDefault
datetimeNo

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It conveys the historical validity window (1986–1991) but says nothing about what happens for out-of-range input, how ambiguous/duplicated clock times during transitions are resolved, or the shape of the returned table/status. For a reference tool with zero annotation coverage this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence, front-loaded with the resource and scope, with no filler. It is slightly cryptic ('status of one clock time') but every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description should explain the return values and error behavior more fully. It covers the two-mode contract adequately but leaves the agent guessing about output format, out-of-range handling, and timezone interpretation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for the single 'datetime' parameter, so the description must compensate. It does partially by implying datetime means 'one clock time' whose DST status is returned, and that omitting it yields the full table, but it gives no format, timezone, or range constraints for the value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource and scope ('China daylight saving time 1986–1991') plus the two modes of output (full table vs. status of one clock time). It is clear what the tool returns, but it never differentiates itself from the time-related siblings (true_solar_time, solar_terms), leaving the agent to infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'the full table, or the status of one clock time' implicitly tells the agent when to omit vs. supply datetime, which is genuine routing guidance. However, no explicit when-to-use framing, no exclusions, and no mention of the sibling tools or edge cases (e.g. datetimes outside 1986–1991).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

solar_termsA

List the exact moments (UTC and Beijing time) of the 24 solar terms for a Gregorian year, or one term if name is given.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNoe.g. 立春 / Start of Spring
yearYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It does disclose useful behavioral detail — the return values are exact moments in both UTC and Beijing time, and the result set shrinks to one term when name is supplied. However, it says nothing about precision, date-range limits, or error behavior for invalid names, leaving gaps for a no-annotation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that states the resource, the output time bases, and the parameter-driven branching with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read-only lookup with no output schema, the description tells the agent what is returned (UTC and Beijing times) and how name changes the result. Sufficient to call correctly, with only minor gaps around name format and precision.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%: name has an example ('立春 / Start of Spring') and year has only type/bounds in the schema. The description adds genuine meaning by tying name to the single-term output mode, but it does not explain accepted name formats beyond the schema example or any year limitations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (List) and a precise resource (the exact moments of the 24 solar terms), plus the scope (Gregorian year) and the narrowing behavior (one term if name is given). This is clearly distinguishable from the astronomy/time siblings true_solar_time and china_dst.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: pass a year to get all 24 terms, or pass name to get one. There is no explicit when-to-use, when-not-to-use, or mention of the sibling tools, so the agent must infer selection from the single sentence.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

true_solar_timeB

Convert a clock birth time at a longitude into local true solar time (longitude correction + equation of time, China 1986–1991 DST aware).

ParametersJSON Schema
NameRequiredDescriptionDefault
dstNo
eotNo
datetimeYesClock time 'YYYY-MM-DD HH:mm' or 'YYYY-MM-DDTHH:mm[:ss]'
latitudeNo
longitudeYesEast longitude in degrees, west negative
utcOffsetNoClock UTC offset in hours, default 8

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does disclose key computation details: longitude correction, equation of time, and DST awareness for China 1986–1991. However, it does not describe the return format, precision behavior, or error handling, leaving significant gaps for a computation tool with no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. The parenthetical efficiently bundles the key technical qualifiers without overwhelming the reader.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter tool with no annotations, no output schema, and only 50% schema coverage, one sentence is insufficient. It omits return value details, latitude usage, parameter option meanings, and any caveats beyond the China 1986–1991 DST window.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 50%, so the description should compensate for undocumented parameters. It hints at equation of time and DST awareness, which loosely map to the eot and dst parameters, but it never explains latitude, utcOffset defaults, or the enum values for eot and dst.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Convert') and resource ('clock birth time at a longitude into local true solar time'), with clarifying scope like longitude correction, equation of time, and China 1986–1991 DST awareness. It is clearly distinct from sibling tools by purpose, though it does not explicitly name solar_terms or china_dst to differentiate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool does but gives no guidance on when to use it versus alternatives such as solar_terms or china_dst. There are no exclusions, prerequisites, or selection conditions to help an agent choose among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedchina_dst
    • First observedsolar_terms
    • First observedtrue_solar_time
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a clearly distinct operation: one converts clock time to true solar time, one lists astronomical solar terms, and one provides China DST data/status. The DST awareness mentioned in true_solar_time does not create ambiguity because china_dst is a standalone lookup tool.

Naming Consistency5/5

All three tools use a consistent snake_case noun-phrase pattern (true_solar_time, solar_terms, china_dst), with no mixing of conventions. The names are descriptive and predictable.

Tool Count5/5

Three tools is a well-scoped set for a specialized solar-time utility. Each tool covers a distinct need without redundancy, fitting the typical 3-15 range.

Completeness4/5

The surface covers core needs: true solar time conversion, solar term moments, and China DST data. A minor gap is the lack of a reverse conversion (true solar time back to clock time) or broader timezone handling, but agents can work around this.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • BaZi (Eight Characters)

    minionszyw
    F
    license
    Not graded
    quality
    Not graded
    maintenance
    Calculates Chinese BaZi (Four Pillars of Destiny) charts based on birth date, time, and location, including solar term information, decade luck cycles, and true solar time corrections.
    2
    -

  • Chinese Fortune Analysis

    deeppath-ai
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables traditional Chinese fortune-telling through BaZi (Four Pillars) analysis, including solar/lunar date conversion, Five Element balance calculations, Ten Gods deduction, and destiny interpretation for metaphysics applications.
    11 npm
    MIT
  • OpenFate Bazi MCP by openfate-ai

    OpenFate Bazi MCPofficial

    openfate-ai
    A
    license
    A
    quality
    A
    maintenance
    Enables AI agents to calculate deterministic Bazi (Four Pillars) charts with True Solar Time and Earthly Branch interactions, avoiding LLM hallucination of calendrical math.
    6
    60 npm
    159
    MIT

  • Jueshan Paipan MCP

    Riki-1124
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides precise Chinese metaphysics chart calculation (Bazi, Ziwei, Qimen) with true solar time correction, outputting structured JSON and Markdown for AI integration.
    3
    MIT