# vedicchart

A local stdio bridge to a hosted Vedic astrology
service, with no astrology logic of its own.

The hosted service computes free Vedic astrology over
the Model Context Protocol: the daily panchang, janam
kundali birth charts, kundli matching, dosha checks
(manglik, kaal sarp, sade sati), dasha periods,
transits, muhurta timings, festival and eclipse
calendars, and several forms of Vedic numerology —
17 tools in all. Results are deterministic, computed
with the Swiss Ephemeris on the sidereal zodiac
(Lahiri ayanamsa). No account and no API key are
needed; the hosted endpoint allows 30 requests per
minute per IP.

vedicchart exists for MCP clients that only speak
stdio. It serves `tools/list` locally — the tool
names, descriptions and input schemas are the hosted
server's own, captured live on 2026-10-27 and served
verbatim — and forwards every `tools/call` to the
hosted endpoint, returning the result unchanged.

## Configuration

- `KUNDLIT_MCP_URL` (optional) — hosted MCP endpoint.
  Defaults to `https://kundlit.com/api/mcp`.

## How a call travels

Each forwarded call runs the streamable-HTTP
JSON-RPC sequence against the endpoint:

1. an `initialize` request,
2. a `notifications/initialized` notification,
3. the `tools/call` request itself.

If the server issues an `Mcp-Session-Id` header, it
is sent back on the later requests of the same call.
Replies framed as server-sent events are understood
as well as plain JSON replies.

If the hop to the hosted server fails — unreachable,
a non-2xx answer, or an unusable reply — the call
fails locally with a JSON-RPC `-32001` error whose
message begins `vedicchart error:`, rather than
leaving the client hanging. An error the hosted
server itself sends is surfaced with its own message
under the same prefix.

## Tools

- `get_panchang` — the daily Hindu almanac for a date
  and place: tithi, nakshatra, yoga, karana, vara,
  sunrise and sunset, and the day's auspicious and
  inauspicious windows.
- `get_janam_kundali` — a full birth chart: lagna,
  the nine grahas, the running dashas and detected
  yogas.
- `get_kundli_match` — ashtakoot matching of two
  birth charts.
- `check_manglik` — whether a chart carries mangal
  dosha, and its strength.
- `get_sade_sati` — sade sati status and phases for
  a birth chart.
- `check_kaal_sarp` — kaal sarp dosha presence and
  type.
- `get_pancha_pakshi` — pancha pakshi activity
  periods for a birth star.
- `get_muhurta_timings` — the full timing surface
  for choosing a moment: choghadiya, horas and the
  periods to avoid.
- `get_year_events` — festivals and observances for
  a year at a place.
- `get_eclipses` — solar and lunar eclipses for a
  year.
- `get_numerology` — Vedic numerology numbers from
  a name and birth date.
- `get_love_compatibility` — compatibility from two
  partners' details.
- `get_mobile_numerology` — how a mobile number
  resonates with its owner.
- `get_birth_details` — the birth star and chart
  basics for one person.
- `get_dasha_periods` — Vimshottari dasha periods
  for a birth chart.
- `get_upapada_arudha` — upapada and arudha lagna
  calculations.
- `get_transits` — current and upcoming planetary
  transits for a chart.

The authoritative description of each tool — its
exact inputs, defaults and caveats — is the one
served in `tools/list`, which is the hosted server's
own text.

## CLI

Each tool is a subcommand taking one JSON argument
string; the forwarded result is printed as JSON:

```bash
npx @reneturcios/vedicchart get_panchang '{"place":"Jaipur, Rajasthan, India"}'
npx @reneturcios/vedicchart get_janam_kundali '{"birth_date":"1992-03-14","birth_time":"06:45","place":"Lucknow, India"}'
npx @reneturcios/vedicchart get_eclipses '{"year":2026}'
npx @reneturcios/vedicchart --version
```

Exit codes: `0` on success, `1` on a runtime error,
`2` on a usage error.

## MCP server

```bash
npx -y @reneturcios/vedicchart mcp
```

MCP client config:

```json
{
  "mcpServers": {
    "vedicchart": {
      "command": "npx",
      "args": ["-y", "@reneturcios/vedicchart", "mcp"]
    }
  }
}
```

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/vedicchart
docker run --rm ghcr.io/cloudcorprecords/vedicchart get_eclipses '{"year":2026}'
```

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source
```

## License

MIT — Copyright (c) 2026 Rene Turcios