@openephemeris/mcp-server 3.0.1 → 3.2.0

package/dist/scripts/schema-packs.js

@@ -0,0 +1,150 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { LLM_V2_ASPECTS_SCHEMA, LLM_V2_DICT, LLM_V2_POINTS_SCHEMA, LlmV2PayloadSchema, llmV2JsonSchema, } from "../src/schema-packs/llm.js";
+function parseMode(argv) {
+    if (argv.includes("--write"))
+        return "write";
+    if (argv.includes("--check"))
+        return "check";
+    throw new Error("Usage: tsx scripts/schema-packs.ts --write|--check");
+}
+function ensureDir(dirPath) {
+    fs.mkdirSync(dirPath, { recursive: true });
+}
+function readJsonFile(filePath) {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(raw);
+}
+function writeJsonFile(filePath, obj) {
+    const raw = JSON.stringify(obj, null, 2) + "\n";
+    fs.writeFileSync(filePath, raw, "utf-8");
+}
+function stableStringify(obj) {
+    // Deterministic enough for our use: we always write with JSON.stringify(..., null, 2)
+    // and compare against the same formatting.
+    return JSON.stringify(obj, null, 2) + "\n";
+}
+function validateFixture(filePath) {
+    const payload = readJsonFile(filePath);
+    const parsed = LlmV2PayloadSchema.safeParse(payload);
+    if (!parsed.success) {
+        const msg = parsed.error.issues
+            .slice(0, 25)
+            .map((i) => `${i.path.join(".")}: ${i.message}`)
+            .join("\n");
+        throw new Error(`Invalid llm fixture: ${filePath}\n${msg}`);
+    }
+}
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const MCP_ROOT = path.resolve(SCRIPT_DIR, "..");
+const PACK_DIR = path.join(MCP_ROOT, "schema-packs", "llm");
+const FIXTURES_DIR = path.join(PACK_DIR, "fixtures");
+const SCHEMA_PATH = path.join(PACK_DIR, "schema.json");
+const REPO_ROOT = path.resolve(MCP_ROOT, "..");
+const CANDIDATE_FIXTURES = [
+    path.join(REPO_ROOT, "tmp", "llm_fe_sample.json"),
+    path.join(REPO_ROOT, "tmp", "llm_payload_user_2025-12-21.json"),
+];
+function copyFirstExistingFixture() {
+    for (const candidate of CANDIDATE_FIXTURES) {
+        if (!fs.existsSync(candidate))
+            continue;
+        const dest = path.join(FIXTURES_DIR, path.basename(candidate));
+        fs.copyFileSync(candidate, dest);
+        return dest;
+    }
+    return null;
+}
+function writeFallbackFixture() {
+    const fallbackPath = path.join(FIXTURES_DIR, "minimal-natal.json");
+    const minimalPayload = {
+        output_mode: "llm",
+        chart: {
+            chart_type: "natal",
+            subject: {
+                datetime: "2026-01-01T00:00:00Z",
+                jd: null,
+                lat: 0,
+                lon: 0,
+            },
+        },
+        dict: LLM_V2_DICT,
+        present: {
+            point_count: 1,
+            kinds: {
+                planet: 1,
+            },
+        },
+        points_schema: LLM_V2_POINTS_SCHEMA,
+        points: [["sun", "planet", 0, 280, 0, 1, 0, 9, 10, null, 23, 0, "none", null, null, 0]],
+        aspects_schema: LLM_V2_ASPECTS_SCHEMA,
+        aspects: [],
+        counts: {
+            point_count: 1,
+            aspect_count: 0,
+        },
+    };
+    writeJsonFile(fallbackPath, minimalPayload);
+    return fallbackPath;
+}
+function listFixtures() {
+    if (!fs.existsSync(FIXTURES_DIR))
+        return [];
+    return fs
+        .readdirSync(FIXTURES_DIR)
+        .filter((f) => f.toLowerCase().endsWith(".json"))
+        .map((f) => path.join(FIXTURES_DIR, f));
+}
+function checkSchemaFile() {
+    if (!fs.existsSync(SCHEMA_PATH)) {
+        throw new Error(`Missing schema file: ${SCHEMA_PATH} (run --write)`);
+    }
+    const disk = readJsonFile(SCHEMA_PATH);
+    const expected = llmV2JsonSchema;
+    const diskRaw = fs.readFileSync(SCHEMA_PATH, "utf-8");
+    const expectedRaw = stableStringify(expected);
+    if (diskRaw !== expectedRaw) {
+        throw new Error(`schema.json drift detected (run --write): ${SCHEMA_PATH}`);
+    }
+}
+function main() {
+    const mode = parseMode(process.argv.slice(2));
+    if (mode === "write") {
+        ensureDir(FIXTURES_DIR);
+        ensureDir(PACK_DIR);
+        writeJsonFile(SCHEMA_PATH, llmV2JsonSchema);
+        if (listFixtures().length === 0) {
+            const copied = copyFirstExistingFixture();
+            if (copied) {
+                validateFixture(copied);
+                // eslint-disable-next-line no-console
+                console.log(`Copied fixture: ${copied}`);
+            }
+            else {
+                const fallback = writeFallbackFixture();
+                validateFixture(fallback);
+                // eslint-disable-next-line no-console
+                console.log(`Wrote fallback fixture: ${fallback}`);
+            }
+        }
+        for (const fixture of listFixtures()) {
+            validateFixture(fixture);
+        }
+        // eslint-disable-next-line no-console
+        console.log(`Wrote schema pack: ${PACK_DIR}`);
+        return;
+    }
+    // check
+    checkSchemaFile();
+    const fixtures = listFixtures();
+    if (fixtures.length === 0) {
+        throw new Error(`No fixtures found in: ${FIXTURES_DIR}`);
+    }
+    for (const fixture of fixtures)
+        validateFixture(fixture);
+    // eslint-disable-next-line no-console
+    console.log(`Schema pack OK (fixtures=${fixtures.length})`);
+}
+main();

package/dist/scripts/smoke-dev-profile.d.ts

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

package/dist/scripts/smoke-dev-profile.js

@@ -0,0 +1,25 @@
+import { initTools, toolRegistry } from "../src/tools/index.js";
+async function main() {
+    await initTools("dev");
+    const list = toolRegistry["dev.list_allowed"];
+    const call = toolRegistry["dev.call"];
+    if (!list || !call) {
+        throw new Error("Dev tools not registered (expected dev.list_allowed and dev.call)");
+    }
+    const allowed = await list.handler({});
+    console.log("ALLOWED_TOOLS:");
+    console.log(JSON.stringify(Object.keys(toolRegistry), null, 2));
+    console.log("\nALLOWLIST:");
+    console.log(JSON.stringify(allowed, null, 2));
+    // Smoke call a simple endpoint that should exist without extra payload.
+    const result = await call.handler({
+        method: "GET",
+        path: "/health",
+    });
+    console.log("\nDEV_CALL_RESULT:");
+    console.log(JSON.stringify(result, null, 2));
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.stack || err.message : String(err));
+    process.exit(1);
+});

package/dist/scripts/sync-readme.d.ts

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

package/dist/scripts/sync-readme.js

@@ -0,0 +1,141 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { initTools, toolRegistry } from "../src/tools/index.js";
+const CURSOR_BEGIN = "<!-- GENERATED:CURSOR_INSTALL:BEGIN -->";
+const CURSOR_END = "<!-- GENERATED:CURSOR_INSTALL:END -->";
+const SNAPSHOT_BEGIN = "<!-- GENERATED:RUNTIME_SNAPSHOT:BEGIN -->";
+const SNAPSHOT_END = "<!-- GENERATED:RUNTIME_SNAPSHOT:END -->";
+function parseMode(argv) {
+    if (argv.includes("--write"))
+        return "write";
+    if (argv.includes("--check"))
+        return "check";
+    throw new Error("Usage: tsx scripts/sync-readme.ts --write|--check");
+}
+function replaceSection(content, beginMarker, endMarker, body) {
+    const start = content.indexOf(beginMarker);
+    const end = content.indexOf(endMarker);
+    if (start === -1 || end === -1 || end < start) {
+        throw new Error(`Missing marker block: ${beginMarker} ... ${endMarker}`);
+    }
+    const before = content.slice(0, start + beginMarker.length);
+    const after = content.slice(end);
+    return `${before}\n${body.trim()}\n${after}`;
+}
+function getRepoPaths() {
+    const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+    const mcpRoot = path.resolve(scriptDir, "..");
+    return {
+        readmePath: path.join(mcpRoot, "README.md"),
+        allowlistPath: path.join(mcpRoot, "config", "dev-allowlist.json"),
+    };
+}
+function loadAllowlist(allowlistPath) {
+    const raw = fs.readFileSync(allowlistPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed.schema !== "astromcp-dev-allowlist-v1" || !Array.isArray(parsed.allow)) {
+        throw new Error(`Invalid allowlist at ${allowlistPath}`);
+    }
+    return parsed;
+}
+function toCursorDeepLink() {
+    const config = {
+        command: "npx",
+        args: ["-y", "@openephemeris/mcp-server"],
+        env: {
+            OPENEPHEMERIS_PROFILE: "dev",
+            OPENEPHEMERIS_BACKEND_URL: "https://api.openephemeris.com",
+            OPENEPHEMERIS_API_KEY: "YOUR_API_KEY_HERE",
+        },
+    };
+    const configJson = JSON.stringify(config, null, 2);
+    const encoded = Buffer.from(JSON.stringify(config), "utf-8").toString("base64");
+    const url = `cursor://anysphere.cursor-deeplink/mcp/install?name=openephemeris&config=${encoded}`;
+    return { url, configJson };
+}
+function buildMethodCounts(entries) {
+    const counts = { GET: 0, POST: 0, PUT: 0, PATCH: 0, DELETE: 0 };
+    for (const e of entries) {
+        counts[e.method] += 1;
+    }
+    return counts;
+}
+function buildFamilyRows(entries) {
+    const families = new Map();
+    for (const e of entries) {
+        const family = e.path.split("/").filter(Boolean)[0] || "root";
+        const existing = families.get(family) || [];
+        existing.push(e);
+        families.set(family, existing);
+    }
+    const rows = [...families.entries()]
+        .map(([family, items]) => {
+        const sorted = [...items].sort((a, b) => `${a.path}:${a.method}`.localeCompare(`${b.path}:${b.method}`));
+        const sample = sorted.slice(0, 2).map((e) => `\`${e.method} ${e.path}\``).join(", ");
+        return { family, count: items.length, sample };
+    })
+        .sort((a, b) => a.family.localeCompare(b.family));
+    return rows;
+}
+async function buildRuntimeSnapshot(allow) {
+    await initTools("dev");
+    const toolNames = Object.keys(toolRegistry).sort((a, b) => a.localeCompare(b));
+    const typedTools = toolNames.filter((t) => !t.startsWith("dev."));
+    const genericTools = toolNames.filter((t) => t.startsWith("dev."));
+    const methodCounts = buildMethodCounts(allow);
+    const familyRows = buildFamilyRows(allow);
+    const familiesTable = [
+        "| Family | Operations | Example |",
+        "|---|---:|---|",
+        ...familyRows.map((row) => `| \`${row.family}\` | ${row.count} | ${row.sample} |`),
+    ].join("\n");
+    return [
+        "## Runtime Snapshot (Generated)",
+        "",
+        "Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live tool registry.",
+        "",
+        `- Allowlisted operations: **${allow.length}**`,
+        `- Methods: \`GET=${methodCounts.GET}\`, \`POST=${methodCounts.POST}\`, \`PUT=${methodCounts.PUT}\`, \`PATCH=${methodCounts.PATCH}\`, \`DELETE=${methodCounts.DELETE}\``,
+        `- Registered tools (\`OPENEPHEMERIS_PROFILE=dev\`): **${toolNames.length}**`,
+        `- Typed tools: ${typedTools.map((t) => `\`${t}\``).join(", ")}`,
+        `- Generic tools: ${genericTools.map((t) => `\`${t}\``).join(", ")}`,
+        "",
+        "### Allowlist Families",
+        "",
+        familiesTable,
+    ].join("\n");
+}
+async function main() {
+    const mode = parseMode(process.argv.slice(2));
+    const { readmePath, allowlistPath } = getRepoPaths();
+    const allowlist = loadAllowlist(allowlistPath);
+    const { url, configJson } = toCursorDeepLink();
+    const runtimeSnapshot = await buildRuntimeSnapshot(allowlist.allow);
+    const cursorSection = [
+        `[![Install in Cursor](https://img.shields.io/badge/Install%20in-Cursor-1f6feb)](${url})`,
+        "",
+        "> Replace `YOUR_API_KEY_HERE` in Cursor MCP settings with your API key from https://openephemeris.com/dashboard.",
+        "",
+        "Cursor deeplink payload:",
+        "```json",
+        configJson,
+        "```",
+    ].join("\n");
+    const original = fs.readFileSync(readmePath, "utf-8");
+    let next = replaceSection(original, CURSOR_BEGIN, CURSOR_END, cursorSection);
+    next = replaceSection(next, SNAPSHOT_BEGIN, SNAPSHOT_END, runtimeSnapshot);
+    if (mode === "check") {
+        if (next !== original) {
+            throw new Error("README drift detected. Run `npm run sync:readme`.");
+        }
+        console.log("README sync OK");
+        return;
+    }
+    fs.writeFileSync(readmePath, next, "utf-8");
+    console.log("README updated");
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

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

@@ -0,0 +1,65 @@
+/**
+ * Stored credential shape persisted to ~/.openephemeris/credentials.json.
+ */
+export interface StoredCredentials {
+    access_token: string;
+    refresh_token: string;
+    /** ISO 8601 timestamp when the access_token expires. */
+    expires_at: string;
+    /** Supabase user ID. */
+    user_id?: string;
+    /** User email for display purposes. */
+    user_email?: string;
+    /** Timestamp when these credentials were created/refreshed. */
+    updated_at: string;
+}
+/**
+ * CredentialManager handles reading, writing, refreshing, and clearing
+ * persisted OAuth credentials for the MCP server.
+ */
+export declare class CredentialManager {
+    private cachedCredentials;
+    private backendBaseURL;
+    constructor(backendBaseURL?: string);
+    /**
+     * Load credentials from disk. Returns null if file doesn't exist or is invalid.
+     */
+    load(): StoredCredentials | null;
+    /**
+     * Save credentials to disk.
+     */
+    save(credentials: StoredCredentials): void;
+    /**
+     * Check whether the current access_token is expired (or nearly expired).
+     */
+    isExpired(credentials?: StoredCredentials | null): boolean;
+    /**
+     * Attempt to refresh the access token using the stored refresh_token.
+     * Uses the Supabase GoTrue refresh endpoint directly.
+     */
+    refresh(): Promise<StoredCredentials | null>;
+    /**
+     * Fallback refresh via the web app's token refresh endpoint.
+     */
+    private refreshViaWebApp;
+    /**
+     * Get a valid access token, refreshing if necessary.
+     * Returns null if no credentials exist or refresh fails.
+     */
+    getValidToken(): Promise<string | null>;
+    /**
+     * Delete stored credentials.
+     */
+    clear(): void;
+    /**
+     * Get display info about the current auth state.
+     */
+    getStatus(): {
+        authenticated: boolean;
+        email?: string;
+        userId?: string;
+        expiresAt?: string;
+    };
+    /** Path to the credentials file (for diagnostics). */
+    static get credentialsPath(): string;
+}

package/dist/src/auth/credentials.js

@@ -0,0 +1,200 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+const CREDENTIALS_DIR = path.join(os.homedir(), ".openephemeris");
+const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, "credentials.json");
+/** How many seconds before actual expiry to consider the token "expired". */
+const EXPIRY_BUFFER_SECONDS = 120;
+/**
+ * CredentialManager handles reading, writing, refreshing, and clearing
+ * persisted OAuth credentials for the MCP server.
+ */
+export class CredentialManager {
+    cachedCredentials = null;
+    backendBaseURL;
+    constructor(backendBaseURL) {
+        this.backendBaseURL =
+            backendBaseURL ||
+                process.env.NEXT_PUBLIC_APP_URL ||
+                process.env.OPENEPHEMERIS_FRONTEND_URL ||
+                "https://openephemeris.com";
+    }
+    /**
+     * Load credentials from disk. Returns null if file doesn't exist or is invalid.
+     */
+    load() {
+        if (this.cachedCredentials)
+            return this.cachedCredentials;
+        try {
+            if (!fs.existsSync(CREDENTIALS_FILE))
+                return null;
+            const raw = fs.readFileSync(CREDENTIALS_FILE, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (!parsed.access_token || !parsed.refresh_token || !parsed.expires_at) {
+                return null;
+            }
+            this.cachedCredentials = parsed;
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Save credentials to disk.
+     */
+    save(credentials) {
+        try {
+            if (!fs.existsSync(CREDENTIALS_DIR)) {
+                fs.mkdirSync(CREDENTIALS_DIR, { recursive: true, mode: 0o700 });
+            }
+            const data = { ...credentials, updated_at: new Date().toISOString() };
+            fs.writeFileSync(CREDENTIALS_FILE, JSON.stringify(data, null, 2), {
+                encoding: "utf-8",
+                mode: 0o600, // Owner read/write only
+            });
+            this.cachedCredentials = data;
+        }
+        catch (err) {
+            console.error("Failed to save credentials:", err);
+        }
+    }
+    /**
+     * Check whether the current access_token is expired (or nearly expired).
+     */
+    isExpired(credentials) {
+        const creds = credentials || this.load();
+        if (!creds?.expires_at)
+            return true;
+        const expiresAt = new Date(creds.expires_at).getTime();
+        const now = Date.now();
+        return now >= expiresAt - EXPIRY_BUFFER_SECONDS * 1000;
+    }
+    /**
+     * Attempt to refresh the access token using the stored refresh_token.
+     * Uses the Supabase GoTrue refresh endpoint directly.
+     */
+    async refresh() {
+        const creds = this.load();
+        if (!creds?.refresh_token)
+            return null;
+        const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL ||
+            process.env.SUPABASE_URL;
+        const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY ||
+            process.env.SUPABASE_ANON_KEY;
+        if (!supabaseUrl || !supabaseAnonKey) {
+            // Can't refresh without Supabase config — fall back to the web app endpoint
+            return this.refreshViaWebApp(creds.refresh_token);
+        }
+        try {
+            const response = await fetch(`${supabaseUrl}/auth/v1/token?grant_type=refresh_token`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "apikey": supabaseAnonKey,
+                },
+                body: JSON.stringify({ refresh_token: creds.refresh_token }),
+            });
+            if (!response.ok)
+                return null;
+            const data = await response.json();
+            if (!data.access_token || !data.refresh_token)
+                return null;
+            const expiresAt = new Date(Date.now() + (data.expires_in || 3600) * 1000).toISOString();
+            const updated = {
+                access_token: data.access_token,
+                refresh_token: data.refresh_token,
+                expires_at: expiresAt,
+                user_id: data.user?.id || creds.user_id,
+                user_email: data.user?.email || creds.user_email,
+                updated_at: new Date().toISOString(),
+            };
+            this.save(updated);
+            return updated;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Fallback refresh via the web app's token refresh endpoint.
+     */
+    async refreshViaWebApp(refreshToken) {
+        try {
+            const response = await fetch(`${this.backendBaseURL}/api/device/token`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    grant_type: "refresh_token",
+                    refresh_token: refreshToken,
+                }),
+            });
+            if (!response.ok)
+                return null;
+            const data = await response.json();
+            if (!data.access_token)
+                return null;
+            const expiresAt = new Date(Date.now() + (data.expires_in || 3600) * 1000).toISOString();
+            const updated = {
+                access_token: data.access_token,
+                refresh_token: data.refresh_token || refreshToken,
+                expires_at: expiresAt,
+                user_id: data.user?.id,
+                user_email: data.user?.email,
+                updated_at: new Date().toISOString(),
+            };
+            this.save(updated);
+            return updated;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get a valid access token, refreshing if necessary.
+     * Returns null if no credentials exist or refresh fails.
+     */
+    async getValidToken() {
+        const creds = this.load();
+        if (!creds)
+            return null;
+        if (!this.isExpired(creds)) {
+            return creds.access_token;
+        }
+        // Try refresh
+        const refreshed = await this.refresh();
+        return refreshed?.access_token || null;
+    }
+    /**
+     * Delete stored credentials.
+     */
+    clear() {
+        this.cachedCredentials = null;
+        try {
+            if (fs.existsSync(CREDENTIALS_FILE)) {
+                fs.unlinkSync(CREDENTIALS_FILE);
+            }
+        }
+        catch {
+            // Ignore
+        }
+    }
+    /**
+     * Get display info about the current auth state.
+     */
+    getStatus() {
+        const creds = this.load();
+        if (!creds)
+            return { authenticated: false };
+        return {
+            authenticated: !this.isExpired(creds),
+            email: creds.user_email,
+            userId: creds.user_id,
+            expiresAt: creds.expires_at,
+        };
+    }
+    /** Path to the credentials file (for diagnostics). */
+    static get credentialsPath() {
+        return CREDENTIALS_FILE;
+    }
+}

package/dist/src/auth/device-auth.d.ts

@@ -0,0 +1,56 @@
+import { CredentialManager } from "./credentials.js";
+export interface DeviceAuthStartResult {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+export interface DeviceAuthTokenResult {
+    access_token: string;
+    refresh_token: string;
+    token_type: string;
+    expires_in: number;
+    user?: {
+        id: string;
+        email: string;
+    };
+}
+/**
+ * Custom error thrown when the MCP server needs authentication
+ * but no credentials are available and device auth hasn't been started.
+ */
+export declare class NeedsAuthError extends Error {
+    readonly verificationUri: string;
+    readonly userCode: string;
+    constructor(verificationUri: string, userCode: string);
+}
+/**
+ * DeviceAuthFlow implements RFC 8628 Device Authorization Grant
+ * for connecting the MCP server to a user's OpenEphemeris account.
+ */
+export declare class DeviceAuthFlow {
+    private baseURL;
+    private credentialManager;
+    constructor(baseURL?: string, credentialManager?: CredentialManager);
+    /**
+     * Start the device authorization flow.
+     * Calls POST /api/device/authorize to get a device code + user code.
+     */
+    start(clientName?: string): Promise<DeviceAuthStartResult>;
+    /**
+     * Poll the token endpoint until the user authorizes the device code
+     * or the code expires.
+     *
+     * @param deviceCode - The device_code from start()
+     * @param onPending - Optional callback fired on each "authorization_pending" poll
+     * @returns The token result with access_token and refresh_token
+     */
+    poll(deviceCode: string, onPending?: (attempt: number) => void): Promise<DeviceAuthTokenResult>;
+    /**
+     * Start the full device auth flow: request code, print instructions, poll for token.
+     * This is the main entry point for interactive use.
+     */
+    authenticate(): Promise<DeviceAuthTokenResult>;
+}