heliofleet-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- heliofleet_mcp-0.1.0/CHANGELOG.md +13 -0
- heliofleet_mcp-0.1.0/LICENSE +21 -0
- heliofleet_mcp-0.1.0/MANIFEST.in +4 -0
- heliofleet_mcp-0.1.0/PKG-INFO +225 -0
- heliofleet_mcp-0.1.0/README.md +199 -0
- heliofleet_mcp-0.1.0/pyproject.toml +43 -0
- heliofleet_mcp-0.1.0/scripts/check_release.py +102 -0
- heliofleet_mcp-0.1.0/scripts/get_mcp_publisher.sh +19 -0
- heliofleet_mcp-0.1.0/scripts/smoke_stdio.py +31 -0
- heliofleet_mcp-0.1.0/server.json +44 -0
- heliofleet_mcp-0.1.0/setup.cfg +4 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp/__init__.py +3 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp/__main__.py +3 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp/catalog.py +67 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp/data.py +198 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp/frames.py +106 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp/geometry.py +383 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp/heliofield.py +319 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp/links.py +87 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp/server.py +155 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp/timeutil.py +56 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp.egg-info/PKG-INFO +225 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp.egg-info/SOURCES.txt +36 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp.egg-info/dependency_links.txt +1 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp.egg-info/entry_points.txt +2 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp.egg-info/requires.txt +6 -0
- heliofleet_mcp-0.1.0/src/heliofleet_mcp.egg-info/top_level.txt +1 -0
- heliofleet_mcp-0.1.0/tests/conftest.py +23 -0
- heliofleet_mcp-0.1.0/tests/data/page_alignments.json +146 -0
- heliofleet_mcp-0.1.0/tests/data/reference.json +446 -0
- heliofleet_mcp-0.1.0/tests/js/page_alignments.mjs +20 -0
- heliofleet_mcp-0.1.0/tests/test_alignments.py +80 -0
- heliofleet_mcp-0.1.0/tests/test_data_sources.py +31 -0
- heliofleet_mcp-0.1.0/tests/test_heliofield.py +89 -0
- heliofleet_mcp-0.1.0/tests/test_links_and_tools.py +92 -0
- heliofleet_mcp-0.1.0/tests/test_reference.py +51 -0
- heliofleet_mcp-0.1.0/tests/test_server_stdio.py +54 -0
- heliofleet_mcp-0.1.0/tests/test_sunpy.py +79 -0
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0 (2026-11-20)
|
|
4
|
+
|
|
5
|
+
First release.
|
|
6
|
+
|
|
7
|
+
- Tools on HelioFleet data: `get_position`, `get_fleet_state`, `find_alignments` (radial,
|
|
8
|
+
quadrature, conjunction, connection), `list_upcoming_events`, `viewing_geometry`,
|
|
9
|
+
`heliofleet_link` and `data_status`. Every result carries a link that reproduces the view.
|
|
10
|
+
- HelioField plugin: `magnetic_connection`, `space_weather`, `coronal_field` and `heliofield_link`.
|
|
11
|
+
- Stonyhurst and Carrington coordinates agree with SunPy to 0.0004° (limit 0.005°). Alignment
|
|
12
|
+
windows are identical to HelioFleet's page code.
|
|
13
|
+
- Data are read from the public sites with a local cache, or from local checkouts offline.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Soumyaranjan Dash
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: heliofleet-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: MCP server for heliophysics spacecraft geometry from HelioFleet's published ephemerides
|
|
5
|
+
Author: Soumyaranjan Dash
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: HelioFleet, https://sr-dash.github.io/heliofleet/
|
|
8
|
+
Project-URL: HelioField, https://sr-dash.github.io/heliofield/
|
|
9
|
+
Project-URL: Source, https://github.com/sr-dash/heliofleet-mcp
|
|
10
|
+
Project-URL: Issues, https://github.com/sr-dash/heliofleet-mcp/issues
|
|
11
|
+
Project-URL: Changelog, https://github.com/sr-dash/heliofleet-mcp/blob/main/CHANGELOG.md
|
|
12
|
+
Keywords: heliophysics,spacecraft,ephemeris,solar,mcp,sunpy,pfss
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Topic :: Scientific/Engineering :: Astronomy
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Requires-Dist: mcp>=1.2
|
|
21
|
+
Provides-Extra: test
|
|
22
|
+
Requires-Dist: pytest>=7; extra == "test"
|
|
23
|
+
Requires-Dist: sunpy>=6; extra == "test"
|
|
24
|
+
Requires-Dist: astropy>=6; extra == "test"
|
|
25
|
+
Dynamic: license-file
|
|
26
|
+
|
|
27
|
+
# heliofleet-mcp
|
|
28
|
+
|
|
29
|
+
<!-- mcp-name: io.github.sr-dash/heliofleet-mcp -->
|
|
30
|
+
|
|
31
|
+
A small [Model Context Protocol](https://modelcontextprotocol.io) server that answers
|
|
32
|
+
spacecraft-geometry questions from [HelioFleet](https://sr-dash.github.io/heliofleet/)'s published
|
|
33
|
+
data: where the heliophysics fleet is, what each spacecraft sees of the Sun, and when two of them
|
|
34
|
+
line up. It is a thin layer over HelioFleet's static JSON files (JPL Horizons ephemerides,
|
|
35
|
+
2010 to about 2030, refreshed monthly). Nothing is recomputed from scratch. The frame and
|
|
36
|
+
alignment code is a line-by-line port of the page's own JavaScript, so the numbers match the site.
|
|
37
|
+
|
|
38
|
+
Every answer carries a HelioFleet link that reproduces the view in the browser.
|
|
39
|
+
|
|
40
|
+
## Tools
|
|
41
|
+
|
|
42
|
+
| Tool | What it returns |
|
|
43
|
+
| --- | --- |
|
|
44
|
+
| `get_position(body, time)` | Distance from the Sun; Stonyhurst lon/lat; Carrington longitude seen from Earth; ecliptic J2000 and HEE vectors; angle from Earth and distance to Earth; light time; Parker-spiral footpoint |
|
|
45
|
+
| `get_fleet_state(time)` | The same columns for Earth, every spacecraft on the map, and optionally Mercury, Venus and Mars |
|
|
46
|
+
| `find_alignments(kind, a, b, tolerance_deg, start, end)` | Windows of `radial` alignment, `quadrature` with Earth, solar `conjunction` (behind the Sun seen from Earth) or magnetic `connection` (Parker-spiral footpoints). Each window has start, end, best time and value, plus a link that reruns the search on the page |
|
|
47
|
+
| `list_upcoming_events(start, end)` | HelioFleet's calendar: perihelia, alignments, quadratures, conjunctions and eclipses. Optionally adds DONKI flares, CMEs and storms |
|
|
48
|
+
| `viewing_geometry(observer, time)` | Light time and offset from Earth, RSUN_OBS, B0, HGLN_OBS, L0 (CRLN_OBS, the observer's own light time), km per arcsec and scale relative to Earth, with a sky-view link |
|
|
49
|
+
| `heliofleet_link(...)` | A map or sky-view URL for a time, frame, zoom, hidden bodies, surface spot, tab or alignment search |
|
|
50
|
+
| `data_status()` | Which data release is loaded, where it came from, and each body's span |
|
|
51
|
+
|
|
52
|
+
### HelioField plugin (on by default)
|
|
53
|
+
|
|
54
|
+
These tools add the coronal magnetic field from [HelioField](https://sr-dash.github.io/heliofield/)'s
|
|
55
|
+
daily PFSS products. They read published files and do not solve the field.
|
|
56
|
+
|
|
57
|
+
| Tool | What it returns |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| `magnetic_connection(body, date, solar_wind_km_s)` | Where Earth, the L1 fleet, Parker, Solar Orbiter, BepiColombo or STEREO-A connects to the Sun: the Parker-spiral point on the source surface, the PFSS footpoint (Carrington), the expansion factor, distance to the coronal-hole boundary and a WSA-type speed. `self_consistent=True` uses each body's own speed estimate |
|
|
60
|
+
| `space_weather(date)` | Model wind speed and sector at Earth, the next sector boundary, a −1 to +7 day outlook, an alert level, and that day's solar wind measured at L1 |
|
|
61
|
+
| `coronal_field(date)` | Magnetogram, PFSS settings, open flux and Earth's L0/B0, plus solar-cycle context per Carrington rotation (open flux and area, current-sheet tilt, polar fields; any date since 2010) |
|
|
62
|
+
| `heliofield_link(...)` | A link to the 3D corona, connectivity, space-weather or observations page |
|
|
63
|
+
|
|
64
|
+
Daily products cover about the last two months. For older dates the tools return links, because the
|
|
65
|
+
HelioField page computes any date since 2010-05-01 in the browser. HelioField's Carrington positions
|
|
66
|
+
of the fleet agree with HelioFleet's to 0.002°, and a test checks this. Set
|
|
67
|
+
`HELIOFLEET_MCP_PLUGINS=none` to serve the HelioFleet tools alone.
|
|
68
|
+
|
|
69
|
+
Bodies: `earth sdo soho aditya ace wind dscovr imap swfo cgo solo psp bepi sta stb maven mercury venus mars`.
|
|
70
|
+
Common names also work, such as "Parker", "Solar Orbiter" and "STEREO-A". Times are UTC in ISO 8601
|
|
71
|
+
(`2026-11-19T12:00Z`, `2026-11-19`), `now`, or a Julian date.
|
|
72
|
+
|
|
73
|
+
## Quick start
|
|
74
|
+
|
|
75
|
+
With [uv](https://docs.astral.sh/uv/) installed, one command downloads and starts the server:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
uvx heliofleet-mcp
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
It speaks MCP over stdio, so on its own it waits silently for a client. Register it with one:
|
|
82
|
+
|
|
83
|
+
**Claude Code**, for all projects:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
claude mcp add heliofleet --scope user -- uvx heliofleet-mcp
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
**Claude Desktop** and other MCP clients take this `mcpServers` entry. In Claude Desktop it goes in
|
|
90
|
+
Settings → Developer → Edit Config, then restart the app. In a project, it can go in `.mcp.json`.
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{
|
|
94
|
+
"mcpServers": {
|
|
95
|
+
"heliofleet": {
|
|
96
|
+
"command": "uvx",
|
|
97
|
+
"args": ["heliofleet-mcp"]
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Then ask, for example, "When are Parker and Solar Orbiter next radially aligned?" To work offline
|
|
104
|
+
from a heliofleet checkout, add `"env": {"HELIOFLEET_SOURCE": "local", "HELIOFLEET_LOCAL_DATA":
|
|
105
|
+
"/path/to/heliofleet/data"}` to the entry.
|
|
106
|
+
|
|
107
|
+
The server is also listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as
|
|
108
|
+
`io.github.sr-dash/heliofleet-mcp`.
|
|
109
|
+
|
|
110
|
+
## Other ways to install
|
|
111
|
+
|
|
112
|
+
The only runtime dependency is the `mcp` Python SDK (1.x or 2.x); Python 3.10 or newer.
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
pipx install heliofleet-mcp # or: pip install heliofleet-mcp
|
|
116
|
+
heliofleet-mcp # or: python -m heliofleet_mcp
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
From a clone, for development:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
git clone https://github.com/sr-dash/heliofleet-mcp && cd heliofleet-mcp
|
|
123
|
+
python3 -m venv .venv && .venv/bin/pip install -e '.[test]' jplephem
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
## Example
|
|
127
|
+
|
|
128
|
+
> When is the next Parker Solar Probe and Solar Orbiter radial alignment within 10° after 2026-11-19?
|
|
129
|
+
|
|
130
|
+
`find_alignments(kind="radial", a="psp", b="solo", tolerance_deg=10, start="2026-11-19", max_windows=1)`:
|
|
131
|
+
|
|
132
|
+
```json
|
|
133
|
+
{
|
|
134
|
+
"start_utc": "2026-12-01T16:00:00Z",
|
|
135
|
+
"end_utc": "2026-12-01T19:00:00Z",
|
|
136
|
+
"duration_days": 0.125,
|
|
137
|
+
"best_time_utc": "2026-12-01T18:00:00Z",
|
|
138
|
+
"best_value_deg": 6.173,
|
|
139
|
+
"a_at_best": {"body": "psp", "r_au": 0.0504, "hgs_lon_deg": 39.551, "hgs_lat_deg": -2.141},
|
|
140
|
+
"b_at_best": {"body": "solo", "r_au": 0.8614, "hgs_lon_deg": 37.749, "hgs_lat_deg": 3.763},
|
|
141
|
+
"link": "https://sr-dash.github.io/heliofleet/?t=2026-12-01T18:00Z&align=radial,psp,solo,10,2026-11-19,2027-11-19&tab=align#tools"
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
This is Parker's perihelion pass. Parker sweeps 4 to 5° an hour in Stonyhurst longitude and
|
|
146
|
+
passes Solar Orbiter's longitude (37.7°). JPL Horizons gives separations of 8.91°, 6.29°, 6.18°
|
|
147
|
+
and 9.07° at 16, 17, 18 and 19 UT.
|
|
148
|
+
|
|
149
|
+
## Data and caching
|
|
150
|
+
|
|
151
|
+
Files are fetched from `https://sr-dash.github.io/heliofleet/data/`. They are cached under
|
|
152
|
+
`~/.cache/heliofleet-mcp/<release>/`, keyed by the manifest's build time, so a monthly update never
|
|
153
|
+
mixes with older files. The manifest is checked again every 6 hours. If the site cannot be reached,
|
|
154
|
+
the server uses the cached manifest, then a local heliofleet checkout. A sibling `heliofleet/data`
|
|
155
|
+
folder is found automatically.
|
|
156
|
+
|
|
157
|
+
| Variable | Default | Meaning |
|
|
158
|
+
| --- | --- | --- |
|
|
159
|
+
| `HELIOFLEET_SOURCE` | `auto` | `auto` (site, then local), `web`, or `local` |
|
|
160
|
+
| `HELIOFLEET_LOCAL_DATA` | sibling `heliofleet/data` | local data folder |
|
|
161
|
+
| `HELIOFLEET_CACHE` | `~/.cache/heliofleet-mcp` | cache folder |
|
|
162
|
+
| `HELIOFLEET_SITE` | `https://sr-dash.github.io/heliofleet/` | site root |
|
|
163
|
+
| `HELIOFLEET_MCP_PLUGINS` | `heliofield` | optional tool sets, or `none` |
|
|
164
|
+
| `HELIOFIELD_SITE` | `https://sr-dash.github.io/heliofield/` | HelioField site root |
|
|
165
|
+
| `HELIOFIELD_LOCAL` | sibling `heliofield` | local HelioField checkout |
|
|
166
|
+
|
|
167
|
+
HelioField files go in the same cache. Dated products are kept for good, and the index and series
|
|
168
|
+
files are refreshed hourly.
|
|
169
|
+
|
|
170
|
+
## Methods
|
|
171
|
+
|
|
172
|
+
- Positions are interpolated with HelioFleet's 4-point Lagrange scheme (`js/ephem.js`). L1
|
|
173
|
+
monitors stored as geocentric km are added to Earth's heliocentric position (`js/scene.js`).
|
|
174
|
+
- Stonyhurst (HEEQ) and Carrington coordinates use the IAU rotation model, as in SunPy (`js/frames.js`).
|
|
175
|
+
The pole is at RA 286.13°, Dec 63.87°, with W = 84.176° + 14.1844°/day since J2000 TT. Carrington
|
|
176
|
+
longitudes see the Sun one light time in the past: Earth's light time for coordinate tables, the
|
|
177
|
+
observer's own for viewing geometry (CRLN_OBS).
|
|
178
|
+
- The alignment search (`js/tools.js` `findAlignments`) samples hourly when Parker is involved and
|
|
179
|
+
every 6 hours otherwise. Windows are runs of samples within the tolerance, so window edges sit on
|
|
180
|
+
that grid. Solar conjunctions follow `scripts/build_calendar.py`.
|
|
181
|
+
- Spacecraft status follows the map: `ok`, `lost` (a prediction after loss of contact), or `approx`
|
|
182
|
+
(SDO past the end of its ephemeris, shown at Earth).
|
|
183
|
+
|
|
184
|
+
Full methods: <https://sr-dash.github.io/heliofleet/methods.html>.
|
|
185
|
+
|
|
186
|
+
## Tests
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
.venv/bin/pip install -e '.[test]' jplephem
|
|
190
|
+
.venv/bin/python -m pytest
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
- `test_reference.py`: interpolation against JPL Horizons, and Stonyhurst/Carrington against SunPy,
|
|
194
|
+
using HelioFleet's reference set (`tests/data/reference.json`). The limit is 0.005°. The worst case
|
|
195
|
+
is 0.0004°.
|
|
196
|
+
- `test_sunpy.py`: frame conversions against SunPy computed live. It covers Earth's B0 and L0
|
|
197
|
+
against `sunpy.coordinates.sun`, and Venus and Mars end to end against DE432s.
|
|
198
|
+
- `test_alignments.py`: windows identical to the page's own `findAlignments` (run live through Node
|
|
199
|
+
when a heliofleet checkout is next to this one, otherwise a stored fixture), and the demo query
|
|
200
|
+
against Horizons.
|
|
201
|
+
- `test_server_stdio.py`: the server started over stdio and called through the MCP client.
|
|
202
|
+
- `test_data_sources.py`: site fetch and cache (marked `network`), and the local fallback.
|
|
203
|
+
- `test_heliofield.py`: the plugin's daily products, links as in HelioField's `llms.txt`, and
|
|
204
|
+
HelioField's fleet positions and L0/B0 against HelioFleet's frames.
|
|
205
|
+
|
|
206
|
+
`HELIOFLEET_TEST_SOURCE=web` runs the suite on the live sites instead of local checkouts.
|
|
207
|
+
|
|
208
|
+
## Releasing
|
|
209
|
+
|
|
210
|
+
1. Set the new version in `src/heliofleet_mcp/__init__.py` and in both `version` fields of
|
|
211
|
+
`server.json`, and add a section to `CHANGELOG.md`. `python scripts/check_release.py` checks
|
|
212
|
+
that they agree.
|
|
213
|
+
2. Commit, push, and publish a GitHub release tagged `vX.Y.Z`.
|
|
214
|
+
3. The `release` workflow then runs the tests and builds the package. It publishes to PyPI by
|
|
215
|
+
trusted publishing, attaches the files to the release, waits for PyPI, and publishes
|
|
216
|
+
`server.json` to the MCP Registry under `io.github.sr-dash/heliofleet-mcp`.
|
|
217
|
+
|
|
218
|
+
The `tests` workflow validates the package and `server.json` on every push.
|
|
219
|
+
|
|
220
|
+
## Licence and citation
|
|
221
|
+
|
|
222
|
+
MIT. When you use positions from this server, please cite HelioFleet: Dash, S. (2026). *HelioFleet:
|
|
223
|
+
an interactive map of heliophysics spacecraft positions* [Computer software]. Zenodo.
|
|
224
|
+
<https://doi.org/10.5281/zenodo.23328187>. Ephemerides: JPL Horizons. For coronal-field results,
|
|
225
|
+
cite HelioField (<https://doi.org/10.5281/zenodo.23487231>) and the magnetogram (NSO/GONG or SDO/HMI).
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
# heliofleet-mcp
|
|
2
|
+
|
|
3
|
+
<!-- mcp-name: io.github.sr-dash/heliofleet-mcp -->
|
|
4
|
+
|
|
5
|
+
A small [Model Context Protocol](https://modelcontextprotocol.io) server that answers
|
|
6
|
+
spacecraft-geometry questions from [HelioFleet](https://sr-dash.github.io/heliofleet/)'s published
|
|
7
|
+
data: where the heliophysics fleet is, what each spacecraft sees of the Sun, and when two of them
|
|
8
|
+
line up. It is a thin layer over HelioFleet's static JSON files (JPL Horizons ephemerides,
|
|
9
|
+
2010 to about 2030, refreshed monthly). Nothing is recomputed from scratch. The frame and
|
|
10
|
+
alignment code is a line-by-line port of the page's own JavaScript, so the numbers match the site.
|
|
11
|
+
|
|
12
|
+
Every answer carries a HelioFleet link that reproduces the view in the browser.
|
|
13
|
+
|
|
14
|
+
## Tools
|
|
15
|
+
|
|
16
|
+
| Tool | What it returns |
|
|
17
|
+
| --- | --- |
|
|
18
|
+
| `get_position(body, time)` | Distance from the Sun; Stonyhurst lon/lat; Carrington longitude seen from Earth; ecliptic J2000 and HEE vectors; angle from Earth and distance to Earth; light time; Parker-spiral footpoint |
|
|
19
|
+
| `get_fleet_state(time)` | The same columns for Earth, every spacecraft on the map, and optionally Mercury, Venus and Mars |
|
|
20
|
+
| `find_alignments(kind, a, b, tolerance_deg, start, end)` | Windows of `radial` alignment, `quadrature` with Earth, solar `conjunction` (behind the Sun seen from Earth) or magnetic `connection` (Parker-spiral footpoints). Each window has start, end, best time and value, plus a link that reruns the search on the page |
|
|
21
|
+
| `list_upcoming_events(start, end)` | HelioFleet's calendar: perihelia, alignments, quadratures, conjunctions and eclipses. Optionally adds DONKI flares, CMEs and storms |
|
|
22
|
+
| `viewing_geometry(observer, time)` | Light time and offset from Earth, RSUN_OBS, B0, HGLN_OBS, L0 (CRLN_OBS, the observer's own light time), km per arcsec and scale relative to Earth, with a sky-view link |
|
|
23
|
+
| `heliofleet_link(...)` | A map or sky-view URL for a time, frame, zoom, hidden bodies, surface spot, tab or alignment search |
|
|
24
|
+
| `data_status()` | Which data release is loaded, where it came from, and each body's span |
|
|
25
|
+
|
|
26
|
+
### HelioField plugin (on by default)
|
|
27
|
+
|
|
28
|
+
These tools add the coronal magnetic field from [HelioField](https://sr-dash.github.io/heliofield/)'s
|
|
29
|
+
daily PFSS products. They read published files and do not solve the field.
|
|
30
|
+
|
|
31
|
+
| Tool | What it returns |
|
|
32
|
+
| --- | --- |
|
|
33
|
+
| `magnetic_connection(body, date, solar_wind_km_s)` | Where Earth, the L1 fleet, Parker, Solar Orbiter, BepiColombo or STEREO-A connects to the Sun: the Parker-spiral point on the source surface, the PFSS footpoint (Carrington), the expansion factor, distance to the coronal-hole boundary and a WSA-type speed. `self_consistent=True` uses each body's own speed estimate |
|
|
34
|
+
| `space_weather(date)` | Model wind speed and sector at Earth, the next sector boundary, a −1 to +7 day outlook, an alert level, and that day's solar wind measured at L1 |
|
|
35
|
+
| `coronal_field(date)` | Magnetogram, PFSS settings, open flux and Earth's L0/B0, plus solar-cycle context per Carrington rotation (open flux and area, current-sheet tilt, polar fields; any date since 2010) |
|
|
36
|
+
| `heliofield_link(...)` | A link to the 3D corona, connectivity, space-weather or observations page |
|
|
37
|
+
|
|
38
|
+
Daily products cover about the last two months. For older dates the tools return links, because the
|
|
39
|
+
HelioField page computes any date since 2010-05-01 in the browser. HelioField's Carrington positions
|
|
40
|
+
of the fleet agree with HelioFleet's to 0.002°, and a test checks this. Set
|
|
41
|
+
`HELIOFLEET_MCP_PLUGINS=none` to serve the HelioFleet tools alone.
|
|
42
|
+
|
|
43
|
+
Bodies: `earth sdo soho aditya ace wind dscovr imap swfo cgo solo psp bepi sta stb maven mercury venus mars`.
|
|
44
|
+
Common names also work, such as "Parker", "Solar Orbiter" and "STEREO-A". Times are UTC in ISO 8601
|
|
45
|
+
(`2026-11-19T12:00Z`, `2026-11-19`), `now`, or a Julian date.
|
|
46
|
+
|
|
47
|
+
## Quick start
|
|
48
|
+
|
|
49
|
+
With [uv](https://docs.astral.sh/uv/) installed, one command downloads and starts the server:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
uvx heliofleet-mcp
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
It speaks MCP over stdio, so on its own it waits silently for a client. Register it with one:
|
|
56
|
+
|
|
57
|
+
**Claude Code**, for all projects:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
claude mcp add heliofleet --scope user -- uvx heliofleet-mcp
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
**Claude Desktop** and other MCP clients take this `mcpServers` entry. In Claude Desktop it goes in
|
|
64
|
+
Settings → Developer → Edit Config, then restart the app. In a project, it can go in `.mcp.json`.
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"mcpServers": {
|
|
69
|
+
"heliofleet": {
|
|
70
|
+
"command": "uvx",
|
|
71
|
+
"args": ["heliofleet-mcp"]
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Then ask, for example, "When are Parker and Solar Orbiter next radially aligned?" To work offline
|
|
78
|
+
from a heliofleet checkout, add `"env": {"HELIOFLEET_SOURCE": "local", "HELIOFLEET_LOCAL_DATA":
|
|
79
|
+
"/path/to/heliofleet/data"}` to the entry.
|
|
80
|
+
|
|
81
|
+
The server is also listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as
|
|
82
|
+
`io.github.sr-dash/heliofleet-mcp`.
|
|
83
|
+
|
|
84
|
+
## Other ways to install
|
|
85
|
+
|
|
86
|
+
The only runtime dependency is the `mcp` Python SDK (1.x or 2.x); Python 3.10 or newer.
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
pipx install heliofleet-mcp # or: pip install heliofleet-mcp
|
|
90
|
+
heliofleet-mcp # or: python -m heliofleet_mcp
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
From a clone, for development:
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
git clone https://github.com/sr-dash/heliofleet-mcp && cd heliofleet-mcp
|
|
97
|
+
python3 -m venv .venv && .venv/bin/pip install -e '.[test]' jplephem
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Example
|
|
101
|
+
|
|
102
|
+
> When is the next Parker Solar Probe and Solar Orbiter radial alignment within 10° after 2026-11-19?
|
|
103
|
+
|
|
104
|
+
`find_alignments(kind="radial", a="psp", b="solo", tolerance_deg=10, start="2026-11-19", max_windows=1)`:
|
|
105
|
+
|
|
106
|
+
```json
|
|
107
|
+
{
|
|
108
|
+
"start_utc": "2026-12-01T16:00:00Z",
|
|
109
|
+
"end_utc": "2026-12-01T19:00:00Z",
|
|
110
|
+
"duration_days": 0.125,
|
|
111
|
+
"best_time_utc": "2026-12-01T18:00:00Z",
|
|
112
|
+
"best_value_deg": 6.173,
|
|
113
|
+
"a_at_best": {"body": "psp", "r_au": 0.0504, "hgs_lon_deg": 39.551, "hgs_lat_deg": -2.141},
|
|
114
|
+
"b_at_best": {"body": "solo", "r_au": 0.8614, "hgs_lon_deg": 37.749, "hgs_lat_deg": 3.763},
|
|
115
|
+
"link": "https://sr-dash.github.io/heliofleet/?t=2026-12-01T18:00Z&align=radial,psp,solo,10,2026-11-19,2027-11-19&tab=align#tools"
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
This is Parker's perihelion pass. Parker sweeps 4 to 5° an hour in Stonyhurst longitude and
|
|
120
|
+
passes Solar Orbiter's longitude (37.7°). JPL Horizons gives separations of 8.91°, 6.29°, 6.18°
|
|
121
|
+
and 9.07° at 16, 17, 18 and 19 UT.
|
|
122
|
+
|
|
123
|
+
## Data and caching
|
|
124
|
+
|
|
125
|
+
Files are fetched from `https://sr-dash.github.io/heliofleet/data/`. They are cached under
|
|
126
|
+
`~/.cache/heliofleet-mcp/<release>/`, keyed by the manifest's build time, so a monthly update never
|
|
127
|
+
mixes with older files. The manifest is checked again every 6 hours. If the site cannot be reached,
|
|
128
|
+
the server uses the cached manifest, then a local heliofleet checkout. A sibling `heliofleet/data`
|
|
129
|
+
folder is found automatically.
|
|
130
|
+
|
|
131
|
+
| Variable | Default | Meaning |
|
|
132
|
+
| --- | --- | --- |
|
|
133
|
+
| `HELIOFLEET_SOURCE` | `auto` | `auto` (site, then local), `web`, or `local` |
|
|
134
|
+
| `HELIOFLEET_LOCAL_DATA` | sibling `heliofleet/data` | local data folder |
|
|
135
|
+
| `HELIOFLEET_CACHE` | `~/.cache/heliofleet-mcp` | cache folder |
|
|
136
|
+
| `HELIOFLEET_SITE` | `https://sr-dash.github.io/heliofleet/` | site root |
|
|
137
|
+
| `HELIOFLEET_MCP_PLUGINS` | `heliofield` | optional tool sets, or `none` |
|
|
138
|
+
| `HELIOFIELD_SITE` | `https://sr-dash.github.io/heliofield/` | HelioField site root |
|
|
139
|
+
| `HELIOFIELD_LOCAL` | sibling `heliofield` | local HelioField checkout |
|
|
140
|
+
|
|
141
|
+
HelioField files go in the same cache. Dated products are kept for good, and the index and series
|
|
142
|
+
files are refreshed hourly.
|
|
143
|
+
|
|
144
|
+
## Methods
|
|
145
|
+
|
|
146
|
+
- Positions are interpolated with HelioFleet's 4-point Lagrange scheme (`js/ephem.js`). L1
|
|
147
|
+
monitors stored as geocentric km are added to Earth's heliocentric position (`js/scene.js`).
|
|
148
|
+
- Stonyhurst (HEEQ) and Carrington coordinates use the IAU rotation model, as in SunPy (`js/frames.js`).
|
|
149
|
+
The pole is at RA 286.13°, Dec 63.87°, with W = 84.176° + 14.1844°/day since J2000 TT. Carrington
|
|
150
|
+
longitudes see the Sun one light time in the past: Earth's light time for coordinate tables, the
|
|
151
|
+
observer's own for viewing geometry (CRLN_OBS).
|
|
152
|
+
- The alignment search (`js/tools.js` `findAlignments`) samples hourly when Parker is involved and
|
|
153
|
+
every 6 hours otherwise. Windows are runs of samples within the tolerance, so window edges sit on
|
|
154
|
+
that grid. Solar conjunctions follow `scripts/build_calendar.py`.
|
|
155
|
+
- Spacecraft status follows the map: `ok`, `lost` (a prediction after loss of contact), or `approx`
|
|
156
|
+
(SDO past the end of its ephemeris, shown at Earth).
|
|
157
|
+
|
|
158
|
+
Full methods: <https://sr-dash.github.io/heliofleet/methods.html>.
|
|
159
|
+
|
|
160
|
+
## Tests
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
.venv/bin/pip install -e '.[test]' jplephem
|
|
164
|
+
.venv/bin/python -m pytest
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
- `test_reference.py`: interpolation against JPL Horizons, and Stonyhurst/Carrington against SunPy,
|
|
168
|
+
using HelioFleet's reference set (`tests/data/reference.json`). The limit is 0.005°. The worst case
|
|
169
|
+
is 0.0004°.
|
|
170
|
+
- `test_sunpy.py`: frame conversions against SunPy computed live. It covers Earth's B0 and L0
|
|
171
|
+
against `sunpy.coordinates.sun`, and Venus and Mars end to end against DE432s.
|
|
172
|
+
- `test_alignments.py`: windows identical to the page's own `findAlignments` (run live through Node
|
|
173
|
+
when a heliofleet checkout is next to this one, otherwise a stored fixture), and the demo query
|
|
174
|
+
against Horizons.
|
|
175
|
+
- `test_server_stdio.py`: the server started over stdio and called through the MCP client.
|
|
176
|
+
- `test_data_sources.py`: site fetch and cache (marked `network`), and the local fallback.
|
|
177
|
+
- `test_heliofield.py`: the plugin's daily products, links as in HelioField's `llms.txt`, and
|
|
178
|
+
HelioField's fleet positions and L0/B0 against HelioFleet's frames.
|
|
179
|
+
|
|
180
|
+
`HELIOFLEET_TEST_SOURCE=web` runs the suite on the live sites instead of local checkouts.
|
|
181
|
+
|
|
182
|
+
## Releasing
|
|
183
|
+
|
|
184
|
+
1. Set the new version in `src/heliofleet_mcp/__init__.py` and in both `version` fields of
|
|
185
|
+
`server.json`, and add a section to `CHANGELOG.md`. `python scripts/check_release.py` checks
|
|
186
|
+
that they agree.
|
|
187
|
+
2. Commit, push, and publish a GitHub release tagged `vX.Y.Z`.
|
|
188
|
+
3. The `release` workflow then runs the tests and builds the package. It publishes to PyPI by
|
|
189
|
+
trusted publishing, attaches the files to the release, waits for PyPI, and publishes
|
|
190
|
+
`server.json` to the MCP Registry under `io.github.sr-dash/heliofleet-mcp`.
|
|
191
|
+
|
|
192
|
+
The `tests` workflow validates the package and `server.json` on every push.
|
|
193
|
+
|
|
194
|
+
## Licence and citation
|
|
195
|
+
|
|
196
|
+
MIT. When you use positions from this server, please cite HelioFleet: Dash, S. (2026). *HelioFleet:
|
|
197
|
+
an interactive map of heliophysics spacecraft positions* [Computer software]. Zenodo.
|
|
198
|
+
<https://doi.org/10.5281/zenodo.23328187>. Ephemerides: JPL Horizons. For coronal-field results,
|
|
199
|
+
cite HelioField (<https://doi.org/10.5281/zenodo.23487231>) and the magnetogram (NSO/GONG or SDO/HMI).
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "heliofleet-mcp"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "MCP server for heliophysics spacecraft geometry from HelioFleet's published ephemerides"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
authors = [{ name = "Soumyaranjan Dash" }]
|
|
12
|
+
requires-python = ">=3.10"
|
|
13
|
+
dependencies = ["mcp>=1.2"]
|
|
14
|
+
keywords = ["heliophysics", "spacecraft", "ephemeris", "solar", "mcp", "sunpy", "pfss"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"Intended Audience :: Science/Research",
|
|
18
|
+
"Topic :: Scientific/Engineering :: Astronomy",
|
|
19
|
+
"Operating System :: OS Independent",
|
|
20
|
+
]
|
|
21
|
+
|
|
22
|
+
[project.optional-dependencies]
|
|
23
|
+
test = ["pytest>=7", "sunpy>=6", "astropy>=6"]
|
|
24
|
+
|
|
25
|
+
[project.scripts]
|
|
26
|
+
heliofleet-mcp = "heliofleet_mcp.server:main"
|
|
27
|
+
|
|
28
|
+
[project.urls]
|
|
29
|
+
HelioFleet = "https://sr-dash.github.io/heliofleet/"
|
|
30
|
+
HelioField = "https://sr-dash.github.io/heliofield/"
|
|
31
|
+
Source = "https://github.com/sr-dash/heliofleet-mcp"
|
|
32
|
+
Issues = "https://github.com/sr-dash/heliofleet-mcp/issues"
|
|
33
|
+
Changelog = "https://github.com/sr-dash/heliofleet-mcp/blob/main/CHANGELOG.md"
|
|
34
|
+
|
|
35
|
+
[tool.setuptools.dynamic]
|
|
36
|
+
version = { attr = "heliofleet_mcp.__version__" }
|
|
37
|
+
|
|
38
|
+
[tool.setuptools.packages.find]
|
|
39
|
+
where = ["src"]
|
|
40
|
+
|
|
41
|
+
[tool.pytest.ini_options]
|
|
42
|
+
testpaths = ["tests"]
|
|
43
|
+
markers = ["network: needs internet access (HelioFleet site or JPL Horizons)"]
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
"""Release consistency checks for the package and its MCP Registry entry.
|
|
2
|
+
|
|
3
|
+
python scripts/check_release.py # versions, names, README marker
|
|
4
|
+
python scripts/check_release.py --tag v0.1.0 # also: the tag matches the version
|
|
5
|
+
python scripts/check_release.py --dist dist # also: built files carry the README marker
|
|
6
|
+
|
|
7
|
+
Exits non-zero with one line per problem.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import argparse
|
|
13
|
+
import json
|
|
14
|
+
import re
|
|
15
|
+
import sys
|
|
16
|
+
import tarfile
|
|
17
|
+
import tomllib
|
|
18
|
+
import zipfile
|
|
19
|
+
from pathlib import Path
|
|
20
|
+
|
|
21
|
+
ROOT = Path(__file__).resolve().parent.parent
|
|
22
|
+
NAME = "io.github.sr-dash/heliofleet-mcp"
|
|
23
|
+
REPO = "https://github.com/sr-dash/heliofleet-mcp"
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def marker(name: str) -> re.Pattern:
|
|
27
|
+
# The registry requires a boundary after the name: whitespace, a tag or the comment close.
|
|
28
|
+
return re.compile(r"mcp-name:\s*" + re.escape(name) + r"(?=\s|<|-->|$)", re.M)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def main() -> int:
|
|
32
|
+
ap = argparse.ArgumentParser()
|
|
33
|
+
ap.add_argument("--tag")
|
|
34
|
+
ap.add_argument("--dist", type=Path)
|
|
35
|
+
a = ap.parse_args()
|
|
36
|
+
bad: list[str] = []
|
|
37
|
+
|
|
38
|
+
init = (ROOT / "src/heliofleet_mcp/__init__.py").read_text()
|
|
39
|
+
version = re.search(r'__version__ = "([^"]+)"', init).group(1)
|
|
40
|
+
if not re.fullmatch(r"\d+\.\d+\.\d+", version):
|
|
41
|
+
bad.append(f"__version__ {version!r} is not MAJOR.MINOR.PATCH")
|
|
42
|
+
project = tomllib.loads((ROOT / "pyproject.toml").read_text())["project"]
|
|
43
|
+
server = json.loads((ROOT / "server.json").read_text())
|
|
44
|
+
|
|
45
|
+
if server.get("name") != NAME:
|
|
46
|
+
bad.append(f"server.json name is {server.get('name')!r}, expected {NAME!r}")
|
|
47
|
+
if server.get("version") != version:
|
|
48
|
+
bad.append(f"server.json version {server.get('version')} != package {version}")
|
|
49
|
+
if len(server.get("description", "")) > 100:
|
|
50
|
+
bad.append("server.json description is longer than 100 characters")
|
|
51
|
+
if server.get("repository", {}).get("url") != REPO:
|
|
52
|
+
bad.append("server.json repository.url does not point at the GitHub repository")
|
|
53
|
+
pkgs = [p for p in server.get("packages", []) if p.get("registryType") == "pypi"]
|
|
54
|
+
if len(pkgs) != 1:
|
|
55
|
+
bad.append("server.json needs exactly one pypi package")
|
|
56
|
+
else:
|
|
57
|
+
p = pkgs[0]
|
|
58
|
+
if p.get("identifier") != project["name"]:
|
|
59
|
+
bad.append(f"package identifier {p.get('identifier')!r} != project name {project['name']!r}")
|
|
60
|
+
if p.get("version") != version:
|
|
61
|
+
bad.append(f"server.json package version {p.get('version')} != {version}")
|
|
62
|
+
if p.get("transport", {}).get("type") != "stdio":
|
|
63
|
+
bad.append("package transport must be stdio")
|
|
64
|
+
if "dynamic" not in project or "version" not in project["dynamic"]:
|
|
65
|
+
bad.append("pyproject.toml should take the version from heliofleet_mcp.__version__")
|
|
66
|
+
|
|
67
|
+
readme = (ROOT / "README.md").read_text()
|
|
68
|
+
if not marker(NAME).search(readme):
|
|
69
|
+
bad.append(f"README.md lacks the line 'mcp-name: {NAME}' (PyPI ownership check)")
|
|
70
|
+
if f"## {version} " not in (ROOT / "CHANGELOG.md").read_text():
|
|
71
|
+
bad.append(f"CHANGELOG.md has no '## {version} ' section")
|
|
72
|
+
|
|
73
|
+
if a.tag and a.tag.removeprefix("refs/tags/") != f"v{version}":
|
|
74
|
+
bad.append(f"tag {a.tag} != v{version}")
|
|
75
|
+
|
|
76
|
+
if a.dist:
|
|
77
|
+
files = sorted(a.dist.glob("*"))
|
|
78
|
+
wheel = [f for f in files if f.name == f"{project['name'].replace('-', '_')}-{version}-py3-none-any.whl"]
|
|
79
|
+
sdist = [f for f in files if f.name == f"{project['name'].replace('-', '_')}-{version}.tar.gz"]
|
|
80
|
+
if not wheel or not sdist:
|
|
81
|
+
bad.append(f"dist/ should hold the {version} wheel and sdist; found {[f.name for f in files]}")
|
|
82
|
+
for w in wheel:
|
|
83
|
+
with zipfile.ZipFile(w) as z:
|
|
84
|
+
meta = z.read(f"{project['name'].replace('-', '_')}-{version}.dist-info/METADATA").decode()
|
|
85
|
+
if not marker(NAME).search(meta):
|
|
86
|
+
bad.append(f"{w.name}: long description lacks the mcp-name marker")
|
|
87
|
+
for s in sdist:
|
|
88
|
+
with tarfile.open(s) as t:
|
|
89
|
+
names = t.getnames()
|
|
90
|
+
for need in ("README.md", "LICENSE", "pyproject.toml"):
|
|
91
|
+
if not any(n.endswith("/" + need) for n in names):
|
|
92
|
+
bad.append(f"{s.name} lacks {need}")
|
|
93
|
+
|
|
94
|
+
for b in bad:
|
|
95
|
+
print(f"FAIL {b}")
|
|
96
|
+
if not bad:
|
|
97
|
+
print(f"ok {NAME} {version}")
|
|
98
|
+
return 1 if bad else 0
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
if __name__ == "__main__":
|
|
102
|
+
sys.exit(main())
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Download a pinned mcp-publisher release and verify its Sigstore bundle before extracting it.
|
|
3
|
+
# Usage: scripts/get_mcp_publisher.sh [version] (needs curl and cosign)
|
|
4
|
+
set -euo pipefail
|
|
5
|
+
version="${1:-${MCP_PUBLISHER_VERSION:-v1.8.9}}"
|
|
6
|
+
os="$(uname -s | tr '[:upper:]' '[:lower:]')"
|
|
7
|
+
arch="$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')"
|
|
8
|
+
archive="mcp-publisher_${os}_${arch}.tar.gz"
|
|
9
|
+
base="https://github.com/modelcontextprotocol/registry/releases/download/${version}"
|
|
10
|
+
curl --fail --location --silent --show-error --output "$archive" "$base/$archive"
|
|
11
|
+
curl --fail --location --silent --show-error --output "$archive.sigstore.json" "$base/$archive.sigstore.json"
|
|
12
|
+
cosign verify-blob \
|
|
13
|
+
--bundle "$archive.sigstore.json" \
|
|
14
|
+
--certificate-identity "https://github.com/modelcontextprotocol/registry/.github/workflows/release.yml@refs/tags/${version}" \
|
|
15
|
+
--certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
|
|
16
|
+
"$archive"
|
|
17
|
+
tar xzf "$archive" mcp-publisher
|
|
18
|
+
rm -f "$archive" "$archive.sigstore.json"
|
|
19
|
+
./mcp-publisher --version || true
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
"""Start an installed server over stdio, list its tools and make one call.
|
|
2
|
+
|
|
3
|
+
Usage: python scripts/smoke_stdio.py /path/to/heliofleet-mcp (needs the mcp package)
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
import sys
|
|
7
|
+
|
|
8
|
+
import anyio
|
|
9
|
+
from mcp import ClientSession
|
|
10
|
+
from mcp.client.stdio import StdioServerParameters, stdio_client
|
|
11
|
+
|
|
12
|
+
EXPECTED = {"get_position", "get_fleet_state", "find_alignments", "list_upcoming_events",
|
|
13
|
+
"viewing_geometry", "heliofleet_link", "data_status",
|
|
14
|
+
"magnetic_connection", "space_weather", "coronal_field", "heliofield_link"}
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
async def run(cmd: str) -> None:
|
|
18
|
+
async with stdio_client(StdioServerParameters(command=cmd, args=sys.argv[2:])) as (r, w):
|
|
19
|
+
async with ClientSession(r, w) as s:
|
|
20
|
+
await s.initialize()
|
|
21
|
+
names = {t.name for t in (await s.list_tools()).tools}
|
|
22
|
+
missing = EXPECTED - names
|
|
23
|
+
if missing:
|
|
24
|
+
raise SystemExit(f"missing tools: {sorted(missing)}")
|
|
25
|
+
res = await s.call_tool("heliofleet_link", {"time": "2026-11-19T00:00Z"})
|
|
26
|
+
if getattr(res, "is_error", False) or getattr(res, "isError", False):
|
|
27
|
+
raise SystemExit(f"tool call failed: {res}")
|
|
28
|
+
print(f"ok: {len(names)} tools")
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
anyio.run(run, sys.argv[1])
|