# NaturaOS

> Headless, deterministic Eastern-metaphysics engine on Cloudflare Workers. Faithfully inherits and digitizes research from Dr. Ho Ngoc Duc (TS. Hồ Ngọc Đức UTC+7 algorithm), Phan Bội Châu, Nguyễn Hiến Lê, and Nhân Tử Nguyễn Văn Thọ. NaturaOS provides a humble, deterministic bridge for modern AI agents and applications.

## Academic Heritage, Multi-Source Synthesis & Copyright Compliance

- **TS. Hồ Ngọc Đức**: Vietnamese astronomical lunar calendar algorithm (VNCal, UTC+7).
- **Cụ Phan Bội Châu**: *Quốc văn Chu Dịch diễn giải* (1926) — philosophical I Ching exposition.
- **Học giả Nguyễn Hiến Lê**: *Kinh Dịch — Đạo của người quân tử* — ethical humanistic commentary.
- **BS. Nhân Tử Nguyễn Văn Thọ**: *Dịch Kinh Đại Toàn*, *Dịch Kinh Yếu Chỉ* — Ten Wings translation.
- **International Scholarship**: Cross-referenced with foundational scholarly works by Richard Wilhelm & Cary F. Baynes, James Legge (Oxford), and Joseph Needham.
- **Copyright & Independent Synthesis**: NaturaOS strictly respects 20th-century authors' copyrights and does not copy proprietary publications verbatim. All data models and translations are synthesized independently from public-domain classical Han texts and open international research.

## Core Endpoints & Documentation

- [Interactive User Guide](https://naturaos.mza.vn/guide): Setup instructions, 1-click MCP configuration for Claude/Cursor/ChatGPT, and quota limits.
- [Swagger UI & REST API Docs](https://naturaos.mza.vn/api/docs): Interactive OpenAPI 3.0 documentation and endpoint tester.
- [OpenAPI 3.0 Spec](https://naturaos.mza.vn/api/openapi.json): Machine-readable OpenAPI specification for tools and code generation.
- [Full LLM Specification](https://naturaos.mza.vn/llms-full.txt): Complete documentation of all operations, schemas, and payload examples for AI agents.

## Operations

- [calendar.dayInfo](https://naturaos.mza.vn/api/v1/calendar/day): Full solar and lunar calendar day calculation (solar date, lunar date, leap month, Julian day, solar term).
- [calendar.convertSolarToLunar](https://naturaos.mza.vn/api/v1/calendar/convert): Convert Gregorian solar date to Vietnamese lunar date.
- [ganzhi.calendarPillars](https://naturaos.mza.vn/api/v1/ganzhi/pillars): Four pillars of time (Year, Month, Day, Hour Can Chi) and 60 Hoa Giap.
- [iching.cast](https://naturaos.mza.vn/api/v1/iching/cast): Cast hexagram via Mai Hoa (time/number) method with moving lines and transformed hexagram.
- [iching.hexagram](https://naturaos.mza.vn/api/v1/iching/hexagram): Detailed 64-hexagram lookup with canonical Zhouyi text and Vietnamese translation.

## MCP Server Integration

Add NaturaOS to Claude Code CLI:
```bash
claude mcp add naturaos https://naturaos.mza.vn/mcp --header "Authorization: Bearer <key>"
```

Add NaturaOS to Cursor (.cursor/mcp.json):
```json
{
  "mcpServers": {
    "naturaos": {
      "url": "https://naturaos.mza.vn/mcp",
      "headers": { "Authorization": "Bearer <key>" }
    }
  }
}
```