Clawlendar
Overview
Provide a single, agent-friendly bridge layer so different tools can ask calendar questions in a common schema and receive normalized JSON. Treat this skill as the date interoperability baseline for multi-agent ecosystems.
Workflow
- 1. Call
capabilities first to discover supported calendars, optional providers, and locale support. - For calendar conversion, parse source payload in declared calendar and bridge through Gregorian.
- For instant-based workflows, use
timeline (timestamp-first) instead of direct date conversion. - Use
calendar_month when UI needs true month boundaries in non-Gregorian systems. - Use
day_profile for one-call details (sexagenary, solar_term_24, chinese_lunar, optional astro, optional metaphysics). - Always pass
locale (en, zh-CN, zh-TW) when user-facing text is required.
Quick Start (MCP Server)
Install and run as an MCP server for Claude Desktop / Claude Code:
CODEBLOCK0
One-line registration in Claude Code:
CODEBLOCK1
Or run directly from source:
CODEBLOCK2
CLI Usage
List supported calendars and optional backends:
CODEBLOCK3
Convert one date into multiple targets:
CODEBLOCK4
Normalize one instant with timestamp-first model (external time wheel):
CODEBLOCK5
Generate an astro snapshot for zodiac wheel rendering:
CODEBLOCK6
Get true month boundaries for non-Gregorian month mode:
CODEBLOCK7
Get unified daily profile payload:
CODEBLOCK8
Include full metaphysics block (Bazi/Huangli + Western almanac):
CODEBLOCK9
HTTP API
Run HTTP API for multi-claw integration:
CODEBLOCK10
Run with Docker:
CODEBLOCK11
Contract
Use the JSON contract in references/integration-contract.md for tool-to-tool integration. Keep payload keys calendar-specific and avoid ambiguous fields.
Tool Mapping
- - MCP tools:
capabilities, convert, timeline, astro_snapshot, calendar_month, INLINECODE18 - CLI commands:
capabilities, convert, timeline, astro, calendar-month, INLINECODE24 - FastAPI endpoints:
GET /capabilities, POST /convert, POST /timeline, POST /astro, POST /calendar-month, INLINECODE30
References
- - Use
references/integration-contract.md for request/response schema and compatibility guidance. - Use
references/calendar-landscape.md for East/West major calendar systems and rollout priorities. - Use
references/time-wheel-model.md for timestamp-first design and instant/date projection rules. - Use
references/mvp-release-notes.md as GitHub release draft baseline.
Notes
- - Treat Gregorian as the canonical bridge format.
- Return warnings instead of hard-failing for optional providers that are not installed.
- Mark approximate outputs explicitly (for example, sexagenary year boundaries and fixed-date solar-term approximation).
- Treat
timeline as the default bridge for multi-agent scheduling and event processing. - INLINECODE36 conversion payload is numeric; Chinese textual month/day labels are exposed via
day_profile.metaphysics.eastern.lunar_date when lunar_python is available.
Clawlendar
概述
提供一个统一的、对智能体友好的桥接层，使不同工具能够以通用模式查询日历问题，并接收标准化的 JSON 响应。将此技能视为多智能体生态系统中的日期互操作性基准。
工作流程
- 1. 首先调用 capabilities 来发现支持的日历、可选提供商和区域设置支持。
- 对于日历转换，在声明的日历中解析源数据负载，并通过公历进行桥接。
- 对于基于时间点的工作流程，使用 timeline（时间戳优先）而非直接日期转换。
- 当用户界面需要在非公历系统中获取真实的月份边界时，使用 calendarmonth。
- 使用 dayprofile 获取一次性详细信息（干支、二十四节气、农历、可选占星、可选玄学）。
- 当需要面向用户显示文本时，始终传递 locale（en、zh-CN、zh-TW）。
快速入门（MCP 服务器）
安装并作为 MCP 服务器运行，用于 Claude Desktop / Claude Code：
bash
python3 -m pip install -U clawlendar[all]
clawlendar
在 Claude Code 中一行注册：
bash
python3 -m pip install -U clawlendar[all] && claude mcp add clawlendar -- clawlendar
或直接从源码运行：
bash
pip install -e .
python -m clawlendar.server
CLI 使用
列出支持的日历和可选后端：
bash
pip install -e .
python3 scripts/calendar_bridge.py capabilities
将一个日期转换为多个目标：
bash
python3 scripts/calendar_bridge.py convert \
--source gregorian \
--targets julian,isoweek,minguo,buddhist,japaneseera,sexagenary,solarterm24 \
--date-json {year: 2026, month: 3, day: 9}
使用时间戳优先模型标准化一个时间点（外部时间轮）：
bash
python3 scripts/calendar_bridge.py timeline \
--input-json {timestamp: 1773014400} \
--timezone Asia/Taipei \
--date-basis local \
--targets minguo,japaneseera,sexagenary,solarterm_24
生成用于黄道轮渲染的占星快照：
bash
python3 scripts/calendar_bridge.py astro \
--input-json {timestamp: 1773014400} \
--timezone Asia/Taipei
获取非公历月份模式的真实月份边界：
bash
python3 scripts/calendar_bridge.py calendar-month \
--source minguo \
--month-json {year:115,month:3}
获取统一的每日档案数据负载：
bash
python3 scripts/calendar_bridge.py day-profile \
--input-json {timestamp: 1773014400} \
--timezone Asia/Taipei \
--locale zh-TW
包含完整的玄学模块（八字/黄历 + 西方历书）：
bash
python3 scripts/calendar_bridge.py day-profile \
--input-json {timestamp: 1773014400} \
--timezone Asia/Taipei \
--locale zh-CN
HTTP API
运行 HTTP API 以实现多爪集成：
bash
pip install -e .[api]
./scripts/run_api.sh
使用 Docker 运行：
bash
docker build -t clawlendar:mvp .
docker run --rm -p 8000:8000 clawlendar:mvp
契约
使用 references/integration-contract.md 中的 JSON 契约进行工具间集成。保持数据负载键的日历特定性，避免歧义字段。
工具映射
- - MCP 工具：capabilities、convert、timeline、astrosnapshot、calendarmonth、day_profile
- CLI 命令：capabilities、convert、timeline、astro、calendar-month、day-profile
- FastAPI 端点：GET /capabilities、POST /convert、POST /timeline、POST /astro、POST /calendar-month、POST /day-profile
参考资料
- - 使用 references/integration-contract.md 了解请求/响应模式和兼容性指南。
- 使用 references/calendar-landscape.md 了解东西方主要日历系统和发布优先级。
- 使用 references/time-wheel-model.md 了解时间戳优先设计和时间点/日期投影规则。
- 使用 references/mvp-release-notes.md 作为 GitHub 发布草案的基准。
注意事项
- - 将公历视为规范的桥接格式。
- 对于未安装的可选提供商，返回警告而非硬性失败。
- 明确标记近似输出（例如，干支年份边界和固定日期节气近似值）。
- 将 timeline 视为多智能体调度和事件处理的默认桥接方式。
- chineselunar 转换数据负载为数字格式；当 lunarpython 可用时，中文文本形式的月份/日期标签通过 dayprofile.metaphysics.eastern.lunardate 暴露。
