Methodology v2
Transit Timing Hierarchy
get_transit_timing_hierarchy
KP transit timing hierarchy: Saturn narrows to ~2.5yr window, Jupiter to the year, Sun to the month, Moon to the day. A transit in the star of a RETROGRADE natal planet is a DELAYED window, never an invalid one (F011): it stays in the hierarchy, and since F063 it carries two dated releases, neither chosen: 'turnsDirect' is the NATAL release, when that natal planet next turns direct (Astrology for Beginners canon p.885), and 'passesStartingPoint' is the HORARY one, Sutra 32, when it is direct and has re-crossed the degree it turned back from (Reader 6 canon p.155). The delayed windows are also listed in 'retroDelays', each row with its 'reason', so the delay has a date. Requires fruitful significators internally, selected with the Ruling Planets of the moment of judgement ('judgement_datetime', default now; KP Reader 4), with the birth-moment set beside them as 'atBirth'. The scan starts at 'start_date', by default that same moment of judgement, and 'startDateUsed' says which instant it started from. **A window opens only where the transiting planet's star lord AND sub lord are both fruitful significators**, per KP Reader 5 canon p.195: the star lord says what is offered, the sub lord says whether it materialises. Each window also carries 'offeredFrom', the earlier moment the star lord alone became fruitful. That is when the matter came on offer, NOT when to act: canon p.192 says "do not expect the result on the day of entry, you have to wait till the significator comes to the sub". Quote 'start', not 'offeredFrom', when giving a date. 'judgement.holdsUntil' is the next instant those Ruling Planets change, solved and never a score: 'instant' in UTC, 'local' with the offset in force then only when 'judgement_time_zone' is sent, otherwise with the judgement's own offset (read 'utcOffsetSource'), and 'changes' naming the member (the Ascendant's or the Moon's sign or star lord, or the day lord at sunrise at the place) with its old and new lord. The fruitful set holds until that instant; say so when you quote it. Books: KP Reader 5 canon pp.192, 195.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| birth_datetime | string | Yes | Birth date and time in ISO 8601 format (e.g., "1990-05-15T14:30:00"). |
| latitude | number | Yes | Birth location latitude. Range: -90 to 90. |
| longitude | number | Yes | Birth location longitude. Range: -180 to 180. |
| utc_offset_minutes | number | Yes | UTC offset in minutes (e.g., 330 for IST, -300 for EST). |
| ayanamsa | enum: kp | kp_new | lahiri | raman | true_chitra | khullar | No | Ayanamsa system. Defaults to kp. |
| event | event name | No | Life event to find transit timing for. If omitted, the engine derives the most active event from the signification of the MD+AD lords running at the moment of judgement, with Ruling Planets tie-break, and returns it in the eventResolution field. Ignored if house_group is provided. |
| start_date | string | No | Where the transit scan starts, ISO 8601 (e.g. 2026-04-01T00:00:00+05:30). Defaults to the moment of judgement, so with judgement_datetime sent and no start_date the scan starts at that moment; with neither, now. `startDateUsed` echoes the instant scanned from and how this value was read. Send a zone (Z, or +hh:mm as in 2026-10-20T10:30:00+05:30). A value without a zone is read as UTC, never as local time, and a date alone is midnight UTC. This is a different moment from judgement_datetime, which is a local wall clock sent with its own offset. |
| judgement_datetime | string | No | The moment the matter is judged, local wall clock at the birth place unless judgement_latitude/longitude are given (e.g. 2026-09-27T12:00:00). Defaults to now. KP selects fruitful significators with the Ruling Planets of THIS moment (KP Reader 4), not the birth moment. |
| judgement_latitude | number | No | Latitude of the place of judgement. Defaults to the birth latitude. |
| judgement_longitude | number | No | Longitude of the place of judgement. Defaults to the birth longitude. |
| judgement_utc_offset_minutes | number | No | UTC offset of the place of judgement in minutes. Defaults to the birth offset when the place defaults to the birth place. |
| judgement_time_zone | string | No | IANA time zone of the place of judgement (e.g. "Asia/Colombo"), instead of judgement_utc_offset_minutes: the offset in force there at judgement_datetime is read from the tz database. If both are given they must agree. |
| house_group | array<house number (1-12)> | No | Override event lookup with explicit house numbers (1-12). When provided, event is ignored. |
Example call
Send the request as a standard MCP tools/call:
POST https://mcp.lumin.guru/mcp
Authorization: Bearer mcp_yourkey...
Accept: application/json, text/event-stream
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_transit_timing_hierarchy",
"arguments": {
"birth_datetime": "1992-08-14T04:32:00",
"latitude": 6.927,
"longitude": 79.861,
"utc_offset_minutes": 330,
"ayanamsa": "kp"
}
}
}Birth data
This tool requires birth data on every call. The MCP server is stateless, so calling set_birth_profile first validates the data and returns the reading plan, but it does not store anything. Repeat the same five fields here.