Astro Skill README

🌌 Astro Skill

High-precision, deterministic Vedic astrology engine, portable agent skill, and stdio MCP server.
Swiss Ephemeris SWIEPH precision • 100% Offline & Zero API Keys • In-process ReportLab PDF • 11 MCP Tools

🎯 Overview

Astro Skill is a production-grade, deterministic Vedic astrology engine that converts birth details and celestial coordinates into structured mathematical charts, timelines, and factual reports.

• 🔬 Zero Hallucinations: 100% calculation-backed using bundled Swiss Ephemeris data (.se1 SWIEPH via pyswisseph) and Lahiri (Chitrapaksha) ayanamsa.
• 🔌 3 Plug-and-Play Surfaces:
  1. Stdio MCP Server (astro-mcp): 11 stable tools for Claude Desktop, Cursor, Codex, OpenClaw, and any Model Context Protocol client.
  2. Python Library & CLI: Import directly in Python or run standalone CLI calculator scripts with --json outputs.
  3. Agent Skill: Portable SKILL.md ready to equip autonomous coding agents and orchestrators.
• 📄 In-Process PDF Generator: Generates bilingual (Hindi & English) Kundali and Panchang charts via ReportLab with bundled Noto Sans Devanagari font — zero headless browser or Chrome dependencies.
• 🔒 100% Offline & Private: Zero external API keys, zero rate-limits, and zero network calls required for astrological calculations.

🏛️ Architecture & Layering

                     [ Client / Agent Request ]
                                 │
                 ┌───────────────┼───────────────┐
                 ▼               ▼               ▼
          Stdio MCP Server   Python CLI     Agent Skill
          (11 Tools/JSON)   (Scripts/Lib)   (SKILL.md)
                 │               │               │
                 └───────────────┬───────────────┘
                                 │
                                 ▼
                     ┌───────────────────────┐
                     │   Astro Core Engine   │
                     │  (Swiss Ephemeris     │
                     │   + Lahiri Ayanamsa)  │
                     └───────────┬───────────┘
                                 │
                 ┌───────────────┴───────────────┐
                 ▼                               ▼
       [ Structured JSON ]            [ In-Process ReportLab PDF ]
       - 12 Bhavas, Grahas, Yogas     - Lagna & Navamsa (D1/D9)
       - Vimshottari Timeline         - Devanagari Hindi/English
       - Gochar & Guna Milan          - Dasha Strips & Panchang

✨ Core Capabilities

🚀 Quick Start

1. Install from PyPI

pip install astro-skill

Requires Python 3.11+.

2. Run the Stdio MCP Server

astro-mcp
# or: python -m services.astro_mcp

3. CLI Command Examples

# Calculate Birth Kundali (JSON output)
python -m astro.scripts.kundali_calculator --dob 26/12/2019 --tob 09:15 \
  --place Delhi --lat 28.6139 --lon 77.2090 --timezone Asia/Kolkata --json

# Calculate Vimshottari Dasha Timeline
python -m astro.scripts.dasha_calculator --kundali-json chart.json --json

# Daily Panchang
python -m astro.scripts.panchang_calculator --date 2026-05-21 \
  --place Delhi --lat 28.6139 --lon 77.209 --timezone Asia/Kolkata --json

# Ashtakoot Guna Milan (Compatibility)
python -m astro.scripts.guna_milan --kundali-a-json person_a.json --kundali-b-json person_b.json --json

# Generate Factual Bilingual PDF Report
python -m astro.scripts.pdf_report --kundali-json chart.json --dasha-json dasha.json \
  --panchang-json panchang.json --output report.pdf --language hi

4. Python Library Usage

from astro.scripts.kundali_calculator import calculate_kundali

kundali = calculate_kundali(
    dob="15/08/1990",
    tob="14:30",
    place="Mumbai",
    lat=19.0760,
    lon=72.8777,
    tz_str="Asia/Kolkata"
)

print(f"Lagna: {kundali['lagna']['sign_name']}, Nakshatra: {kundali['nakshatra']['name']}")

🤖 MCP Server Setup

The built-in MCP server exposes 11 tools over stdio. It includes SQLite client profile management and report generation out of the box.

📋 Available MCP Tools (11)

⚙️ Client Configurations

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "astro": {
      "command": "astro-mcp"
    }
  }
}

Cursor (settings.json / MCP Config)

{
  "mcpServers": {
    "astro": {
      "command": "python",
      "args": ["-m", "services.astro_mcp"],
      "cwd": "C:/path/to/astro-skill"
    }
  }
}

👑 Pro Report Tier

This repository contains the open-core deterministic engine — mathematical calculations, structured JSON schemas, and factual ReportLab PDFs.

For astrologers, consultancies, and consumer apps seeking client-ready, beautifully designed Janma Patrikas, a Pro Report Tier is available:

• 📖 Pandit-Grade LLM Synthesis: Deep house-by-house, dasha-by-dasha, and transit narrative analysis in Hindi, English, or Hinglish.
• 🎨 Premium Print-Ready Layout: Multi-page styled Janma Patrika with rich cover pages, divisional charts, and branded styling.
• ⚡ Prioritized Actionable Remedies: Context-aware Gemstone, Mantra, Yantra, and Daan suggestions tailored to running dasha periods.

📩 Interested in licensing the Pro Tier or API? Contact: adityaryawork@gmail.com

🛠️ Development & Testing

git clone https://github.com/adityarya24/astro-skill.git
cd astro-skill
python -m venv .venv
source .venv/bin/activate  # Windows: .\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

# Run full test suite (154 tests)
pytest -q

# Linter & format check
ruff check astro services scripts

🛡️ Safety Boundaries

1. Calculation-Backed Drafts: Reports are mathematical baselines intended for review by an astrologer or operator before sharing.
2. Missing Birth Details: Never guess or synthesize birth times or locations; prompt the user if inputs are missing.
3. Ethical Guardrails: Strictly prohibits generating fatalistic claims, death timing, medical diagnoses, or unavoidable harm predictions.

📜 License

MIT License © 2026 Aditya Arya