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) | 简体中文 | Contributing guide in Chinese

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

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:

.\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:

[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:

{
  "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:

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

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

.\.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 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.