Shirabe Calendar API

Eine KI-native REST-API + MCP-Server, die den japanischen Kalender (Rokuyo, Rekichu, Eto, 24 Sonnenbegriffe) und glückverheißende Tage für verschiedene Zwecke mit astronomischer Präzision liefert.

Produktions-URL: https://shirabe.dev ・ OpenAPI 3.1 Spezifikation: https://shirabe.dev/openapi.yaml ・ MCP: https://shirabe.dev/mcp ・ Offizielle Website: https://shirabe.dev

Inhaltsverzeichnis

• Was ist das?

• Warum Shirabe?

• Schnellstart (REST)

• KI-Agenten-Integration (MCP / GPTs / Function Calling)

• Endpunkt-Übersicht

• Antwortbeispiel

• Anwendungsfälle

• Preispläne

• Authentifizierung und Ratenbegrenzung

• Fehlerbehandlung

• Genauigkeit und Berechnungsgrundlage

• Technologie-Stack

• Lokale Entwicklung

• Lizenz

Related MCP server: Edition Intelligence Platform

Was ist das?

Die Shirabe Calendar API ist eine KI-native API, die japanische Kalenderinformationen mit astronomischer Präzision bereitstellt. Sie liefert Rokuyo, Rekichu, Eto, 24 Sonnenbegriffe, Monddaten und japanische Ären sowie Glücks- und Unglücksbewertungen mit Scores für 8 Kategorien (Hochzeit, Beerdigung, Umzug, Baubeginn, Geschäftseröffnung, Fahrzeugübergabe, Eheschließung, Reisen) in einer einzigen Anfrage.

OpenAPI 3.1-konform. Sofort einsatzbereit mit ChatGPT GPTs Actions, Claude Tool Use, Gemini Function Calling, LangChain, LlamaIndex, Dify und anderen führenden KI-Frameworks.

Schlüsselwörter

Rokuyo API Rekichu API Taian API Ichiryumanbaibi API Tenshachi API Mondkalender API Japanischer Kalender API Hochzeitstermin API Umzugstermin API KI Kalender LLM calendar rokuyo api japanese calendar api lucky days api auspicious days japan mcp server japan openapi japanese calendar

Warum Shirabe?

Eigene Implementierungen (durch LLMs generierter Code zur Rokuyo-Berechnung) führen häufig zu Fehlern. Die Berechnung des Neumonds (Saku) im Mondkalender erfordert astronomische Präzision, die mit einfachen Algorithmen nicht erreicht werden kann. Shirabe enthält eine astronomisch exakte Mondkalender-Engine und deckt komplexe Kombinationen von Rekichu (z. B. Ichiryumanbaibi × Tenshachi) ab.

Schnellstart (REST)

1. Erster Test (keine Authentifizierung erforderlich, kostenloses Kontingent bis 10.000 Anfragen/Monat)

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

2. Aufruf mit API-Schlüssel

# 指定日の暦情報
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. Automatische Generierung aus OpenAPI 3.1 Spezifikation

# 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

KI-Agenten-Integration (MCP / GPTs / Function Calling)

Model Context Protocol (MCP)

Fügen Sie einfach Folgendes zu Ihrer claude_desktop_config.json hinzu, um den Dienst direkt in Claude Desktop zu nutzen:

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

Clients mit Streamable-HTTP-Unterstützung können die URL auch direkt angeben:

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

Verfügbare MCP-Tools

ChatGPT GPTs Actions / Custom GPTs

Verwenden Sie im GPT Builder unter "Create new action" die folgende Import-URL:

https://shirabe.dev/openapi.yaml

Wählen Sie als Authentifizierung API Key (Header X-API-Key). Damit kann Ihr Custom GPT Shirabe automatisch aufrufen.

Claude Tool Use / Anthropic SDK

Funktioniert mit dem Standardmuster zur Umwandlung von OpenAPI in Tools für das anthropic SDK. Details finden Sie unter docs/claude-tool-use.md (in Vorbereitung).

Gemini Function Calling / LangChain / LlamaIndex / Dify

Die operationId und Parameter der OpenAPI 3.1 Spezifikation sind so konzipiert, dass sie direkt als Funktionssignaturen dienen. Verwenden Sie einfach den OpenAPI-Loader des jeweiligen Frameworks.

Endpunkt-Übersicht

Die vollständige Spezifikation aller Endpunkte finden Sie unter OpenAPI 3.1 (inklusive Beschreibungen, x-llm-hint, Beispielen und recoveryHint in Englisch und Japanisch).

GET /api/v1/calendar/{date}

Liefert Kalenderinformationen und Bewertungen für 8 Kategorien für einen Tag.

GET /api/v1/calendar/range

Liefert Kalenderinformationen für einen Zeitraum von start bis end (max. 93 Tage).

GET /api/v1/calendar/best-days

Liefert ein Ranking der Tage mit den höchsten Scores für einen Zweck innerhalb eines Zeitraums (max. 365 Tage).

GET /health

Authentifizierungsfreier Health-Check für Monitoring-Systeme.

Antwortbeispiel

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日（水）大安・一粒万倍日。結婚式・開業に大吉の日。"
}

Vollständige Antwortbeispiele, Felddefinitionen und Fehlerbeispiele finden Sie im Abschnitt examples der OpenAPI 3.1 Spezifikation.

Anwendungsfälle

1. KI-Chatbot für Hochzeitslocations

"Nenne mir 5 empfohlene Tage für eine Hochzeit an einem Wochenende im nächsten Monat" → best-days?purpose=wedding&limit=5&exclude_weekdays=mon,tue,wed,thu,fri

2. KI für Umzugsunternehmen

Bewertung des Wunschdatums des Kunden und Vorschlag von Alternativen → calendar/{date} für den Tagesscore + range für nahegelegene Tage mit hohem Score.

3. Wahrsagerei-SaaS

Automatische Erklärung von Eto, Rokuyo und Rekichu basierend auf Geburtsdatum oder Eheschließungsdatum → Kontinuierliche Aufrufe von calendar/{date}.

4. Kalender-App-Overlay

Einblenden von Rokuyo und Rekichu in der Monatsansicht → range?start=...&end=...

5. Geschäftsautomatisierung (RPA / Agenten)

Automatische Festlegung von Rechnungsdaten auf Taian-Tage, Empfehlung von glückverheißenden Tagen für Vertragsabschlüsse etc.

Preispläne

Alle Pläne beinhalten ein kostenloses Kontingent von 10.000 Anfragen/Monat. Überschreitungen werden berechnet. Abrechnung erfolgt nach dem transform_quantity[divide_by]=1000 Prinzip.

Vertragsabschluss, Abrechnung, Stopp und Reaktivierung erfolgen vollautomatisch über Stripe Webhooks (kein menschlicher Eingriff erforderlich).

Authentifizierung und Ratenbegrenzung

API-Schlüssel

Fügen Sie den X-API-Key Header mit einem shrb_ + 32-stelligen alphanumerischen Schlüssel hinzu:

X-API-Key: shrb_a1b2c3d4e5f67890...

Ohne Schlüssel erfolgt der Zugriff über das anonyme Free-Kontingent (10.000 Anfragen/Monat pro IP).

Ratenbegrenzungs-Header

Jede Antwort enthält folgende Header:

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

Fehlerbehandlung

Alle Fehler werden im einheitlichen Format { error: { code, message, details?, recoveryHint? } } zurückgegeben.

{
  "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."
  }
}

Details finden Sie im Abschnitt ErrorCode der OpenAPI-Spezifikation.

Genauigkeit und Berechnungsgrundlage

• Mondkalender/Neumond: Eigene Implementierung basierend auf astronomischen Algorithmen (Mondalter, ekliptikale Länge der Sonne). Keine einfachen 60-Tage-Tabellen.

• Rokuyo: Deterministisch aus dem Monddatum abgeleitet (Regeln wie 1.1 = Sensho, 2.1 = Tomobiki etc.).

• Rekichu: Deckt 13 Arten ab: Ichiryumanbaibi, Tenshachi, Daimyo-nichi, Tora-no-hi, Mi-no-hi, Kishi-no-hi, Kinoe-ne-no-hi, Bosho-nichi, Tennon-nichi, Fujoju-nichi, Sanrinbo, Jushi-nichi, Jusshi-nichi.

• 24 Sonnenbegriffe: Berechnet basierend auf 15-Grad-Intervallen der ekliptikalen Länge der Sonne, inklusive Tagesprüfung (isToday).

• Eto: Vollständiger 60-Jahre-Zyklus, inklusive Jikkan, Junishi und Tierkreiszeichen.

• Abdeckungsbereich: 1873-01-01 bis 2100-12-31 (seit der Kalenderreform im 6. Jahr der Meiji-Ära).

Algorithmen und Methodik sind Teil der OpenAPI-Spezifikation und durch 326 Unit-Tests verifiziert (siehe test/core/).

Technologie-Stack

• Runtime: Cloudflare Workers (Edge-Verteilung)

• Framework: Hono

• Sprache: TypeScript (strict mode)

• MCP SDK: @modelcontextprotocol/sdk

• Abrechnung: Stripe Billing (nutzungsbasiert, Meter + transform_quantity)

• KV: Cloudflare KV (API-Schlüssel, Ratenbegrenzung, Cache)

• Messung: Cloudflare Analytics Engine (KI/Mensch-UA-Klassifizierung, KI-Such-Referrer)

• Tests: Vitest (326 Tests, alle bestanden)

• CI/CD: GitHub Actions

• Monitoring: BetterStack

Lokale Entwicklung

# 依存関係
pnpm install

# 開発サーバー
pnpm run dev

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

# 型チェック
pnpm run typecheck

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

Deployments erfolgen ausschließlich über GitHub Actions (wrangler deploy direkt ist untersagt).

Design-Philosophie (KI-native API)

Die Shirabe Calendar API wurde mit dem Ziel entworfen, dass "generative KI sie eigenständig nutzt".

1. KI als Hauptnutzer: Design für Ketten von 10–50 Anfragen pro Aufgabe.

2. Strukturierte Daten priorisiert: Sofortige Unterstützung für OpenAPI 3.1, MCP und Function Calling.

3. Kein SaaS-Denken für Menschen: Keine Anmeldeseiten, keine Dashboards, keine Einstellungsmenüs. Alles wird über API und Umgebungsvariablen gesteuert.

4. Automatische Skalierung: Vertrag, Abrechnung, Stopp und Reaktivierung sind über Stripe Webhooks vollständig automatisiert.

Dies ist eine KI-native API: Entwickelt, um von LLMs und autonomen Agenten entdeckt und genutzt zu werden, nicht von Menschen über eine Dashboard-UI.

Lizenz

• API-Dienst: Proprietär (kommerzielle Nutzung gemäß kostenpflichtigen Plänen)

• Beispielcode/Client-Beispiele in diesem Repository: MIT

• Nutzungsbedingungen: https://shirabe.dev/terms

• Kontakt: support@shirabe.dev

Verwandte Links

• Produktions-API: https://shirabe.dev

• OpenAPI 3.1 Spezifikation: https://shirabe.dev/openapi.yaml

• MCP-Endpunkt: https://shirabe.dev/mcp

• Health-Check: https://shirabe.dev/health

• Betreiber: 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"
  ]
}