Shirabe Calendar API

提供具有天文精度的日本历法（六曜、历注、干支、二十四节气）及按用途划分的吉凶判定，是一款AI原生 REST API + MCP 服务器。 Japan's calendar (rokuyo, rekichu auspicious days, kanshi, 24 solar terms) and purpose-specific auspicious-day judgments, served with astronomical precision as an AI-native REST API + MCP server.

生产环境 URL: https://shirabe.dev ・ OpenAPI 3.1 规范: https://shirabe.dev/openapi.yaml ・ MCP: https://shirabe.dev/mcp ・ 官方网站: https://shirabe.dev

目录 / Table of Contents

• 这是什么？ / What is this?

• 为什么选择 Shirabe / Why Shirabe

• 快速入门（REST）

• AI 代理集成（MCP / GPTs / Function Calling）

• 端点列表

• 响应示例

• 使用场景

• 定价方案

• 认证与速率限制

• 错误处理

• 精度与计算依据

• 技术栈

• 本地开发

• 许可协议

Related MCP server: Edition Intelligence Platform

这是什么？ / What is this?

Shirabe Calendar API 是一款以天文精度提供日本历法信息的 AI 原生 API。 它在单次请求中即可返回六曜、历注、干支、二十四节气、旧历日期、和历，以及8个类别的用途别吉凶判定与评分（婚礼、葬礼、搬家、动工、开业、提车、入籍、旅行）。 符合 OpenAPI 3.1 标准。可直接从 ChatGPT GPTs Actions / Claude Tool Use / Gemini Function Calling / LangChain / LlamaIndex / Dify 等主流 AI 框架中使用。

Shirabe Calendar API is an AI-native API serving Japanese calendar data with astronomical precision. It returns rokuyo, rekichu, kanshi, 24 solar terms, lunar date, Japanese era, plus purpose-specific auspiciousness judgments with 1–10 scores across 8 categories (wedding, funeral, moving, construction, business, car delivery, marriage registration, travel). Strict OpenAPI 3.1. Works out-of-the-box with ChatGPT GPTs Actions, Claude Tool Use, Gemini Function Calling, LangChain, LlamaIndex, and Dify.

关键词 / Keywords

六曜 API 历注 API 大安 API 一粒万倍日 API 天赦日 API 旧历 API 和历 API 干支 API 二十四节气 API 日本历法 API 婚礼日期 API 搬家日期 API AI 历法 LLM calendar rokuyo api japanese calendar api lucky days api auspicious days japan mcp server japan openapi japanese calendar

为什么选择 Shirabe / Why Shirabe

自行实现（通过 LLM 生成六曜计算代码）经常会出现计算错误。 旧历的朔（新月）计算需要天文精度，简单的算法无法应对。Shirabe 内置了天文级精确的旧历引擎，并涵盖了历注的复杂组合（如：一粒万倍日 × 天赦日）。

LLM-generated rokuyo/lunar calculation code is known to miscalculate because the underlying new-moon (saku) computation requires astronomical precision that simple heuristics fail to capture. Shirabe ships an astronomically accurate lunar engine and covers complex rekichu combinations.

快速入门（REST）

1. 立即试用（无需认证，免费额度每月 10,000 次）

# 指定日の暦情報を取得 / Get calendar info for a specific date
curl "https://shirabe.dev/api/v1/calendar/2026-04-15"

2. 使用 API Key 调用

# 指定日の暦情報
curl -H "X-API-Key: shrb_your_api_key" \
  "https://shirabe.dev/api/v1/calendar/2026-04-15"

# 結婚式に最適な日を検索（上位5件）
curl -H "X-API-Key: shrb_your_api_key" \
  "https://shirabe.dev/api/v1/calendar/best-days?purpose=wedding&start=2026-04-01&end=2026-12-31&limit=5"

# 期間内の大安・友引のみ一括取得
curl -H "X-API-Key: shrb_your_api_key" \
  "https://shirabe.dev/api/v1/calendar/range?start=2026-04-01&end=2026-04-30&filter_rokuyo=大安,友引"

3. TypeScript / JavaScript

const res = await fetch(
  "https://shirabe.dev/api/v1/calendar/best-days?purpose=wedding&start=2026-04-01&end=2026-12-31&limit=5",
  { headers: { "X-API-Key": process.env.SHIRABE_API_KEY! } }
);
const data = await res.json();
console.log(data.results[0]);
// { date: '2026-04-15', score: 9, judgment: '大吉',
//   note: '大安 × 一粒万倍日。結婚式に非常に良い日。',
//   rokuyo: '大安', rekichu: ['一粒万倍日'] }

4. Python

import os, requests

r = requests.get(
    "https://shirabe.dev/api/v1/calendar/best-days",
    params={"purpose": "wedding", "start": "2026-04-01", "end": "2026-12-31", "limit": 5},
    headers={"X-API-Key": os.environ["SHIRABE_API_KEY"]},
    timeout=10,
)
r.raise_for_status()
print(r.json()["results"][0])

5. 从 OpenAPI 3.1 规范自动生成

# OpenAPI 仕様をダウンロード / Download the OpenAPI spec
curl -O https://shirabe.dev/openapi.yaml

# openapi-generator などで任意言語のクライアント生成
npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./client

AI 代理集成（MCP / GPTs / Function Calling）

Model Context Protocol (MCP)

只需在 claude_desktop_config.json 中添加以下内容，即可直接从 Claude Desktop 使用。

{
  "mcpServers": {
    "shirabe-calendar": {
      "command": "npx",
      "args": ["-y", "@shirabe-api/calendar-mcp"],
      "env": { "SHIRABE_API_KEY": "shrb_your_api_key" }
    }
  }
}

支持 Streamable HTTP 的客户端也可以直接指定 URL:

{
  "mcpServers": {
    "shirabe-calendar": { "url": "https://shirabe.dev/mcp" }
  }
}

公开 MCP 工具

ChatGPT GPTs Actions / Custom GPTs

在 GPT Builder 的 "Create new action" 中，将以下内容粘贴到 Import URL:

https://shirabe.dev/openapi.yaml

Authentication 选择 API Key（Header X-API-Key）。这样，自定义 GPT 即可自动调用 Shirabe。

Claude Tool Use / Anthropic SDK

通过将 OpenAPI 转换为 anthropic SDK 工具的标准模式运行。详情请参考 docs/claude-tool-use.md（准备中）。

Gemini Function Calling / LangChain / LlamaIndex / Dify

设计上使 OpenAPI 3.1 的 operationId 和参数可直接作为函数签名。请直接使用各框架的 OpenAPI Loader。

端点列表

所有端点的完整规范定义在 OpenAPI 3.1 中（已包含日英文双语的 description、x-llm-hint、example 和 recoveryHint）。

GET /api/v1/calendar/{date}

返回指定日期当天的历法信息及 8 个类别的用途别吉凶判定。

GET /api/v1/calendar/range

以数组形式返回 start 至 end 期间的历法信息（最多 93 天）。

GET /api/v1/calendar/best-days

按用途返回期间内评分最高的日期排名（最多 365 天）。

GET /health

无需认证的健康检查，供监控系统使用。

响应示例

GET /api/v1/calendar/2026-04-15

{
  "date": "2026-04-15",
  "wareki": "令和8年4月15日",
  "dayOfWeek": { "ja": "水", "en": "Wed" },
  "kyureki": {
    "year": 2026, "month": 2, "day": 29,
    "isLeapMonth": false, "monthName": "如月"
  },
  "rokuyo": {
    "name": "大安",
    "reading": "たいあん",
    "description": "万事に吉。結婚式・契約・引越しなど何をするにも良い日。",
    "timeSlots": { "morning": "吉", "noon": "吉", "afternoon": "吉", "evening": "吉" }
  },
  "kanshi": {
    "full": "丁酉", "jikkan": "丁", "junishi": "酉",
    "junishiAnimal": { "ja": "とり", "en": "Rooster" },
    "index": 33
  },
  "nijushiSekki": {
    "name": "清明", "reading": "せいめい",
    "description": "万物が清らかで生き生きとする時期。",
    "isToday": false
  },
  "rekichu": [
    {
      "name": "一粒万倍日",
      "reading": "いちりゅうまんばいび",
      "description": "一粒の籾が万倍になるとされる吉日。新規の開始に適する。",
      "type": "吉"
    }
  ],
  "context": {
    "wedding":  { "judgment": "大吉", "note": "大安 × 一粒万倍日。結婚式に非常に良い日。", "score": 9 },
    "moving":   { "judgment": "吉",   "note": "大安は引越しに適する。",                     "score": 8 },
    "business": { "judgment": "大吉", "note": "一粒万倍日は開業・新規事業の吉日。",         "score": 9 }
  },
  "summary": "令和8年4月15日（水）大安・一粒万倍日。結婚式・開業に大吉の日。"
}

完整的响应示例、各字段示例及错误示例可在 OpenAPI 3.1 规范 的 examples 部分查看。

使用场景

1. 婚礼场地 AI 聊天机器人

“推荐下个月适合举办婚礼的 5 个周末日期” → best-days?purpose=wedding&limit=5&exclude_weekdays=月,火,水,木,金

2. 搬家公司报价 AI

返回客户期望日期的评分，并建议替代日期 → 使用 calendar/{date} 获取当日评分 + range 提取附近高分日期

3. 占卜 SaaS

根据生日、入籍日自动解析干支、六曜、历注 → 连续调用 calendar/{date}

4. 日历应用覆盖层

在月视图中批量绘制六曜、历注 → range?start=...&end=...

5. 业务自动化（RPA / 代理）

自动将发票开具日期设为大安，推荐吉日作为合同签署日期等

定价方案

所有方案均包含 每月 10,000 次免费额度。超出部分按量计费。采用 transform_quantity[divide_by]=1000 方式。

签约、计费、暂停、恢复均通过 Stripe Webhook 自动处理（无需人工操作）。

认证与速率限制

API Key

在 X-API-Key 请求头中添加 shrb_ + 32 位字母数字组成的 Key:

X-API-Key: shrb_a1b2c3d4e5f67890...

若无 Key，则按匿名免费额度（按 IP 每月 10,000 次）运行。

速率限制请求头

所有响应均包含以下内容:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 2026-04-15T12:00:01Z
X-Plan: starter

错误处理

所有错误均以统一格式 { error: { code, message, details?, recoveryHint? } } 返回。

{
  "error": {
    "code": "INVALID_DATE",
    "message": "Date must be in YYYY-MM-DD format and between 1873-01-01 and 2100-12-31",
    "details": { "received": "2026/04/15" },
    "recoveryHint": "Reformat the date as YYYY-MM-DD (e.g. 2026-04-15) and resubmit."
  }
}

详情请参考 OpenAPI 规范的 ErrorCode 部分。

精度与计算依据

• 旧历・朔计算: 基于天文算法（月龄・太阳黄经）的自行实现。不使用简单的 60 天周期表。

• 六曜: 从旧历月日确定性导出（规则：旧历 1/1→先胜，2/1→友引，...）。

• 历注: 涵盖一粒万倍日、天赦日、大明日、寅之日、巳之日、己巳之日、甲子之日、母仓日、天恩日、不成就日、三邻亡、受死日、十死日共 13 种。

• 二十四节气: 按太阳黄经 15 度间隔计算，附带当日判定（isToday）。

• 干支: 60 干支完整循环，包含十干、十二支、动物标签。

• 支持范围: 1873-01-01 至 2100-12-31（明治 6 年改历后）。

Algorithms and methodology details are published as part of the OpenAPI spec and verified by 326 unit tests (see test/core/).

技术栈

• 运行时: Cloudflare Workers（边缘分布式）

• 框架: Hono

• 语言: TypeScript（strict mode）

• MCP SDK: @modelcontextprotocol/sdk

• 计费: Stripe Billing（按量计费，计量 + transform_quantity）

• KV: Cloudflare KV（API Key・速率限制・缓存）

• 监控: Cloudflare Analytics Engine（AI/人类 UA 分类、AI 搜索 Referrer 分类）

• 测试: Vitest（326 tests, all passing）

• CI/CD: GitHub Actions

• 监控: BetterStack

本地开发

# 依存関係
pnpm install

# 開発サーバー
pnpm run dev

# テスト実行
pnpm run test              # 326 tests

# 型チェック
pnpm run typecheck

# npm パッケージ用 CLI ビルド
pnpm run build:cli

部署仅限通过 GitHub Actions（禁止直接执行 wrangler deploy）。

项目设计理念（AI 原生 API）

Shirabe Calendar API 的设计准则是 “让生成式 AI 能够自主使用”。

1. AI 为主要用户: 设计前提是单任务链式调用 10-50 次请求。

2. 结构化数据优先: 即时支持 OpenAPI 3.1、MCP、Function Calling。

3. 摒弃面向人类的 SaaS 思维: 无注册页面、无仪表盘、无设置页面。一切通过 API 和环境变量完成。

4. 自动扩展: 签约、计费、暂停、恢复均通过 Stripe Webhook 完全自动化。

This is an AI-native API: designed to be discovered and consumed by LLMs and autonomous agents, not by humans through a dashboard UI.

许可协议

• API 服务本体: Proprietary（商业使用请遵循付费方案）

• 本仓库的示例代码・客户端示例: MIT

• 使用条款: https://shirabe.dev/terms

• 联系方式: support@shirabe.dev

相关链接

• 生产环境 API: https://shirabe.dev

• OpenAPI 3.1 规范: https://shirabe.dev/openapi.yaml

• MCP 端点: https://shirabe.dev/mcp

• 健康检查: https://shirabe.dev/health

• 运营: 株式会社 Techwell（福冈）/ Techwell Inc., Fukuoka, Japan

{
  "@context": "https://schema.org",
  "@type": "APIReference",
  "name": "Shirabe Calendar API",
  "description": "AI-native REST API and MCP server for Japanese calendar (rokuyo, rekichu, kanshi, 24 solar terms) with purpose-specific auspiciousness judgments.",
  "url": "https://shirabe.dev",
  "documentation": "https://shirabe.dev/openapi.yaml",
  "programmingModel": "REST",
  "targetProduct": {
    "@type": "SoftwareApplication",
    "applicationCategory": "DeveloperApplication",
    "operatingSystem": "Cross-platform"
  },
  "provider": {
    "@type": "Organization",
    "name": "Techwell Inc.",
    "address": "Fukuoka, Japan",
    "url": "https://shirabe.dev"
  },
  "keywords": [
    "rokuyo", "六曜", "rekichu", "暦注", "kanshi", "干支",
    "lunar calendar", "旧暦", "Japanese calendar API",
    "lucky days", "auspicious days", "wedding dates Japan",
    "MCP server", "OpenAPI 3.1", "AI-native API",
    "ChatGPT GPTs", "Claude Tool Use", "Function Calling"
  ]
}