RishiAI — Ground-Truth Vedic Astrology

Vedic astrology tools powered by the DashaFlow calculation engine, served over the Model Context Protocol — plus the ground-truth reading contract those tools are read under: doctrine that binds the interpreter, a verifier pass on high-stakes slices, and an auditable output format.

Works over stdio — as a plugin in Claude Code and Codex, or as a pip-installed MCP server for any other MCP-compatible client.

https://github.com/user-attachments/assets/9c183b94-bb54-4af6-867c-fa3daeef2d03

Install

A. Host install — Claude Code (plugin) · Codex (MCP + skill) · OpenCode (MCP + skill)

Claude Code

/plugin marketplace add adarshj322/rishi-ai-mcp
/plugin install rishi-ai@rishi-ai-mcp

Codex (CLI v0.128.0, verified 2026-11-08)

codex plugin marketplace add adarshj322/rishi-ai-mcp

Limit: this CLI version ships only marketplace subcommands — no plugin add, plugin list, or plugin install. The marketplace registers, and the repo carries .codex-plugin/plugin.json + root hooks.json + .agents/plugins/marketplace.json for when a newer CLI adds install support, but Codex cannot install the plugin bundle from the CLI today. The working path is pip + a copied skill (no clone needed):

pip install rishi-ai-mcp
SRC=$(python -c "import rishi_ai_mcp, os; print(os.path.join(os.path.dirname(rishi_ai_mcp.__file__), 'skills', 'rishi-reading'))")
mkdir -p ~/.codex/skills/rishi-reading
cp -r "$SRC/SKILL.md" "$SRC/contract.md" "$SRC/references" ~/.codex/skills/rishi-reading/

~/.codex/config.toml needs:

[mcp_servers.vedic-astrology]
command = "uvx"
args = ["rishi-ai-mcp"]

Verify with codex mcp list (shows vedic-astrology ... enabled). The two verification subagent definitions (agents/chart-verifier.md, agents/doctrine-critic.md) ship in the plugin bundle and the repo — not in the pip wheel; fetch them from the repo if you want them as reference. No verification binding ships on this path; the contract is read, not enforced.

What the plugin ships:

• skills/rishi-reading/SKILL.md + skills/rishi-reading/references/*.md — the doctrine, auto-discovered by the host

• agents/chart-verifier.md and agents/doctrine-critic.md — bounded verification subagents (gated; see Limitations)

• hooks/hooks.json (Claude Code; Codex uses root hooks.json) — a one-line UserPromptSubmit reminder. Echo only, no side effects

• .mcp.json — wires uvx rishi-ai-mcp. The plugin bundle carries no Python; the package is resolved on first run

Verified: Claude Code plugin install cached at 1.6.0 with skill, agent definitions, reminder hook, and .mcp.json all present; claude mcp list shows vedic-astrology: connected.

The plugin doctrine is built around 5 tools by design: cast_vedic_chart, cast_transit_chart, calculate_compatibility_tool, check_muhurtha_tool, analyze_career_chart. The pip-installed server exposes all 12 (the remaining 7 are drill-downs — see MCP Tools).

B. pip — everything else

pip install rishi-ai-mcp

• Console script: rishi-ai-mcp

• Exposes all 12 tools over stdio

• The doctrine is vendored into the wheel at <site-packages>/skills/rishi-reading/ (contract.md + references/). Read it directly, or paste it into your host's system-prompt field; system_prompt.md in this repo is a minimap that points at it

• Lahiri ayanamsha by default; other variants are named, never mixed

OpenCode (verified 2026-11-08 on v2.2.6)

No plugin bundle ships for OpenCode — a plugin cannot register an MCP server or a skills directory (verified against the plugin API), so there is nothing to npx install. The working path is the same two pieces by hand (no clone needed):

pip install rishi-ai-mcp
SRC=$(python -c "import rishi_ai_mcp, os; print(os.path.join(os.path.dirname(rishi_ai_mcp.__file__), 'skills', 'rishi-reading'))")
mkdir -p ~/.config/opencode/skills/rishi-reading
cp -r "$SRC/SKILL.md" "$SRC/contract.md" "$SRC/references" ~/.config/opencode/skills/rishi-reading/

Then add to ~/.config/opencode/opencode.jsonc, inside the top-level "mcp" object (flat keys — a nested mcp.servers object is ignored):

"vedic-astrology": {
  "type": "local",
  "command": ["uvx", "rishi-ai-mcp"]
},

Verified: the session then lists rishi-reading in its available skills, and opencode mcp list --print-logs reports vedic-astrology: connected. No verification binding ships this way — the contract is read; it is not enforced. (The doctrine covers 5 core tools by design; the pip server itself exposes all 12 — see MCP Tools.)

Other harnesses — Gemini CLI, VS Code Copilot, Cursor, Roo/Kilo

Docs path only: pip install rishi-ai-mcp, add the stdio server per your host's MCP documentation, and adapt system_prompt.md to the host's instruction format. These are not plugins; there is no verification binding; the doctrine ships as text, not as an enforced contract.

Warning: there is no published npm/npx package and no plugin bundle outside this repository. Any third-party copy of "rishi-ai-mcp" — a fork, a repackaging, a registry listing — is unaffiliated and unverified. Install from this repo or from PyPI only.

Related MCP server: AstroConsultant

Quick Start

rishi-ai-mcp                    # console entry point (after pip install)
python rishi_ai_mcp.py          # or run directly from source

Communicates over stdio. Any MCP client that can spawn a subprocess and speak MCP can use it — no IDE required. Plugin installs skip this step; the plugin wires the server for you.

MCP Tools

The server exposes all 12 tools over stdio. The plugin doctrine is built around 5 by design — cast_vedic_chart, cast_transit_chart, calculate_compatibility_tool, check_muhurtha_tool, analyze_career_chart; the rest are drill-downs documented for the pip path.

cast_vedic_chart

Generates a Vedic natal chart. Compact by default (<4KB), full on request.

Returns (compact): lagna, condensed planets (sign/house/nakshatra/dignity + vargottama/yogakaraka flags), active dasha lords (Vimshottari/Yogini/Chara), yoga names, strength totals, SAV, dosha flags, time_sensitivity verdict (robust/borderline/fragile) — each section naming its drill-down tool.

Returns (full): JSON with metadata, panchang, lagna (with D2–D60 signs), planets (with dignity, combustion, Shadbala, all 14 Varga signs, aspects), dashas (5 levels: Maha/Antar/Pratyantar/Sukshma/Prana + timeline), yogini_dasha, chara_dasha, yogas (24 detections), ashtakavarga (SAV + BAV + Prashtara), sodhita_ashtakavarga (reduced + Sodhya Pinda), jaimini_karakas, shadbala (with Ishta/Kashta Phala), vimshopaka, bhava_chalit, avasthas, kaal_sarpa, graha_yuddha, gandanta, arudha_padas (A1–A12), upapada, karakamsha.

Errors raise MCP ToolError (no {"error"} data payloads).

get_dasha_periods_tool, get_strength_table_tool, get_yoga_list_tool, get_time_sensitivity_tool

Drill-downs for the compact chart: full dasha chains with dates (all 3 systems), per-planet strength components, full yoga entries, birth-time sensitivity (robust/borderline/fragile verdict with notes). Same birth parameters as cast_vedic_chart; time accepts "HH:MM[:SS]".

cast_transit_chart

Calculates planetary transits overlaid on a natal chart.

Returns: JSON with transit planets (sign, degree, nakshatra, sav_points, house from Lagna/Moon), sade_sati status and phase, and rahu_ketu_axis.

get_transit_ingresses_tool, get_sade_sati_timeline_tool, get_gochara_tool

Timing tools for "when" questions. Same birth parameters as cast_vedic_chart; time accepts "HH:MM[:SS]".

calculate_compatibility_tool

Calculates 16-factor compatibility + Kuja Dosha. Person 1 = Male, Person 2 = Female.

Returns: 8 Ashtakoot kutas (36 pts), additional kutas (Mahendra, Stree Deergha, Vedha, Rajju, BadConstellations, LagnaHouse7, SexEnergy), exception logic, and Kuja Dosha analysis.

check_muhurtha_tool

Evaluates whether a date/time is auspicious for a specific activity (electional astrology).

Returns: JSON with verdict, score, positive_factors, negative_factors, panchang_suddhi, and marriage_doshas (for marriage activity).

analyze_career_chart

Analyzes career potential using the 10th house, D10 Dashamsha, and planetary significations.

Returns: JSON with tenth_house info, d10_indicators, career_themes, and strength_factors.

The RishiAI persona (ground truth, not flattery)

RishiAI is a Vedic astrologer (Jyotishi) bound by an explicit contract rather than by vibe. The model is an interpreter of tool-computed chart data — never a calculator, working under Brihat Parashara Hora Shastra with Desh–Kaal–Patra (person, time, place, circumstance) framing. Birth details come first or not at all; positions, dashas, and divisional charts are never computed by hand — only the tools speak for the chart.

What it honestly claims: the consistency and auditability of its interpretation. Every factual claim cites its chart grounds — planet, sign, house, degree, dignity, shadbala, dasha window — or is tagged UNSUPPORTED and cut or printed beside the tag. Its compute layer is checkable: sidereal positions (Lahiri ayanamsha default) via Swiss Ephemeris/pyswisseph, deterministic run to run. Its reading layer is auditable: every reading ends with a grounds appendix, a calibration footer, a disagreement log, and a provenance line — the artifacts make the reading checkable by anyone, not trusted by default.

What it honestly refuses: certainty about the future. No claim in this repository licenses telling someone what will happen to them; the correspondence layer is out of scope until a preregistered prospective registry exists (it does not yet). It refuses medical, legal, or financial advice — those get gentle language and a professional. It never states or hints longevity probabilities; maraka periods read only as deep transformation. It carries no fear framing, never sells or bundles remedies, and treats "no remedy needed" as a valid — often correct — output.

The contract — skills/rishi-reading/contract.md — in one line each:

1. R1 Falsifiability — every claim cites its chart grounds or is tagged UNSUPPORTED; the grounds appendix prints in every reading.

2. R2 Uncertainty — stated in plain words, scored by a separate pass, never as a numeric self-report; the footer counts what was withheld and flagged.

3. R3 Discriminating agreement — never retract a tool-supported claim under challenge without new grounds; never adopt a user premise the chart contradicts.

4. R4 Forbidden behaviors — no fear framing; never a death/longevity probability; medical/financial/crisis deferral to professionals; five checkable-error refusal triggers.

5. R5 Remedy restraint — matched remedies only, after the facts; "no remedy needed" is always a valid output.

6. R6 Accountability — grounds appendix + calibration footer + disagreement log + provenance line in every reading; provenance missing means not a valid reading.

How a reading actually unfolds — intake, cast-before-counsel, verify-by-default on high-stakes slices — lives in the entry skill skills/rishi-reading/SKILL.md and its references/. Plugin hosts auto-discover it; pip installs get it vendored in the wheel. Where any file disagrees with the contract, the contract wins.

High-stakes slices — marriage, health, career, remedies, fear content — route through the gated verification pair (agents/chart-verifier.md re-derives each cited value from tool output; agents/doctrine-critic.md checks the prose against the contract). Verification is currently off until the pre-committed equal-cost bar clears — see evals/README.md and Limitations.

Architecture

rishi_ai_mcp.py            MCP server — all 12 tools, stdio, single file
  └── dashaflow (pip)      Calculation engine — Swiss Ephemeris via pyswisseph, Moshier fallback (no .se1 files)
        ├── vedic_calculator   Swiss Ephemeris core
        ├── constants          Zodiac, nakshatras, dignities
        ├── panchang           Tithi, Vara, Yoga, Karana
        ├── yoga               24 yoga types + Kaal Sarpa, Graha Yuddha, Gandanta
        ├── dasha              Vimshottari 5-level
        ├── dignity            Dignity, combustion, digbala
        ├── ashtakavarga       SAV, BAV, Prashtara
        ├── jaimini            Karakas, Arudha Padas, Upapada, Karakamsha
        ├── shadbala           Six-fold strength + Ishta/Kashta
        ├── matchmaking        16-factor compatibility + Kuja Dosha
        ├── muhurtha           Electional astrology
        └── career             D10 career analysis

skills/rishi-reading/       Doctrine — contract.md + references/ (entry skill auto-discovered by plugin hosts;
                            vendored into the wheel for pip installs)
agents/                     chart-verifier.md, doctrine-critic.md — gated verification (off until the
                            equal-cost bar clears; see evals/README.md)
evals/                      JyotishQA seed set + Tier-1 conformance corpus (300 moments) + the gate pre-commitment
tools/build_plugin.py       Renders and verifies the per-host manifests (--check runs in CI)
tools/tier1_check.py        Tier-1 determinism gate (dual invocation, 300 moments)
.claude-plugin/             Claude Code — plugin.json + marketplace.json (auto-discovers skills/, agents/, hooks/)
.codex-plugin/              Codex — plugin.json (skills/ and mcpServers pointers + interface block)
.agents/plugins/            Codex marketplace catalog
hooks/hooks.json            Claude Code reminder hook (UserPromptSubmit; echo only, no side effects)
hooks.json                  Codex reminder hook (repo root; Codex does not read hooks/hooks.json)
.mcp.json                   uvx rishi-ai-mcp wiring (unpinned until the release flow pins it)
system_prompt.md            Minimap for non-plugin hosts — points at the vendored contract
AGENTS.md                   Doctrine pointer for agent harnesses

Limitations

Stated plainly, because a reading tool that overclaims is worse than none:

• No ephemeris files. The engine computes through pyswisseph's Moshier fallback (no .se1 data files). Positions are ~1″-class and deterministic run to run — adequate for Jyotish sign/degree work, but this is not a Swiss Ephemeris Professional setup and no such claim is made.

• No astronomical-truth verification. The Tier-1 corpus (300 pinned moments, 1900–2030) is a regression and determinism gate — the same input produces the same output, path to path. It verifies determinism, not astronomical truth, and must not be cited as doing so.

• Lahiri ayanamsha by default. Other variants are named when used; systems are never mixed within one reading.

• No predictions. No claim here licenses telling someone what will happen. There is no ground truth for outcomes; the correspondence layer is out of scope until a preregistered prospective registry exists — it does not yet.

• No interpretive-validity claim. What a placement means is an interpretation under a stated rulebook, not a measured fact. The claim is consistency and auditability of interpretation — nothing more.

• Verification is off by default. The plugin ships with the verification path disabled. It unlocks only if the pre-committed equal-cost bar clears — delta > seed-set standard error at first measurement, locked, with the set expanded rather than the bar relaxed; the bar is written down in evals/README.md before any run. Until then, sample-and-vote plus the deterministic tool-check is what ships.

• Not medical, legal, or financial advice. The chart may frame themes; it may not triage, dose, or time treatment. Crisis language routes to professionals and crisis resources, never to a chart.

• OpenCode and other hosts get no binding. Outside the two plugin hosts, the contract is documentation, not enforcement — the tools and doctrine text are real, but nothing gates the reading.

Prerequisites

• Python 3.10+

• dashaflow — installed automatically as a dependency

• mcp — installed automatically as a dependency

• Plugin installs: uv (for uvx) — no local Python environment needed for the doctrine; uvx resolves the package on first run

Contributing

Contributions are welcome — see CONTRIBUTING.md. House rules: new tools go through dashaflow first; the single-file rishi_ai_mcp.py pattern stays; run pytest -q and ruff --select E,F,W,I,UP,B --ignore E501 . before opening a PR.

License

MIT — see LICENSE.