Skip to main content
Glama

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 小时)后被删除。

Related MCP server: agent-bridge-mcp

架构

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 步骤失败,但其他一切(路由、认证、排队、状态/错误报告) 都可以测试。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers