# WinJUPOS MCP

A local MCP server for **Windows + WinJUPOS 12.4.1**. It gives Codex, ChatGPT Desktop, and other MCP-compatible clients a guarded workflow for Jupiter image measurement, image de-rotation, and moon-trail repair.

> This project is currently Alpha software. GUI automation depends on the window structure of WinJUPOS 12.4.1. Always review the state before and after F11/F12 operations.

English (current) | [简体中文](README.zh-CN.md) | [Contributing guide in Chinese](CONTRIBUTING.md)

## Features

- Inspect the WinJUPOS installation, version, process state, active body, and open modules.
- Calculate central meridians and altitude through the native WinJUPOS command-line interface.
- Open image measurement, image de-rotation, ephemerides, and other supported modules.
- Set UTC timestamps for Jupiter measurements, run an initial F11 outline fit, and normalize north/south orientation.
- Save new `.ims` measurement files and `.icm` de-rotation recipes.
- Load multiple `.ims` files, configure per-frame LD values, and run guarded F12 compilation to 48-bit PNG.
- Repair moons and moon shadows stretched by a long de-rotation span while retaining real single-frame detail and 16-bit RGB output.
- Capture a selected WinJUPOS window for visual review.
- List and inspect supported WinJUPOS settings files without modifying them.

The server currently registers 22 MCP tools. Call `list_modules` to discover the stable module keys.

## Requirements

- Windows 10 or 11
- Python 3.11
- WinJUPOS 12.4.1 (default path: `D:\WinJUPOS 12.4.1\WinJUPOS.x64.exe`)

## Installation

```powershell
git clone https://github.com/nuan-xing/winjupos-mcp.git
cd winjupos-mcp
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e .
```

Start the STDIO server manually:

```powershell
.\run_server.cmd
```

An STDIO MCP server does not display a normal interactive prompt after it starts. This is expected.

## MCP configuration example

The following example targets Codex `config.toml`. Replace the repository and allowed astronomy-data directories with paths from your own machine:

```toml
[mcp_servers.winjupos]
command = 'C:\path\to\winjupos-mcp\run_server.cmd'

[mcp_servers.winjupos.env]
WINJUPOS_EXE = 'D:\WinJUPOS 12.4.1\WinJUPOS.x64.exe'
WINJUPOS_ALLOWED_ROOTS = 'D:\Astro;D:\WinJUPOS 12.4.1;C:\path\to\winjupos-mcp'
WINJUPOS_ARTIFACTS_DIR = 'C:\path\to\winjupos-mcp\artifacts'
```

Separate multiple allowed roots with semicolons. Restart the MCP client after changing its configuration.

### Environment variables

| Variable | Purpose |
| --- | --- |
| `WINJUPOS_EXE` | Path to the WinJUPOS x64 executable |
| `WINJUPOS_ALLOWED_ROOTS` | Semicolon-separated local roots that the MCP may read or write |
| `WINJUPOS_ARTIFACTS_DIR` | Destination for bounded window screenshots |
| `WINJUPOS_MAX_ARTIFACTS` | Number of recent screenshots to retain; defaults to 50 |

## Recommended image de-rotation workflow

1. Call `set_planet("jupiter")`.
2. Open a source image with `open_image_for_measurement(...)`.
3. Call `configure_image_measurement(...)`, `auto_align_jupiter()`, and `ensure_jupiter_north_up()`.
4. Use `capture_window("image_measurement")` to review the outline, timestamp, central meridians, and orientation.
5. Save a new `.ims` with `save_image_measurement(...)`, then repeat for every frame.
6. Open `derotation_images`, then call `add_derotation_measurements(...)`, `set_derotation_ld_values(...)`, and `configure_derotation_output(...)`.
7. Use `capture_window("derotation_images")` to review frame order, reference time, LD, orientation, and output settings.
8. Save an `.icm` with `save_derotation_settings(...)`, then call `execute_image_derotation(...)`.
9. If a moon or its shadow is stretched, call `repair_derotation_satellites(...)` to create a separate repaired PNG.

## Moon and moon-shadow repair

WinJUPOS planet-surface de-rotation does not track fast-moving satellites. `repair_derotation_satellites` first suppresses the complete motion trail, then moves high-frequency information from the real source frame nearest the reference time to the interpolated target position. It does not use generative image editing and does not average the already deformed satellite back into the result.

Each item in `feature_tracks` represents one moon or shadow:

```json
{
  "name": "moon_shadow",
  "centers": [[232, 312], [241, 312], [251, 311], [254, 311]],
  "radius_x": 10.5,
  "radius_y": 8.5
}
```

- `centers` must map one-to-one to time-ordered `source_paths`.
- Every timestamp must include `Z` or an explicit UTC offset.
- The tool linearly interpolates the target position between adjacent frames by default.
- If the output has an additional translation, use `target_center: [x, y]` to override the interpolated coordinate.
- Source frames and the de-rotated image must have identical dimensions.
- The output must be a new PNG path. Inputs are never overwritten.

## Safety boundaries

- Every path must be inside `WINJUPOS_ALLOWED_ROOTS`.
- GUI operations share a process-level lock to avoid concurrent changes to stateful WinJUPOS windows.
- The server does not expose arbitrary mouse, keyboard, command-execution, or WinJUPOS macro tools.
- It does not fabricate or rewrite proprietary `.ims/.icm/.ics/.drs/.wjm` binary content; WinJUPOS remains the writer.
- F11 is only a starting fit and never replaces visual outline/grid verification.
- F12 is exposed only through a high-level guarded tool and refuses to overwrite existing output.
- `artifacts/`, `jobs/`, virtual environments, caches, and user images are excluded from Git by default.

## Testing

Run unit tests that do not require a live WinJUPOS GUI:

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -p "test_*.py" -v
```

When WinJUPOS is installed locally, run the STDIO smoke test:

```powershell
.\.venv\Scripts\python.exe .\tests\smoke_stdio.py
```

`smoke_gui_stdio.py` opens and controls real WinJUPOS windows. Run it only when there is no unsaved WinJUPOS work.

## Contributing

This is a public repository, so anyone may fork it and submit a Pull Request. For long-term co-maintainers, the repository owner may invite selected GitHub accounts under **Settings → Collaborators**. See the [Chinese contribution guide](CONTRIBUTING.md) for branch, test, privacy, and safety requirements.

## Current limitations

- Only WinJUPOS 12.4.1 x64 has been verified.
- GUI labels and window classes may change between WinJUPOS releases.
- Satellite repair currently requires a center coordinate from each source frame. It automates time interpolation and compositing, but does not automatically detect every satellite.
- Guarded image de-rotation currently targets PNG. This project does not parse or rewrite WinJUPOS proprietary settings formats.