# mcp-dm

**让 AI 帮你使用 DigitalMicrograph，少点重复的 GUI，少做手动的数据搬运。**

[English](README.en.md) · [Agent 安装与使用指南](README.agent.md) · [完整技术参考](REFERENCE.md) · [开发者说明](AGENTS.md)

平时在 DM 里看图、裁剪、做 FFT；遇到更复杂的分析，再把数据导出到 Python。`mcp-dm` 就是为这样的工作方式做的。

它把本机的 Gatan DigitalMicrograph（DM）连接到支持 MCP 的 AI 助手，让助手通过明确的工具读取图像信息、执行已支持的操作、取得带标定的结果。你继续使用熟悉的 DM，不必为了每一次重复操作在它的脚本编辑器里手写程序。

**它不是另一个聊天软件，也不是一个替你决定科学结论的图像分析模型。它是让 Agent 使用 DM 的接口。**

## 可以拿它做什么？

安装并连接后，可以从一个具体任务开始。以下示例面向主线默认的 Python 后端；实验性 C++ 后端的能力不同，见下文。

| 你想做的事 | 可以这样告诉助手 |
|---|---|
| 了解当前数据 | “看看 DM 里打开了哪些图，列出尺寸、数据类型和标定，先别改任何东西。” |
| 比较几个区域 | “对我指定的两个区域分别做强度统计，保留选区坐标和结果。” |
| 测量剖面或周期 | “沿这两个点取剖面，再检查这个区域的 FFT；标定不完整的地方请说明。” |
| 检查选区 | “先给我预览，并标出准备分析的区域，我确认后再继续。” |
| 交给外部分析 | “把这个区域导出为保留原始数值和标定的数据，再在独立目录里做拟合。不要修改源图。” |

最后一个例子需要 Agent 自身具有文件和代码执行能力：**MCP 负责数据交接，外部脚本负责额外计算，两者的来源应明确区分。** 它不是一个已经内置的自动拟合工具。

FFT 的频率峰也不是自动确认的晶面或物相。预览是否能被模型直接看到，取决于客户端；生成 PNG 不等于模型已经看见了图。

## 不换掉你的工作方式，只减少中间步骤

你仍然可以在 DM 中手动观察和选择区域，把重复测量、裁剪、结果整理交给 Agent。需要其它科学库时，再显式导出数据继续处理。

```text
你提出任务 → Agent 调用 MCP → DM 中的数据与已支持的处理
                              ↓
                    带数值、坐标和标定的结果
                              ↓
                 继续查看，或交给外部 Python 分析
```

不要求每个任务都生成报告，也不要求把所有算法塞进插件。报告与复跑是可选工作流。当前数据交接以读取、捕获和导出为主；外部结果自动回传 DM 并不是已完成的通用能力。

我们优先保证的是：处理的是你指定的图、选区没有被偷偷改变、单位没有丢失、失败不会被说成成功。

## 现在能用到哪一步？

| 路径 | 当前范围 | 使用前要知道 |
|---|---|---|
| **主线默认：v0.6 Python 后端** | 图像与元数据读取、二维统计、剖面、FFT 摘要、裁剪、科学数据导出，以及可选的捕获与预览 | 通过 DM 内嵌 Python 连接；部分数值计算使用 NumPy。预览需要独立环境，详见安装指南。 |
| **主线可选：原生 C++ 实验后端** | 14 个工具：原生摘要、裁剪、有限算术/FFT/滤波、PNG 预览、可见文档和有界数值交接 | 仅限 Windows x64 GMS **3.53.4137.0** 的精确指纹与各操作已验证的类型/尺寸。NPY 交接不等于 DM 原生文件保存；详见[原生工作流](experiments/native-bridge/mvp/NATIVE_WORKFLOW.md)。 |
| **下一阶段** | GUI 选区、原生剖面/直方图、分块交接和结果释放 | 见[官方功能对照与优先级](docs/NATIVE_NEXT_STAGE.md)；未实现的项目不是当前能力。 |

**第一次试用，先用主线默认后端。** 原生版本请单独阅读[实验说明与版本限制](experiments/native-bridge/mvp/README.md)，不要直接在未知 GMS 版本上使用。

现有谱学和 4D-STEM 接口仍保留，但支持的数据布局有限；真实 EDS/EELS 定量、通用 4D 数据兼容和重构不属于本项目已验证的承诺。先用小型合成数据检查自己的环境，再处理实验数据。

## 怎么开始？

你需要 **Windows x64、已启用内嵌 Python 的 DigitalMicrograph/GMS、Node.js 18 或更新版本**，以及一个支持 MCP 的 Agent 客户端。使用 Agent 不等于必须更换 DM，也不需要为本项目单独注册账号。

### 让 Agent 帮你安装

把仓库地址和这句话交给具有本机操作权限的 Agent：

> 请按 https://github.com/wuchqwq/mcp-dm 中的 README.agent.md 帮我安装并连接默认 DigitalMicrograph MCP。先检查环境和现有配置，不覆盖其它 MCP、不升级 GMS 的 Python。连接后确认是真实 DM，并列出当前图像；不要修改实验数据。

安装仍可能需要你确认环境或完成客户端操作，不是所有客户端都能自动安装。

### 自己安装

先取得代码，在仓库根目录启动默认桥：

```powershell
git clone https://github.com/wuchqwq/mcp-dm.git
Set-Location .\mcp-dm
powershell -NoProfile -ExecutionPolicy Bypass -File .\setup\start_bridge.ps1
```

Node 服务没有 npm 运行依赖。随后按 [MCP 配置示例](mcp.json.example)填写仓库绝对路径，并在自己的客户端注册服务。完整的环境检查、Codex 注册、停止方式和故障排查见 [Agent 安装与使用指南](README.agent.md)及[技术参考](REFERENCE.md)。

**默认 Python 后端需要图像预览时**，另外创建外部 Python 环境，安装 [requirements-preview.txt](requirements-preview.txt) 并配置它的解释器路径；不要安装进 GMS 管理的环境。只做基本读取和测量不需要这一步。

第一次连接可以说：“确认连接的是真实 DM，然后只列出图像和标定。”配置成功、发现工具和实际执行成功是三件不同的事。

## 用之前，请留意这几件事

**保护原数据。** 从副本或合成数据开始，明确图像和选区，导出到新路径。图像 ID 固定的是对象，不会冻结它的像素；处理期间不要同时编辑源图。

**默认桥会占用 DM 的 Python 脚本槽。** 需要运行另一个 DM Python 脚本时，应先断开客户端并正常停止桥，完成后再启动。不要因此强制结束 DM。原生 C++ 路线旨在避免这一长期占用，但目前有严格的版本和功能限制。

**本地连接不等于数据不会进入模型服务。** 客户端可能把预览、元数据、路径或数值发送给所选模型；请按实验室的数据政策选择和配置服务。

**这里没有显微镜硬件控制。** 本项目只面向采集后的数据，不控制相机、电子束、样品台或光路，也不把 AI 解释当作科研结论。

## 继续了解

[Agent 安装与使用指南](README.agent.md)说明如何接入、选对数据、处理错误和交接结果；[完整技术参考](REFERENCE.md)保留安装命令、工具参数和数值约定。修改代码请读 [AGENTS.md](AGENTS.md)，开发方向见 [ROADMAP.md](ROADMAP.md)。

原生频谱导出同时保留数学频率坐标和 DM 原始标定；该新增元数据链的实机验收仍需单独完成，见[科学数据交接说明](docs/SCIENTIFIC_HANDOFF.md)。

多版本兼容层生成器目前只是[独立提案](https://github.com/wuchqwq/mcp-dm/pull/3)，不是现成的自动适配功能。

项目代码采用 [MIT License](LICENSE)。DigitalMicrograph/GMS、Gatan 运行时、厂商文档和实验数据不随仓库分发；本项目不是 Gatan 官方产品。