astronomy-oracle 0.1.0

package/dist/tools/search-objects.js

@@ -0,0 +1,108 @@
+/**
+ * search_objects tool — filter and browse the celestial object catalog.
+ */
+import { z } from "zod";
+import { getCatalog } from "../data/catalog.js";
+import { OBJECT_TYPES } from "../types.js";
+import { formatSearchResults } from "../format.js";
+const typeKeys = Object.keys(OBJECT_TYPES).filter((k) => k !== "NonEx" && k !== "Dup");
+export function registerSearchObjects(server) {
+    server.tool("search_objects", "Search and filter the celestial object catalog by type, constellation, magnitude, angular size, or catalog membership. Returns a formatted table of matching objects sorted by brightness.", {
+        type: z
+            .enum(typeKeys)
+            .optional()
+            .describe("Object type code (e.g. G=Galaxy, PN=Planetary Nebula, OCl=Open Cluster)"),
+        constellation: z
+            .string()
+            .optional()
+            .describe("IAU constellation abbreviation (e.g. Ori, And, Sgr)"),
+        maxMagnitude: z
+            .number()
+            .optional()
+            .describe("Maximum (faintest) visual magnitude to include"),
+        minMagnitude: z
+            .number()
+            .optional()
+            .describe("Minimum (brightest) visual magnitude to include"),
+        minSize: z
+            .number()
+            .optional()
+            .describe("Minimum angular size in arcminutes"),
+        catalog: z
+            .enum(["messier", "caldwell", "ngc", "ic"])
+            .optional()
+            .describe("Filter by catalog membership"),
+        limit: z
+            .number()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe("Maximum number of results (default 20, max 100)"),
+    }, async (params) => {
+        const store = await getCatalog();
+        const { type, constellation, maxMagnitude, minMagnitude, minSize, catalog: catalogFilter, limit, } = params;
+        const maxResults = limit ?? 20;
+        let results = [...store.all.values()];
+        // Filter by type
+        if (type) {
+            results = results.filter((obj) => obj.type === type);
+        }
+        // Filter by constellation
+        if (constellation) {
+            const lc = constellation.toLowerCase();
+            results = results.filter((obj) => obj.constellation.toLowerCase() === lc);
+        }
+        // Filter by max magnitude (faintest)
+        if (maxMagnitude !== undefined) {
+            results = results.filter((obj) => obj.magnitude !== null && obj.magnitude <= maxMagnitude);
+        }
+        // Filter by min magnitude (brightest)
+        if (minMagnitude !== undefined) {
+            results = results.filter((obj) => obj.magnitude !== null && obj.magnitude >= minMagnitude);
+        }
+        // Filter by minimum angular size
+        if (minSize !== undefined) {
+            results = results.filter((obj) => obj.majorAxis !== null && obj.majorAxis >= minSize);
+        }
+        // Filter by catalog
+        if (catalogFilter) {
+            switch (catalogFilter) {
+                case "messier":
+                    results = results.filter((obj) => obj.messier !== null);
+                    break;
+                case "ngc":
+                    results = results.filter((obj) => obj.name.startsWith("NGC"));
+                    break;
+                case "ic":
+                    results = results.filter((obj) => obj.name.startsWith("IC"));
+                    break;
+                case "caldwell":
+                    // Caldwell objects have "C" in otherIdentifiers — approximate
+                    results = results.filter((obj) => obj.otherIdentifiers !== null &&
+                        /\bC\d+\b/.test(obj.otherIdentifiers));
+                    break;
+            }
+        }
+        // Sort by magnitude (brightest first, nulls last)
+        results.sort((a, b) => {
+            if (a.magnitude === null && b.magnitude === null)
+                return 0;
+            if (a.magnitude === null)
+                return 1;
+            if (b.magnitude === null)
+                return -1;
+            return a.magnitude - b.magnitude;
+        });
+        // Apply limit
+        results = results.slice(0, maxResults);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatSearchResults(results),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=search-objects.js.map

package/dist/tools/search-objects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-objects.js","sourceRoot":"","sources":["../../src/tools/search-objects.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Core data types for the astronomy-oracle MCP server.
+ */
+/** Map of OpenNGC object type codes to human-readable names. */
+export declare const OBJECT_TYPES: {
+    readonly "*": "Star";
+    readonly "**": "Double Star";
+    readonly "*Ass": "Stellar Association";
+    readonly OCl: "Open Cluster";
+    readonly GCl: "Globular Cluster";
+    readonly "Cl+N": "Cluster + Nebula";
+    readonly G: "Galaxy";
+    readonly GPair: "Galaxy Pair";
+    readonly GTrpl: "Galaxy Triplet";
+    readonly GGroup: "Galaxy Group";
+    readonly PN: "Planetary Nebula";
+    readonly HII: "HII Region";
+    readonly DrkN: "Dark Nebula";
+    readonly EmN: "Emission Nebula";
+    readonly Neb: "Nebula";
+    readonly RfN: "Reflection Nebula";
+    readonly SNR: "Supernova Remnant";
+    readonly Nova: "Nova";
+    readonly NonEx: "Non-Existent";
+    readonly Dup: "Duplicate";
+    readonly Other: "Other";
+};
+/** Valid object type codes from the OpenNGC catalog. */
+export type ObjectTypeCode = keyof typeof OBJECT_TYPES;
+/** A parsed celestial object from the catalog. */
+export interface CelestialObject {
+    name: string;
+    type: ObjectTypeCode;
+    typeName: string;
+    ra: number;
+    dec: number;
+    constellation: string;
+    magnitude: number | null;
+    surfaceBrightness: number | null;
+    majorAxis: number | null;
+    minorAxis: number | null;
+    positionAngle: number | null;
+    hubbleType: string | null;
+    messier: string | null;
+    ngcCrossRef: string | null;
+    icCrossRef: string | null;
+    commonName: string | null;
+    otherIdentifiers: string | null;
+}
+/** Supported catalog identifiers. */
+export type Catalog = "messier" | "caldwell" | "ngc" | "ic";
+/** Visibility information for an object at a given time and location. */
+export interface VisibilityInfo {
+    altitude: number;
+    azimuth: number;
+    riseTime: Date | null;
+    transitTime: Date | null;
+    setTime: Date | null;
+    isCircumpolar: boolean;
+    neverRises: boolean;
+}
+/** Time window within an observing session. */
+export type SessionWindow = "evening" | "midnight" | "predawn";
+/** An object scored and scheduled within an observing session. */
+export interface SessionObject {
+    object: CelestialObject;
+    peakAltitude: number;
+    transitTime: Date;
+    window: SessionWindow;
+    score: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,gEAAgE;AAChE,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;CAsBf,CAAC;AAEX,wDAAwD;AACxD,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,YAAY,CAAC;AAEvD,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,qCAAqC;AACrC,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,KAAK,GAAG,IAAI,CAAC;AAE5D,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,+CAA+C;AAC/C,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAE/D,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,eAAe,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,IAAI,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/types.js

@@ -0,0 +1,28 @@
+/**
+ * Core data types for the astronomy-oracle MCP server.
+ */
+/** Map of OpenNGC object type codes to human-readable names. */
+export const OBJECT_TYPES = {
+    "*": "Star",
+    "**": "Double Star",
+    "*Ass": "Stellar Association",
+    OCl: "Open Cluster",
+    GCl: "Globular Cluster",
+    "Cl+N": "Cluster + Nebula",
+    G: "Galaxy",
+    GPair: "Galaxy Pair",
+    GTrpl: "Galaxy Triplet",
+    GGroup: "Galaxy Group",
+    PN: "Planetary Nebula",
+    HII: "HII Region",
+    DrkN: "Dark Nebula",
+    EmN: "Emission Nebula",
+    Neb: "Nebula",
+    RfN: "Reflection Nebula",
+    SNR: "Supernova Remnant",
+    Nova: "Nova",
+    NonEx: "Non-Existent",
+    Dup: "Duplicate",
+    Other: "Other",
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,gEAAgE;AAChE,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,GAAG,EAAE,MAAM;IACX,IAAI,EAAE,aAAa;IACnB,MAAM,EAAE,qBAAqB;IAC7B,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,kBAAkB;IACvB,MAAM,EAAE,kBAAkB;IAC1B,CAAC,EAAE,QAAQ;IACX,KAAK,EAAE,aAAa;IACpB,KAAK,EAAE,gBAAgB;IACvB,MAAM,EAAE,cAAc;IACtB,EAAE,EAAE,kBAAkB;IACtB,GAAG,EAAE,YAAY;IACjB,IAAI,EAAE,aAAa;IACnB,GAAG,EAAE,iBAAiB;IACtB,GAAG,EAAE,QAAQ;IACb,GAAG,EAAE,mBAAmB;IACxB,GAAG,EAAE,mBAAmB;IACxB,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,cAAc;IACrB,GAAG,EAAE,WAAW;IAChB,KAAK,EAAE,OAAO;CACN,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "astronomy-oracle",
+  "version": "0.1.0",
+  "description": "Celestial object catalog and observing session planner MCP server",
+  "mcpName": "io.github.gregario/astronomy-oracle",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gregario/astronomy-oracle.git"
+  },
+  "type": "module",
+  "bin": {
+    "astronomy-oracle": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "data",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && chmod 755 dist/index.js",
+    "dev": "tsx src/index.ts",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12",
+    "zod": "^3.25"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}