PixInsight Connector

PixInsight Connector

一个 MCP 连接器，让任何 AI Agent 都能操作 PixInsight：提供约 80 个 PixInsight 操作作为工具，供聊天会话及其引导技能使用。初次使用？请从快速入门开始。

社区项目，与 Pleiades Astrophoto 无关，也未获得其认可。PixInsight® 是 Pleiades Astrophoto S.L. 的注册商标。

原则：工具箱，而非流水线

连接器只知道如何操作 PixInsight，绝不判断什么是好照片。没有流水线、顺序、推荐值或评判：每个工具都将影响图像的值作为输入，每项测量都返回数字。知识（用哪些工具、按什么顺序、使用哪些值、怎样才算足够好）存放在技能中：即你自己仓库里的 Markdown 文件，可公开或私有。

%%{init: {'theme': 'base', 'flowchart': {'wrappingWidth': 400, 'curve': 'basis', 'padding': 18}, 'themeVariables': {'fontFamily': "-apple-system, BlinkMacSystemFont, 'Segoe UI', Inter, Helvetica, Arial, sans-serif", 'lineColor': '#94a3b8', 'textColor': '#334155', 'edgeLabelBackground': '#e2e8f0'}}}%%
flowchart TB
    classDef know fill:#0f766e,stroke:#115e59,color:#f0fdfa,stroke-width:1px,rx:12,ry:12
    classDef harness fill:#475569,stroke:#334155,color:#f8fafc,stroke-width:1px,rx:12,ry:12
    classDef tool fill:#1e293b,stroke:#64748b,color:#f8fafc,stroke-width:1px,rx:12,ry:12
    classDef app fill:#e2e8f0,stroke:#94a3b8,color:#0f172a,stroke-width:1px
    You(["You, in a chat session"]):::know
    Skills("<b>The knowledge · yours</b><br/>your skills: order, values, quality gates<br/>kept in your own repositories"):::know
    Harness("<b>Any MCP agent harness</b><br/>Claude Code · Codex · Cursor · Gemini CLI · …"):::harness
    Tools("<b>The toolbox · this connector</b><br/>~80 PixInsight operations as MCP tools<br/>measurements return numbers, never verdicts"):::tool
    Bridge("<b>File bridge + watcher script</b><br/>starts PixInsight on the first call"):::tool
    PI(["PixInsight 1.9.5+"]):::app
    You --> Harness
    Skills -. guides .-> Harness
    Harness -- MCP tool calls --> Tools
    Tools --> Bridge
    Bridge <--> PI
    linkStyle default stroke:#8b949e,stroke-width:1.5px

安装

需要 Node 22+ 和 PixInsight 1.9.5+。无论由你还是 Agent 执行，都只需相同的三个步骤。

1. 安装连接器，从 npm 安装：

npm install -g pixinsight-connector

2. 注册连接器，将其作为 MCP 服务 pixinsight 添加到你的 Agent 宿主中。Claude Code：

claude mcp add -s user pixinsight -- pixinsight-connector

任何通过 mcpServers JSON 文件配置的宿主（Cursor、Windsurf、Gemini CLI、Claude Desktop、Cline、Kiro）：

{ "mcpServers": { "pixinsight": { "command": "pixinsight-connector" } } }

Codex、OpenCode、VS Code 和 Zed 使用其他配置格式；各自的格式及配置文件位置见：docs/setup.md。

3. 检查机器：

pixinsight-connector doctor

PixInsight 和其监视脚本会在首次调用工具时启动；无需启动其他程序。使用 npm install -g pixinsight-connector@latest 升级。无需安装时，也可以将 npx -y pixinsight-connector 注册为命令（npx 会从 npm 获取，因此首次启动需要网络）。从 pixinsight-mcp 1.x 迁移：将你的 pixinsight 条目指向 pixinsight-connector（而非另一个服务），并执行 npm uninstall -g pixinsight-mcp。

文件存放位置

这些工具在目标文件夹中工作：该文件夹由 set_workspace 指定；若未指定，则使用 PIXINSIGHT_CONNECTOR_WORKSPACE；若仍未设置，则使用宿主启动时所在的文件夹。连接器只会写入 <target>/agentic/（临时文件、桥接程序、调用日志）和 <target>/output/，不会写入你的主目录。详情及所有环境变量见：docs/setup.md。

工具、工具包与技能

• **工具：**78 个，分为图像、处理、通道、色调、细节、蒙版、恒星、窄带、天体测量、测量、预览、PJSR 执行、内省和会话。完整列表：docs/tools.md。
• 技能承载技术方法。配套技能（环境预检、数据集导入、基础 LRGB 流程）：pixinsight-connector-skills。
• 工具包是 ES 模块，可在启动时添加或替换工具，并在 PIXINSIGHT_CONNECTOR_PACKS 中列出。工具包可运行具有你权限的任意代码；只会加载你配置的工具包。参见 CONTRIBUTING.md。
• **模型：**任何具备视觉能力且能可靠调用工具的模型。可先从 Sonnet 级别的模型开始（Claude Sonnet 5、GPT-6 Sol、Gemini 3.8 Flash），再尝试成本更低的模型（GPT-6 Luna、GLM-5.3-Flash、DeepSeek V4.1 Flash）：价格和列表见 docs/setup.md。

贡献

尚无工具支持的 PixInsight 功能，只需在 src/tools/ 中新增一个模块，无需注册表：CONTRIBUTING.md。 欢迎人类和 Agent 参与；运行 npm test 无需 PixInsight。

跨平台

macOS、Windows 和 Linux 都是一等支持平台，既可运行此连接器，也可用于开发。 在一个操作系统上可用、却在另一个操作系统上出问题的更改属于 bug，而非限制。

• 不使用 Shell 管道。 不得在 src/ 或 npm 脚本中使用 ps、grep、awk、wc、df 或 &&。 特定操作系统的行为应放在 src/platform.mjs（路径）或 src/process-probe.mjs（进程检查）中，每个操作系统各自实现。
• 不使用 POSIX 路径字面量。 使用 path.join。只有在向 PixInsight 传递路径时才使用正斜杠，因为 PixInsight 在任何平台上都接受这种格式。
• CI 会在 Linux、macOS 和 Windows 上运行完整测试套件。 在一个平台上通过，不代表全部通过。
• 尽可能降级，绝不失败。 如果某个操作系统无法提供可选信息，例如内存读数或进程启动时间，就继续运行。绝不能将此报告为崩溃。
• 覆盖设置始终优先： 可执行文件使用 PIXINSIGHT_BIN，安装根目录使用 PIXINSIGHT_DIR。

测试无需 PixInsight 或任何天文软件，因此你可以在这三种操作系统中的任意一种上进行开发。

故障排除

首先运行 pixinsight-connector doctor。常见症状及解决方法：docs/troubleshooting.md。

致谢与许可证

本项目最初由 Alain Escaffre 创建，源自 aescaffre/pixinsight-mcp； 原始文件桥接和监视脚本的部分内容仍保留在项目中。采用 MIT 许可证：请参阅 LICENSE。