@mrfentmen/spaceweather-mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# Space Weather
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+NOAA space weather: planetary Kp index, aurora probability for a place and active alerts from SWPC - keyless.
+
+Keyless — no signup, no API key, no environment variables.
+
+## Install
+
+```bash
+npx -y @mrfentmen/spaceweather-mcp
+```
+
+Or add it to your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "spaceweather-mcp": { "command": "npx", "args": ["-y", "@mrfentmen/spaceweather-mcp"] }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `kp_index` | Recent planetary Kp values (3-hourly) and the geomagnetic storm level they imply. |
+| `aurora_forecast` | Aurora visibility probability from the OVATION model, at a location or as a global summary. |
+| `alerts` | The latest SWPC alerts and warnings with issue times and message text. |
+
+## Data source
+
+NOAA Space Weather Prediction Center JSON feeds (services.swpc.noaa.gov), no key required

package/dist/api.d.ts

@@ -0,0 +1,15 @@
+export declare class SourceError extends Error {
+}
+export declare function getJson(path: string, accept?: string, timeoutMs?: number): Promise<any>;
+export declare function clampLimit(n: number | undefined, fallback: number, max: number): number;
+export declare function clean(s: unknown): string;
+export declare function kpIndex(a: {
+    hours?: number;
+}): Promise<string>;
+export declare function auroraForecast(a: {
+    lat?: number;
+    lon?: number;
+}): Promise<string>;
+export declare function alerts(a: {
+    limit?: number;
+}): Promise<string>;

package/dist/api.js

@@ -0,0 +1,146 @@
+/**
+ * Space Weather — keyless public API client.
+ */
+const BASE = "https://services.swpc.noaa.gov";
+const SOURCE = "Space Weather";
+export class SourceError extends Error {
+}
+async function request(path, accept = "application/json", timeoutMs = 25000) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const res = await fetch(path.startsWith("http") ? path : BASE + path, {
+            signal: ctrl.signal,
+            headers: { "user-agent": "spaceweather-mcp", accept },
+        });
+        if (!res.ok)
+            throw new SourceError(`${SOURCE} responded ${res.status}`);
+        return res;
+    }
+    catch (e) {
+        if (e instanceof SourceError)
+            throw e;
+        if (e.name === "AbortError")
+            throw new SourceError(`${SOURCE} request timed out`);
+        throw new SourceError(`${SOURCE} request failed: ${e.message}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function getJson(path, accept = "application/json", timeoutMs = 25000) {
+    const res = await request(path, accept, timeoutMs);
+    const body = await res.text();
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        throw new SourceError(`${SOURCE} returned malformed JSON`);
+    }
+}
+export function clampLimit(n, fallback, max) {
+    const v = n ?? fallback;
+    if (!Number.isInteger(v) || v < 1 || v > max)
+        throw new SourceError(`limit must be between 1 and ${max}`);
+    return v;
+}
+export function clean(s) {
+    return String(s ?? "").replace(/\s+/g, " ").trim();
+}
+function stormLevel(kp) {
+    if (kp >= 9)
+        return "G5 extreme storm";
+    if (kp >= 8)
+        return "G4 severe storm";
+    if (kp >= 7)
+        return "G3 strong storm";
+    if (kp >= 6)
+        return "G2 moderate storm";
+    if (kp >= 5)
+        return "G1 minor storm";
+    if (kp >= 4)
+        return "active";
+    return "quiet";
+}
+export async function kpIndex(a) {
+    const hours = clampLimit(a.hours, 8, 24);
+    const data = await getJson("/products/noaa-planetary-k-index.json", "application/json", 25000);
+    if (!Array.isArray(data) || !data.length)
+        throw new SourceError("SWPC returned no Kp data");
+    const rows = data.slice(-hours);
+    const latest = rows[rows.length - 1];
+    const kp = Number(latest?.Kp);
+    const maxKp = Math.max(...rows.map((r) => Number(r?.Kp)).filter(Number.isFinite));
+    return [
+        `Latest Kp: ${kp.toFixed(2)} (${stormLevel(kp)}) at ${clean(latest?.time_tag)} UTC`,
+        `Highest in the last ${rows.length} entries: ${maxKp.toFixed(2)}`,
+        "",
+        "time (UTC)            Kp    level",
+        ...rows.map((r) => {
+            const v = Number(r?.Kp);
+            return `${clean(r?.time_tag).padEnd(20)} ${v.toFixed(2).padStart(5)}  ${stormLevel(v)}`;
+        }),
+        "",
+        "Kp is the 3-hour planetary geomagnetic index; 5 or above means a storm and visible aurora at lower latitudes.",
+    ].join("\n");
+}
+export async function auroraForecast(a) {
+    const data = await getJson("/json/ovation_aurora_latest.json", "application/json", 30000);
+    const coords = Array.isArray(data?.coordinates) ? data.coordinates : [];
+    if (!coords.length)
+        throw new SourceError("SWPC returned no aurora grid");
+    const observed = clean(data["Observation Time"]);
+    const forecast = clean(data["Forecast Time"]);
+    const hasPoint = a.lat !== undefined && a.lon !== undefined;
+    const lines = [
+        `Aurora model: observed ${observed}, forecast for ${forecast}`,
+        "",
+    ];
+    if (hasPoint) {
+        const lat = Math.round(a.lat);
+        const lon = Math.round(a.lon);
+        let best = null;
+        for (const [x, y, v] of coords) {
+            const dLat = Math.abs(Number(y) - lat);
+            // Longitude wraps at 360, so -22 is the same column as 338.
+            const dLonRaw = Math.abs(Number(x) - lon);
+            const dLon = Math.min(dLonRaw, 360 - dLonRaw);
+            const score = dLat + dLon;
+            if (!best || score < best.score)
+                best = { lat: Number(y), lon: Number(x), value: Number(v), score };
+        }
+        const value = best ? best.value : 0;
+        lines.push(`At ${lat}, ${lon} (nearest grid cell ${best?.lat}, ${best?.lon}): aurora probability ${value}%`, "", value >= 50 ? "Aurora is likely overhead if skies are clear." :
+            value >= 20 ? "Aurora is possible overhead, better chance looking toward the pole." :
+                value >= 5 ? "Aurora is unlikely overhead; look north for a glow." :
+                    "No aurora expected at this location.", "", "The model is a 30-90 minute forecast; clouds and moonlight decide what you actually see.");
+    }
+    else {
+        const cells = coords.map(([x, y, v]) => ({ lat: Number(y), lon: Number(x), value: Number(v) }));
+        for (const hemisphere of [{ name: "north", test: (c) => c.lat > 0 }, { name: "south", test: (c) => c.lat < 0 }]) {
+            const subset = cells.filter(hemisphere.test);
+            const strong = subset.filter((c) => c.value >= 50);
+            const mild = subset.filter((c) => c.value >= 10);
+            const lowestLat = strong.length ? Math.min(...strong.map((c) => Math.abs(c.lat))) : null;
+            lines.push(`${hemisphere.name}: ${strong.length} cell(s) with 50%+ probability, ${mild.length} with 10%+` +
+                (lowestLat !== null ? ` - aurora reaching down to about ${lowestLat} degrees latitude` : " - no strong aurora belt right now"));
+        }
+        lines.push("", "Pass lat and lon to check one place.");
+    }
+    return lines.join("\n");
+}
+export async function alerts(a) {
+    const limit = clampLimit(a.limit, 5, 20);
+    const data = await getJson("/products/alerts.json", "application/json", 25000);
+    if (!Array.isArray(data) || !data.length)
+        return "SWPC has no active alerts or warnings right now.";
+    const rows = data.slice(0, limit);
+    return [
+        `${data.length} alert(s) on the feed, newest first (showing ${rows.length}):`,
+        "",
+        ...rows.map((al, i) => {
+            const message = clean(al?.message).replace(/\s+/g, " ");
+            return `${i + 1}. [${clean(al?.product_id)}] ${clean(al?.issue_datetime)} UTC\n   ${message.slice(0, 240)}${message.length > 240 ? " ..." : ""}`;
+        }),
+    ].join("\n");
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("spaceweather-mcp running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,44 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { alerts, auroraForecast, kpIndex, SourceError } from "./api.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+function errorMessage(e) {
+    if (e instanceof SourceError || e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}
+export function createServer() {
+    const server = new McpServer({ name: "spaceweather-mcp", version: "1.0.0" });
+    server.tool("kp_index", "Recent planetary Kp values (3-hourly) and the geomagnetic storm level they imply.", {
+        hours: z.number().int().min(1).max(24).default(8).describe("How many recent 3-hour entries to list")
+    }, async (a) => {
+        try {
+            return text(await kpIndex(a));
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: errorMessage(e) }], isError: true };
+        }
+    });
+    server.tool("aurora_forecast", "Aurora visibility probability from the OVATION model, at a location or as a global summary.", {
+        lat: z.number().min(-90).max(90).optional().describe("Latitude to look up, e.g. 60"),
+        lon: z.number().min(-180).max(180).optional().describe("Longitude to look up, e.g. 19")
+    }, async (a) => {
+        try {
+            return text(await auroraForecast(a));
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: errorMessage(e) }], isError: true };
+        }
+    });
+    server.tool("alerts", "The latest SWPC alerts and warnings with issue times and message text.", {
+        limit: z.number().int().min(1).max(20).default(5).describe("How many recent alerts to show")
+    }, async (a) => {
+        try {
+            return text(await alerts(a));
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: errorMessage(e) }], isError: true };
+        }
+    });
+    return server;
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@mrfentmen/spaceweather-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "NOAA space weather: planetary Kp index, aurora probability for a place and active alerts from SWPC - keyless.",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/spaceweather-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrfentmen/awesome-servers.git"
+  },
+  "bin": {
+    "spaceweather-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "space",
+    "weather",
+    "aurora",
+    "solar",
+    "noaa",
+    "keyless"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}