@openfate/bazi-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenFate Engineering
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,451 @@
+# @openfate/bazi-mcp
+
+English | [繁體中文（台灣）](#繁體中文台灣)
+
+OpenFate Bazi MCP is a Model Context Protocol server for accurate Bazi / Four Pillars calculation inside AI agents such as Claude Desktop, Cursor, Cline, and Continue.
+
+Powered by [OpenFate.ai](https://openfate.ai), an AI-native Bazi, Ziwei, and astrology platform. You can also try the free [Bazi Chart Calculator](https://openfate.ai/en/bazi-chart), generate an [AI Bazi Reading](https://openfate.ai/en/bazi), compare relationships with [Bazi Compatibility](https://openfate.ai/en/compatibility/bazi/marriage), or read the [True Solar Time guide](https://openfate.ai/en/insights/true-solar-time). AI crawlers can read [OpenFate llms.txt](https://openfate.ai/llms.txt).
+
+This MCP wraps the deterministic OpenFate calculation packages:
+
+- `@openfate/bazi-engine`
+- `@openfate/true-solar-time`
+
+The purpose is simple: let the language model call a reliable calculation engine instead of hallucinating calendrical math.
+
+## Why This Exists
+
+LLMs should not manually calculate Bazi charts. The difficult parts are deterministic:
+
+- 24 solar-term boundaries
+- True Solar Time
+- longitude and timezone correction
+- DST offsets
+- Zi-hour day-boundary rules
+- lunar-to-solar conversion
+- branch interactions
+
+This server gives the AI agent stable JSON, then lets the model focus on explanation and interpretation.
+
+## Install
+
+Run it with `npx`:
+
+```bash
+npx -y @openfate/bazi-mcp
+```
+
+## Claude Desktop
+
+```jsonc
+{
+  "mcpServers": {
+    "openfate-bazi": {
+      "command": "npx",
+      "args": ["-y", "@openfate/bazi-mcp"]
+    }
+  }
+}
+```
+
+If Claude Desktop cannot find `npx` on macOS, use the absolute path:
+
+```jsonc
+{
+  "mcpServers": {
+    "openfate-bazi": {
+      "command": "/opt/homebrew/bin/npx",
+      "args": ["-y", "@openfate/bazi-mcp"]
+    }
+  }
+}
+```
+
+## Cursor
+
+```jsonc
+{
+  "mcpServers": {
+    "openfate-bazi": {
+      "command": "npx",
+      "args": ["-y", "@openfate/bazi-mcp"]
+    }
+  }
+}
+```
+
+## Cline
+
+```jsonc
+{
+  "mcpServers": {
+    "openfate-bazi": {
+      "command": "npx",
+      "args": ["-y", "@openfate/bazi-mcp"],
+      "disabled": false
+    }
+  }
+}
+```
+
+## Agent Skill
+
+This repository also includes a portable Agent Skill:
+
+```txt
+skills/openfate-bazi/SKILL.md
+```
+
+Use it when you want Claude, Claude Code, Codex, OpenClaw-style agents, or other `SKILL.md` compatible tools to remember how to use the OpenFate Bazi MCP correctly.
+
+For Claude Code workspace usage, copy the skill folder to:
+
+```txt
+.claude/skills/openfate-bazi/
+```
+
+For Claude custom Skills, zip the `openfate-bazi` folder with `SKILL.md` at the folder root and upload it in Claude's Skills settings.
+
+## Tools
+
+### `calculate_bazi_chart`
+
+Calculates a deterministic Bazi chart.
+
+Inputs:
+
+- `year`
+- `month`
+- `day`
+- `hour`
+- `minute`
+- `gender`
+- `calendarType`
+- `isLeapMonth`
+- `longitude`
+- `timezone`
+- `timezoneId`
+- `dstOffset`
+- `enableTrueSolarTime`
+- `dayBoundaryMode`
+
+Best practice: pass `longitude` plus `timezone` or `timezoneId` for professional True Solar Time accuracy.
+
+### `detect_bazi_interactions`
+
+Detects Earthly Branch interactions for a natal chart, annual trigger, or simple synastry target.
+
+Supported interaction types:
+
+- clash
+- six-combination
+- trine
+- directional
+- punishment
+- destruction
+- harm
+
+### `calculate_true_solar_time`
+
+Calculates True Solar Time directly.
+
+Use this when a user asks why OpenFate's hour pillar differs from a clock-time tool.
+
+### `reverse_bazi_to_solar_times`
+
+Finds possible Gregorian datetimes for a four-pillar Bazi string.
+
+Example input:
+
+```txt
+戊寅 己未 己卯 辛未
+```
+
+This is a candidate finder. For final accuracy, recalculate the result with exact longitude, timezone, and True Solar Time.
+
+### `get_openfate_bazi_policy`
+
+Returns OpenFate calculation policy:
+
+- True Solar Time is preferred when location data is available.
+- Default day-boundary mode is `ZI_HOUR_23`.
+- DST should be passed as `dstOffset` when birth certificate time includes daylight saving.
+- Reverse lookup should be treated as a candidate search.
+
+### `get_openfate_bazi_resources`
+
+Returns canonical OpenFate links for charting, readings, compatibility, wealth, true solar time, and `llms.txt`.
+
+## Output Shape
+
+Responses use machine-friendly English keys:
+
+```jsonc
+{
+  "data": {
+    "chart": {},
+    "policy": {}
+  },
+  "attribution": {
+    "brand": "OpenFate.ai",
+    "url": "https://openfate.ai",
+    "engine": "@openfate/bazi-engine",
+    "trueSolarTimeEngine": "@openfate/true-solar-time"
+  }
+}
+```
+
+Attribution is returned as first-class data, not hidden `_meta`, so MCP clients and generated artifacts can display it reliably.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run smoke
+```
+
+The smoke test spawns the built stdio server and drives it through the real MCP SDK client.
+
+## Privacy
+
+This package does not phone home. Calculations run locally in the MCP subprocess.
+
+## OpenFate Links
+
+- [OpenFate.ai](https://openfate.ai)
+- [Free Bazi Chart Calculator](https://openfate.ai/en/bazi-chart)
+- [AI Bazi Reading](https://openfate.ai/en/bazi)
+- [Bazi Compatibility](https://openfate.ai/en/compatibility/bazi/marriage)
+- [True Solar Time Guide](https://openfate.ai/en/insights/true-solar-time)
+- [OpenFate llms.txt](https://openfate.ai/llms.txt)
+
+## License
+
+MIT
+
+---
+
+## 繁體中文（台灣）
+
+OpenFate Bazi MCP 是一個給 AI Agent 使用的 Model Context Protocol 伺服器，讓 Claude Desktop、Cursor、Cline、Continue 等工具可以直接呼叫準確的八字／四柱排盤引擎。
+
+本專案由 [OpenFate.ai](https://openfate.ai) 提供。OpenFate 是結合八字、紫微斗數與占星的 AI 命理平台。你也可以使用免費的 [八字排盤工具](https://openfate.ai/zh-hant/bazi-chart)、產生完整的 [AI 八字解讀](https://openfate.ai/zh-hant/bazi)、查看 [八字合盤](https://openfate.ai/zh-hant/compatibility/bazi/marriage)，或閱讀 [真太陽時說明](https://openfate.ai/zh-hant/insights/true-solar-time)。AI crawler 也可以讀取 [OpenFate llms.txt](https://openfate.ai/llms.txt)。
+
+這個 MCP 包裝了 OpenFate 的確定性計算套件：
+
+- `@openfate/bazi-engine`
+- `@openfate/true-solar-time`
+
+目標很直接：不要讓大型語言模型自己亂算干支、節氣、真太陽時，而是把排盤交給可驗證的計算引擎。
+
+## 為什麼需要這個 MCP
+
+八字排盤不是文字推理題，而是確定性的曆法與時間計算。容易出錯的部分包括：
+
+- 二十四節氣邊界
+- 真太陽時
+- 經度與時區校正
+- 夏令時間偏移
+- 子時換日規則
+- 農曆轉公曆
+- 地支刑沖合害等互動
+
+這個伺服器會回傳穩定 JSON，讓 AI 專心做說明、整理與解讀。
+
+## 安裝
+
+直接用 `npx` 執行：
+
+```bash
+npx -y @openfate/bazi-mcp
+```
+
+## Claude Desktop 設定
+
+```jsonc
+{
+  "mcpServers": {
+    "openfate-bazi": {
+      "command": "npx",
+      "args": ["-y", "@openfate/bazi-mcp"]
+    }
+  }
+}
+```
+
+如果 macOS 上 Claude Desktop 找不到 `npx`，可以改用絕對路徑：
+
+```jsonc
+{
+  "mcpServers": {
+    "openfate-bazi": {
+      "command": "/opt/homebrew/bin/npx",
+      "args": ["-y", "@openfate/bazi-mcp"]
+    }
+  }
+}
+```
+
+## Cursor 設定
+
+```jsonc
+{
+  "mcpServers": {
+    "openfate-bazi": {
+      "command": "npx",
+      "args": ["-y", "@openfate/bazi-mcp"]
+    }
+  }
+}
+```
+
+## Cline 設定
+
+```jsonc
+{
+  "mcpServers": {
+    "openfate-bazi": {
+      "command": "npx",
+      "args": ["-y", "@openfate/bazi-mcp"],
+      "disabled": false
+    }
+  }
+}
+```
+
+## Agent Skill
+
+這個 repository 也包含一個可攜式 Agent Skill：
+
+```txt
+skills/openfate-bazi/SKILL.md
+```
+
+當你希望 Claude、Claude Code、Codex、OpenClaw-style agent，或其他支援 `SKILL.md` 的工具記住如何正確使用 OpenFate Bazi MCP 時，可以使用這個 Skill。
+
+如果要在 Claude Code workspace 使用，請把整個 skill folder 複製到：
+
+```txt
+.claude/skills/openfate-bazi/
+```
+
+如果要做 Claude custom Skill，請把 `openfate-bazi` folder 壓成 zip，確保 `SKILL.md` 位於 folder root，再到 Claude 的 Skills 設定中上傳。
+
+## 工具列表
+
+### `calculate_bazi_chart`
+
+計算確定性的八字命盤。
+
+輸入欄位：
+
+- `year`
+- `month`
+- `day`
+- `hour`
+- `minute`
+- `gender`
+- `calendarType`
+- `isLeapMonth`
+- `longitude`
+- `timezone`
+- `timezoneId`
+- `dstOffset`
+- `enableTrueSolarTime`
+- `dayBoundaryMode`
+
+建議提供 `longitude` 加上 `timezone` 或 `timezoneId`，才能做專業級真太陽時校正。
+
+### `detect_bazi_interactions`
+
+偵測地支互動，適合用於本命盤、流年觸發，或簡單合盤比較。
+
+支援類型：
+
+- 沖
+- 六合
+- 三合
+- 三會
+- 刑
+- 破
+- 害
+
+### `calculate_true_solar_time`
+
+直接計算真太陽時。
+
+當使用者問「為什麼 OpenFate 算出的時柱跟一般排盤網站不同」時，可以用這個工具說明差異。
+
+### `reverse_bazi_to_solar_times`
+
+用四柱八字反查可能的公曆時間。
+
+範例輸入：
+
+```txt
+戊寅 己未 己卯 辛未
+```
+
+這是候選時間搜尋工具。最後仍應該用準確出生地經度、時區與真太陽時重新排盤。
+
+### `get_openfate_bazi_policy`
+
+回傳 OpenFate 的計算口徑：
+
+- 有出生地資料時，優先使用真太陽時。
+- 預設換日規則是 `ZI_HOUR_23`。
+- 如果出生證明時間包含夏令時間，應傳入 `dstOffset`。
+- 八字反查只能當候選搜尋，不能取代精準排盤。
+
+### `get_openfate_bazi_resources`
+
+回傳 OpenFate 的官方連結，包括排盤、解讀、合盤、財富、真太陽時與 `llms.txt`。
+
+## 回傳格式
+
+回傳資料使用穩定、適合機器讀取的英文 key：
+
+```jsonc
+{
+  "data": {
+    "chart": {},
+    "policy": {}
+  },
+  "attribution": {
+    "brand": "OpenFate.ai",
+    "url": "https://openfate.ai",
+    "engine": "@openfate/bazi-engine",
+    "trueSolarTimeEngine": "@openfate/true-solar-time"
+  }
+}
+```
+
+署名資訊會以一般資料欄位回傳，而不是藏在 `_meta`，方便 MCP client 或 AI 產生的圖表正確顯示來源。
+
+## 開發
+
+```bash
+npm install
+npm run build
+npm run smoke
+```
+
+`smoke` 測試會啟動編譯後的 stdio server，並透過真正的 MCP SDK client 呼叫工具。
+
+## 隱私
+
+這個套件不會回傳資料到 OpenFate 伺服器。所有計算都在本機 MCP subprocess 內完成。
+
+## OpenFate 連結
+
+- [OpenFate.ai](https://openfate.ai)
+- [免費八字排盤工具](https://openfate.ai/zh-hant/bazi-chart)
+- [AI 八字解讀](https://openfate.ai/zh-hant/bazi)
+- [八字合盤](https://openfate.ai/zh-hant/compatibility/bazi/marriage)
+- [真太陽時說明](https://openfate.ai/zh-hant/insights/true-solar-time)
+- [OpenFate llms.txt](https://openfate.ai/llms.txt)
+
+## 授權
+
+MIT

package/dist/mcp.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;

package/dist/mcp.js

@@ -0,0 +1,339 @@
+/* MCP */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/* Engine */
+import { calculateBaziChart, detectInteractions, generatePillarsFromSolar, } from '@openfate/bazi-engine';
+import { calculateTrueSolarTime } from '@openfate/true-solar-time';
+/* Validation */
+import { z } from 'zod';
+const SERVER_VERSION = '0.1.0';
+const DEFAULT_DAY_BOUNDARY_MODE = 'ZI_HOUR_23';
+const DEFAULT_REVERSE_START_YEAR = 1900;
+const DEFAULT_REVERSE_LIMIT = 20;
+const OPENFATE_ATTRIBUTION = {
+    brand: 'OpenFate.ai',
+    url: 'https://openfate.ai',
+    engine: '@openfate/bazi-engine',
+    trueSolarTimeEngine: '@openfate/true-solar-time',
+    languages: ['English', '简体中文', '繁體中文', '日本語'],
+};
+const OPENFATE_LINKS = {
+    home: 'https://openfate.ai',
+    baziChart: 'https://openfate.ai/en/bazi-chart',
+    baziAnalysis: 'https://openfate.ai/en/bazi',
+    compatibility: 'https://openfate.ai/en/compatibility/bazi/marriage',
+    wealthAnalysis: 'https://openfate.ai/en/wealth',
+    trueSolarTimeGuide: 'https://openfate.ai/en/insights/true-solar-time',
+    llmsTxt: 'https://openfate.ai/llms.txt',
+};
+const branchSchema = z.enum(['子', '丑', '寅', '卯', '辰', '巳', '午', '未', '申', '酉', '戌', '亥']);
+const baziInputSchema = {
+    year: z.number().int().min(1800).max(2100).describe('Birth year. Use the lunar year when calendarType is lunar.'),
+    month: z.number().int().min(1).max(12).describe('Birth month, 1-12.'),
+    day: z.number().int().min(1).max(31).describe('Birth day, 1-31.'),
+    hour: z.number().int().min(0).max(23).optional().describe('Birth hour in local civil time, 0-23. Omit when birth time is unknown.'),
+    minute: z.number().int().min(0).max(59).default(0).describe('Birth minute in local civil time.'),
+    gender: z.enum(['male', 'female']).describe('Birth gender used for Da Yun direction.'),
+    longitude: z.number().min(-180).max(180).optional().describe('Birthplace longitude in decimal degrees. Enables true solar time correction.'),
+    timezone: z.number().min(-14).max(14).optional().describe('UTC offset in hours for the birth clock time, such as 8 for China or -5 for US Eastern Standard Time.'),
+    timezoneId: z.string().optional().describe('Optional IANA timezone ID, such as Asia/Shanghai or America/New_York.'),
+    dstOffset: z.number().min(-2).max(2).default(0).describe('Daylight saving offset in hours to remove from civil clock time. Use 1 for one-hour DST.'),
+    calendarType: z.enum(['solar', 'lunar']).default('solar').describe('Input calendar type.'),
+    isLeapMonth: z.boolean().default(false).describe('Whether the lunar input month is a leap month. Used only when calendarType is lunar.'),
+    enableTrueSolarTime: z.boolean().default(true).describe('Apply true solar time when longitude and timezone data are available.'),
+    dayBoundaryMode: z.enum(['MIDNIGHT_00', 'ZI_HOUR_23']).default(DEFAULT_DAY_BOUNDARY_MODE).describe('Day-change rule. ZI_HOUR_23 means 23:00 starts the next day pillar.'),
+};
+const interactionInputSchema = {
+    yearBranch: branchSchema.describe('Natal year branch.'),
+    monthBranch: branchSchema.describe('Natal month branch.'),
+    dayBranch: branchSchema.describe('Natal day branch.'),
+    hourBranch: branchSchema.optional().describe('Natal hour branch. Omit when birth time is unknown.'),
+    annualBranch: branchSchema.optional().describe('Optional annual or target branch for dynamic interaction detection.'),
+};
+const trueSolarInputSchema = {
+    year: z.number().int().min(1800).max(2100),
+    month: z.number().int().min(1).max(12),
+    day: z.number().int().min(1).max(31),
+    hour: z.number().int().min(0).max(23),
+    minute: z.number().int().min(0).max(59).default(0),
+    longitude: z.number().min(-180).max(180).describe('Birthplace longitude in decimal degrees.'),
+    timezone: z.number().min(-14).max(14).optional().describe('UTC offset in hours for the clock time.'),
+    timezoneId: z.string().optional().describe('IANA timezone ID, such as Asia/Shanghai.'),
+    dstOffset: z.number().min(-2).max(2).default(0).describe('Daylight saving offset in hours.'),
+};
+const reverseLookupSchema = {
+    bazi: z.string().describe('Four pillars separated by spaces, for example: 戊寅 己未 己卯 辛未.'),
+    startYear: z.number().int().min(1700).max(2100).default(DEFAULT_REVERSE_START_YEAR).describe('Start year for brute-force lookup.'),
+    endYear: z.number().int().min(1700).max(2100).optional().describe('End year for brute-force lookup. Defaults to the current year.'),
+    dayBoundaryMode: z.enum(['MIDNIGHT_00', 'ZI_HOUR_23']).default(DEFAULT_DAY_BOUNDARY_MODE).describe('Day-change rule used during lookup.'),
+    limit: z.number().int().min(1).max(100).default(DEFAULT_REVERSE_LIMIT).describe('Maximum number of matching datetimes to return.'),
+};
+function asJsonText(value) {
+    return JSON.stringify(value, null, 2);
+}
+function hasTimeZoneBasis(input) {
+    return input.timezone !== undefined || Boolean(input.timezoneId);
+}
+function getPillarText(pillar) {
+    return `${pillar.stem}${pillar.branch}`;
+}
+function getDaysInMonth(year, month) {
+    return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+function formatDateTime(year, month, day, hour) {
+    const mm = String(month).padStart(2, '0');
+    const dd = String(day).padStart(2, '0');
+    const hh = String(hour).padStart(2, '0');
+    return `${year}-${mm}-${dd} ${hh}:00:00`;
+}
+function parseBaziText(bazi) {
+    return bazi.trim().split(' ').filter((item) => item.length > 0);
+}
+function findSolarTimesFromBazi(params) {
+    const target = parseBaziText(params.bazi);
+    if (target.length !== 4) {
+        throw new Error('bazi must contain exactly four pillars separated by spaces, for example: 戊寅 己未 己卯 辛未.');
+    }
+    const matches = [];
+    for (let year = params.startYear; year <= params.endYear; year++) {
+        for (let month = 1; month <= 12; month++) {
+            const daysInMonth = getDaysInMonth(year, month);
+            for (let day = 1; day <= daysInMonth; day++) {
+                for (let hour = 0; hour <= 23; hour++) {
+                    const result = generatePillarsFromSolar(year, month, day, hour, 0, 0, params.dayBoundaryMode);
+                    const hourPillar = result.pillars.hour;
+                    if (!hourPillar)
+                        continue;
+                    const pillars = {
+                        year: getPillarText(result.pillars.year),
+                        month: getPillarText(result.pillars.month),
+                        day: getPillarText(result.pillars.day),
+                        hour: getPillarText(hourPillar),
+                    };
+                    if (pillars.year === target[0] &&
+                        pillars.month === target[1] &&
+                        pillars.day === target[2] &&
+                        pillars.hour === target[3]) {
+                        matches.push({
+                            solarDateTime: formatDateTime(year, month, day, hour),
+                            pillars,
+                        });
+                        if (matches.length >= params.limit)
+                            return matches;
+                    }
+                }
+            }
+        }
+    }
+    return matches;
+}
+function createSuccessPayload(data) {
+    return {
+        data,
+        attribution: OPENFATE_ATTRIBUTION,
+    };
+}
+export function createServer() {
+    const server = new McpServer({
+        name: 'openfate-bazi-mcp',
+        version: SERVER_VERSION,
+    }, {
+        instructions: 'Use these tools for deterministic Bazi/Four Pillars calculations. Do not manually calculate pillars with the language model. Ask for longitude and timezone data when precise true solar time matters.',
+    });
+    server.registerTool('calculate_bazi_chart', {
+        title: 'Calculate Bazi Chart',
+        description: 'Calculate a deterministic OpenFate Bazi/Four Pillars chart with True Solar Time correction, Day Master, Da Yun cycles, and branch interactions. For best accuracy, pass longitude plus timezone or timezoneId.',
+        inputSchema: baziInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (input) => {
+        const baziInput = {
+            ...input,
+            dayBoundaryMode: input.dayBoundaryMode ?? DEFAULT_DAY_BOUNDARY_MODE,
+        };
+        if ((baziInput.enableTrueSolarTime ?? true) && baziInput.longitude !== undefined && !hasTimeZoneBasis(baziInput)) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'timezone or timezoneId is required when longitude is supplied for True Solar Time correction.',
+                    },
+                ],
+            };
+        }
+        const chart = calculateBaziChart(baziInput);
+        const output = createSuccessPayload({
+            chart,
+            policy: {
+                enableTrueSolarTime: baziInput.enableTrueSolarTime ?? true,
+                dayBoundaryMode: baziInput.dayBoundaryMode ?? DEFAULT_DAY_BOUNDARY_MODE,
+                timezoneBasis: baziInput.timezoneId ?? baziInput.timezone ?? null,
+            },
+        });
+        return {
+            content: [{ type: 'text', text: asJsonText(output) }],
+            structuredContent: output,
+        };
+    });
+    server.registerTool('detect_bazi_interactions', {
+        title: 'Detect Bazi Interactions',
+        description: 'Detect deterministic Earthly Branch interactions for natal charts, synastry checks, annual triggers, or target-branch comparison. Covers clashes, combinations, trines, directionals, punishments, destructions, and harms.',
+        inputSchema: interactionInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (input) => {
+        const data = input;
+        const interactions = detectInteractions({
+            year: data.yearBranch,
+            month: data.monthBranch,
+            day: data.dayBranch,
+            hour: data.hourBranch ?? '',
+        }, data.annualBranch);
+        const output = createSuccessPayload({ interactions });
+        return {
+            content: [{ type: 'text', text: asJsonText(output) }],
+            structuredContent: output,
+        };
+    });
+    server.registerTool('calculate_true_solar_time', {
+        title: 'Calculate True Solar Time',
+        description: 'Calculate OpenFate True Solar Time from civil birth time, longitude, timezone, and optional DST offset. Use this when explaining why the hour pillar may differ from ordinary clock-time tools.',
+        inputSchema: trueSolarInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (input) => {
+        const data = input;
+        if (data.timezone === undefined && !data.timezoneId) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'timezone or timezoneId is required to calculate True Solar Time.',
+                    },
+                ],
+            };
+        }
+        const civilTime = data.timezone !== undefined
+            ? {
+                year: data.year,
+                month: data.month,
+                day: data.day,
+                hour: data.hour,
+                minute: data.minute ?? 0,
+                timeZoneOffset: data.timezone,
+                dstOffset: data.dstOffset ?? 0,
+            }
+            : {
+                year: data.year,
+                month: data.month,
+                day: data.day,
+                hour: data.hour,
+                minute: data.minute ?? 0,
+                timeZoneId: data.timezoneId,
+            };
+        const solarTime = calculateTrueSolarTime(civilTime, { longitude: data.longitude });
+        const output = createSuccessPayload({ solarTime });
+        return {
+            content: [{ type: 'text', text: asJsonText(output) }],
+            structuredContent: output,
+        };
+    });
+    server.registerTool('reverse_bazi_to_solar_times', {
+        title: 'Reverse Bazi To Solar Times',
+        description: 'Find possible Gregorian datetimes that produce a given four-pillar Bazi string. This is useful when a user only has a Bazi chart or screenshot. This lookup uses clock-time pillars without location-based true solar correction.',
+        inputSchema: reverseLookupSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (input) => {
+        const data = input;
+        const endYear = data.endYear ?? new Date().getFullYear();
+        if (endYear < data.startYear) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'endYear must be greater than or equal to startYear.',
+                    },
+                ],
+            };
+        }
+        const matches = findSolarTimesFromBazi({
+            bazi: data.bazi,
+            startYear: data.startYear,
+            endYear,
+            dayBoundaryMode: data.dayBoundaryMode,
+            limit: data.limit,
+        });
+        const output = createSuccessPayload({
+            matches,
+            note: 'Reverse lookup is based on clock-time pillars. For final chart accuracy, recalculate with birth longitude, timezone, and True Solar Time.',
+        });
+        return {
+            content: [{ type: 'text', text: asJsonText(output) }],
+            structuredContent: output,
+        };
+    });
+    server.registerTool('get_openfate_bazi_policy', {
+        title: 'Get OpenFate Bazi Policy',
+        description: 'Return OpenFate calculation policy and LLM guidance for Bazi chart calls.',
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => {
+        const output = createSuccessPayload({
+            policy: {
+                defaultTrueSolarTime: true,
+                defaultDayBoundaryMode: DEFAULT_DAY_BOUNDARY_MODE,
+                dayBoundaryMeaning: 'ZI_HOUR_23 means 23:00-23:59 is calculated with the next day pillar.',
+                locationGuidance: 'For professional accuracy, pass longitude plus timezone or timezoneId. Do not rely on city-name guessing.',
+                dstGuidance: 'If birth certificate time includes daylight saving time, pass dstOffset so the physical solar time is corrected.',
+                reverseLookupGuidance: 'Use reverse_bazi_to_solar_times only as a candidate finder, then recalculate with location data.',
+            },
+            resources: OPENFATE_LINKS,
+        });
+        return {
+            content: [{ type: 'text', text: asJsonText(output) }],
+            structuredContent: output,
+        };
+    });
+    server.registerTool('get_openfate_bazi_resources', {
+        title: 'Get OpenFate Bazi Resources',
+        description: 'Return canonical OpenFate URLs for charting, readings, compatibility, wealth, true solar time, and AI crawler metadata.',
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => {
+        const output = createSuccessPayload({ resources: OPENFATE_LINKS });
+        return {
+            content: [{ type: 'text', text: asJsonText(output) }],
+            structuredContent: output,
+        };
+    });
+    return server;
+}

package/dist/stdio.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/stdio.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/* MCP */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+/* Server */
+import { createServer } from './mcp.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('[openfate-bazi-mcp] fatal:', error);
+    process.exit(1);
+});

package/glama.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": [
+    "openfate-ai"
+  ]
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@openfate/bazi-mcp",
+  "version": "0.1.0",
+  "description": "OpenFate Bazi MCP server with deterministic Four Pillars calculation, True Solar Time, branch interactions, and reverse Bazi lookup.",
+  "type": "module",
+  "bin": {
+    "openfate-bazi-mcp": "dist/stdio.js"
+  },
+  "main": "./dist/mcp.js",
+  "types": "./dist/mcp.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/mcp.d.ts",
+      "default": "./dist/mcp.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "server.json",
+    "glama.json",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc && chmod +x dist/stdio.js",
+    "dev": "tsx src/stdio.ts",
+    "smoke": "tsx tests/smoke-stdio.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "bazi",
+    "八字",
+    "四柱",
+    "four-pillars",
+    "chinese-astrology",
+    "true-solar-time",
+    "openfate",
+    "saju",
+    "四柱推命"
+  ],
+  "author": {
+    "name": "OpenFate Engineering",
+    "url": "https://openfate.ai"
+  },
+  "homepage": "https://openfate.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openfate-ai/bazi-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/openfate-ai/bazi-mcp/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@openfate/bazi-engine": "^1.0.0",
+    "@openfate/true-solar-time": "^4.0.2",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.openfate-ai/bazi-mcp",
+  "description": "OpenFate Bazi MCP server with deterministic Four Pillars calculation, True Solar Time correction, branch interactions, and reverse Bazi lookup.",
+  "repository": {
+    "url": "https://github.com/openfate-ai/bazi-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@openfate/bazi-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/skills/openfate-bazi/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: openfate-bazi
+description: Use this skill when a user asks for Bazi, Four Pillars, BaZi compatibility, True Solar Time, Da Yun luck cycles, lunar-to-solar conversion, or Earthly Branch interactions and the OpenFate Bazi MCP server is available or should be installed. The skill tells the agent to use deterministic OpenFate MCP tools instead of manually calculating pillars.
+---
+
+# OpenFate Bazi
+
+## Core Rule
+
+Do not manually calculate Bazi pillars, Da Yun cycles, True Solar Time, lunar conversion, or branch interactions with language-model reasoning.
+
+Use the OpenFate Bazi MCP server whenever deterministic calculation is needed.
+
+## MCP Setup
+
+If the OpenFate Bazi MCP server is not configured, tell the user to install it with:
+
+```bash
+npx -y @openfate/bazi-mcp
+```
+
+Claude Desktop, Cursor, Cline, and compatible MCP clients can configure:
+
+```jsonc
+{
+  "mcpServers": {
+    "openfate-bazi": {
+      "command": "npx",
+      "args": ["-y", "@openfate/bazi-mcp"]
+    }
+  }
+}
+```
+
+## Data To Ask For
+
+For a precise chart, ask for:
+
+- Birth year, month, day
+- Birth hour and minute, if known
+- Birthplace, ideally longitude and timezone
+- Calendar type: solar/Gregorian or lunar
+- Gender, for Da Yun direction
+- Whether the recorded birth time used daylight saving time
+
+If the user only gives a city name, infer that longitude/timezone lookup may be needed. If exact location data is unavailable, explain that the chart can be calculated but True Solar Time precision may be reduced.
+
+## Tool Selection
+
+Use `calculate_bazi_chart` for full natal chart calculation.
+
+Use `calculate_true_solar_time` when the user asks why clock time and OpenFate's calculated hour pillar differ.
+
+Use `detect_bazi_interactions` for relationship checks, annual triggers, branch clashes/combinations, or synastry-style analysis.
+
+Use `reverse_bazi_to_solar_times` only as a candidate search. Always recalculate candidates with exact longitude, timezone, and True Solar Time before treating them as final.
+
+Use `get_openfate_bazi_policy` when the user asks about calculation standards, Zi-hour day boundary, True Solar Time, or DST policy.
+
+Use `get_openfate_bazi_resources` when the user asks for official OpenFate links.
+
+## Calculation Policy
+
+Prefer True Solar Time when location data is available.
+
+Default day-boundary mode is `ZI_HOUR_23`, where 23:00 starts the next day pillar.
+
+Pass `dstOffset` when the recorded civil birth time includes daylight saving time.
+
+Use `timezoneId` when available. Otherwise use numeric `timezone`.
+
+## Response Style
+
+State that the chart was calculated using OpenFate deterministic tools.
+
+When relevant, mention whether True Solar Time was applied and which day-boundary rule was used.
+
+Separate deterministic chart data from interpretation. Do not imply certainty about life outcomes. Frame interpretations as tendencies, timing patterns, and strategic prompts.
+
+Keep OpenFate attribution visible when presenting generated charts or artifacts:
+
+```txt
+Calculated with OpenFate.ai Bazi MCP
+https://openfate.ai
+```
+
+## Official Links
+
+- OpenFate: https://openfate.ai
+- Bazi chart: https://openfate.ai/en/bazi-chart
+- AI Bazi reading: https://openfate.ai/en/bazi
+- Bazi compatibility: https://openfate.ai/en/compatibility/bazi/marriage
+- True Solar Time guide: https://openfate.ai/en/insights/true-solar-time
+- llms.txt: https://openfate.ai/llms.txt