# Orbital Watch (MCP server)

**Live MCP URL (Streamable HTTP):** `https://orbital-watch-mcp.vercel.app/mcp`  
Health check: `https://orbital-watch-mcp.vercel.app/health`

Orbital Watch is space-situational-awareness for Grok Bot (or any MCP client). It covers four areas:

- **Satellite and debris lookup**: any tracked object, with owner, launch, status, decay, current orbit and live position.
- **Debris fields and constellations**: how many objects from the 2007 Fengyun-1C ASAT test, the 2009 Iridium–Cosmos collision and others are still up, and at what altitudes.
- **Close approaches**: predicted conjunctions from CelesTrak SOCRATES for the next 7 days.
- **Space weather**: NOAA G/R/S scales, Kp, solar flares, alerts and the 3-day outlook, explained in plain English for **GPS, HF radio, Starlink/LEO satellites and aurora**.

All data is public and needs no keys. Every output cites its source URL and fetch time.

## Tools

| Tool | What it does |
|---|---|
| `satellite_info` | CelesTrak SATCAT and GP lookup by NORAD id, name or international designator. Live lat/lon/altitude via SGP4 (satellite.js) |
| `track_group` | Object count, perigee bands and regimes for a debris event (`cosmos-1408`, `fengyun-1c`, `iridium-33`, `cosmos-2251`) or any CelesTrak group (`starlink`, `stations`, `gps-ops`, …) |
| `conjunctions` | SOCRATES Plus close approaches by NORAD id, name pattern or overall, ordered by max probability, miss distance or time |
| `space_weather_now` | NOAA scales, current Kp, latest and strongest flares, Kp forecast, 3-day probabilities, and plain-English impacts |
| `space_weather_alerts` | Recent SWPC alerts, warnings and watches, with their stated impacts |

## Example prompts

- "Where is the ISS right now, and how high is it?"
- "How much Fengyun-1C debris is still in orbit, and at what altitude?"
- "Any close approaches for the ISS this week?" / "What are the riskiest Starlink conjunctions?"
- "Is there a geomagnetic storm? Will it affect my GPS, ham radio or Starlink?"
- "What space weather alerts has NOAA issued in the last day?"

## Notes on the data

- **Impacts** come from NOAA's G/R/S scale levels, following NOAA SWPC's scale descriptions:
  - **G** (geomagnetic storms; Kp 5→G1 … Kp 9→G5) affects GPS at high latitudes, LEO drag (the Feb 2022 Starlink loss happened during a minor storm, to satellites still in a very low orbit) and aurora.
  - **R** (radio blackouts from flares; M1→R1, M5→R2, X1→R3, X10→R4, X20→R5) affects dayside HF radio.
  - **S** (solar radiation) affects polar HF and satellites.
- **SOCRATES "max probability"** is CelesTrak's worst-case figure from public GP data, not operator-grade covariance. The output explains this.
- **Caching**:
  - CelesTrak SATCAT/GP: 2 h, as CelesTrak asks.
  - SOCRATES: 30 min. It updates about every 8 h.
  - SWPC: 1–5 min.
  - On upstream failure, the cached copy is served and marked STALE.
- **Space-Track.org is not used.** Its API returns HTTP 401 without an account, and its terms don't allow redistribution. CelesTrak republishes the same public catalogue and GP data.

## Run locally

```bash
npm install && npm test && npm run build
npm start             # http://localhost:3000/mcp
npm run start:stdio
npm run smoke         # live calls to every tool
```

## Deploy to Vercel

Push to GitHub, import it at vercel.com/new (preset: Other), and use `https://<project>.vercel.app/mcp`. No environment variables are needed. Check it with `node scripts/smoke.mjs <url>`.

## Testing instructions for marketplace reviewers

No credentials needed.

1. List tools. You should see 5.
2. `satellite_info` with `{"noradId": 25544}`: the ISS, with orbit (~420 km), live position and source lines.
3. `track_group` with `{"debrisEvent": "fengyun-1c"}`: around 2,000 objects, broken down by altitude band.
4. `conjunctions` with `{"name": "STARLINK", "max": 5}`: a table of close approaches with miss distances.
5. `space_weather_now` with `{}`: G/R/S scales, Kp, flares, and impact lines for GPS, HF, Starlink and aurora.
6. `space_weather_alerts` with `{"hours": 72}`.

## Data sources

[CelesTrak](https://celestrak.org) (SATCAT, GP, SOCRATES) by Dr. T.S. Kelso, and [NOAA Space Weather Prediction Center](https://www.swpc.noaa.gov). This tool is for information only and is not for operational collision avoidance.

## License

MIT