Galaxy Morphology

一个用于星系形态学分析的 MCP (Model Context Protocol) 服务器，封装了 GALFIT 和 GalfitS 工具，支持单波段和多波段星系图像拟合与分析。同时提供基于 FastAPI + Celery 的 HTTP 服务接口，支持异步任务提交。

功能特性

核心工具

工具名称	功能描述	可用条件
run_galfit	执行 GALFIT 单波段拟合，返回优化的 FITS 文件、对比图像和拟合摘要	需设置 GALFIT_BIN
run_galfits	执行 GalfitS 多波段同时拟合，返回摘要文件、图像、SED 模型等结果	需设置 GALFITS_BIN
view_original_image	分析原始星系图像，提取形态分类和结构组件信息	要求提供2 panel图
component_analysis	分析拟合残差图像，诊断缺失或配置不当的物理组件（bulge、disk、bar、AGN 等）；多轮迭代中维护"最优轮次"登记并做轮间对比	始终可用

输出说明

GALFIT 输出：

• optimized_fits_file: 包含原始数据、模型和残差的 FITS 文件
• image_file: 2×3 科学对比图（行0：低/高动态范围原图 | 模型；行1：全场残差/σ | 残差放大 | 1D 表面亮度剖面）
• summary_file: Markdown 格式的拟合参数摘要

GalfitS 输出：

• summary_files: .gssummary 拟合摘要文件
• imagefit_pngs: 多波段图像拟合对比图
• sedmodel_pngs: SED (光谱能量分布) 模型图
• result_fits: 最佳拟合 FITS 结果文件

HTTP 服务接口

除 MCP 协议外，还提供基于 FastAPI + Celery 的 HTTP 服务，支持异步拟合任务提交：

• POST /api/fitting/ — 提交拟合任务（支持 image fitting / pure sed fitting / image sed fitting 三种模式）
• GET /api/fitting-status/{task_id} — 查询任务状态
• GET /health — MCP 服务健康检查
• GET /api/tools — 列出当前可用的 MCP 工具

安装

环境要求

• Python >= 3.10
• GALFIT（用于单波段拟合，可选）
• GalfitS（用于多波段拟合，可选）

通过 pip 安装

pip install -e .

Docker 部署

docker-compose up -d

服务包含两个容器：

• fastapi: Web 服务 (端口 8000)，负责任务提交和状态查询
• celery: 异步任务 Worker，执行后台拟合计算

配置

根据使用场景选择配置方式：

• 本地开发/直接运行：创建 .env 文件（参考 .env.example），服务启动时自动加载。
• MCP 客户端接入（如 Claude Code）：优先在 .mcp.json 的 env 字段中配置环境变量，无需 .env 文件。

# LLM API 配置（用于多模态分析）
OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=           # 可选，默认使用官方端点
OPENAI_MODEL=gemini-3-flash-preview  # 推荐 gemini-3-flash-preview（性价比高）

# 分析后端选择：vlm（默认）、cc 或 acp
# vlm: 使用 OpenAI 兼容 API 进行分析（需配置 OPENAI_*）
# cc:  使用 Claude Code Agent SDK 进行分析（需配置 CLAUDECODE_*）
# acp: 使用 Gemini CLI ACP 模式进行分析（默认使用本地已登录会话）
ANALYSIS_MODE=vlm

# Claude Code Agent SDK 配置（ANALYSIS_MODE=cc 时需要）
# cc 模式通过 claude-agent-sdk 调用 Anthropic API
# 如需使用非 Anthropic 模型（如第三方 LLM），可安装 Claude Code Router 作为本地代理：
# https://github.com/musistudio/claude-code-router
CLAUDECODE_API_KEY=your_anthropic_api_key_here
CLAUDECODE_BASE_URL=xxx
CLAUDECODE_MODEL=gemini-3-flash-preview 

# Gemini CLI ACP 模式配置 (ANALYSIS_MODE=acp 时)
# 默认使用本地通过 `gemini login` 建立的会话。
# 如在 CI 等无登录环境，可配置 GEMINI_API_KEY。
# GEMINI_API_KEY=your_google_api_key_here
# GEMINI_MODEL=gemini-2.0-flash

# GALFIT 配置
GALFIT_BIN=/path/to/galfit  # GALFIT 可执行文件路径

# GalfitS 配置
GALFITS_BIN=/path/to/galfits       # GalfitS 命令或 Python 模块路径
GS_DATA_PATH=/path/to/gs_data      # GalfitS 数据目录

# HTTP 服务（可选）
MCP_ALLOWED_HOSTS=*                # 允许的主机，默认允许所有

# visualRAG 残差检索增强（可选，仅 ANALYSIS_MODE=vlm 时生效）
# 留空 VISUALRAG_SERVICE_URL 即关闭（静默降级为无参考样例的单图分析）
VISUALRAG_SERVICE_URL=http://127.0.0.1:8765   # 检索服务地址；空 = 关闭（唯一真正的开启开关）
VISUALRAG_ENABLED=1                # kill-switch，仅 =0 关闭（判据 != "0"，故 =false/no/off 不生效，须写 0）
VISUALRAG_TOP_K=5                  # 每个 role（baseline/positive/hard_negative）检索返回上限
VISUALRAG_STRATEGY=both            # 检索策略：both = DINOv2 视觉嵌入 + 参数化特征双特征
VISUALRAG_MIN_SCORE=0.3            # 质量门：服务端丢弃 score < 该值的样例；留空 = 不传，用服务端默认（当前 0.3）

使用方法

启动 MCP 服务器

STDIO 模式（本地 MCP 客户端，如 Claude Code）：

python -m mcp_server --transport stdio

HTTP 模式（远程网络访问）：

python -m mcp_server --transport http --port 38507

支持的启动参数：

参数	说明	默认值
--transport, -t	传输模式：stdio 或 http	stdio
--host, -H	HTTP 监听地址	0.0.0.0
--port, -p	HTTP 监听端口	38507
--path, -P	MCP 协议路径	/mcp

配置 Claude Code

在项目的 .mcp.json 中添加：

{
  "mcpServers": {
    "galmcp": {
      "command": "python",
      "args": [
        "src/mcp_server.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "GALFIT_BIN": "/usr/bin/galfit",
        "GALFITS_BIN": "python /path/to/GalfitS/src/galfits/galfitS.py",
        "GS_DATA_PATH": "/path/to/GalfitS",
        "OPENAI_API_KEY": "your-apikey",
        "OPENAI_BASE_URL": "https://open.bigmodel.cn/api/coding/paas/v4",
        "OPENAI_MODEL": "glm-4.6v",
        "ANALYSIS_MODE": "vlm",
        "CLAUDECODE_API_KEY": "your-anthropic-apikey",
        "CLAUDECODE_BASE_URL": "",
        "CLAUDECODE_MODEL": "gemini-3-flash-preview"
      }
    }
  }
}

分析模式说明： ANALYSIS_MODE 控制残差分析（component_analysis）的后端：

• vlm（默认）：通过 OpenAI 兼容 API 调用多模态模型，需配置 OPENAI_API_KEY、OPENAI_BASE_URL、OPENAI_MODEL。
• cc：通过 Claude Code Agent SDK 调用 Anthropic API，需配置 CLAUDECODE_API_KEY。支持通过 Claude Code Router 代理到其他 LLM 提供商。
• acp：通过 Gemini CLI ACP 模式调用分析，默认使用 gemini login 后的本地会话。

visualRAG 检索增强（可选）

visualRAG 是一个在线残差检索服务，为 component_analysis 的 vlm 分析模式提供 Few-shot 参考样例。开启后，分析的第 1 轮（turn-1）会在目标星系图之前注入若干「参考样例图 + 专家图注」（按顺序：基线样例 / 困难反例 / 正样例），帮助多模态模型校准「视觉特征 → 诊断 → 处方」的判别规则；最后一张图仍是本轮待分析的目标星系。

仅在 ANALYSIS_MODE=vlm 时生效；cc / acp 模式不调用。客户端实现见 src/tools/visualrag_client.py。

触发与数据流

每次 component_analysis（vlm 模式）执行 turn-1 前，会调用 _maybe_fetch_reference_blocks：

1. 从 comparison PNG 路径反推 GALFIT archive 目录（以 galfit.[0-9]* 为标记）。
2. 收集本轮原料打成一个自包含 zip 上传（文件路径引用改写为 basename）：
   • feedme、模型输出 cube（*_galfit.fits）、mask、sigma、最新的 galfit.NN。
   • 不上传原始科学图像——服务端只依据模型 cube + mask + sigma + feedme 抽特征。
3. POST 到 {VISUALRAG_SERVICE_URL}/query，服务端用 DINOv2 视觉嵌入 + 主导成分参数化特征（Re / n / b/a / mag）做 FAISS 检索。
4. 返回 JSON，含 baseline（基线）、positive（正样例）、hard_negatives（困难反例）、perfect、query（查询特征）、warnings。
5. 按 Few-shot 顺序 [baseline → hard_negative → positive] 下载各样例对比 PNG 到临时文件，拼到 turn-1 图像序列最前面；分析结束后清理临时文件。

整个过程是 best-effort：服务关闭 / 不可用 / 返回空 → 静默降级为普通单图 turn-1（无参考样例），不影响分析流程。

环境变量

变量	默认值	说明
VISUALRAG_SERVICE_URL	""（空）	检索服务地址（如 http://127.0.0.1:8765）。空 = 检索关闭，是唯一真正的开启开关。
VISUALRAG_ENABLED	"1"	显式 kill-switch。仅 =0 关闭；判据是 != "0"，故 =false/=no/=off 不会关闭（须写 0）。
VISUALRAG_TOP_K	5	每个 role 检索返回上限。
VISUALRAG_STRATEGY	both	检索策略：both = 视觉 + 参数化双特征。
VISUALRAG_MIN_SCORE	空（用 server 默认 0.3）	检索质量下限：服务端丢弃 score < min_score 的样例（被丢弃的正样例会连带丢掉它的 hard-neg）。留空 = 不传该字段，由服务端 config 默认决定（当前 0.3）。

配置方式与其它变量一致（.env 或 .mcp.json 的 env 字段）。注意 query_service 对 top_k/strategy 的回退顺序是「显式参数 → 环境变量 → 默认值」，且用 or 判断，因此传 0/空串会被当成未传而回退到默认值。min_score 不同：用 is None 判断，空串/未设 = 不传该字段（服务端走其默认 0.3），而显式 0 会被如实发送（含义为「丢弃负分样例」）。服务端库规模、模型、当前 min_score 默认等可通过 GET {VISUALRAG_SERVICE_URL}/health 查看。

最优轮次登记与轮间对比（best-round registry）

component_analysis 在多轮迭代拟合中会维护一个最优轮次登记表（src/tools/best_round_registry.py），按星系主目录索引，记录当前星系的历史最优轮次及其成分参数、卡方、component_analysis 结论。

• 每轮分析前，若存在历史最优且与当前轮不同，会自动生成一份轮间对比（run_round_comparison）：把历史最优轮与当前轮的对比图交给多模态模型判定 CURRENT_BETTER / HISTORICAL_BETTER / EQUAL；判定退步（HISTORICAL_BETTER）时额外输出结构化字段 regression_focus / salvage / direction(REVERT|AUGMENT)，指明下一轮应回到历史最优轮起点重拟（REVERT），还是在当前方向上补全缺失要素（AUGMENT）。
• 退步结论作为软参考注入 component_analysis 的参数审查阶段（turn-2），不干预 turn-1 的视觉特征提取。
• 登记状态默认持久化到星系主目录下的 .best_round.json（已加入 .gitignore），便于跨会话恢复；设置环境变量 BEST_ROUND_PERSIST=0 可关闭，退化为纯内存登记。

落锁前强制审计（best-round-verifier）

正式锁定"最优轮次"之前，工作流（workflow_galfit / workflow_galfits）的阶段三会调用只读 subagent best-round-verifier（定义见 .claude/agents/best-round-verifier.md），对候选轮按成分 / 拟合 / 物理 / 参数 / 校验 / 指标六个维度做独立、机械、可追溯的审计，返回 PASS | FAIL：

• FAIL → 严禁落锁，按"阻断性问题"清单修复后重拟、复审至 PASS；
• PASS（含 WARN）→ 方可落锁。

审计细则与工作流约束详见 AGENTS.md。

项目结构

src/
├── mcp_server.py          # MCP 服务主入口，工具注册与传输配置
├── tools/
│   ├── run_galfit.py      # GALFIT 单波段拟合执行
│   ├── run_galfits.py     # GalfitS 多波段拟合执行
│   ├── analyze_image.py   # VLM 多模态分析（GALFIT/GalfitS 结果）
│   ├── view_original_image.py  # 原始星系图像形态分类
│   ├── component_analysis.py   # 残差分析与组件诊断
│   ├── best_round_registry.py  # 最优轮次登记与轮间对比（持久化 .best_round.json）
│   ├── visualrag_client.py     # visualRAG Few-shot 检索客户端（vlm 模式）
│   ├── modify_feedme.py   # GALFIT feedme 配置文件修改
│   ├── extract_summary_galfit.py  # GALFIT 参数摘要提取
│   ├── pix2radec.py       # 像素坐标转赤经赤纬
│   ├── read_fits.py       # FITS 文件读取工具
│   ├── multi_thresh_plot.py  # 多阈值可视化
│   └── prompt.py          # 工作流 Prompt 定义
├── service/
│   ├── main.py            # FastAPI 应用，HTTP 任务提交接口
│   ├── tasks.py           # Celery 异步任务定义
│   └── file_manager.py    # 文件与工作空间管理
├── llms/
│   ├── base.py            # LLM 客户端基类
│   ├── openai_llm.py      # OpenAI API 客户端
│   └── glm_llm.py         # 智谱 GLM API 客户端
└── prompts/               # Prompt 模板（分类、分析、工作流）

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！