Shirabe Calendar API

AI-native REST API + MCP-сервер, предоставляющий японский календарь (рокуё, рэкитю, это, 24 солнечных сезона) и оценку благоприятности дней по различным целям с астрономической точностью.

Production URL: https://shirabe.dev ・ Спецификация OpenAPI 3.1: https://shirabe.dev/openapi.yaml ・ MCP: https://shirabe.dev/mcp ・ Официальный сайт: https://shirabe.dev

Оглавление / Table of Contents

• Что это такое?

• Почему Shirabe?

• Быстрый старт (REST)

• Интеграция с AI-агентами (MCP / GPTs / Function Calling)

• Список эндпоинтов

• Примеры ответов

• Варианты использования

• Тарифные планы

• Аутентификация и лимиты

• Обработка ошибок

• Точность и методология

• Технологический стек

• Локальная разработка

• Лицензия

Related MCP server: Edition Intelligence Platform

Что это такое?

Shirabe Calendar API — это AI-native API, предоставляющий информацию о японском календаре с астрономической точностью. В одном запросе вы получаете рокуё, рэкитю, это, 24 солнечных сезона, дату по лунному календарю, японскую эру, а также оценку благоприятности по 8 категориям (свадьба, похороны, переезд, строительство, бизнес, получение автомобиля, регистрация брака, путешествия) с баллами от 1 до 10. Соответствует OpenAPI 3.1. Готов к использованию с ChatGPT GPTs Actions, Claude Tool Use, Gemini Function Calling, LangChain, LlamaIndex, Dify и другими фреймворками.

Ключевые слова

рокуё 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?

Самописные реализации (генерация кода расчёта рокуё через LLM) часто ошибаются. Расчёт новолуния для лунного календаря требует астрономической точности, недоступной простым алгоритмам. Shirabe содержит встроенный астрономически точный движок лунного календаря и охватывает сложные комбинации рэкитю (например, Итирю-манбайби × Тэнсяби).

Быстрый старт (REST)

1. Попробуйте (без аутентификации, бесплатный лимит 10 000 запросов/мес)

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

2. Вызов с API-ключом

# 指定日の暦情報
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

В качестве аутентификации выберите API Key (заголовок X-API-Key). Теперь ваш кастомный GPT сможет автоматически вызывать Shirabe.

Claude Tool Use / Anthropic SDK

Работает по стандартному шаблону преобразования OpenAPI в инструменты SDK anthropic. Подробности см. в docs/claude-tool-use.md (в разработке).

Gemini Function Calling / LangChain / LlamaIndex / Dify

Спроектировано так, чтобы operationId и параметры OpenAPI 3.1 напрямую соответствовали сигнатурам функций. Используйте стандартные OpenAPI Loader для каждого фреймворка.

Список эндпоинтов

Полная спецификация всех эндпоинтов доступна в OpenAPI 3.1 (описания, x-llm-hint, примеры и 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日（水）大安・一粒万倍日。結婚式・開業に大吉の日。"
}

Полные примеры ответов, описание полей и примеры ошибок можно найти в разделе examples спецификации OpenAPI 3.1.

Варианты использования

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-ключ

Добавьте заголовок X-API-Key с ключом shrb_ + 32 буквенно-цифровых символа:

X-API-Key: shrb_a1b2c3d4e5f67890...

Без ключа используется анонимный бесплатный лимит (10 000 запросов в месяц на IP).

Заголовки лимитов

Все ответы содержат:

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

Подробности см. в разделе ErrorCode спецификации OpenAPI.

Точность и методология

• Расчёт лунного календаря: Собственная реализация на основе астрономических алгоритмов (фазы луны, долгота солнца). Не используются простые 60-дневные таблицы.

• Рокуё: Определяется детерминированно из даты лунного календаря (правило: 1/1 лунного календаря → Сэнсё, 2/1 → Томобики и т.д.).

• Рэкитю: Охватывает 13 видов, включая Итирю-манбайби, Тэнсяби, Даймёнити, дни Тигра, Змеи, Змеи-Земли, Крысы, Босёнити, Тэнъоннити, Фудзёдзюнити, Санринбо, Дзюсинити, Дзюссинити.

• 24 солнечных сезона: Рассчитываются с интервалом 15 градусов долготы солнца, с индикатором текущего дня (isToday).

• Это: Полный цикл 60-ричной системы, включая 10 небесных стволов, 12 земных ветвей и названия животных.

• Диапазон: 1873-01-01 – 2100-12-31 (после календарной реформы 6-го года Мэйдзи).

Детали алгоритмов опубликованы в спецификации OpenAPI и проверены 326 модульными тестами (см. test/core/).

Технологический стек

• Runtime: Cloudflare Workers (Edge-распределение)

• Framework: Hono

• Язык: TypeScript (strict mode)

• MCP SDK: @modelcontextprotocol/sdk

• Оплата: Stripe Billing (оплата по факту, meter + transform_quantity)

• KV: Cloudflare KV (API-ключи, лимиты, кэш)

• Аналитика: Cloudflare Analytics Engine (классификация AI/человек, рефереры AI-поиска)

• Тесты: Vitest (326 тестов, все проходят)

• 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-native API)

Shirabe Calendar API спроектирован с расчётом на то, что «генеративный AI начнет использовать его самостоятельно».

1. AI — основной пользователь: Проектирование с учётом цепочек из 10–50 запросов на одну задачу.

2. Приоритет структурированных данных: Полная поддержка OpenAPI 3.1, MCP, Function Calling.

3. Исключение SaaS-мышления для людей: Нет экранов регистрации, дашбордов, настроек. Всё через API и переменные окружения.

4. Автоматическое масштабирование: Контракты, оплата, приостановка и возобновление полностью автоматизированы через Stripe Webhook.

Это AI-native API: создано для обнаружения и использования LLM и автономными агентами, а не людьми через дашборд.

Лицензия

• API-сервис: Proprietary (коммерческое использование согласно платным тарифам)

• Примеры кода и клиентов в этом репозитории: MIT

• Условия использования: https://shirabe.dev/terms

• Контакты: support@shirabe.dev

Ссылки

• Production API: https://shirabe.dev

• Спецификация OpenAPI 3.1: https://shirabe.dev/openapi.yaml

• MCP-эндпоинт: https://shirabe.dev/mcp

• Health check: https://shirabe.dev/health

• Оператор: Techwell Inc., Фукуока, Япония

{
  "@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"
  ]
}