@openephemeris/mcp-server 3.1.0 → 3.2.2

package/dist/scripts/dev-allowlist.d.ts

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

package/dist/scripts/dev-allowlist.js

@@ -0,0 +1,287 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+import axios from "axios";
+function normalizeTier(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const value = raw.trim().toLowerCase();
+    if (value === "free" ||
+        value === "all" ||
+        value === "free/all" ||
+        value === "anonymous" ||
+        value === "anonymous/all" ||
+        value === "public" ||
+        value === "public/all")
+        return "free";
+    if (value === "dev" || value === "developer")
+        return "developer";
+    if (value === "pro")
+        return "pro";
+    if (value === "production")
+        return "production";
+    if (value === "admin" || value === "internal")
+        return "admin";
+    return null;
+}
+function isCommercialTier(tierNormalized) {
+    // Dev MCP should expose all commercially available tiers up through production.
+    return tierNormalized === "free" || tierNormalized === "developer" || tierNormalized === "pro" || tierNormalized === "production";
+}
+function sha256(text) {
+    return crypto.createHash("sha256").update(text).digest("hex");
+}
+function readJsonFile(filePath) {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    return { raw, json: JSON.parse(raw) };
+}
+function writeJsonFile(filePath, obj) {
+    fs.writeFileSync(filePath, JSON.stringify(obj, null, 2) + "\n", "utf-8");
+}
+function normalizeTag(tag) {
+    return tag.trim().toLowerCase();
+}
+function isDeniedByPrefix(pathname, prefixes) {
+    return prefixes.some((p) => pathname.startsWith(p));
+}
+function hasDeniedTag(tags, denyTags) {
+    const deny = new Set(denyTags.map(normalizeTag));
+    return tags.some((t) => deny.has(normalizeTag(t)));
+}
+function getDefaults() {
+    const here = path.dirname(fileURLToPath(import.meta.url)); // .../mcp-server/scripts
+    const mcpServerRoot = path.resolve(here, "..");
+    const repoRoot = path.resolve(mcpServerRoot, "..");
+    return {
+        mcpServerRoot,
+        repoRoot,
+        allowlistPath: path.join(mcpServerRoot, "config", "dev-allowlist.json"),
+        openapiPath: path.join(repoRoot, "go-sidecar", "openapi.json"),
+    };
+}
+function parseArgs(argv) {
+    const args = {
+        openapiPath: undefined,
+        allowlistPath: undefined,
+        write: false,
+        check: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--openapi")
+            args.openapiPath = argv[++i];
+        else if (a === "--allowlist")
+            args.allowlistPath = argv[++i];
+        else if (a === "--write")
+            args.write = true;
+        else if (a === "--check")
+            args.check = true;
+        else if (a === "--help" || a === "-h") {
+            console.log([
+                "Dev allowlist helper (astromcp-dev-allowlist-v1)",
+                "",
+                "Usage:",
+                "  tsx scripts/dev-allowlist.ts --check",
+                "  tsx scripts/dev-allowlist.ts --write",
+                "",
+                "Options:",
+                "  --openapi <path>    Path to OpenAPI JSON (default: ../go-sidecar/openapi.json)",
+                "  --allowlist <path>  Path to allowlist JSON (default: config/dev-allowlist.json)",
+                "  --check             Validate allowlist against OpenAPI + deny rules (exit 1 on failure)",
+                "  --write             Update allowlist metadata + candidates + auto-allow commercial-tier operations",
+            ].join("\n"));
+            process.exit(0);
+        }
+    }
+    return args;
+}
+function asHttpMethod(m) {
+    const up = m.toUpperCase();
+    if (up === "GET" || up === "POST" || up === "PUT" || up === "PATCH" || up === "DELETE")
+        return up;
+    return null;
+}
+function buildCandidates(openapi, denyPrefixes, denyTags) {
+    const candidatesGet = [];
+    const candidatesNonGet = [];
+    const index = new Map();
+    for (const [pathname, pathItem] of Object.entries(openapi.paths || {})) {
+        // OpenAPI keys can include templated params; we keep as-is.
+        if (denyPrefixes.length && isDeniedByPrefix(pathname, denyPrefixes))
+            continue;
+        for (const [methodKey, operation] of Object.entries(pathItem || {})) {
+            const method = asHttpMethod(methodKey);
+            if (!method)
+                continue;
+            const tags = Array.isArray(operation?.tags) ? operation.tags : [];
+            if (denyTags.length && hasDeniedTag(tags, denyTags))
+                continue;
+            const tier = typeof operation?.["x-meridian-tier"] === "string" ? String(operation["x-meridian-tier"]) : undefined;
+            const tier_normalized = tier ? normalizeTier(tier) ?? undefined : undefined;
+            const candidate = {
+                method,
+                path: pathname,
+                tags,
+                tier,
+                tier_normalized,
+                operationId: typeof operation?.operationId === "string" ? operation.operationId : undefined,
+                summary: typeof operation?.summary === "string" ? operation.summary : undefined,
+            };
+            const key = `${method} ${pathname}`;
+            index.set(key, candidate);
+            if (method === "GET")
+                candidatesGet.push(candidate);
+            else
+                candidatesNonGet.push(candidate);
+        }
+    }
+    candidatesGet.sort((a, b) => (a.path + a.method).localeCompare(b.path + b.method));
+    candidatesNonGet.sort((a, b) => (a.path + a.method).localeCompare(b.path + b.method));
+    return { candidatesGet, candidatesNonGet, index };
+}
+function buildCommercialAllow(candidates, existingAllow) {
+    // Build a lookup of existing notes/metadata to preserve across regen
+    const existingMeta = new Map();
+    for (const e of existingAllow) {
+        if (e.note)
+            existingMeta.set(`${e.method} ${e.path}`, { note: e.note });
+    }
+    const allow = candidates
+        .filter((c) => isCommercialTier(c.tier_normalized))
+        .map((c) => {
+        const key = `${c.method} ${c.path}`;
+        const entry = { method: c.method, path: c.path };
+        const meta = existingMeta.get(key);
+        if (meta?.note)
+            entry.note = meta.note;
+        return entry;
+    });
+    // Deterministic ordering for diffs.
+    allow.sort((a, b) => (a.path + a.method).localeCompare(b.path + b.method));
+    return allow;
+}
+function validateAllowlist(allowlist, index, denyPrefixes, denyTags) {
+    const errors = [];
+    const warnings = [];
+    for (const entry of allowlist.allow) {
+        if (!entry || typeof entry !== "object") {
+            errors.push(`Invalid allow entry (not an object): ${JSON.stringify(entry)}`);
+            continue;
+        }
+        const method = entry.method;
+        const pathname = entry.path;
+        if (!asHttpMethod(method)) {
+            errors.push(`Invalid method in allow entry: ${JSON.stringify(entry)}`);
+            continue;
+        }
+        if (typeof pathname !== "string" || !pathname.startsWith("/")) {
+            errors.push(`Invalid path in allow entry: ${JSON.stringify(entry)}`);
+            continue;
+        }
+        if (denyPrefixes.length && isDeniedByPrefix(pathname, denyPrefixes)) {
+            errors.push(`Allowlisted entry violates deny prefix rule: ${method} ${pathname}`);
+            continue;
+        }
+        const key = `${method.toUpperCase()} ${pathname}`;
+        const candidate = index.get(key);
+        if (!candidate) {
+            errors.push(`Allowlisted entry not found in OpenAPI: ${key}`);
+            continue;
+        }
+        if (!isCommercialTier(candidate.tier_normalized)) {
+            errors.push(`Allowlisted entry is not a commercial-tier operation: ${key} (x-meridian-tier=${candidate.tier ?? "<missing>"})`);
+            continue;
+        }
+        if (denyTags.length && hasDeniedTag(candidate.tags, denyTags)) {
+            errors.push(`Allowlisted entry violates deny tag rule: ${key} (tags=${candidate.tags.join(",")})`);
+            continue;
+        }
+        // Method gating reminder: non-GET is allowed only by explicit allowlist (which it is),
+        // but we keep a warning so reviewers notice.
+        if (method.toUpperCase() !== "GET") {
+            warnings.push(`Non-GET allowlisted: ${key}`);
+        }
+    }
+    return { errors, warnings };
+}
+async function getOpenApiDocument(inputPathOrUrl) {
+    if (inputPathOrUrl.startsWith("http")) {
+        console.log(`Fetching OpenAPI from URL: ${inputPathOrUrl}`);
+        const response = await axios.get(inputPathOrUrl);
+        const json = response.data;
+        return { raw: JSON.stringify(json), json };
+    }
+    const raw = fs.readFileSync(inputPathOrUrl, "utf-8");
+    return { raw, json: JSON.parse(raw) };
+}
+async function main() {
+    const defaults = getDefaults();
+    const args = parseArgs(process.argv.slice(2));
+    const allowlistPath = path.resolve(args.allowlistPath || defaults.allowlistPath);
+    const openapiPathOrUrl = args.openapiPath || process.env.ASTROMCP_OPENAPI_URL || defaults.openapiPath;
+    const { raw: allowRaw, json: allowlist } = readJsonFile(allowlistPath);
+    if (!allowlist || allowlist.schema !== "astromcp-dev-allowlist-v1" || !Array.isArray(allowlist.allow)) {
+        throw new Error(`Invalid allowlist schema at ${allowlistPath}`);
+    }
+    const denyPrefixes = allowlist.deny?.path_prefixes ?? [];
+    const denyTags = allowlist.deny?.tags ?? [];
+    const { raw: openapiRaw, json: openapi } = await getOpenApiDocument(openapiPathOrUrl);
+    if (!openapi || typeof openapi !== "object" || !openapi.paths) {
+        throw new Error(`Invalid OpenAPI document at ${openapiPathOrUrl}`);
+    }
+    const openapiHash = sha256(openapiRaw);
+    const allowlistHash = sha256(allowRaw);
+    const { candidatesGet, candidatesNonGet, index } = buildCandidates(openapi, denyPrefixes, denyTags);
+    const computedAllow = buildCommercialAllow([...candidatesGet, ...candidatesNonGet], allowlist.allow);
+    const allowlistForValidation = args.write ? { ...allowlist, allow: computedAllow } : allowlist;
+    const { errors, warnings } = validateAllowlist(allowlistForValidation, index, denyPrefixes, denyTags);
+    const report = {
+        ok: errors.length === 0,
+        allowlistPath,
+        openapiPath: openapiPathOrUrl,
+        openapi_sha256: openapiHash,
+        allowlist_sha256: allowlistHash,
+        counts: {
+            allow: allowlistForValidation.allow.length,
+            candidates_get: candidatesGet.length,
+            candidates_non_get: candidatesNonGet.length,
+            errors: errors.length,
+            warnings: warnings.length,
+        },
+        errors,
+        warnings,
+    };
+    if (args.write) {
+        const now = new Date().toISOString();
+        const updated = {
+            ...allowlist,
+            generated_from: openapiPathOrUrl,
+            last_generated_at: now,
+            openapi_sha256: openapiHash,
+            allow: computedAllow,
+            candidates_get: candidatesGet.map((c) => ({ method: c.method, path: c.path, tags: c.tags, operationId: c.operationId })),
+            candidates_non_get: candidatesNonGet.map((c) => ({ method: c.method, path: c.path, tags: c.tags, operationId: c.operationId })),
+            validation: {
+                ok: errors.length === 0,
+                errors,
+                warnings,
+            },
+        };
+        writeJsonFile(allowlistPath, updated);
+    }
+    if (args.check) {
+        if (!report.ok) {
+            console.error(JSON.stringify(report, null, 2));
+            process.exit(1);
+        }
+        // Print a small success line for CI.
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log(JSON.stringify(report, null, 2));
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/scripts/pack-audit.d.ts

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

package/dist/scripts/pack-audit.js

@@ -0,0 +1,45 @@
+import { execSync } from "node:child_process";
+function main() {
+    const raw = execSync("npm pack --dry-run --json", {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "inherit"],
+    });
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new Error("Unable to parse npm pack --dry-run --json output.");
+    }
+    const pack = parsed[0];
+    const filePaths = new Set(pack.files.map((f) => f.path));
+    const required = ["dist/index.js", "config/dev-allowlist.json", "README.md", "package.json"];
+    const missing = required.filter((f) => !filePaths.has(f));
+    if (missing.length > 0) {
+        throw new Error(`Pack audit failed: required files missing: ${missing.join(", ")}`);
+    }
+    const bannedPatterns = [
+        /^src\//,
+        /^test\//,
+        /^scripts\//,
+        /^test-output/,
+        /^diff\.txt$/,
+        /^tsconfig(?:\.test)?\.json$/,
+        /^package-lock\.json$/,
+        /^node_modules\//,
+    ];
+    const banned = pack.files
+        .map((f) => f.path)
+        .filter((p) => bannedPatterns.some((re) => re.test(p)));
+    if (banned.length > 0) {
+        throw new Error(`Pack audit failed: unexpected files in tarball: ${banned.join(", ")}`);
+    }
+    const distFiles = pack.files.filter((f) => f.path.startsWith("dist/"));
+    if (distFiles.length === 0) {
+        throw new Error("Pack audit failed: no dist/* files present in tarball.");
+    }
+    console.log(JSON.stringify({
+        ok: true,
+        filename: pack.filename,
+        file_count: pack.files.length,
+        dist_file_count: distFiles.length,
+    }, null, 2));
+}
+main();

package/dist/scripts/schema-packs.d.ts

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

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/scripts/test-client.d.ts

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