NiChart DLMUSE MCP server

将 cbica/nichart_dlmuse（T1 MRI 颅骨剥离 + MUSE ROI 分割）托管在 GPU EC2 实例上的 MCP 服务器后面，因此 Claude Code 可以远程运行分割，而无须每个用户都配备本地 GPU。

为什么这样设计

MCP 工具参数是 JSON。一个 .nii.gz 文件有几十 MB 的二进制数据，分割 在 GPU 上需要 ~1-2 分钟——对于单个阻塞式工具调用来说太大也太慢了。 因此：

• 文件传输发生在 MCP 协议之外，通过一个普通的带认证的 POST /upload 端点。只有一个小小的 upload_id 会流经 MCP 工具 参数。

• 作业是异步的：run_dlmuse_segmentation 入队后立即返回； get_job_status 轮询；get_job_result 获取内联的 CSV 以及 掩码文件的下载链接。

• 单一 worker，串行执行：它是一块共享 GPU，所以同一时间只有一个 docker run 在执行， 排在 asyncio.Queue 后面。

• Bearer token 认证：每个团队成员在除 /healthz 之外的每个端点上都需要。

• 私有实例，没有公共 Web 层：应用只绑定 127.0.0.1，并且 安全组只开放 SSH（22）。用户通过 SSH 端口转发将笔记本电脑映射到该回环端口，并使用他们的私钥访问—— 没有域名，也没有任何面向互联网的可攻击面。

• TLS 使用自签名证书，在实例上生成一次，因为公开签发的证书（Let's Encrypt 等）要求实例能够从互联网访问以进行域名验证，而这个实例不行。 每个用户在自己的笔记本电脑上信任这一个证书（见下文）。

• 扫描数据不会永久保留：上传和作业输出会在 RETENTION_HOURS（默认 24 小时）后被删除。

架构

Claude Code (laptop)                    SSH tunnel                  EC2 (private, SG: 22 only)
  │  ssh -i key.pem -L 8420:127.0.0.1:8420 user@instance ─────────────────►  │
  │                                                                          │
  │  1. curl https://127.0.0.1:8420/upload ─────(via tunnel)──────────►  MCP server :8420 (127.0.0.1, self-signed TLS)
  │  2. run_dlmuse_segmentation ────────────────(via tunnel)──────────►         │
  │  3. get_job_status (poll) ──────────────────(via tunnel)──────────►  asyncio job queue (1 worker)
  │  4. get_job_result ─────────────────────────(via tunnel)──────────►         │
                                                                   docker run --gpus all cbica/nichart_dlmuse

仓库布局

server/app.py     MCP tools (run_dlmuse_segmentation, get_job_status, get_job_result)
                  + HTTP routes (/upload, /download/{job_id}/{filename}, /healthz)
server/jobs.py    job queue/worker, docker invocation, root-owned-output cleanup
server/auth.py    bearer-token ASGI middleware
server/config.py  env-driven settings
deploy/           EC2 provisioning script (installs Docker, GPU toolkit, self-signed cert, systemd unit)

一次性 EC2 设置

需要一台现有的 GPU EC2 实例（推荐使用 AWS Deep Learning AMI——通常已安装 NVIDIA 驱动和 Docker）。

1. 将此仓库复制到实例上（git clone / scp -r）。

2. 执行 cp .env.example .env，并至少填写 TOKENS——每个团队成员一个 name:token 对， 用逗号分隔。使用 openssl rand -hex 32 生成 token。

3. 在实例的安全组中：仅允许入站 22（SSH），并限制为团队 IP 或堡垒机。不要开放其他任何端口——不要开放 443，也不要开放 8420。应用 绑定 127.0.0.1，只能通过 SSH 隧道访问。

4. 运行配置脚本：

   sudo ./deploy/setup_ec2.sh

   它是幂等的——仅在缺失时安装 Docker/nvidia-container-toolkit， 拉取 DLMUSE 镜像，创建专用的 nichart-mcp 服务用户，将代码部署到 /opt/nichart-mcp，生成自签名 TLS 证书（SAN = 127.0.0.1/localhost）， 并安装 nichart-mcp systemd 服务。

5. 在实例本身上验证：

   curl --cacert /opt/nichart-mcp/tls/server.crt https://127.0.0.1:8420/healthz

6. 将 /opt/nichart-mcp/tls/server.crt 从实例上复制出来，以便分发给 每个团队成员（例如 scp -i key.pem ec2-user@<instance-ip>:/opt/nichart-mcp/tls/server.crt .）。

以后要添加或撤销用户：在实例上编辑 /opt/nichart-mcp/.env 中的 TOKENS， 然后运行 sudo systemctl restart nichart-mcp。

更新代码

在实例上从更新后的检出重新运行 sudo ./deploy/setup_ec2.sh——它会 重新同步 /opt/nichart-mcp（保持现有 TLS 证书不变），重新安装 依赖项，并重启服务。

从笔记本电脑连接

每个团队成员需要：他们的 SSH 私钥（对于 Windows PuTTY .ppk 密钥， 用 puttygen key.ppk -O private-openssh -o key.pem 转换一次，以便标准 ssh 客户端可以使用）、他们的 bearer token，以及 server.crt 文件 （来自设置步骤 6）。

1. 信任自签名证书一次，这样 curl/Claude Code 就不会拒绝它：

• macOS: security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain-db server.crt

• Linux: sudo cp server.crt /usr/local/share/ca-certificates/nichart-mcp.crt && sudo update-ca-certificates

• Windows: certutil -addstore -f "ROOT" server.crt

2. 打开 SSH 隧道（在使用 Claude Code 期间让此命令在终端中保持运行）：

ssh -i key.pem -N -L 8420:127.0.0.1:8420 <ssh_user>@<instance-ip>

如果实例没有公网 IP，只能通过堡垒机访问，请添加 -J <bastion_user>@<bastion_host>。

3. 向 Claude Code 注册 MCP 服务器（只需一次）：

claude mcp add --transport http nichart-dlmuse https://127.0.0.1:8420/mcp \
  --header "Authorization: Bearer <their-token>"

使用方法

隧道打开后，让 Claude Code 对扫描进行分割；它将：

1. 上传文件（通过隧道，所以 127.0.0.1:8420 是正确的，即使文件最终要发送到远程实例）：

   curl -X POST -H "Authorization: Bearer <token>" \
     -F "file=@/path/to/scan.nii.gz" \
     https://127.0.0.1:8420/upload
   # -> {"upload_id": "..."}

2. 使用该 upload_id 调用 run_dlmuse_segmentation 工具 -> 得到一个 job_id。

3. 轮询 get_job_status(job_id)，直到 status == "done"（通常在 GPU 上需要 ~1-2 分钟）。

4. 调用 get_job_result(job_id) -> 获取内联的 ROI 体积 CSV，以及 /download/{job_id}/{filename} 链接，用于 ICV 和 MUSE 掩码 NIfTI 文件 （使用相同的 bearer token，通过同一条隧道从 https://127.0.0.1:8420/download/... 获取）。

运维说明

• GPU 并发：按设计同一时间只运行一个作业（单一共享 GPU）。 繁忙的团队会看到作业排队；get_job_status 会报告 queue_position。

• 作业状态保存在内存中：systemctl restart nichart-mcp 会丢失进行中的作业记录 （已上传的扫描和磁盘上的任何部分输出不受影响，但你需要重新提交）。在小团队规模下没问题； 如果规模超出，请将 server/jobs.py 中的内存字典替换为 Redis/RQ。

• PHI：扫描是真实的患者数据。RETENTION_HOURS 限制了它们在磁盘上的保留时间， 但在用于真实患者之前，请确认这符合你的数据处理要求。如果尚未启用实例卷的 EBS 加密，请考虑启用。

• DLMUSE 容器在内部以 root 身份运行（它硬编码写入 /app/pipeline.log，因此无法在 --user 下运行）。其输出最终归 root 所有； server/jobs.py 的清理会回退到临时 alpine 容器来强制删除这些目录。

本地开发

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
cp .env.example .env   # fill in TOKENS
TOKENS=dev:devtoken DATA_DIR=/tmp/nichart-dev .venv/bin/python -m server.app

这会在本地运行完整的服务器（认证、上传、作业队列、MCP 工具）。实际 运行分割仍然需要具备 GPU 访问权限的 Docker——在没有 GPU 的机器上， 作业会在 docker run 步骤失败，但其他一切（路由、认证、排队、状态/错误报告） 都可以测试。