@openephemeris/mcp-server 3.1.0 → 3.2.0

package/dist/src/schema-packs/llm.js

@@ -0,0 +1,429 @@
+import { z } from "zod";
+export const LLM_V2_POINTS_SCHEMA = [
+    "id",
+    "kind",
+    "src",
+    "lon",
+    "lat",
+    "spd",
+    "rx",
+    "sg",
+    "deg",
+    "hs",
+    "dec",
+    "oob",
+    "ed",
+    "ed_sc",
+    "ad_sc",
+    "on_cusp",
+];
+export const LLM_V2_ASPECTS_SCHEMA = ["a_i", "b_i", "t", "orb", "orb_pct", "app", "str"];
+export const LLM_V2_DICT = {
+    sign_id: ["ari", "tau", "gem", "can", "leo", "vir", "lib", "sco", "sag", "cap", "aqu", "pis"],
+    aspect_id: ["con", "opp", "tri", "sqr", "sex"],
+    aspect_angle: [0, 180, 120, 90, 60],
+    kind_id: ["planet", "angle", "node", "lilith", "asteroid", "other"],
+};
+const PointsSchemaZ = z.tuple(LLM_V2_POINTS_SCHEMA.map((v) => z.literal(v)));
+const AspectsSchemaZ = z.tuple(LLM_V2_ASPECTS_SCHEMA.map((v) => z.literal(v)));
+const PointKindZ = z.enum(LLM_V2_DICT.kind_id);
+const EdZ = z.enum(["none", "dom", "ex", "det", "fall"]);
+const PointRowZ = z.tuple([
+    z.string(), // id
+    PointKindZ, // kind
+    z.number().int(), // src (single-frame currently 0)
+    z.number(), // lon
+    z.number().nullable(), // lat
+    z.number().nullable(), // spd
+    z.number().int(), // rx
+    z.number().int(), // sg
+    z.number(), // deg
+    z.number().nullable(), // hs
+    z.number().nullable(), // dec
+    z.number().int(), // oob
+    EdZ, // ed
+    z.number().nullable(), // ed_sc
+    z.number().nullable(), // ad_sc
+    z.number().int(), // on_cusp
+]);
+const AspectRowZ = z.tuple([
+    z.number().int(), // a_i
+    z.number().int(), // b_i
+    z.number().int(), // t
+    z.number(), // orb
+    z.number(), // orb_pct
+    z.number().int(), // app
+    z.number(), // str
+]);
+const ChartSubjectZ = z
+    .object({
+    datetime: z.string().nullable().optional(),
+    jd: z.number().nullable().optional(),
+    lat: z.number().nullable().optional(),
+    lon: z.number().nullable().optional(),
+})
+    .strict();
+const ChartZ = z
+    .object({
+    chart_type: z.enum(["natal", "synastry"]),
+    // Natal-style payloads include subject; synastry-style table payloads omit it.
+    subject: ChartSubjectZ.optional(),
+})
+    .strict();
+const RulesZ = z
+    .object({
+    zodiac_type: z.string().nullable().optional(),
+    house_system: z.string().nullable().optional(),
+    coordinate_system: z.string().nullable().optional(),
+    node_source: z.string().nullable().optional(),
+    lon_range: z.literal("0_360"),
+    aspect_set: z.literal("major_default"),
+    orb_profile: z.string().nullable().optional(),
+    strength_basis: z.literal("engine"),
+    point_order_id: z.literal("astro_point_order_v1"),
+    core_set_id: z.literal("core_interp_set_v1"),
+})
+    .strict();
+const ProvenanceZ = z
+    .object({
+    engine: z.string(),
+    ephemeris_source: z.string(),
+    ephemeris_version: z.string(),
+    validation_profile: z.string().nullable().optional(),
+    precision_level: z.string().nullable().optional(),
+    checksum: z.string().nullable().optional(),
+})
+    .strict();
+const DictZ = z
+    .object({
+    sign_id: z.tuple(LLM_V2_DICT.sign_id.map((v) => z.literal(v))),
+    aspect_id: z.tuple(LLM_V2_DICT.aspect_id.map((v) => z.literal(v))),
+    aspect_angle: z.tuple(LLM_V2_DICT.aspect_angle.map((v) => z.literal(v))),
+    kind_id: z.tuple(LLM_V2_DICT.kind_id.map((v) => z.literal(v))),
+})
+    .strict();
+const PresentZ = z
+    .object({
+    point_count: z.number().int(),
+    kinds: z.record(z.string(), z.number().int()),
+})
+    .strict();
+const AnglesZ = z
+    .object({
+    asc: z.number().nullable().optional(),
+    mc: z.number().nullable().optional(),
+    dsc: z.number().nullable().optional(),
+    ic: z.number().nullable().optional(),
+})
+    .strict();
+const HousesZ = z
+    .object({
+    system: z.string().nullable().optional(),
+    cusps: z.array(z.number()),
+})
+    .strict();
+const PatternsZ = z
+    .object({
+    stellium: z.array(z.unknown()),
+    t_square: z.array(z.unknown()),
+    grand_trine: z.array(z.unknown()),
+    kite: z.array(z.unknown()),
+    yod: z.array(z.unknown()),
+    grand_cross: z.array(z.unknown()),
+})
+    .strict();
+const ExtrasZ = z
+    .object({
+    fixed_star_conjunctions: z.array(z.unknown()),
+    lots: z.array(z.unknown()),
+})
+    .strict();
+const CountsZ = z
+    .object({
+    point_count: z.number().int(),
+    aspect_count: z.number().int(),
+    // Natal-style payloads include these; synastry-style may omit.
+    aspect_count_unfiltered: z.number().int().optional(),
+    midpoint_count: z.number().int().optional(),
+    declination_aspect_count: z.number().int().optional(),
+    stellium_count: z.number().int().optional(),
+})
+    .strict();
+const HumanDesignZ = z
+    .object({
+    gates_schema: z.array(z.string()),
+    gates: z.array(z.array(z.any())),
+})
+    .strict();
+export const LlmV2PayloadSchema = z
+    .object({
+    // Some fixtures include this (envelope-like), but backend projector may omit it.
+    output_mode: z.literal("llm").optional(),
+    // Backend keeps schema versioning internal; allow older fixtures to include it.
+    schema_version: z.literal("llm").optional(),
+    chart: ChartZ,
+    // Natal-style payloads include these blocks; synastry-style may omit.
+    rules: RulesZ.optional(),
+    reliability: z.record(z.string(), z.unknown()).optional(),
+    provenance: ProvenanceZ.optional(),
+    dict: DictZ,
+    present: PresentZ,
+    points_schema: PointsSchemaZ,
+    points: z.array(PointRowZ),
+    angles: AnglesZ.optional(),
+    houses: HousesZ.optional(),
+    aspects_schema: AspectsSchemaZ,
+    aspects: z.array(AspectRowZ),
+    patterns: PatternsZ.optional(),
+    extras: ExtrasZ.optional(),
+    counts: CountsZ,
+    // Optional enrichment blocks added by some endpoints.
+    analysis: z.record(z.string(), z.unknown()).optional(),
+    human_design: HumanDesignZ.optional(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const expectedPointsLen = LLM_V2_POINTS_SCHEMA.length;
+    for (let i = 0; i < Math.min(value.points.length, 200); i++) {
+        const row = value.points[i];
+        if (row.length !== expectedPointsLen) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["points", i],
+                message: `points[${i}] row length ${row.length} != ${expectedPointsLen}`,
+            });
+        }
+    }
+    const expectedAspectsLen = LLM_V2_ASPECTS_SCHEMA.length;
+    for (let i = 0; i < Math.min(value.aspects.length, 2000); i++) {
+        const row = value.aspects[i];
+        if (row.length !== expectedAspectsLen) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["aspects", i],
+                message: `aspects[${i}] row length ${row.length} != ${expectedAspectsLen}`,
+            });
+        }
+    }
+});
+// A JSON Schema companion for downstream consumers.
+// (We intentionally keep this small and explicit rather than depending on a zod->jsonschema lib.)
+export const llmV2JsonSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "Open Ephemeris LLM Projection (format=llm)",
+    type: "object",
+    additionalProperties: false,
+    required: ["chart", "dict", "present", "points_schema", "points", "aspects_schema", "aspects", "counts"],
+    properties: {
+        output_mode: { type: "string", enum: ["llm"] },
+        schema_version: { type: "string", enum: ["llm"] },
+        chart: {
+            type: "object",
+            additionalProperties: false,
+            required: ["chart_type"],
+            properties: {
+                chart_type: { type: "string", enum: ["natal", "synastry"] },
+                subject: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        datetime: { anyOf: [{ type: "string" }, { type: "null" }] },
+                        jd: { anyOf: [{ type: "number" }, { type: "null" }] },
+                        lat: { anyOf: [{ type: "number" }, { type: "null" }] },
+                        lon: { anyOf: [{ type: "number" }, { type: "null" }] },
+                    },
+                },
+            },
+        },
+        rules: {
+            type: "object",
+            additionalProperties: false,
+            required: [
+                "lon_range",
+                "aspect_set",
+                "strength_basis",
+                "point_order_id",
+                "core_set_id",
+            ],
+            properties: {
+                zodiac_type: { anyOf: [{ type: "string" }, { type: "null" }] },
+                house_system: { anyOf: [{ type: "string" }, { type: "null" }] },
+                coordinate_system: { anyOf: [{ type: "string" }, { type: "null" }] },
+                node_source: { anyOf: [{ type: "string" }, { type: "null" }] },
+                lon_range: { type: "string", enum: ["0_360"] },
+                aspect_set: { type: "string", enum: ["major_default"] },
+                orb_profile: { anyOf: [{ type: "string" }, { type: "null" }] },
+                strength_basis: { type: "string", enum: ["engine"] },
+                point_order_id: { type: "string", enum: ["astro_point_order_v1"] },
+                core_set_id: { type: "string", enum: ["core_interp_set_v1"] },
+            },
+        },
+        reliability: { type: "object" },
+        provenance: {
+            type: "object",
+            additionalProperties: false,
+            required: ["engine", "ephemeris_source", "ephemeris_version"],
+            properties: {
+                engine: { type: "string" },
+                ephemeris_source: { type: "string" },
+                ephemeris_version: { type: "string" },
+                validation_profile: { anyOf: [{ type: "string" }, { type: "null" }] },
+                precision_level: { anyOf: [{ type: "string" }, { type: "null" }] },
+                checksum: { anyOf: [{ type: "string" }, { type: "null" }] },
+            },
+        },
+        dict: {
+            type: "object",
+            additionalProperties: false,
+            required: ["sign_id", "aspect_id", "aspect_angle", "kind_id"],
+            properties: {
+                sign_id: {
+                    type: "array",
+                    items: { type: "string" },
+                    const: LLM_V2_DICT.sign_id,
+                },
+                aspect_id: {
+                    type: "array",
+                    items: { type: "string" },
+                    const: LLM_V2_DICT.aspect_id,
+                },
+                aspect_angle: {
+                    type: "array",
+                    items: { type: "number" },
+                    const: LLM_V2_DICT.aspect_angle,
+                },
+                kind_id: {
+                    type: "array",
+                    items: { type: "string" },
+                    const: LLM_V2_DICT.kind_id,
+                },
+            },
+        },
+        present: {
+            type: "object",
+            additionalProperties: false,
+            required: ["point_count", "kinds"],
+            properties: {
+                point_count: { type: "integer" },
+                kinds: { type: "object", additionalProperties: { type: "integer" } },
+            },
+        },
+        points_schema: {
+            type: "array",
+            items: { type: "string" },
+            const: LLM_V2_POINTS_SCHEMA,
+        },
+        points: {
+            type: "array",
+            items: {
+                type: "array",
+                minItems: LLM_V2_POINTS_SCHEMA.length,
+                maxItems: LLM_V2_POINTS_SCHEMA.length,
+                prefixItems: [
+                    { type: "string" },
+                    { type: "string" },
+                    { type: "integer" },
+                    { type: "number" },
+                    { anyOf: [{ type: "number" }, { type: "null" }] },
+                    { anyOf: [{ type: "number" }, { type: "null" }] },
+                    { type: "integer" },
+                    { type: "integer" },
+                    { type: "number" },
+                    { anyOf: [{ type: "number" }, { type: "null" }] },
+                    { anyOf: [{ type: "number" }, { type: "null" }] },
+                    { type: "integer" },
+                    { type: "string" },
+                    { anyOf: [{ type: "number" }, { type: "null" }] },
+                    { anyOf: [{ type: "number" }, { type: "null" }] },
+                    { type: "integer" },
+                ],
+            },
+        },
+        angles: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                asc: { anyOf: [{ type: "number" }, { type: "null" }] },
+                mc: { anyOf: [{ type: "number" }, { type: "null" }] },
+                dsc: { anyOf: [{ type: "number" }, { type: "null" }] },
+                ic: { anyOf: [{ type: "number" }, { type: "null" }] },
+            },
+        },
+        houses: {
+            type: "object",
+            additionalProperties: false,
+            required: ["cusps"],
+            properties: {
+                system: { anyOf: [{ type: "string" }, { type: "null" }] },
+                cusps: { type: "array", items: { type: "number" } },
+            },
+        },
+        aspects_schema: {
+            type: "array",
+            items: { type: "string" },
+            const: LLM_V2_ASPECTS_SCHEMA,
+        },
+        aspects: {
+            type: "array",
+            items: {
+                type: "array",
+                minItems: LLM_V2_ASPECTS_SCHEMA.length,
+                maxItems: LLM_V2_ASPECTS_SCHEMA.length,
+                prefixItems: [
+                    { type: "integer" },
+                    { type: "integer" },
+                    { type: "integer" },
+                    { type: "number" },
+                    { type: "number" },
+                    { type: "integer" },
+                    { type: "number" },
+                ],
+            },
+        },
+        patterns: {
+            type: "object",
+            additionalProperties: false,
+            required: ["stellium", "t_square", "grand_trine", "kite", "yod", "grand_cross"],
+            properties: {
+                stellium: { type: "array" },
+                t_square: { type: "array" },
+                grand_trine: { type: "array" },
+                kite: { type: "array" },
+                yod: { type: "array" },
+                grand_cross: { type: "array" },
+            },
+        },
+        extras: {
+            type: "object",
+            additionalProperties: false,
+            required: ["fixed_star_conjunctions", "lots"],
+            properties: {
+                fixed_star_conjunctions: { type: "array" },
+                lots: { type: "array" },
+            },
+        },
+        counts: {
+            type: "object",
+            additionalProperties: false,
+            required: ["point_count", "aspect_count"],
+            properties: {
+                point_count: { type: "integer" },
+                aspect_count: { type: "integer" },
+                aspect_count_unfiltered: { type: "integer" },
+                midpoint_count: { type: "integer" },
+                declination_aspect_count: { type: "integer" },
+                stellium_count: { type: "integer" },
+            },
+        },
+        analysis: { type: "object" },
+        human_design: {
+            type: "object",
+            additionalProperties: false,
+            required: ["gates_schema", "gates"],
+            properties: {
+                gates_schema: { type: "array", items: { type: "string" } },
+                gates: { type: "array", items: { type: "array" } },
+            },
+        },
+    },
+};

package/dist/src/tools/auth.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/tools/auth.js

@@ -0,0 +1,202 @@
+import { registerTool } from "./index.js";
+import { CredentialManager } from "../auth/credentials.js";
+import { DeviceAuthFlow } from "../auth/device-auth.js";
+const credentialManager = new CredentialManager();
+// ────────────────────────────────────────────────────────
+// auth.login — Start the device authorization flow
+// ────────────────────────────────────────────────────────
+registerTool({
+    name: "auth.login",
+    description: "Start the device authorization flow to connect this MCP server to your OpenEphemeris account. " +
+        "Returns a verification URL and code for the user to enter in their browser. " +
+        "The MCP server will then automatically receive credentials and all API calls will be " +
+        "linked to the user's account (tier, credits, rate limits). " +
+        "Only needed if no OPENEPHEMERIS_API_KEY env var is set and no cached credentials exist.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+    },
+    annotations: {
+        title: "Connect Account",
+        readOnlyHint: false,
+        destructiveHint: false,
+    },
+    handler: async () => {
+        // Check if already authenticated
+        const status = credentialManager.getStatus();
+        if (status.authenticated) {
+            return {
+                already_authenticated: true,
+                email: status.email,
+                user_id: status.userId,
+                expires_at: status.expiresAt,
+                message: `Already authenticated as ${status.email}. Use auth.logout to disconnect.`,
+            };
+        }
+        // Check if env var credentials are set
+        if (process.env.OPENEPHEMERIS_API_KEY ||
+            process.env.OPENEPHEMERIS_JWT ||
+            process.env.OPENEPHEMERIS_SERVICE_KEY) {
+            return {
+                already_authenticated: true,
+                method: "environment_variable",
+                message: "Credentials are configured via environment variables. " +
+                    "Device auth is not needed.",
+            };
+        }
+        // Start the device auth flow
+        const flow = new DeviceAuthFlow();
+        const startResult = await flow.start();
+        // Begin polling in the background — this runs until the user authorizes
+        // or the code expires. We don't await it here because the tool should
+        // return immediately with the code for the user.
+        flow
+            .poll(startResult.device_code, (attempt) => {
+            if (attempt % 6 === 0) {
+                console.error(`Still waiting... Visit ${startResult.verification_uri} and enter code: ${startResult.user_code}`);
+            }
+        })
+            .then((result) => {
+            console.error(`✅ Authenticated as ${result.user?.email || "user"}`);
+            console.error(`   Credentials saved to ${CredentialManager.credentialsPath}`);
+        })
+            .catch((err) => {
+            console.error(`❌ Device auth failed: ${err.message}`);
+        });
+        return {
+            action_required: true,
+            verification_uri: startResult.verification_uri,
+            user_code: startResult.user_code,
+            verification_uri_complete: startResult.verification_uri_complete,
+            expires_in: startResult.expires_in,
+            message: `Please visit ${startResult.verification_uri} and enter the code: ${startResult.user_code}. ` +
+                `Alternatively, open this direct link: ${startResult.verification_uri_complete}. ` +
+                `The server is polling in the background — once you authorize, all subsequent ` +
+                `tool calls will be linked to your account automatically.`,
+            instructions_for_agent: "Present the verification URL and code to the user clearly. " +
+                "They need to open the URL in a browser, log in to their OpenEphemeris account, " +
+                "and enter the code. After that, all API calls will work automatically. " +
+                "Wait 10-15 seconds after the user confirms they've entered the code, " +
+                "then try the original request again.",
+        };
+    },
+});
+// ────────────────────────────────────────────────────────
+// auth.status — Check current authentication state
+// ────────────────────────────────────────────────────────
+registerTool({
+    name: "auth.status",
+    description: "Check the current authentication status of this MCP server. " +
+        "Shows whether the server is authenticated, which account it's linked to, " +
+        "the authentication method (API key, JWT, device auth), and token expiry.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+    },
+    annotations: {
+        title: "Auth Status",
+        readOnlyHint: true,
+        destructiveHint: false,
+    },
+    handler: async () => {
+        // Check env var methods first
+        const hasApiKey = !!(process.env.OPENEPHEMERIS_API_KEY ||
+            process.env.ASTROMCP_API_KEY ||
+            process.env.MERIDIAN_API_KEY);
+        const hasJwt = !!(process.env.OPENEPHEMERIS_JWT ||
+            process.env.ASTROMCP_JWT ||
+            process.env.MERIDIAN_AUTH_TOKEN);
+        const hasServiceKey = !!(process.env.OPENEPHEMERIS_SERVICE_KEY ||
+            process.env.ASTROMCP_SERVICE_KEY ||
+            process.env.MERIDIAN_SERVICE_KEY);
+        if (hasServiceKey) {
+            return {
+                authenticated: true,
+                method: "service_key",
+                message: "Authenticated via service key (admin/internal access).",
+            };
+        }
+        if (hasApiKey) {
+            return {
+                authenticated: true,
+                method: "api_key",
+                message: "Authenticated via API key environment variable.",
+            };
+        }
+        if (hasJwt) {
+            return {
+                authenticated: true,
+                method: "jwt_env_var",
+                message: "Authenticated via JWT environment variable.",
+            };
+        }
+        // Check cached credentials
+        const status = credentialManager.getStatus();
+        if (status.authenticated) {
+            return {
+                authenticated: true,
+                method: "device_auth",
+                email: status.email,
+                user_id: status.userId,
+                expires_at: status.expiresAt,
+                credentials_path: CredentialManager.credentialsPath,
+                message: `Authenticated as ${status.email} via device authorization.`,
+            };
+        }
+        // Check if credentials exist but are expired
+        const creds = credentialManager.load();
+        if (creds) {
+            return {
+                authenticated: false,
+                method: "device_auth_expired",
+                email: creds.user_email,
+                expired_at: creds.expires_at,
+                message: "Device auth credentials exist but are expired. " +
+                    "The server will attempt to refresh automatically on the next API call, " +
+                    "or you can run auth.login to re-authenticate.",
+            };
+        }
+        return {
+            authenticated: false,
+            method: "none",
+            message: "Not authenticated. Set OPENEPHEMERIS_API_KEY in your MCP server config, " +
+                "or run auth.login to connect your account interactively.",
+        };
+    },
+});
+// ────────────────────────────────────────────────────────
+// auth.logout — Clear cached credentials
+// ────────────────────────────────────────────────────────
+registerTool({
+    name: "auth.logout",
+    description: "Disconnect this MCP server from your OpenEphemeris account by clearing " +
+        "cached credentials. Does NOT revoke the API key if one is set via environment " +
+        "variable — only clears device-auth cached credentials.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+    },
+    annotations: {
+        title: "Disconnect Account",
+        readOnlyHint: false,
+        destructiveHint: true,
+    },
+    handler: async () => {
+        const status = credentialManager.getStatus();
+        if (!status.authenticated && !credentialManager.load()) {
+            return {
+                success: true,
+                message: "No cached credentials to clear.",
+            };
+        }
+        credentialManager.clear();
+        return {
+            success: true,
+            previous_email: status.email,
+            message: `Disconnected. Cached credentials for ${status.email || "unknown user"} have been removed.`,
+        };
+    },
+});

package/dist/src/tools/dev.d.ts

@@ -0,0 +1 @@
+export {};