vaws-coordinator
Provides tools for managing Docker containers on remote hosts, including binding existing containers via docker exec, creating user-specific Ascend NPU containers, and enumerating or unbinding containers.
Allows capturing local Git worktree snapshots, including uncommitted changes and submodules, and synchronizing them to remote containers for execution without altering the local HEAD or staging area.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
为什么需要 mindie-coordinator?
在多人共用的昇腾(Ascend)NPU 服务器上改 vllm / vllm-ascend、调算子或跑评测时,开发者和 AI Agent 最头疼三件事:
代码同步乱:手动
rsync或在服务器上直接改代码,跑着跑着就不知道刚才那个分数到底是哪版代码跑出来的,还经常把别人的目录覆盖掉。抢卡撞车:几个人同时往 0 号卡上起服务,显存瞬间 OOM;或者任务崩了但子进程还占着卡和端口不放。
环境每次重配太慢:每次切分支都要重新编译算子、重新检查
torch_npu能不能import,白白浪费十几分钟。
mindie-coordinator 作为运行在你本机的轻量级协调守护进程,通过 remote-dev 帮你把整套流程管得井井有条:
本地改代码,远端自动隔离同步:提交任务那一刻自动锁定你本地 Git 工作树(连同未提交的修改和子模块),增量同步到远端你专属的持久化容器(
mindie-<你的用户名>)里的独立目录中,完全不动你本地的HEAD和暂存区。宿主机统一排队分卡,跑完立即释放:通过部署在宿主机上的零依赖协调脚本统一分配物理 NPU 卡和服务端口(
30000–45999)。既支持独占多卡,也支持显式指定单张卡跟别人共享调试(allow_external_busy=True);任务结束或停止时自动清理整个进程树并归还 NPU 租约。编译好的算子与环境智能复用:只要底层依赖和 C++/Ascend 算子没变、只改了 Python 代码,下次启动秒级复用已验证过的运行环境,省去重复编译和漫长的导入检查。
一套后台,三种用法:同时提供 5 个标准 MCP 工具(给 AI 编程助手用)、
mindie命令行工具(给终端用)和 PythonTaskClientSDK(给脚本用)。
flowchart LR
Dev["👩💻 本地 Git 代码库 & AI Agent"]
Daemon["⚙️ mindie-coordinator<br/>(本机单用户守护进程)"]
Container["🐳 远端专属容器 mindie-<user><br/>(独立代码目录 + 算子缓存复用)"]
HostQueue["🎛️ 宿主机 NPU 与端口队列<br/>(独占分卡 / 单卡共享 / 自动释放)"]
Dev -->|"1. 提交任务 (mindie_run / mindie run)"| Daemon
Daemon -->|"2. 增量同步 Git 快照 & 准备环境"| Container
Daemon -->|"3. 申请物理 NPU 卡与空闲端口"| HostQueue
HostQueue -->|"4. 注入设备租约启动 & 结束自动回收"| ContainerRelated MCP server: LinkedRun
快速开始
直接复制下面这句话发给你的 Claude Code、Codex、Kimi Code、DeepSeek Harness(DSH)或 Google Antigravity(AGY),由 AI Agent 自动完成安装和 MCP 接入:
帮我安装并配置 https://github.com/mindie-agent/coordinator如果你是收到上述指令的 AI Agent,请按以下步骤完成 mindie-coordinator 的安装与 MCP 配置:
检查环境要求:确认本机具备 Python
>= 3.11、git、ssh以及uv(pyproject.toml已锁定匹配的remote-dev与mindie-diagnostics版本,无需单独手动找版本)。在当前宿主客户端注册 MCP Server:
Claude Code(写入
.mcp.json或直接运行命令):claude mcp add mindie-coordinator -- uvx --from git+https://github.com/mindie-agent/coordinator@main mindie-coordinator task-serverCursor(写入
.cursor/mcp.json)或通用.mcp.json:{ "mcpServers": { "mindie-coordinator": { "type": "stdio", "command": "uvx", "args": [ "--from", "git+https://github.com/mindie-agent/coordinator@main", "mindie-coordinator", "task-server" ] } } }Kimi Code(写入
.kimi-code/mcp.json,不要包含type字段):{ "mcpServers": { "mindie-coordinator": { "command": "uvx", "args": [ "--from", "git+https://github.com/mindie-agent/coordinator@main", "mindie-coordinator", "task-server" ], "startupTimeoutMs": 30000, "toolTimeoutMs": 600000 } } }OpenAI Codex(追加到
.codex/config.toml):[mcp_servers.mindie_coordinator] command = "uvx" args = ["--from", "git+https://github.com/mindie-agent/coordinator@main", "mindie-coordinator", "task-server"]
验证命令可用:
uvx --from git+https://github.com/mindie-agent/coordinator@main mindie --help告知用户:提示用户重启/新开对话后,即可直接使用
mindie_hosts、mindie_probe、mindie_container、mindie_lease、mindie_session、mindie_run、mindie_execution、mindie_finish、mindie_message调度远端昇腾任务。
真实使用场景
场景 1:把本地正在修改的 vllm 和 vllm-ascend 同步到远端 NPU 跑测试
不用手动传文件,也不用担心弄乱本地分支——直接指定本地源码目录和需要的 NPU 卡号,跑完自动释放卡:
from mindie_coordinator.task_client import TaskClient
client = TaskClient("/local/task-context.json")
run = client.run(
'"$MINDIE_PYTHON" -c "import torch_npu; print(torch_npu.npu.device_count())"',
sources={"vllm": "/local/vllm", "vllm-ascend": "/local/vllm-ascend"},
resources={"devices": [0]},
topology={"host": "npu-host"},
wait_until="released",
wait_timeout_seconds=180,
)
print(run["execution_id"], run["state"], run["resources_released"], run.get("stdout", ""))场景 2:在终端直接提交本地 Shell 脚本并等待结果
写好了一个复杂的启动或评测脚本 business.sh?用 mindie run --script-file 一键推到远端受管执行:
# 提交本地脚本,同步 /local/app 源码,等待执行结束并释放资源
mindie run --script-file business.sh --source app=/local/app --wait released --wait-timeout-seconds 180
# 随时查看某个正在跑的任务状态或继续等待它结束
mindie execution --execution-id <EXECUTION_ID> --wait released --wait-timeout-seconds 180
# 查验该次执行实际用到的 Git 代码快照、环境准备耗时或编译回执
mindie execution --execution-id <EXECUTION_ID> --action evidence --section build --path kernel_name场景 3:卡上已经有别人的服务,想显式跟他在同一张卡上共享调试
默认情况下分配器只挑完全空闲的 NPU 卡。如果你明确知道 0 号卡显存还够、想跟上面的外部进程共用这张卡跑个小实验,只需加上 allow_external_busy=True:
run = client.run(
'"$MINDIE_PYTHON" test_small_op.py',
resources={"devices": [0], "allow_external_busy": True},
topology={"host": "npu-host"},
wait_until="released",
)
# 任务结束时只会清理你自己的进程和租约,绝不会误杀卡上别人的原进程!MCP 工具与 CLI 一览
1. 远端 SSH 环境、容器与 NPU 算力管理(无需前置会话即可直接调用)
这四类接口在 CLI 和 MCP 中均不要求 MindIE 任务绑定;省略 context_file 即使用独立环境管理入口,原生调用携带的会话元数据不会额外触发任务准入。显式传入 context_file 时仍核验对应任务归属。资源探测可先行完成,再按实际空闲情况申请租约;缺少任务绑定不应阻止查看容器、定位源码和模型目录或执行无需上卡的测试。
MCP 工具名 | 对应的 CLI 入口 | 它能帮你做什么 |
|
| 统一管理 SSH 主机台账( |
|
| 免 Agent 单趟 SSH 探测昇腾 NPU 显存/算力/进程归属(兼容 910B/A2、双 Die 910C/A3、950/A5)、智能推荐连续空闲卡( |
|
| 绑定已有容器(支持 |
|
| 轻量级宿主机 NPU 卡与服务端口租约申请( |
共享 SSH 认证(与
remote-dev和npu-top互通):SSH 认证与免密公钥统一存储在~/.mindie/ssh/(可通过REMOTE_DEV_AUTH_DIR或REMOTE_DEV_CREDENTIAL_FILE自定义)。首次接入新机器时,运行一次remote-dev auth setup --host HOST --port 22 --user USER --prompt(或在mindie_hosts(action="bootstrap_key")中传入password_env),系统会自动安装并验证免密公钥(不支持公钥时保留密码模式)。machines.json与endpoints.json仅记录认证引用auth_ref与密钥路径,后续跨会话、mindie-coordinator、remote-dev与npu-top均可直接复用,无需重复输入密码。
2. 受管源码快照与任务执行生命周期
mindie_run 会物化独立远端执行目录,sources 是待捕获的本地输入;用户希望直接开发某个现有或新远端目录时,应使用 remote-dev 操作该目录并通过 coordinator 申请资源租约。源码位置与 Python 环境分别选择,新源码不要求重建虚拟环境。容器就绪探测复用 remote-dev 的多解释器依赖元数据发现,选择实际具备 Torch / Torch-NPU 的环境并保存其路径;后续命令保留 venv 的 sys.executable,不转换成丢失私有依赖的底层 Python。多个合格候选返回歧义,显式选择失败不静默换环境;元数据就绪仍不等同于上卡验证通过。
标准准备不适用时,可在已有授权内改用现有 CLI 或 Agent 自编任务脚本。受管隔离执行接受 script_file;指定目录开发可直接使用 remote-dev / 原生 SSH 并保留资源租约。失败响应的 next 返回原执行的查询入口与资源释放事实,避免因换工具而重复启动未确认结束的作业;辅助工具失败只影响对应步骤,独立工作继续。
MCP 工具名 | 对应的 CLI / Python 方法 | 它能帮你做什么 |
|
| 查看当前本地任务绑定了哪些默认源码目录(支持自动识别 Git Worktree 与 Submodule),或更新默认源码路径 |
|
| 锁定本地 Git 代码快照,准备远端容器环境,排队申请 NPU 卡与空闲端口,并启动受管任务或常驻服务 |
|
| 秒级读取任务最新状态、拉取增量日志( |
|
| 结束当前任务,把名下还在跑的受管进程全部停掉,并归还所有运行环境绑定与 NPU 租约 |
|
| 当排队等卡看到队友也在用机器时( |
3. 编译槽、独占进程组与构建缓存复用机制
编译与跑卡分离(两阶段租约、CPU 编译槽与按卡显存配额):宿主机
HostQueue将 CPU 编译槽(compile slots)与物理 NPU 执行租约分开管理——多个任务可以同时在后台拉代码、编扩展(支持按单次授权分配多核编译预算),互不阻塞;上卡跑测试或起服务时,既支持独占整张物理 NPU,也支持按每张卡/每个 Die 申请显存配额(granted_memory_mb_per_device)安全拼卡。独占进程组与干净退出回收:每次受管执行都在独立的进程组中启动,任务自然结束、超时或收到
stop指令时,协调器会排空整个子进程树并校验宿主机/proc与设备占用,确保不留僵尸进程、不漏端口,随后立即归还 NPU 租约。跨任务原生构建缓存复用(
native_cache_pool):按sha256(csrc 源码树 + CANN 版本 + SoC 型号 + Python ABI + 编译参数)对编译产物做内容寻址缓存并记录native_cache_receipt,相同源码与环境直接秒级复用(注:当前实机并行构建池验收覆盖torch.utils.cpp_extensionCPU C++ 扩展;完整AscendC算子工程的编译池复用正在持续扩展中)。可追溯的执行清单(
RunManifest):mindie_coordinator/run_manifest.py为每次运行记录完整的 Git 源码快照身份(source_head与snapshot_commit),并按需附带硬件遥测(hardware_telemetry)、缓存命中回执(native_cache_receipt)、活跃执行证明(active_execution_proof)与性能剖析引用(profile_summary_ref),方便随时复盘某次实验到底跑的是哪版代码和环境。
文档导航
文档主题 | 中文文档 | English |
文档中心导航 | ||
专属容器与任务全生命周期说明 | ||
工具参数、单卡共享、算子复用与诊断参考 |
仓库目录结构
路径 | 作用说明 |
|
|
| 面向日常环境管理与任务提交的轻量 |
| 给 AI 编程助手提供的 stdio MCP Server(暴露 9 个环境管理与任务调度工具) |
| SSH 主机管理、容器绑定/开通、硬件探测与轻量 NPU 租约的核心编排实现 |
|
|
| 面向 Agent 的单趟无代理 SSH 昇腾 NPU、容器与共享权重盘探测及容量排序引擎 |
| Python |
| 宿主机 NPU 排队分配器的公共 Python API |
| 零第三方依赖的宿主机 NPU、端口与编译槽仲裁模块(通过 SSH 下发到物理机执行) |
| 容器内运行环境校验、算子构建缓存复用与发布 |
| 内容寻址原生构建缓存池( |
| 原生扩展构建与执行存在性探测配方(当前实机并行验收范围为 CPU C++ 扩展) |
| 本地 Git 工作树快照打包与远端容器增量同步 |
| 执行清单(Run Manifest v1)、已接受源码版本身份( |
| 中英双语生命周期与工具配置文档 |
| 单元测试套件(本地即可运行,无需物理 NPU 或 Docker) |
本地开发与测试
克隆仓库并在虚拟环境中安装测试依赖即可直接运行本地单元测试(无需物理 NPU 或 Docker;若同时在本地联调 remote-dev,可一并执行 -e ../remote-dev):
uv venv
uv pip install -e ".[test]"
HOME="$(mktemp -d)" .venv/bin/python -m pytest许可证
本项目采用 MIT License 开源。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted MCP server for task-first delegation to remote workstations and workers.
Coordinate and verify OpenCode workers over MCP Streamable HTTP.
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
Streamable HTTP MCP gateway for NV oOS fleets — one API key, namespaced tools, quotas and policy.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server orchestrating local multi-agent workflows with gated lifecycle, handoff events, and host-level continuation.-
- AlicenseAqualityCmaintenanceEnables agents to submit and manage persistent, dependency-aware task graphs with immutable artifacts, resource reservations, durable event streaming, and retryable process execution over MCP.12MIT
- AlicenseNot gradedqualityCmaintenanceServes as a single local MCP entry point that proxies configured upstream MCP tools to multiple coding agents, keeps sessions warm, serializes exclusive services, and provides SQLite-backed task, lock, and memory tools.MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables enterprise agent fleets to register workers, dispatch tasks by capability, monitor continuous heartbeat telemetry, trip automated circuit breakers, and recover from checkpointed state through a zero-dependency MCP server.MIT