@morphemeris/mcp 0.4.0 → 0.5.0

package/dist/index.js

@@ -68,23 +68,31 @@ var MorphemerisClient = class {
 // src/tools/calculate-positions.ts
 import { z } from "zod";
 function registerCalculatePositions(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "calculate_positions",
-    "Calculates ecliptic positions (longitude, latitude, distance, daily motion) for celestial bodies at a given moment. Supports tropical and sidereal zodiacs, heliocentric and topocentric corrections, and equatorial coordinates.",
     {
-      datetime: z.string().optional().describe("ISO 8601 UTC datetime, e.g. '2024-01-01T12:00:00Z'. Provide either datetime or jd."),
-      jd: z.number().optional().describe("Julian Day number in UT1. Provide either datetime or jd."),
-      bodies: z.string().optional().describe("Comma-separated body names, or group name: 'planets' (default), 'asteroids', 'all'. Use list_available_values to see all options."),
-      lat: z.number().min(-90).max(90).optional().describe("Observer latitude in decimal degrees (-90 to 90). Required for topocentric correction."),
-      lon: z.number().min(-180).max(180).optional().describe("Observer longitude in decimal degrees (-180 to 180, east positive). Required for topocentric correction."),
-      alt: z.number().optional().describe("Observer altitude in meters above sea level."),
-      sidereal: z.string().optional().describe("Ayanamsha system name or ID for sidereal positions. Use list_available_values to see options."),
-      equatorial: z.boolean().optional().describe("If true, return Right Ascension / Declination instead of ecliptic longitude/latitude."),
-      speed: z.boolean().optional().describe("Include daily motion in the response. Default: true."),
-      topocentric: z.boolean().optional().describe("Apply topocentric correction (requires lat and lon)."),
-      heliocentric: z.boolean().optional().describe("Return heliocentric positions instead of geocentric."),
-      no_nutation: z.boolean().optional().describe("Skip nutation correction."),
-      j2000: z.boolean().optional().describe("Use J2000 reference frame instead of ecliptic of date.")
+      title: "Calculate Planetary Positions",
+      description: "Calculates ecliptic positions (longitude, latitude, distance, daily motion) for celestial bodies at a given moment. Supports tropical and sidereal zodiacs, heliocentric and topocentric corrections, and equatorial coordinates.",
+      inputSchema: {
+        datetime: z.string().optional().describe("ISO 8601 UTC datetime, e.g. '2024-01-01T12:00:00Z'. Provide either datetime or jd."),
+        jd: z.number().optional().describe("Julian Day number in UT1. Provide either datetime or jd."),
+        bodies: z.string().optional().describe("Comma-separated body names, or group name: 'planets' (default), 'asteroids', 'all'. Use list_available_values to see all options."),
+        lat: z.number().min(-90).max(90).optional().describe("Observer latitude in decimal degrees (-90 to 90). Required for topocentric correction."),
+        lon: z.number().min(-180).max(180).optional().describe("Observer longitude in decimal degrees (-180 to 180, east positive). Required for topocentric correction."),
+        alt: z.number().optional().describe("Observer altitude in meters above sea level."),
+        sidereal: z.string().optional().describe("Ayanamsha system name or ID for sidereal positions. Use list_available_values to see options."),
+        equatorial: z.boolean().optional().describe("If true, return Right Ascension / Declination instead of ecliptic longitude/latitude."),
+        speed: z.boolean().optional().describe("Include daily motion in the response. Default: true."),
+        topocentric: z.boolean().optional().describe("Apply topocentric correction (requires lat and lon)."),
+        heliocentric: z.boolean().optional().describe("Return heliocentric positions instead of geocentric."),
+        no_nutation: z.boolean().optional().describe("Skip nutation correction."),
+        j2000: z.boolean().optional().describe("Use J2000 reference frame instead of ecliptic of date.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime, jd, bodies, lat, lon, alt, sidereal, equatorial, speed, topocentric, heliocentric, no_nutation, j2000 }) => {
       if (!datetime && jd === void 0) {
@@ -118,16 +126,24 @@ function registerCalculatePositions(server2, client) {
 // src/tools/calculate-houses.ts
 import { z as z2 } from "zod";
 function registerCalculateHouses(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "calculate_houses",
-    "Calculates house cusps and angles (Ascendant, MC, etc.) for a given moment and location. Supports 21 house systems and sidereal mode. Use list_available_values with category 'house_systems' to see all options.",
     {
-      datetime: z2.string().optional().describe("ISO 8601 UTC datetime, e.g. '2024-01-01T12:00:00Z'. Provide either datetime or jd."),
-      jd: z2.number().optional().describe("Julian Day number in UT1. Provide either datetime or jd."),
-      lat: z2.number().min(-90).max(90).describe("Observer latitude in decimal degrees (-90 to 90). REQUIRED."),
-      lon: z2.number().min(-180).max(180).describe("Observer longitude in decimal degrees (-180 to 180, east positive). REQUIRED."),
-      system: z2.string().optional().describe("House system name or single-letter code. Default: 'placidus'. Use list_available_values to see options."),
-      sidereal: z2.string().optional().describe("Ayanamsha system name or ID for sidereal house cusps.")
+      title: "Calculate House Cusps",
+      description: "Calculates house cusps and angles (Ascendant, MC, etc.) for a given moment and location. Supports 21 house systems and sidereal mode. Use list_available_values with category 'house_systems' to see all options.",
+      inputSchema: {
+        datetime: z2.string().optional().describe("ISO 8601 UTC datetime, e.g. '2024-01-01T12:00:00Z'. Provide either datetime or jd."),
+        jd: z2.number().optional().describe("Julian Day number in UT1. Provide either datetime or jd."),
+        lat: z2.number().min(-90).max(90).describe("Observer latitude in decimal degrees (-90 to 90). REQUIRED."),
+        lon: z2.number().min(-180).max(180).describe("Observer longitude in decimal degrees (-180 to 180, east positive). REQUIRED."),
+        system: z2.string().optional().describe("House system name or single-letter code. Default: 'placidus'. Use list_available_values to see options."),
+        sidereal: z2.string().optional().describe("Ayanamsha system name or ID for sidereal house cusps.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime, jd, lat, lon, system, sidereal }) => {
       if (!datetime && jd === void 0) {
@@ -152,24 +168,32 @@ function registerCalculateHouses(server2, client) {
 // src/tools/calculate-chart.ts
 import { z as z3 } from "zod";
 function registerCalculateChart(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "calculate_chart",
-    "Calculates a complete astrological chart: planetary positions, house cusps, and angles for a given moment and location. Combines calculate_positions and calculate_houses into one call. This is the most commonly used tool for natal charts, transits, and event charts.",
     {
-      datetime: z3.string().optional().describe("ISO 8601 UTC datetime, e.g. '2024-01-01T12:00:00Z'. Provide either datetime or jd."),
-      jd: z3.number().optional().describe("Julian Day number in UT1. Provide either datetime or jd."),
-      lat: z3.number().min(-90).max(90).describe("Observer latitude in decimal degrees (-90 to 90). REQUIRED."),
-      lon: z3.number().min(-180).max(180).describe("Observer longitude in decimal degrees (-180 to 180, east positive). REQUIRED."),
-      bodies: z3.string().optional().describe("Comma-separated body names, or group name: 'planets' (default), 'asteroids', 'all'."),
-      alt: z3.number().optional().describe("Observer altitude in meters above sea level."),
-      system: z3.string().optional().describe("House system name or single-letter code. Default: 'placidus'."),
-      sidereal: z3.string().optional().describe("Ayanamsha system name or ID for sidereal positions and house cusps."),
-      equatorial: z3.boolean().optional().describe("If true, return Right Ascension / Declination instead of ecliptic coordinates."),
-      speed: z3.boolean().optional().describe("Include daily motion. Default: true."),
-      topocentric: z3.boolean().optional().describe("Apply topocentric correction."),
-      heliocentric: z3.boolean().optional().describe("Return heliocentric positions."),
-      no_nutation: z3.boolean().optional().describe("Skip nutation correction."),
-      j2000: z3.boolean().optional().describe("Use J2000 reference frame.")
+      title: "Calculate Complete Chart",
+      description: "Calculates a complete astrological chart: planetary positions, house cusps, and angles for a given moment and location. Combines calculate_positions and calculate_houses into one call. This is the most commonly used tool for natal charts, transits, and event charts.",
+      inputSchema: {
+        datetime: z3.string().optional().describe("ISO 8601 UTC datetime, e.g. '2024-01-01T12:00:00Z'. Provide either datetime or jd."),
+        jd: z3.number().optional().describe("Julian Day number in UT1. Provide either datetime or jd."),
+        lat: z3.number().min(-90).max(90).describe("Observer latitude in decimal degrees (-90 to 90). REQUIRED."),
+        lon: z3.number().min(-180).max(180).describe("Observer longitude in decimal degrees (-180 to 180, east positive). REQUIRED."),
+        bodies: z3.string().optional().describe("Comma-separated body names, or group name: 'planets' (default), 'asteroids', 'all'."),
+        alt: z3.number().optional().describe("Observer altitude in meters above sea level."),
+        system: z3.string().optional().describe("House system name or single-letter code. Default: 'placidus'."),
+        sidereal: z3.string().optional().describe("Ayanamsha system name or ID for sidereal positions and house cusps."),
+        equatorial: z3.boolean().optional().describe("If true, return Right Ascension / Declination instead of ecliptic coordinates."),
+        speed: z3.boolean().optional().describe("Include daily motion. Default: true."),
+        topocentric: z3.boolean().optional().describe("Apply topocentric correction."),
+        heliocentric: z3.boolean().optional().describe("Return heliocentric positions."),
+        no_nutation: z3.boolean().optional().describe("Skip nutation correction."),
+        j2000: z3.boolean().optional().describe("Use J2000 reference frame.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime, jd, lat, lon, bodies, alt, system, sidereal, equatorial, speed, topocentric, heliocentric, no_nutation, j2000 }) => {
       if (!datetime && jd === void 0) {
@@ -202,16 +226,24 @@ function registerCalculateChart(server2, client) {
 // src/tools/get-fixed-stars.ts
 import { z as z4 } from "zod";
 function registerGetFixedStars(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "get_fixed_stars",
-    "Returns position data for one or all fixed stars at a given moment. Includes ecliptic coordinates, magnitude, and spectral type. Use star name (e.g. 'Aldebaran') or Bayer designation (e.g. 'alTau'), or 'all' for the full catalog.",
     {
-      datetime: z4.string().optional().describe("ISO 8601 UTC datetime, e.g. '2024-01-01T12:00:00Z'. Provide either datetime or jd."),
-      jd: z4.number().optional().describe("Julian Day number in UT1. Provide either datetime or jd."),
-      star: z4.string().describe("Star name (e.g. 'Aldebaran', 'Regulus'), Bayer designation (e.g. 'alTau'), or 'all' for every star."),
-      lat: z4.number().min(-90).max(90).optional().describe("Observer latitude in decimal degrees (-90 to 90)."),
-      lon: z4.number().min(-180).max(180).optional().describe("Observer longitude in decimal degrees (-180 to 180, east positive)."),
-      equatorial: z4.boolean().optional().describe("If true, return Right Ascension / Declination instead of ecliptic coordinates.")
+      title: "Get Fixed Star Positions",
+      description: "Returns position data for one or all fixed stars at a given moment. Includes ecliptic coordinates, magnitude, and spectral type. Use star name (e.g. 'Aldebaran') or Bayer designation (e.g. 'alTau'), or 'all' for the full catalog.",
+      inputSchema: {
+        datetime: z4.string().optional().describe("ISO 8601 UTC datetime, e.g. '2024-01-01T12:00:00Z'. Provide either datetime or jd."),
+        jd: z4.number().optional().describe("Julian Day number in UT1. Provide either datetime or jd."),
+        star: z4.string().describe("Star name (e.g. 'Aldebaran', 'Regulus'), Bayer designation (e.g. 'alTau'), or 'all' for every star."),
+        lat: z4.number().min(-90).max(90).optional().describe("Observer latitude in decimal degrees (-90 to 90)."),
+        lon: z4.number().min(-180).max(180).optional().describe("Observer longitude in decimal degrees (-180 to 180, east positive)."),
+        equatorial: z4.boolean().optional().describe("If true, return Right Ascension / Declination instead of ecliptic coordinates.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime, jd, star, lat, lon, equatorial }) => {
       if (!datetime && jd === void 0) {
@@ -237,13 +269,21 @@ function registerGetFixedStars(server2, client) {
 // src/tools/get-ayanamsha.ts
 import { z as z5 } from "zod";
 function registerGetAyanamsha(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "get_ayanamsha",
-    "Returns the ayanamsha value (precession offset) for a given moment and system. Used to convert between tropical and sidereal zodiacs. Use list_available_values with category 'ayanamsha_systems' to see all 47 supported systems.",
     {
-      datetime: z5.string().optional().describe("ISO 8601 UTC datetime, e.g. '2024-01-01T12:00:00Z'. Provide either datetime or jd."),
-      jd: z5.number().optional().describe("Julian Day number in UT1. Provide either datetime or jd."),
-      system: z5.string().optional().describe("Ayanamsha system name or numeric ID. Default: 'lahiri'. Use 'all' to return all 47 systems.")
+      title: "Get Ayanamsha Value",
+      description: "Returns the ayanamsha value (precession offset) for a given moment and system. Used to convert between tropical and sidereal zodiacs. Use list_available_values with category 'ayanamsha_systems' to see all 47 supported systems.",
+      inputSchema: {
+        datetime: z5.string().optional().describe("ISO 8601 UTC datetime, e.g. '2024-01-01T12:00:00Z'. Provide either datetime or jd."),
+        jd: z5.number().optional().describe("Julian Day number in UT1. Provide either datetime or jd."),
+        system: z5.string().optional().describe("Ayanamsha system name or numeric ID. Default: 'lahiri'. Use 'all' to return all 47 systems.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime, jd, system }) => {
       if (!datetime && jd === void 0) {
@@ -267,12 +307,20 @@ function registerGetAyanamsha(server2, client) {
 // src/tools/get-delta-t.ts
 import { z as z6 } from "zod";
 function registerGetDeltaT(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "get_delta_t",
-    "Returns Delta T (the difference between Terrestrial Time and Universal Time) for a given moment. Useful for converting between time scales in astronomical calculations.",
     {
-      datetime: z6.string().optional().describe("ISO 8601 UTC datetime, e.g. '2024-01-01T12:00:00Z'. Provide either datetime or jd."),
-      jd: z6.number().optional().describe("Julian Day number in UT1, e.g. 2460310.0. Provide either datetime or jd.")
+      title: "Get Delta T",
+      description: "Returns Delta T (the difference between Terrestrial Time and Universal Time) for a given moment. Useful for converting between time scales in astronomical calculations.",
+      inputSchema: {
+        datetime: z6.string().optional().describe("ISO 8601 UTC datetime, e.g. '2024-01-01T12:00:00Z'. Provide either datetime or jd."),
+        jd: z6.number().optional().describe("Julian Day number in UT1, e.g. 2460310.0. Provide either datetime or jd.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime, jd }) => {
       if (!datetime && jd === void 0) {
@@ -295,13 +343,21 @@ function registerGetDeltaT(server2, client) {
 // src/tools/get-sidereal-time.ts
 import { z as z7 } from "zod";
 function registerGetSiderealTime(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "get_sidereal_time",
-    "Returns Greenwich Apparent Sidereal Time (GAST) and optionally Local Sidereal Time (LST) for a given moment. LST is included when longitude is provided.",
     {
-      datetime: z7.string().optional().describe("ISO 8601 UTC datetime, e.g. '2024-01-01T12:00:00Z'. Provide either datetime or jd."),
-      jd: z7.number().optional().describe("Julian Day number in UT1. Provide either datetime or jd."),
-      lon: z7.number().min(-180).max(180).optional().describe("Observer longitude in decimal degrees (-180 to 180, east positive). If provided, Local Sidereal Time is included.")
+      title: "Get Sidereal Time",
+      description: "Returns Greenwich Apparent Sidereal Time (GAST) and optionally Local Sidereal Time (LST) for a given moment. LST is included when longitude is provided.",
+      inputSchema: {
+        datetime: z7.string().optional().describe("ISO 8601 UTC datetime, e.g. '2024-01-01T12:00:00Z'. Provide either datetime or jd."),
+        jd: z7.number().optional().describe("Julian Day number in UT1. Provide either datetime or jd."),
+        lon: z7.number().min(-180).max(180).optional().describe("Observer longitude in decimal degrees (-180 to 180, east positive). If provided, Local Sidereal Time is included.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime, jd, lon }) => {
       if (!datetime && jd === void 0) {
@@ -325,18 +381,26 @@ function registerGetSiderealTime(server2, client) {
 // src/tools/find-eclipses-solar.ts
 import { z as z8 } from "zod";
 function registerFindSolarEclipses(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "find_solar_eclipses",
-    "Finds upcoming or past solar eclipses from a given date. Returns global eclipse data by default, or location-specific data (magnitude, obscuration) when observer coordinates are provided. Supports filtering by eclipse type and returning multiple results.",
     {
-      datetime: z8.string().optional().describe("ISO 8601 UTC datetime to search from. Provide either datetime or jd."),
-      jd: z8.number().optional().describe("Julian Day number in UT1 to search from. Provide either datetime or jd."),
-      lat: z8.number().min(-90).max(90).optional().describe("Observer latitude (-90 to 90). Enables local mode with magnitude and obscuration."),
-      lon: z8.number().min(-180).max(180).optional().describe("Observer longitude (-180 to 180, east positive)."),
-      alt: z8.number().optional().describe("Observer altitude in meters above sea level."),
-      type: z8.string().optional().describe("Filter by eclipse type: 'total', 'annular', 'partial', 'annular_total' (comma-separated)."),
-      backward: z8.boolean().optional().describe("If true, search backward in time. Default: false."),
-      count: z8.number().min(1).max(10).optional().describe("Number of eclipses to return (1-10). Default: 1.")
+      title: "Find Solar Eclipses",
+      description: "Finds upcoming or past solar eclipses from a given date. Returns global eclipse data by default, or location-specific data (magnitude, obscuration) when observer coordinates are provided. Supports filtering by eclipse type and returning multiple results.",
+      inputSchema: {
+        datetime: z8.string().optional().describe("ISO 8601 UTC datetime to search from. Provide either datetime or jd."),
+        jd: z8.number().optional().describe("Julian Day number in UT1 to search from. Provide either datetime or jd."),
+        lat: z8.number().min(-90).max(90).optional().describe("Observer latitude (-90 to 90). Enables local mode with magnitude and obscuration."),
+        lon: z8.number().min(-180).max(180).optional().describe("Observer longitude (-180 to 180, east positive)."),
+        alt: z8.number().optional().describe("Observer altitude in meters above sea level."),
+        type: z8.string().optional().describe("Filter by eclipse type: 'total', 'annular', 'partial', 'annular_total' (comma-separated)."),
+        backward: z8.boolean().optional().describe("If true, search backward in time. Default: false."),
+        count: z8.number().min(1).max(10).optional().describe("Number of eclipses to return (1-10). Default: 1.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime, jd, lat, lon, alt, type, backward, count }) => {
       if (!datetime && jd === void 0) {
@@ -365,18 +429,26 @@ function registerFindSolarEclipses(server2, client) {
 // src/tools/find-eclipses-lunar.ts
 import { z as z9 } from "zod";
 function registerFindLunarEclipses(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "find_lunar_eclipses",
-    "Finds upcoming or past lunar eclipses from a given date. Returns eclipse phase times (penumbral, partial, total). When observer coordinates are provided, includes a visibility flag. Supports filtering by type and returning multiple results.",
     {
-      datetime: z9.string().optional().describe("ISO 8601 UTC datetime to search from. Provide either datetime or jd."),
-      jd: z9.number().optional().describe("Julian Day number in UT1 to search from. Provide either datetime or jd."),
-      lat: z9.number().min(-90).max(90).optional().describe("Observer latitude (-90 to 90). Enables visibility check."),
-      lon: z9.number().min(-180).max(180).optional().describe("Observer longitude (-180 to 180, east positive)."),
-      alt: z9.number().optional().describe("Observer altitude in meters above sea level."),
-      type: z9.string().optional().describe("Filter by eclipse type: 'total', 'partial', 'penumbral' (comma-separated)."),
-      backward: z9.boolean().optional().describe("If true, search backward in time. Default: false."),
-      count: z9.number().min(1).max(10).optional().describe("Number of eclipses to return (1-10). Default: 1.")
+      title: "Find Lunar Eclipses",
+      description: "Finds upcoming or past lunar eclipses from a given date. Returns eclipse phase times (penumbral, partial, total). When observer coordinates are provided, includes a visibility flag. Supports filtering by type and returning multiple results.",
+      inputSchema: {
+        datetime: z9.string().optional().describe("ISO 8601 UTC datetime to search from. Provide either datetime or jd."),
+        jd: z9.number().optional().describe("Julian Day number in UT1 to search from. Provide either datetime or jd."),
+        lat: z9.number().min(-90).max(90).optional().describe("Observer latitude (-90 to 90). Enables visibility check."),
+        lon: z9.number().min(-180).max(180).optional().describe("Observer longitude (-180 to 180, east positive)."),
+        alt: z9.number().optional().describe("Observer altitude in meters above sea level."),
+        type: z9.string().optional().describe("Filter by eclipse type: 'total', 'partial', 'penumbral' (comma-separated)."),
+        backward: z9.boolean().optional().describe("If true, search backward in time. Default: false."),
+        count: z9.number().min(1).max(10).optional().describe("Number of eclipses to return (1-10). Default: 1.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime, jd, lat, lon, alt, type, backward, count }) => {
       if (!datetime && jd === void 0) {
@@ -405,33 +477,41 @@ function registerFindLunarEclipses(server2, client) {
 // src/tools/find-heliacal-event.ts
 import { z as z10 } from "zod";
 function registerFindHeliacalEvent(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "find_heliacal_event",
-    "Finds the next heliacal rising or setting of a planet \u2014 when it first becomes visible in the morning or evening sky. Requires observer location. Uses the Schaefer sky brightness model with configurable atmospheric and observer parameters. Sun and Moon are excluded. Outer planets cannot have evening_first or morning_last events.",
     {
-      datetime: z10.string().optional().describe("ISO 8601 UTC datetime to search from. Provide either datetime or jd."),
-      jd: z10.number().optional().describe("Julian Day number in UT1 to search from. Provide either datetime or jd."),
-      body: z10.string().describe("Planet name (not sun or moon). E.g., 'venus', 'mars', 'jupiter'."),
-      event: z10.enum([
-        "morning_first",
-        "evening_last",
-        "evening_first",
-        "morning_last",
-        "acronychal_rising",
-        "acronychal_setting"
-      ]).describe("Heliacal event type. evening_first and morning_last are for inner planets only."),
-      lat: z10.number().min(-90).max(90).describe("Observer latitude in decimal degrees (-90 to 90). Required."),
-      lon: z10.number().min(-180).max(180).describe("Observer longitude in decimal degrees (-180 to 180, east positive). Required."),
-      alt: z10.number().optional().describe("Observer altitude in meters above sea level. Default: 0."),
-      pressure_mbar: z10.number().optional().describe("Atmospheric pressure in mbar. Default: 1013.25."),
-      temp_celsius: z10.number().optional().describe("Temperature in Celsius. Default: 15.0."),
-      humidity_pct: z10.number().optional().describe("Relative humidity (0-100). Default: 40.0."),
-      visibility_range_km: z10.number().optional().describe("Visibility range in km (0 = model default). Default: 0.0."),
-      age_years: z10.number().optional().describe("Observer age in years. Default: 36.0."),
-      snellen_ratio: z10.number().optional().describe("Visual acuity (1.0 = normal). Default: 1.0."),
-      binoculars: z10.boolean().optional().describe("Binocular vision. Default: true."),
-      telescope_aperture_cm: z10.number().optional().describe("Telescope aperture in cm (0 = naked eye). Default: 0.0."),
-      telescope_magnification: z10.number().optional().describe("Telescope magnification (1.0 = naked eye). Default: 1.0.")
+      title: "Find Heliacal Event",
+      description: "Finds the next heliacal rising or setting of a planet \u2014 when it first becomes visible in the morning or evening sky. Requires observer location. Uses the Schaefer sky brightness model with configurable atmospheric and observer parameters. Sun and Moon are excluded. Outer planets cannot have evening_first or morning_last events.",
+      inputSchema: {
+        datetime: z10.string().optional().describe("ISO 8601 UTC datetime to search from. Provide either datetime or jd."),
+        jd: z10.number().optional().describe("Julian Day number in UT1 to search from. Provide either datetime or jd."),
+        body: z10.string().describe("Planet name (not sun or moon). E.g., 'venus', 'mars', 'jupiter'."),
+        event: z10.enum([
+          "morning_first",
+          "evening_last",
+          "evening_first",
+          "morning_last",
+          "acronychal_rising",
+          "acronychal_setting"
+        ]).describe("Heliacal event type. evening_first and morning_last are for inner planets only."),
+        lat: z10.number().min(-90).max(90).describe("Observer latitude in decimal degrees (-90 to 90). Required."),
+        lon: z10.number().min(-180).max(180).describe("Observer longitude in decimal degrees (-180 to 180, east positive). Required."),
+        alt: z10.number().optional().describe("Observer altitude in meters above sea level. Default: 0."),
+        pressure_mbar: z10.number().optional().describe("Atmospheric pressure in mbar. Default: 1013.25."),
+        temp_celsius: z10.number().optional().describe("Temperature in Celsius. Default: 15.0."),
+        humidity_pct: z10.number().optional().describe("Relative humidity (0-100). Default: 40.0."),
+        visibility_range_km: z10.number().optional().describe("Visibility range in km (0 = model default). Default: 0.0."),
+        age_years: z10.number().optional().describe("Observer age in years. Default: 36.0."),
+        snellen_ratio: z10.number().optional().describe("Visual acuity (1.0 = normal). Default: 1.0."),
+        binoculars: z10.boolean().optional().describe("Binocular vision. Default: true."),
+        telescope_aperture_cm: z10.number().optional().describe("Telescope aperture in cm (0 = naked eye). Default: 0.0."),
+        telescope_magnification: z10.number().optional().describe("Telescope magnification (1.0 = naked eye). Default: 1.0.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({
       datetime,
@@ -485,17 +565,25 @@ function registerFindHeliacalEvent(server2, client) {
 // src/tools/find-ingresses.ts
 import { z as z11 } from "zod";
 function registerFindIngresses(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "find_ingresses",
-    "Finds when a planet crosses into a zodiac sign or reaches a specific ecliptic longitude. Useful for tracking equinoxes, solstices, and zodiac ingresses. Provide either 'sign' (e.g., 'aries') or 'longitude' (0-360), not both. Supported bodies: sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto.",
     {
-      datetime: z11.string().optional().describe("ISO 8601 UTC datetime to search from. Provide either datetime or jd."),
-      jd: z11.number().optional().describe("Julian Day number in UT1 to search from. Provide either datetime or jd."),
-      body: z11.string().describe("Body name: sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto."),
-      sign: z11.string().optional().describe("Zodiac sign name (e.g., 'aries', 'taurus'). Provide either sign or longitude."),
-      longitude: z11.number().min(0).max(360).optional().describe("Target ecliptic longitude (0-360). Provide either sign or longitude."),
-      backward: z11.boolean().optional().describe("If true, search backward in time. Default: false."),
-      count: z11.number().min(1).max(10).optional().describe("Number of ingresses to return (1-10). Default: 1.")
+      title: "Find Zodiac Ingresses",
+      description: "Finds when a planet crosses into a zodiac sign or reaches a specific ecliptic longitude. Useful for tracking equinoxes, solstices, and zodiac ingresses. Provide either 'sign' (e.g., 'aries') or 'longitude' (0-360), not both. Supported bodies: sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto.",
+      inputSchema: {
+        datetime: z11.string().optional().describe("ISO 8601 UTC datetime to search from. Provide either datetime or jd."),
+        jd: z11.number().optional().describe("Julian Day number in UT1 to search from. Provide either datetime or jd."),
+        body: z11.string().describe("Body name: sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto."),
+        sign: z11.string().optional().describe("Zodiac sign name (e.g., 'aries', 'taurus'). Provide either sign or longitude."),
+        longitude: z11.number().min(0).max(360).optional().describe("Target ecliptic longitude (0-360). Provide either sign or longitude."),
+        backward: z11.boolean().optional().describe("If true, search backward in time. Default: false."),
+        count: z11.number().min(1).max(10).optional().describe("Number of ingresses to return (1-10). Default: 1.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime, jd, body: bodyName, sign, longitude, backward, count }) => {
       if (!datetime && jd === void 0) {
@@ -693,20 +781,28 @@ var VALID_SIGN_NAMES = new Set(ZODIAC_SIGNS.map((s) => s.name));
 
 // src/tools/list-available-values.ts
 function registerListAvailableValues(server2) {
-  server2.tool(
+  server2.registerTool(
     "list_available_values",
-    "Lists valid values for celestial bodies, house systems, ayanamsha systems, eclipse types, heliacal events, or zodiac signs. Use this to discover what values are accepted by other tools.",
     {
-      category: z12.enum([
-        "bodies",
-        "house_systems",
-        "ayanamsha_systems",
-        "eclipse_types",
-        "heliacal_events",
-        "zodiac_signs"
-      ]).describe(
-        "Which category to list: 'bodies', 'house_systems', 'ayanamsha_systems', 'eclipse_types', 'heliacal_events', or 'zodiac_signs'"
-      )
+      title: "List Available Values",
+      description: "Lists valid values for celestial bodies, house systems, ayanamsha systems, eclipse types, heliacal events, or zodiac signs. Use this to discover what values are accepted by other tools.",
+      inputSchema: {
+        category: z12.enum([
+          "bodies",
+          "house_systems",
+          "ayanamsha_systems",
+          "eclipse_types",
+          "heliacal_events",
+          "zodiac_signs"
+        ]).describe(
+          "Which category to list: 'bodies', 'house_systems', 'ayanamsha_systems', 'eclipse_types', 'heliacal_events', or 'zodiac_signs'"
+        )
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
     },
     async ({ category }) => {
       let result;
@@ -783,13 +879,21 @@ function registerListAvailableValues(server2) {
 // src/tools/batch-requests.ts
 import { z as z13 } from "zod";
 function registerBatchRequests(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "batch_requests",
-    "Send up to 50 sub-requests in a single API call. Each sub-request specifies an endpoint and its parameters. Sub-requests execute sequentially; individual failures do not abort the batch. Credit cost is the sum of individual endpoint costs. Counts as 1 rate-limit request. Ideal for computing positions across a date range, fetching a full chart (positions + houses + stars), or any workflow that would otherwise require many sequential API calls.",
     {
-      requests_json: z13.string().describe(
-        'JSON array of sub-requests. Each element: {"endpoint": "/v1/positions", "params": {...}}. Allowed endpoints: /v1/positions, /v1/houses, /v1/chart, /v1/stars, /v1/ayanamsha, /v1/delta-t, /v1/sidereal-time, /v1/eclipses/solar, /v1/eclipses/lunar, /v1/heliacal, /v1/ingresses. Max 50 sub-requests. Nested /v1/batch is NOT allowed. Example: [{"endpoint":"/v1/positions","params":{"datetime":"2024-01-01T00:00:00Z","bodies":"sun,moon"}}]'
-      )
+      title: "Batch API Requests",
+      description: "Send up to 50 sub-requests in a single API call. Each sub-request specifies an endpoint and its parameters. Sub-requests execute sequentially; individual failures do not abort the batch. Credit cost is the sum of individual endpoint costs. Counts as 1 rate-limit request. Ideal for computing positions across a date range, fetching a full chart (positions + houses + stars), or any workflow that would otherwise require many sequential API calls.",
+      inputSchema: {
+        requests_json: z13.string().describe(
+          'JSON array of sub-requests. Each element: {"endpoint": "/v1/positions", "params": {...}}. Allowed endpoints: /v1/positions, /v1/houses, /v1/chart, /v1/stars, /v1/ayanamsha, /v1/delta-t, /v1/sidereal-time, /v1/eclipses/solar, /v1/eclipses/lunar, /v1/heliacal, /v1/ingresses. Max 50 sub-requests. Nested /v1/batch is NOT allowed. Example: [{"endpoint":"/v1/positions","params":{"datetime":"2024-01-01T00:00:00Z","bodies":"sun,moon"}}]'
+        )
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ requests_json }) => {
       let requests;
@@ -840,22 +944,30 @@ function registerBatchRequests(server2, client) {
 // src/tools/natal-chart.ts
 import { z as z14 } from "zod";
 function registerNatalChart(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "natal_chart",
-    "Computes a full natal chart with positions (sign, house, retrograde, out-of-bounds), house cusps, aspects, and parallels. This is the recommended tool for complete chart analysis \u2014 it returns everything in one call. Cost: 2 credits.",
     {
-      datetime: z14.string().optional().describe("ISO 8601 UTC datetime. Provide either datetime or jd."),
-      jd: z14.number().optional().describe("Julian Day number in UT1. Provide either datetime or jd."),
-      lat: z14.number().min(-90).max(90).describe("Observer latitude in decimal degrees. REQUIRED."),
-      lon: z14.number().min(-180).max(180).describe("Observer longitude in decimal degrees (east positive). REQUIRED."),
-      bodies: z14.string().optional().describe("Comma-separated body names, or 'planets' (default), 'asteroids', 'all'."),
-      system: z14.string().optional().describe("House system name or code. Default: 'placidus'."),
-      sidereal: z14.string().optional().describe("Ayanamsha system for sidereal positions."),
-      aspects: z14.string().optional().describe("Comma-separated aspect types. Default: conjunction,opposition,trine,square,sextile,semi_sextile,quincunx."),
-      orb: z14.number().optional().describe("Default orb in degrees for all aspects (0-30)."),
-      applying: z14.boolean().optional().describe("Compute applying/separating status. Default: true."),
-      parallels: z14.boolean().optional().describe("Include parallels/contraparallels. Default: true."),
-      parallel_orb: z14.number().optional().describe("Parallel orb in degrees (0-5). Default: 1.0.")
+      title: "Compute Natal Chart",
+      description: "Computes a full natal chart with positions (sign, house, retrograde, out-of-bounds), house cusps, aspects, and parallels. This is the recommended tool for complete chart analysis \u2014 it returns everything in one call. Cost: 2 credits.",
+      inputSchema: {
+        datetime: z14.string().optional().describe("ISO 8601 UTC datetime. Provide either datetime or jd."),
+        jd: z14.number().optional().describe("Julian Day number in UT1. Provide either datetime or jd."),
+        lat: z14.number().min(-90).max(90).describe("Observer latitude in decimal degrees. REQUIRED."),
+        lon: z14.number().min(-180).max(180).describe("Observer longitude in decimal degrees (east positive). REQUIRED."),
+        bodies: z14.string().optional().describe("Comma-separated body names, or 'planets' (default), 'asteroids', 'all'."),
+        system: z14.string().optional().describe("House system name or code. Default: 'placidus'."),
+        sidereal: z14.string().optional().describe("Ayanamsha system for sidereal positions."),
+        aspects: z14.string().optional().describe("Comma-separated aspect types. Default: conjunction,opposition,trine,square,sextile,semi_sextile,quincunx."),
+        orb: z14.number().optional().describe("Default orb in degrees for all aspects (0-30)."),
+        applying: z14.boolean().optional().describe("Compute applying/separating status. Default: true."),
+        parallels: z14.boolean().optional().describe("Include parallels/contraparallels. Default: true."),
+        parallel_orb: z14.number().optional().describe("Parallel orb in degrees (0-5). Default: 1.0.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime, jd, lat, lon, bodies, system, sidereal, aspects, orb, applying, parallels, parallel_orb }) => {
       if (!datetime && jd === void 0) {
@@ -881,19 +993,27 @@ function registerNatalChart(server2, client) {
 // src/tools/aspects.ts
 import { z as z15 } from "zod";
 function registerAspects(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "calculate_aspects",
-    "Computes aspects (angular relationships) and optionally parallels between bodies at a given time. No location or houses required. Returns aspect type, orb, and applying/separating status. Cost: 1 credit.",
     {
-      datetime: z15.string().optional().describe("ISO 8601 UTC datetime. Provide either datetime or jd."),
-      jd: z15.number().optional().describe("Julian Day number in UT1."),
-      bodies: z15.string().optional().describe("Comma-separated body names, or 'planets' (default), 'asteroids', 'all'."),
-      aspects: z15.string().optional().describe("Comma-separated aspect types. Default: major aspects. Available: conjunction, opposition, trine, square, sextile, semi_sextile, quincunx, semi_square, sesquiquadrate, quintile, bi_quintile, septile, bi_septile, tri_septile, quindecile."),
-      orb: z15.number().optional().describe("Default orb in degrees for all aspects (0-30)."),
-      applying: z15.boolean().optional().describe("Compute applying/separating status. Default: true."),
-      parallels: z15.boolean().optional().describe("Include parallels/contraparallels. Default: true."),
-      parallel_orb: z15.number().optional().describe("Parallel orb in degrees (0-5). Default: 1.0."),
-      contraparallel: z15.boolean().optional().describe("Include contraparallels. Default: true.")
+      title: "Calculate Aspects",
+      description: "Computes aspects (angular relationships) and optionally parallels between bodies at a given time. No location or houses required. Returns aspect type, orb, and applying/separating status. Cost: 1 credit.",
+      inputSchema: {
+        datetime: z15.string().optional().describe("ISO 8601 UTC datetime. Provide either datetime or jd."),
+        jd: z15.number().optional().describe("Julian Day number in UT1."),
+        bodies: z15.string().optional().describe("Comma-separated body names, or 'planets' (default), 'asteroids', 'all'."),
+        aspects: z15.string().optional().describe("Comma-separated aspect types. Default: major aspects. Available: conjunction, opposition, trine, square, sextile, semi_sextile, quincunx, semi_square, sesquiquadrate, quintile, bi_quintile, septile, bi_septile, tri_septile, quindecile."),
+        orb: z15.number().optional().describe("Default orb in degrees for all aspects (0-30)."),
+        applying: z15.boolean().optional().describe("Compute applying/separating status. Default: true."),
+        parallels: z15.boolean().optional().describe("Include parallels/contraparallels. Default: true."),
+        parallel_orb: z15.number().optional().describe("Parallel orb in degrees (0-5). Default: 1.0."),
+        contraparallel: z15.boolean().optional().describe("Include contraparallels. Default: true.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime, jd, bodies, aspects, orb, applying, parallels, parallel_orb, contraparallel }) => {
       if (!datetime && jd === void 0) {
@@ -918,16 +1038,24 @@ function registerAspects(server2, client) {
 // src/tools/dignities.ts
 import { z as z16 } from "zod";
 function registerDignities(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "calculate_dignities",
-    "Computes essential dignities (domicile, exaltation, triplicity, term, face) with Lilly-style scores. Optionally includes dispositorship chains, mutual receptions, and final dispositors. Cost: 1 credit.",
     {
-      datetime: z16.string().optional().describe("ISO 8601 UTC datetime. Provide either datetime or jd."),
-      jd: z16.number().optional().describe("Julian Day number in UT1."),
-      bodies: z16.string().optional().describe("Comma-separated body names, or 'planets' (default)."),
-      rulership: z16.string().optional().describe("Rulership scheme: 'modern' (default, includes outer planets) or 'classical' (visible planets only)."),
-      day_chart: z16.string().optional().describe("Is this a day chart? 'true', 'false', or 'auto' (default, skips triplicity)."),
-      dispositors: z16.boolean().optional().describe("Include dispositorship chains, mutual receptions, final dispositors. Default: false.")
+      title: "Calculate Essential Dignities",
+      description: "Computes essential dignities (domicile, exaltation, triplicity, term, face) with Lilly-style scores. Optionally includes dispositorship chains, mutual receptions, and final dispositors. Cost: 1 credit.",
+      inputSchema: {
+        datetime: z16.string().optional().describe("ISO 8601 UTC datetime. Provide either datetime or jd."),
+        jd: z16.number().optional().describe("Julian Day number in UT1."),
+        bodies: z16.string().optional().describe("Comma-separated body names, or 'planets' (default)."),
+        rulership: z16.string().optional().describe("Rulership scheme: 'modern' (default, includes outer planets) or 'classical' (visible planets only)."),
+        day_chart: z16.string().optional().describe("Is this a day chart? 'true', 'false', or 'auto' (default, skips triplicity)."),
+        dispositors: z16.boolean().optional().describe("Include dispositorship chains, mutual receptions, final dispositors. Default: false.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime, jd, bodies, rulership, day_chart, dispositors }) => {
       if (!datetime && jd === void 0) {
@@ -949,23 +1077,31 @@ function registerDignities(server2, client) {
 // src/tools/synastry.ts
 import { z as z17 } from "zod";
 function registerSynastry(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "calculate_synastry",
-    "Computes synastry between two natal charts: each chart's positions, houses, and aspects, plus inter-chart aspects and parallels. Requires two sets of datetime and location (suffixed _a and _b). Cost: 3 credits.",
     {
-      datetime_a: z17.string().optional().describe("Chart A datetime (ISO 8601 UTC). Provide either datetime_a or jd_a."),
-      jd_a: z17.number().optional().describe("Chart A Julian Day in UT1."),
-      lat_a: z17.number().min(-90).max(90).describe("Chart A latitude. REQUIRED."),
-      lon_a: z17.number().min(-180).max(180).describe("Chart A longitude (east positive). REQUIRED."),
-      datetime_b: z17.string().optional().describe("Chart B datetime (ISO 8601 UTC). Provide either datetime_b or jd_b."),
-      jd_b: z17.number().optional().describe("Chart B Julian Day in UT1."),
-      lat_b: z17.number().min(-90).max(90).describe("Chart B latitude. REQUIRED."),
-      lon_b: z17.number().min(-180).max(180).describe("Chart B longitude (east positive). REQUIRED."),
-      bodies: z17.string().optional().describe("Comma-separated body names. Default: 'planets'."),
-      system: z17.string().optional().describe("House system. Default: 'placidus'."),
-      aspects: z17.string().optional().describe("Comma-separated aspect types."),
-      orb: z17.number().optional().describe("Default orb in degrees."),
-      parallels: z17.boolean().optional().describe("Include parallels. Default: true.")
+      title: "Calculate Synastry",
+      description: "Computes synastry between two natal charts: each chart's positions, houses, and aspects, plus inter-chart aspects and parallels. Requires two sets of datetime and location (suffixed _a and _b). Cost: 3 credits.",
+      inputSchema: {
+        datetime_a: z17.string().optional().describe("Chart A datetime (ISO 8601 UTC). Provide either datetime_a or jd_a."),
+        jd_a: z17.number().optional().describe("Chart A Julian Day in UT1."),
+        lat_a: z17.number().min(-90).max(90).describe("Chart A latitude. REQUIRED."),
+        lon_a: z17.number().min(-180).max(180).describe("Chart A longitude (east positive). REQUIRED."),
+        datetime_b: z17.string().optional().describe("Chart B datetime (ISO 8601 UTC). Provide either datetime_b or jd_b."),
+        jd_b: z17.number().optional().describe("Chart B Julian Day in UT1."),
+        lat_b: z17.number().min(-90).max(90).describe("Chart B latitude. REQUIRED."),
+        lon_b: z17.number().min(-180).max(180).describe("Chart B longitude (east positive). REQUIRED."),
+        bodies: z17.string().optional().describe("Comma-separated body names. Default: 'planets'."),
+        system: z17.string().optional().describe("House system. Default: 'placidus'."),
+        aspects: z17.string().optional().describe("Comma-separated aspect types."),
+        orb: z17.number().optional().describe("Default orb in degrees."),
+        parallels: z17.boolean().optional().describe("Include parallels. Default: true.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime_a, jd_a, lat_a, lon_a, datetime_b, jd_b, lat_b, lon_b, bodies, system, aspects, orb, parallels }) => {
       if (!datetime_a && jd_a === void 0) {
@@ -993,22 +1129,30 @@ function registerSynastry(server2, client) {
 // src/tools/composite.ts
 import { z as z18 } from "zod";
 function registerComposite(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "calculate_composite",
-    "Computes a midpoint composite chart from two natal charts. Each position is the shortest-arc midpoint of the two charts' positions. Cost: 3 credits.",
     {
-      datetime_a: z18.string().optional().describe("Chart A datetime (ISO 8601 UTC)."),
-      jd_a: z18.number().optional().describe("Chart A Julian Day."),
-      lat_a: z18.number().min(-90).max(90).describe("Chart A latitude. REQUIRED."),
-      lon_a: z18.number().min(-180).max(180).describe("Chart A longitude. REQUIRED."),
-      datetime_b: z18.string().optional().describe("Chart B datetime (ISO 8601 UTC)."),
-      jd_b: z18.number().optional().describe("Chart B Julian Day."),
-      lat_b: z18.number().min(-90).max(90).describe("Chart B latitude. REQUIRED."),
-      lon_b: z18.number().min(-180).max(180).describe("Chart B longitude. REQUIRED."),
-      bodies: z18.string().optional().describe("Comma-separated body names. Default: 'planets'."),
-      system: z18.string().optional().describe("House system. Default: 'placidus'."),
-      aspects: z18.string().optional().describe("Comma-separated aspect types."),
-      resolution: z18.string().optional().describe("Midpoint resolution: 'lower' (default) or 'higher'.")
+      title: "Calculate Composite Chart",
+      description: "Computes a midpoint composite chart from two natal charts. Each position is the shortest-arc midpoint of the two charts' positions. Cost: 3 credits.",
+      inputSchema: {
+        datetime_a: z18.string().optional().describe("Chart A datetime (ISO 8601 UTC)."),
+        jd_a: z18.number().optional().describe("Chart A Julian Day."),
+        lat_a: z18.number().min(-90).max(90).describe("Chart A latitude. REQUIRED."),
+        lon_a: z18.number().min(-180).max(180).describe("Chart A longitude. REQUIRED."),
+        datetime_b: z18.string().optional().describe("Chart B datetime (ISO 8601 UTC)."),
+        jd_b: z18.number().optional().describe("Chart B Julian Day."),
+        lat_b: z18.number().min(-90).max(90).describe("Chart B latitude. REQUIRED."),
+        lon_b: z18.number().min(-180).max(180).describe("Chart B longitude. REQUIRED."),
+        bodies: z18.string().optional().describe("Comma-separated body names. Default: 'planets'."),
+        system: z18.string().optional().describe("House system. Default: 'placidus'."),
+        aspects: z18.string().optional().describe("Comma-separated aspect types."),
+        resolution: z18.string().optional().describe("Midpoint resolution: 'lower' (default) or 'higher'.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime_a, jd_a, lat_a, lon_a, datetime_b, jd_b, lat_b, lon_b, bodies, system, aspects, resolution }) => {
       if (!datetime_a && jd_a === void 0) {
@@ -1035,21 +1179,29 @@ function registerComposite(server2, client) {
 // src/tools/davison.ts
 import { z as z19 } from "zod";
 function registerDavison(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "calculate_davison",
-    "Computes a Davison relationship chart \u2014 a natal chart cast at the time-space midpoint of two charts. Uses great-circle geographic midpoint and Julian Day midpoint. Cost: 3 credits.",
     {
-      datetime_a: z19.string().optional().describe("Chart A datetime (ISO 8601 UTC)."),
-      jd_a: z19.number().optional().describe("Chart A Julian Day."),
-      lat_a: z19.number().min(-90).max(90).describe("Chart A latitude. REQUIRED."),
-      lon_a: z19.number().min(-180).max(180).describe("Chart A longitude. REQUIRED."),
-      datetime_b: z19.string().optional().describe("Chart B datetime (ISO 8601 UTC)."),
-      jd_b: z19.number().optional().describe("Chart B Julian Day."),
-      lat_b: z19.number().min(-90).max(90).describe("Chart B latitude. REQUIRED."),
-      lon_b: z19.number().min(-180).max(180).describe("Chart B longitude. REQUIRED."),
-      bodies: z19.string().optional().describe("Comma-separated body names. Default: 'planets'."),
-      system: z19.string().optional().describe("House system. Default: 'placidus'."),
-      aspects: z19.string().optional().describe("Comma-separated aspect types.")
+      title: "Calculate Davison Chart",
+      description: "Computes a Davison relationship chart \u2014 a natal chart cast at the time-space midpoint of two charts. Uses great-circle geographic midpoint and Julian Day midpoint. Cost: 3 credits.",
+      inputSchema: {
+        datetime_a: z19.string().optional().describe("Chart A datetime (ISO 8601 UTC)."),
+        jd_a: z19.number().optional().describe("Chart A Julian Day."),
+        lat_a: z19.number().min(-90).max(90).describe("Chart A latitude. REQUIRED."),
+        lon_a: z19.number().min(-180).max(180).describe("Chart A longitude. REQUIRED."),
+        datetime_b: z19.string().optional().describe("Chart B datetime (ISO 8601 UTC)."),
+        jd_b: z19.number().optional().describe("Chart B Julian Day."),
+        lat_b: z19.number().min(-90).max(90).describe("Chart B latitude. REQUIRED."),
+        lon_b: z19.number().min(-180).max(180).describe("Chart B longitude. REQUIRED."),
+        bodies: z19.string().optional().describe("Comma-separated body names. Default: 'planets'."),
+        system: z19.string().optional().describe("House system. Default: 'placidus'."),
+        aspects: z19.string().optional().describe("Comma-separated aspect types.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime_a, jd_a, lat_a, lon_a, datetime_b, jd_b, lat_b, lon_b, bodies, system, aspects }) => {
       if (!datetime_a && jd_a === void 0) {
@@ -1075,19 +1227,27 @@ function registerDavison(server2, client) {
 // src/tools/progressed.ts
 import { z as z20 } from "zod";
 function registerProgressed(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "calculate_progressed",
-    "Computes a secondary progressed chart using the day-for-a-year method. Provide the natal birth datetime and a target date to progress to. Returns a full chart at the progressed datetime. Cost: 2 credits.",
     {
-      datetime: z20.string().optional().describe("Natal birth datetime (ISO 8601 UTC). Provide either datetime or jd."),
-      jd: z20.number().optional().describe("Natal birth Julian Day."),
-      target_datetime: z20.string().optional().describe("Target date to progress to (ISO 8601 UTC). Provide either target_datetime or target_jd."),
-      target_jd: z20.number().optional().describe("Target Julian Day to progress to."),
-      lat: z20.number().min(-90).max(90).describe("Birth location latitude. REQUIRED."),
-      lon: z20.number().min(-180).max(180).describe("Birth location longitude. REQUIRED."),
-      bodies: z20.string().optional().describe("Comma-separated body names. Default: 'planets'."),
-      system: z20.string().optional().describe("House system. Default: 'placidus'."),
-      aspects: z20.string().optional().describe("Comma-separated aspect types.")
+      title: "Calculate Progressed Chart",
+      description: "Computes a secondary progressed chart using the day-for-a-year method. Provide the natal birth datetime and a target date to progress to. Returns a full chart at the progressed datetime. Cost: 2 credits.",
+      inputSchema: {
+        datetime: z20.string().optional().describe("Natal birth datetime (ISO 8601 UTC). Provide either datetime or jd."),
+        jd: z20.number().optional().describe("Natal birth Julian Day."),
+        target_datetime: z20.string().optional().describe("Target date to progress to (ISO 8601 UTC). Provide either target_datetime or target_jd."),
+        target_jd: z20.number().optional().describe("Target Julian Day to progress to."),
+        lat: z20.number().min(-90).max(90).describe("Birth location latitude. REQUIRED."),
+        lon: z20.number().min(-180).max(180).describe("Birth location longitude. REQUIRED."),
+        bodies: z20.string().optional().describe("Comma-separated body names. Default: 'planets'."),
+        system: z20.string().optional().describe("House system. Default: 'placidus'."),
+        aspects: z20.string().optional().describe("Comma-separated aspect types.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime, jd, target_datetime, target_jd, lat, lon, bodies, system, aspects }) => {
       if (!datetime && jd === void 0) {
@@ -1113,18 +1273,26 @@ function registerProgressed(server2, client) {
 // src/tools/draconic.ts
 import { z as z21 } from "zod";
 function registerDraconic(server2, client) {
-  server2.tool(
+  server2.registerTool(
     "calculate_draconic",
-    "Computes a draconic chart by rotating all positions so the North Node falls at 0\xB0 Aries. Make sure to include mean_node or true_node in the bodies list. Cost: 2 credits.",
     {
-      datetime: z21.string().optional().describe("ISO 8601 UTC datetime. Provide either datetime or jd."),
-      jd: z21.number().optional().describe("Julian Day number in UT1."),
-      lat: z21.number().min(-90).max(90).describe("Observer latitude. REQUIRED."),
-      lon: z21.number().min(-180).max(180).describe("Observer longitude. REQUIRED."),
-      bodies: z21.string().optional().describe("Comma-separated body names. Must include mean_node or true_node. Default: 'planets' (includes mean_node)."),
-      system: z21.string().optional().describe("House system. Default: 'placidus'."),
-      node: z21.string().optional().describe("Node body for rotation: 'mean_node' (default) or 'true_node'."),
-      aspects: z21.string().optional().describe("Comma-separated aspect types.")
+      title: "Calculate Draconic Chart",
+      description: "Computes a draconic chart by rotating all positions so the North Node falls at 0\xB0 Aries. Make sure to include mean_node or true_node in the bodies list. Cost: 2 credits.",
+      inputSchema: {
+        datetime: z21.string().optional().describe("ISO 8601 UTC datetime. Provide either datetime or jd."),
+        jd: z21.number().optional().describe("Julian Day number in UT1."),
+        lat: z21.number().min(-90).max(90).describe("Observer latitude. REQUIRED."),
+        lon: z21.number().min(-180).max(180).describe("Observer longitude. REQUIRED."),
+        bodies: z21.string().optional().describe("Comma-separated body names. Must include mean_node or true_node. Default: 'planets' (includes mean_node)."),
+        system: z21.string().optional().describe("House system. Default: 'placidus'."),
+        node: z21.string().optional().describe("Node body for rotation: 'mean_node' (default) or 'true_node'."),
+        aspects: z21.string().optional().describe("Comma-separated aspect types.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ datetime, jd, lat, lon, bodies, system, node, aspects }) => {
       if (!datetime && jd === void 0) {
@@ -1143,6 +1311,55 @@ function registerDraconic(server2, client) {
   );
 }
 
+// src/tools/returns.ts
+import { z as z22 } from "zod";
+function registerReturns(server2, client) {
+  server2.registerTool(
+    "find_returns",
+    {
+      title: "Find Planetary Returns",
+      description: "Finds the moment(s) when a transiting body returns to its natal ecliptic longitude and computes a full chart at each return moment. Supports solar, lunar, and planetary returns. Cost: 2 credits.",
+      inputSchema: {
+        body: z22.string().describe("Body to find the return for (e.g., 'sun', 'moon', 'saturn'). REQUIRED."),
+        datetime: z22.string().optional().describe("Natal birth datetime (ISO 8601 UTC). Provide either datetime or jd."),
+        jd: z22.number().optional().describe("Natal birth Julian Day."),
+        search_start: z22.string().optional().describe("When to start searching for the return (ISO 8601 UTC). Provide either search_start or search_start_jd."),
+        search_start_jd: z22.number().optional().describe("Search start Julian Day."),
+        lat: z22.number().min(-90).max(90).describe("Return chart location latitude (typically current residence). REQUIRED."),
+        lon: z22.number().min(-180).max(180).describe("Return chart location longitude. REQUIRED."),
+        count: z22.number().min(1).max(13).optional().describe("Number of consecutive returns to find (default 1, max 13 for Moon, 5 for others)."),
+        bodies: z22.string().optional().describe("Comma-separated body names for the return chart. Default: 'planets'."),
+        system: z22.string().optional().describe("House system. Default: 'placidus'."),
+        aspects: z22.string().optional().describe("Comma-separated aspect types.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async ({ body: returnBody, datetime, jd, search_start, search_start_jd, lat, lon, count, bodies, system, aspects }) => {
+      if (!datetime && jd === void 0) {
+        return { isError: true, content: [{ type: "text", text: "Natal birth time required: provide either 'datetime' or 'jd'." }] };
+      }
+      if (!search_start && search_start_jd === void 0) {
+        return { isError: true, content: [{ type: "text", text: "Search start required: provide either 'search_start' or 'search_start_jd'." }] };
+      }
+      const reqBody = { body: returnBody, lat, lon };
+      if (datetime) reqBody.datetime = datetime;
+      if (jd !== void 0) reqBody.jd = jd;
+      if (search_start) reqBody.search_start = search_start;
+      if (search_start_jd !== void 0) reqBody.search_start_jd = search_start_jd;
+      if (count !== void 0) reqBody.count = count;
+      if (bodies) reqBody.bodies = bodies;
+      if (system) reqBody.system = system;
+      if (aspects) reqBody.aspects = aspects;
+      const response = await client.callEndpoint("/v1/returns", reqBody);
+      return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
+    }
+  );
+}
+
 // src/tools/index.ts
 function registerAllTools(server2, client) {
   registerCalculatePositions(server2, client);
@@ -1165,6 +1382,7 @@ function registerAllTools(server2, client) {
   registerDavison(server2, client);
   registerProgressed(server2, client);
   registerDraconic(server2, client);
+  registerReturns(server2, client);
   registerListAvailableValues(server2);
 }
 
@@ -1177,7 +1395,7 @@ function createServer(options) {
   });
   const server2 = new McpServer({
     name: "morphemeris",
-    version: "0.1.0"
+    version: "0.5.0"
   });
   registerAllTools(server2, client);
   return server2;