Gesicherter Fork von @pardovot/pixinsight-mcp 0.9.1 – MCP-Server, der KI-Assistenten mit PixInsight verbindet (MIT). Preserved fork, see FORK.md.
  • JavaScript 57.4%
  • TypeScript 26.4%
  • C++ 14.5%
  • CMake 1.4%
  • C 0.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
MarcusL1979 4ccb046d3c
Some checks failed
CI / test (macos-latest) (push) Has been cancelled
CI / test (ubuntu-latest) (push) Has been cancelled
CI / test (windows-latest) (push) Has been cancelled
PixInsight 1.9.5: lokale Signier-Identität richtig anmelden, Modulstart verifiziert
Der Wegwerf-Schlüssel aus dem vorigen Commit wurde abgelehnt, weil er nie als
lokale Identität registriert war. FORK.md beschreibt jetzt den Weg über
SigningKeys, Edit > Local Signing Identity und CodeSign.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 14:02:06 +01:00
.claude/skills/process-v2 Pick the variant axis from the library, always emit grading stubs 2026-07-30 03:14:07 +03:00
.github/workflows Restore state dc2eacb (2026-08-18), last working combination with module 1.3.x 2026-11-15 11:06:04 +01:00
data Record the M106 run 1 grades, track the run provenance 2026-07-30 03:03:25 +03:00
docs PixInsight 1.9.5: lokale Signier-Identität richtig anmelden, Modulstart verifiziert 2026-11-15 14:02:06 +01:00
module Restore state dc2eacb (2026-08-18), last working combination with module 1.3.x 2026-11-15 11:06:04 +01:00
pjsr Multi instance bridge isolation with heartbeat auto detection 2026-07-26 21:38:13 +03:00
recipes Make the macOS dev setup work end to end (#6) 2026-08-11 23:51:53 +03:00
references Record the M106 run 1 grades, track the run provenance 2026-07-30 03:03:25 +03:00
scripts Restore state dc2eacb (2026-08-18), last working combination with module 1.3.x 2026-11-15 11:06:04 +01:00
src Drop config fields nothing reads 2026-08-11 17:06:07 +03:00
test Test what the update repository actually declares 2026-08-11 14:38:57 +03:00
vendor Fork: Hinweis, Doku, gesicherte Original-Binärdateien 2026-11-15 11:06:05 +01:00
.gitattributes Sign updates.xri in Node, pinned to PixInsight fixtures 2026-08-10 22:38:04 +03:00
.gitignore Document installing on any MCP client, not just Claude 2026-08-11 12:37:09 +03:00
CLAUDE.md Restore state dc2eacb (2026-08-18), last working combination with module 1.3.x 2026-11-15 11:06:04 +01:00
FORK.md PixInsight 1.9.5: lokale Signier-Identität richtig anmelden, Modulstart verifiziert 2026-11-15 14:02:06 +01:00
LICENSE Update project identity and authorship 2026-07-25 01:58:17 +03:00
package-lock.json Fork: Hinweis, Doku, gesicherte Original-Binärdateien 2026-11-15 11:06:05 +01:00
package.json Fork: Hinweis, Doku, gesicherte Original-Binärdateien 2026-11-15 11:06:05 +01:00
README.md Fork: Hinweis, Doku, gesicherte Original-Binärdateien 2026-11-15 11:06:05 +01:00
tsconfig.json Implement MCP server, PJSR watcher, and HaRGB processing pipeline 2026-02-10 05:57:18 +01:00

PixInsight MCP

Fork notice: this is a preserved fork of @pardovot/pixinsight-mcp 0.9.1. Upstream removed its PixInsight update repository and rewrote its history. See FORK.md for why, what is kept, and how to restore the signed module.

An MCP server that lets an AI assistant drive PixInsight: open images, measure them, run any installed process, read the results back. PixInsight stays responsive while it works, so you can watch and intervene.

Cross-platform: Windows, macOS and Linux.

Install

1. MCP server. Any MCP client works. This is a stock stdio server with no client-specific code.

Claude Code:

claude mcp add pixinsight -- npx -y @pardovot/pixinsight-mcp

Claude Desktop, Cursor, Windsurf and anything else that takes an mcp.json:

{
  "mcpServers": {
    "pixinsight": { "command": "npx", "args": ["-y", "@pardovot/pixinsight-mcp"] }
  }
}

Codex CLI, in ~/.codex/config.toml:

[mcp_servers.pixinsight]
command = "npx"
args = ["-y", "@pardovot/pixinsight-mcp"]

On Windows, if a client cannot resolve npx, use "command": "cmd" with "args": ["/c", "npx", "-y", "@pardovot/pixinsight-mcp"].

2. PixInsight module. Resources > Updates > Manage Repositories, add:

https://raw.githubusercontent.com/pardovot/pixinsight-mcp/dist/

Then Resources > Updates > Check for Updates and restart. Signed with a Certified PixInsight Developer identity, so the dialog shows Verified. Certified developer: OfirPardo.

3. Start it. Process > Utilities > MCP Watcher > Start, then ask your assistant to list your open images. If it answers, you are connected.

Requires PixInsight 1.9.4+ (V8 engine), Node 18+, and an MCP client.

Tools

24 tools. Bold ones carry the work.

Category Tools
Execution run_process, get_process_parameters, run_script
Images list_open_images, open_image, save_image, close_image, get_image_statistics
Measurement get_noise, get_background_gradient, get_background_neutrality, get_star_metrics, get_structure_color
Rendering render_view, render_critic_pack
History get_history, get_full_history, undo, redo, snapshot, restore
Instances list_instances, use_instance
Export export_container

run_process runs any process by class name, including third-party ones you have installed, so nothing needs adding when you install a new tool.

Measurement tools exist so settings come from your frame instead of a tutorial. Two traps: get_noise returns an MRS estimate, stdDev is signal-dominated on astro frames and will lie to you. get_background_neutrality needs mode:'poststretch' after stretching, the sky-band metric is only valid pre-curve.

Definitions live in src/tools/*.ts. Verified gotchas: docs/facts.md.

How it works

  MCP client
    │  MCP (stdio)
  MCP server                    src/ (TypeScript)
    │  file bridge              ~/.pixinsight-mcp/bridge/{commands,results}
  MCPWatcher-pxm.dll            pcl::Timer on PixInsight's event loop
    │  MetaModule::EvaluateScript
  Embedded JS handlers          generated from pjsr/pixinsight-mcp-watcher.js
  PixInsight

PixInsight has no socket or HTTP API, so a file bridge is the only route in. Round trip is about one poll interval, 300 ms by default.

The runtime is a compiled module rather than a PJSR script because a running script holds PixInsight's only thread, which blocks the interface until it returns. The module's timer fires on the event loop instead, which is why the application stays usable while a run is in progress.

Anything that can write to ~/.pixinsight-mcp/bridge/commands can run arbitrary code inside PixInsight. Keep the directory user-private, never on a shared or synced path.

Platform

Module installed as
Windows bin/MCPWatcher-pxm.dll
macOS MacOS/MCPWatcher-pxm.dylib, universal x86_64 + arm64
Linux bin/MCPWatcher-pxm.so

All three build in CI on every change and ship in every release. Nothing in the design is platform-specific: Node server, file bridge, PJSR handlers, CMake build with per-platform branches.

Building from source

Needs Node 18+, a C++ toolchain and CMake:

Toolchain
Windows Visual Studio 2022 or Build Tools, with the C++ workload (found via vswhere)
macOS Xcode Command Line Tools, plus brew install cmake ninja
Linux build-essential cmake ninja-build
npm run module:pcl       # once, builds PCL from PixInsight's bundled source
npm run module:build     # regenerate handlers, compile
npm run module:sign      # needs your own signing identity, see docs/SIGNING.md
npm run module:install   # admin/root, PixInsight closed

node module/config.mjs prints every path resolved on your machine, start there when a build cannot find something. install.mjs copies the module and its .xsgn, and refuses a signature older than the binary.

PixInsight's bundled makefiles compile in-tree, so on a read-only install (/opt/PixInsight is root-owned) module:pcl mirrors the ~20 MB source tree into $PCL_BUILD_OUT/src and builds the copy. The install directory is never written to except by module:install.

Full local setup per platform: docs/dev-setup.md.

Handler logic lives in pjsr/pixinsight-mcp-watcher.js only. module/src/BridgeHandlersJS.h is generated from it, never edit it by hand.

Configuration

Every path is a default an environment variable overrides, derived rather than hardcoded, so a stock install needs nothing.

Variable Default Purpose
PIXINSIGHT_EXE probed PixInsight executable, for the build scripts
PIXINSIGHT_MCP_TIMEOUT_MS 300000 per-command timeout
PIXINSIGHT_MCP_EXTENDED_TIMEOUT_MS 3600000 long operations
PIXINSIGHT_MCP_POLL_INTERVAL_MS 200 bridge poll cadence
PI_ROOT probed install root, build scripts derive the rest
PCL_BUILD_OUT ~/pcl-build where the PCL library and its source mirror land
PI_SIGN_KEY, PI_SIGN_DEVELOPER_ID none signing, how CI supplies it
PI_SIGN_KEY_FILE ~/.pixinsight-mcp/signing-key.json exported key for local signing

PI_ROOT is probed per platform: %ProgramFiles%\PixInsight, /Applications/PixInsight, /opt/PixInsight. Everything else derives from it, so overriding one variable relocates the rest.

PI_ROOT=/opt/PixInsight-1.9.5 node module/build.mjs

Signing

PixInsight refuses unsigned modules by default. Modules and the repository index are both signed, in Node, with no PixInsight involved, which is why CI can publish a signed release from a runner that has none installed. PixInsight is needed once, to export the key.

Both constructions and the security caveats: docs/SIGNING.md. Release process: docs/RELEASING.md.

Layout

src/                MCP server: tools/, pjsr/, bridge/
module/             native module (the runtime), build/sign/install tooling
pjsr/               JS watcher, source of truth for handler logic
docs/               SIGNING, RELEASING, bridge-protocol, facts, architecture
scripts/            ping-watcher, build-pi-repo
test/               node --test suites

Origins

Began in 2026 as a fork of aescaffre/pixinsight-mcp, independent codebase since. The file bridge and the PJSR handler bodies come from there. The native module, the generic process runner, the measurement layer, signing and the update repository were added here.

Credits

  • Alain Escaffre (@aescaffre), originator of the project this one grew from: the file bridge, the agentic architecture, and the PJSR watcher whose handler logic still runs here. Developed as a member of Astro ARO, a remote observatory in the Alentejo Dark Sky Reserve (Portugal), Bortle 2-3.
  • Andre Couto (@4ndr3c0ut0), V8 runtime port of the watcher for PixInsight 1.9.4+ "Lockhart" (PR #1 on the original repository).
  • pardovot, native module, generic process runner, measurement and knowledge layer, signing and release pipeline, packaging.

License

MIT © Alain Escaffre (original work) and pardovot. See LICENSE.