Skip to main content
Glama
Sign In
RCF MCP Server

RCF MCP Server

by Diraw
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Research Compute Fabric (RCF)

Python 3.11+ License: MIT

给 AI Agent 用的科研算力控制面：先计划、再确认、可追溯。

RCF 把本机、SSH 工作站（含 WSL）和 Slurm 集群收进同一套 CLI 与 stdio MCP 接口。它不取代调度器， 也不要求远端常驻服务；配置用 TOML，计划、运行、GPU 租约与审计用 SQLite。

Agent / CLI → RcfService → 配置、计划、SQLite、审计
                            ├─ Local 进程
                            ├─ SSH + 状态文件
                            └─ Slurm 客户端命令

为什么不是又一个 sbatch 包装器

提交一条命令很容易，难的是回答：

  • 这次跑的是哪份代码、哪个环境、哪批输入？

  • 命令会在哪台机器、哪个目录、用哪张 GPU 执行？

  • 提交回执丢了，作业是没跑、在跑，还是已经结束？

  • 产物在哪、能不能复现，旧文件能不能安全清理？

RCF 把这些答案放进同一条链路：plan → review → submit → observe。所有执行先有一份可审阅的 计划，计划里包含命令预览、工作目录、资源需求、环境指纹和阻塞项；提交必须显式确认； 运行状态从执行器重新读取，不拿数据库里的旧值冒充事实。

Related MCP server: secure-cluster-mcp

能做什么

能力

说明

节点登记与探测

Local / SSH / Slurm；只读探测 CPU、内存、磁盘、GPU 与分区

计划与执行

先 run plan 审阅，再 run submit --yes；阻塞项存在时拒绝提交

运行观测

状态、日志、退出码、事件、结果清单；不确定提交保持 unknown

环境证据

环境指纹、漂移、env lock，以及按路径所有权放行的安装计划

代码与数据

project sync / project push，按内容差异传输并逐文件校验

存储治理

台账、扫描、两阶段清理；删除必须审阅具体文件清单并再次确认

进度与预算

项目写入 JSONL 证据；ETA 只来自实测推进，没有证据就返回不可估

Agent 接入

31 个 MCP 工具；CLI 与 MCP 共用 RcfService 和同一套错误码

安装

需要 Python 3.11+。仓库带 uv.lock，推荐用 uv：

cd research-compute-fabric
uv sync
uv run rcf --help

没有 uv 时也可以用虚拟环境：

python -m venv .venv
# Linux / macOS
.venv/bin/python -m pip install -e .
python -m venv .venv
.venv\Scripts\python.exe -m pip install -e .

安装依赖可能需要网络，请只在你允许的环境中执行；RCF 不会自行下载依赖，也不会连接未登记的节点。 安装后可直接使用 rcf；如果没有激活虚拟环境，用 uv run rcf 或虚拟环境中的绝对路径。

5 分钟本机演示

uv run python examples/quickstart.py

脚本会在系统临时目录创建独立的 RCF home，用当前 Python 运行 examples/demo/compute.py， 执行一次 1000 步的 CPU 小任务，并核对确定性结果。它不连接远程节点，临时目录会保留供检查。

输出类似下面这样（路径和 ID 因机器而异）：

Isolated RCF home retained at: .../rcf-example-...
Plan plan_...: ...
Run run_...: succeeded
Completed 1000 steps; result written to the declared output directory
Verified result: .../outputs/result.json

这证明本机链路可用，不代表远程集群、GPU、MPI 或你的项目环境已经验证。

配置与第一次真实运行

uv run rcf init        # 生成 ~/.rcf/{rcf,nodes,projects,environments}.toml
uv run rcf doctor      # 检查配置、依赖与安全姿态

按 examples/ 修改自己的 RCF home。示例里的 /home/researcher、/path/to/checkout 和 example-* 都是占位符，必须替换；不要把实际配置提交到仓库。

--home 是全局参数，要放在子命令之前：

rcf --home /path/to/private-rcf-home doctor

一次运行的最小闭环：

rcf run plan --project demo --node local \
  --param steps=1000 --param seed=1 --minutes 1
rcf run submit PLAN_ID --yes
rcf run status RUN_ID
rcf run logs RUN_ID
rcf run results RUN_ID

PLAN_ID / RUN_ID 用上一步实际返回值替换，不是可以直接执行的字面参数。submit 只接受 plan_id，不接受临时拼的命令行；计划默认 30 分钟后过期，过期后应重新 plan。

接入新机器前，先手动 ssh 一次并核对主机指纹，再运行：

rcf node inspect NODE
rcf node selftest NODE   # 约 10 秒，只验证控制路径与目录，不提交作业

接入 Agent（MCP）

rcf mcp serve（等价 rcf-mcp）启动 stdio MCP server。当前暴露 31 个工具，覆盖节点探测、 计划/提交/状态/日志、环境、项目同步、结果回收、存储治理和进度/ETA。

Claude Code 或其他兼容 stdio 的客户端示例：

{
  "mcpServers": {
    "rcf": {
      "command": "rcf",
      "args": ["mcp", "serve"],
      "env": { "RCF_HOME": "/home/you/.rcf" }
    }
  }
}

Windows 把 RCF_HOME 写成 C:/Users/you/.rcf；如果 rcf 不在 PATH，使用虚拟环境中的 绝对路径。rcf mcp tools 可查看当前工具清单，完整配置、工具表和 Agent 工作循环见 Agent 接入指南。

安全边界（先读这一段）

RCF 不是沙箱。任务以当前账户权限运行；危险命令检测、日志脱敏都是启发式，不是安全隔离。

已经强制的约束：

  • 计划与执行分离：plan_run 无副作用，submit_run 需要 confirm 且计划中没有阻塞项；

  • 配置中没有密码、私钥或 token 字段，SSH 主机密钥验证永不放宽；

  • 环境写入按路径所有权与显式确认放行，[environments].managed_roots 默认为空；

  • 有副作用的操作写审计；RCF 内部 GPU 租约用 SQLite 部分唯一索引避免重复占用。

明确不保证：多用户隔离、恶意脚本防护、远程文件防篡改、全局 GPU 调度、跨机断点续传、 自动备份/清理，以及多节点 MPI 的普适兼容。完整清单见安全模型与边界 和验收状态。

项目状态

当前版本 0.1.0，处于公开候选阶段：离线回归与模拟执行器已有覆盖；原生 Linux/macOS、 远端 CI 和真实计算节点尚未在本轮公开验收中声明通过。能力、测试入口和已知限制以 docs/status.md 为唯一可信来源。

文档

文档

内容

文档索引

按角色选择阅读路径

Agent 接入指南

CLI/MCP、配置、进度与存储工作流

架构

组件、模型、状态机与关键流程

安全边界

已实现约束与明确不保证的内容

验收状态

公开版本的验证口径与待验收项

开发规范

离线测试、平台约定与构建

发布清单

隐私检查、源码交付与发布边界

技术决策

依赖选择与取舍

HPC 应用兼容性

LAMMPS / Python / MPI 检查方法

路线图

未覆盖场景与后续工作

仓库结构

src/rcf/       服务层、执行器、运行管理、进度证据、存储治理
docs/          深入文档（从 docs/README.md 进入）
examples/      本机快速开始、示例配置与 CPU demo
tests/         离线/模拟执行器测试；真实设备测试默认不启用
tools/         公开材料扫描与发布候选验收

开发前请读开发规范。测试默认不连接真实节点；真实设备验证需要单独授权。

许可证

MIT，见 LICENSE。

Available Tools

31 tools
compute_apply_environmentcompute.apply_environmentA

Execute a reviewed environment plan (conda create/install or venv+pip). Requires confirm=true. RCF only writes prefixes it owns (managed_roots or managed=true) and refuses plans with blockers; every write is audited.

Inputs: env_id (required), node_id (required), confirm.

compute_apply_storage_plancompute.apply_storage_planA

Apply one reviewed cleanup or adoption plan. Requires fresh human approval and confirm=true.

Inputs: plan_id (required), resume, confirm.

compute_cancel_runcompute.cancel_runB

Cancel a run through its executor (scancel on Slurm, process-group signal elsewhere).

Inputs: run_id (required), confirm.

compute_check_storagecompute.check_storageC
Read-only

Check project storage evidence and safety issues without deleting files.

Inputs: project_id (required), node_id.

compute_collect_resultscompute.collect_resultsB
Read-only

List the result files of a run in place (no bulk transfer between nodes).

Inputs: run_id (required).

compute_doctorcompute.doctorA
Read-only

Report configuration, dependency and security status of this RCF installation.

Inputs: no named parameters.

compute_fetch_resultscompute.fetch_resultsA

Copy a run's artifacts to the control machine (tar + scp, SHA-256 verified). Writes to a local directory, so it needs confirm=true.

Inputs: dest (required), run_id (required), force, confirm.

compute_get_logscompute.get_logsA
Read-only

Read the tail of a run's log (stdout+stderr), redacted for secrets.

Inputs: run_id (required), tail.

compute_get_runcompute.get_runB
Read-only

Fetch a run's state, exit code and recent events, refreshing from the executor.

Inputs: run_id (required), refresh.

compute_get_run_progresscompute.get_run_progressB
Read-only

Read run progress, phase, ETA interval/scope/confidence and alerts; unknown ETA is explicit.

Inputs: run_id (required).

compute_get_storage_plancompute.get_storage_planB
Read-only

Read a stored storage plan with owner/stage, per-file journal and protection guards. Read-only evidence; heartbeat age does not authorize takeover or application.

Inputs: plan_id (required).

compute_inspect_environmentcompute.inspect_environmentB
Read-only

Inspect one environment read-only; never run its arbitrary verification command.

Inputs: env_id (required), node_id (required).

compute_inspect_nodecompute.inspect_nodeA
Read-only

Probe a node read-only: CPU, memory, disk, GPUs and Slurm partitions, plus an explicit GPU schedulability assessment (free VRAM is never treated as availability).

Inputs: node_id (required), refresh.

compute_list_environmentscompute.list_environmentsC
Read-only

Inspect declared environments per node: installed / compatible / verified, missing packages.

Inputs: node_id.

compute_list_nodescompute.list_nodesA
Read-only

List declared compute nodes with kind, labels and SSH alias (no network access).

Inputs: no named parameters.

compute_list_projectscompute.list_projectsA
Read-only

List research projects with entrypoint, environment and per-node paths.

Inputs: no named parameters.

compute_list_runscompute.list_runsB
Read-only

List recent runs from the local database, optionally filtered by state.

Inputs: limit, state.

compute_node_selftestcompute.node_selftestA

Prove the control path to a node in ~10s: ssh, POSIX shell, work_root write/read/cleanup, python3 and GPU. Creates and removes one temp dir; never submits a job.

Inputs: node_id (required).

compute_pin_runcompute.pin_runA

Pin or unpin a run against cleanup. Requires confirm=true; pinning requires a reason. Unpinning does not delete files.

Inputs: run_id (required), pinned, reason, confirm.

compute_plan_environmentcompute.plan_environmentA
Read-only

Plan how to create or complete an environment on one node: exact commands, missing packages, network needs and the ownership verdict. Read-only: nothing is installed and no directory is created.

Inputs: env_id (required), node_id (required).

compute_plan_runcompute.plan_runA
Read-only

Build an execution plan for a project (node selection, environment check, GPU choice, exact command). Pure planning: nothing is started, written or reserved. Optional pilot_seconds uses a hard watchdog when submitted; runtime_budget_seconds only gates planning/alerts, never cancels a normal run. Neither walltime nor budget is an ETA.

Inputs: project_id (required), cpus, gpus, tasks, +11 more.

compute_plan_storage_adoptioncompute.plan_storage_adoptionA
Read-only

Plan adoption of explicitly listed relative file paths in one root; never selects a whole root by default. Code adoption also needs source_node_id and requires a per-file hash match with that checkout. No adoption until the reviewed plan is separately applied with confirmation.

Inputs: paths (required), node_id (required), root_id (required), project_id (required), +3 more.

compute_plan_storage_cleanupcompute.plan_storage_cleanupA
Read-only

Plan exact-file cleanup for stale-code, disposable, replica or cache. No files deleted; review paths and blockers before separately applying with confirmation.

Inputs: node_id (required), project_id (required), kind, run_id, +2 more.

compute_push_projectcompute.push_projectA

Copy a project checkout to a node, sending only the files that differ. Plans by default; confirm=true applies. Never deletes, and never overwrites a file that is newer on the target unless force=true.

Inputs: node_id (required), project_id (required), data, force, +2 more.

compute_reconcile_storage_plancompute.reconcile_storage_planA

Observe the stored manifest and close an old storage plan as superseded, releasing its guards. Never continues deletion or resumes the plan. Requires fresh human approval and confirm=true.

Inputs: plan_id (required), confirm.

compute_report_storagecompute.report_storageC
Read-only

Report project storage statistics, classification and largest files.

Inputs: project_id (required), largest, node_id.

compute_scan_storagecompute.scan_storageC
Read-only

Scan declared project storage roots read-only; never changes research files.

Inputs: node_id (required), project_id (required).

compute_submit_runcompute.submit_runA

Submit a reviewed plan. Requires confirm=true and an executable plan; idempotency_key makes retries safe.

Inputs: plan_id (required), confirm, idempotency_key.

compute_sync_projectcompute.sync_projectA

Show (or apply, with confirm=true) a git fetch/checkout for a project on one node. Refuses on a dirty working tree.

Inputs: node_id (required), project_id (required), apply, confirm.

compute_verify_environmentcompute.verify_environmentB

Run the configured environment verification command only with confirm=true; execution permission required.

Inputs: env_id (required), node_id (required), confirm.

compute_wait_runcompute.wait_runA
Read-only

Bounded read-only long-poll (0 <= timeout_seconds <= 60, also capped by [progress].max_wait_seconds; zero reads cache) for change, terminal state, phase or alert. Not a background notification; repeat with after_revision. Never submits or cancels.

Inputs: run_id (required), until, after_revision, timeout_seconds.

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    B3.3/5.0

    Scored across 31 tools

    Disambiguation4/5

    The tools are mostly separable by resource and lifecycle stage: nodes, environments, runs, projects, and storage each have distinct actions. A few storage tools overlap in purpose (check_storage, scan_storage, report_storage) and the plan/get/reconcile/apply storage-plan sequence requires careful reading to avoid misselection, but descriptions provide strong guardrails.

    Naming Consistency5/5

    Every tool follows the same compute_<verb>_<noun> snake_case pattern, with predictable verbs such as list, inspect, plan, apply, get, and submit. The few longer names (compute_plan_storage_adoption, compute_reconcile_storage_plan) remain consistent and readable.

    Tool Count2/5

    With 31 tools, the surface is heavy for an agent to navigate even though it spans several real subdomains (nodes, environments, runs, projects, storage). The count exceeds the 25+ threshold where tools begin to feel excessive and many operations are split into plan/apply/inspect variants.

    Completeness4/5

    Coverage is broad: environments can be inspected, planned, verified, and applied; runs can be planned, submitted, monitored, cancelled, pinned, and fetched; storage cleanup/adoption has planning and guarded application. Minor lifecycle gaps exist, such as no obvious environment deletion or project creation, but core workflows are well covered.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • mcp-slurm

      tejasvinu
      F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage SLURM HPC clusters via SSH. Supports job submission, resource monitoring, queue management, and file operations.
      8 npm
      4
      -

    • vanth

      holdfast-labs
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to launch, monitor, and manage background shell jobs with durable event tracking, live progress dashboards, and wake-on-attention for interactive sessions.
      1
      Apache 2.0

    • gpuctl-mcp

      EricYuan2007
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to manage GPU training end-to-end through natural language, including submitting and scheduling jobs, monitoring logs and metrics, diagnosing failures, comparing runs, and recommending the best checkpoints.
      Apache 2.0