# RISBridge MCP

> **Run jobs on the WashU RIS Compute2 cluster by describing what you want.**
> An intent-to-compute server that turns plain English into safe, validated Slurm work — no SSH, `sbatch`, partitions, GRES, modules, or storage layout to learn.

![License](https://img.shields.io/badge/license-Proprietary-d33)
![Platform](https://img.shields.io/badge/platform-WashU%20RIS%20Compute2-1f6feb)
![Scheduler](https://img.shields.io/badge/scheduler-Slurm-2da44e)
![Runtime](https://img.shields.io/badge/node-%E2%89%A5%2018.18-339933)
![Protocol](https://img.shields.io/badge/MCP-server-6f42c1)
![Type](https://img.shields.io/badge/TypeScript-strict-3178c6)

RISBridge is a [Model Context Protocol](https://modelcontextprotocol.io) server. You talk to it
in plain language through an MCP client (Claude Desktop or Claude Code); it plans the job, shows
you exactly what it will submit, and runs it on the cluster only after you confirm. It is
**deliberately not a terminal** — there is no arbitrary-shell tool. Every action is a specific,
schema-validated operation, which is what makes it safe to let an agent drive real HPC work.

---

## Why it exists

Getting research code onto an HPC cluster usually means learning SSH, Duo, `sbatch`, partitions,
GRES, modules, and a storage layout — before running a single line. RISBridge removes that wall:

- **Researchers new to HPC** get a guided path — a setup wizard, plain-English planning, dry-run
  previews, and clear status/log/diagnose tools. No Slurm knowledge required.
- **Experienced HPC users** get speed and consistency — job arrays, `afterok` pipelines,
  single-node multi-GPU `torchrun`, vLLM serving, efficiency right-sizing, run comparison, and
  reproducible history.

Same server, both audiences. The tools scale from "hold my hand" to "give me the template and get
out of the way."

## How it works

```mermaid
flowchart LR
    A([Plain-English intent]) --> B[Plan & validate<br/>partition · resources · paths]
    B --> C{Dry-run preview<br/>“I will submit: …”}
    C -- confirm --> D[Build sbatch from<br/>fixed, validated templates]
    D --> E[[SSH · Duo / multiplexing]]
    E --> F[(Slurm on Compute2)]
    F --> G[Monitor · logs · explain<br/>efficiency · history]
    G --> A
```

Login nodes are used only for submitting — every workload runs through Slurm on compute nodes.
Submissions are **dry-run by default** and require an explicit confirm before anything reaches the
scheduler.

## Highlights

- **Intent → compute.** *"Run `src/train.py` on a GPU for 4 hours"* becomes a validated `sbatch`
  submission. *"Why is my job pending?"* returns a plain-English answer with a fix.
- **Safe by construction.** No arbitrary-shell tool; strict input validation; remote commands run
  via argument arrays (never shell strings); file uploads are base64-encoded; paths are
  workspace-confined; job control verifies ownership; a redacted audit log records every action.
- **Auth that respects policy.** SSH-key setup, Duo-aware connection multiplexing (approve once,
  reuse for hours), and an optional per-user worker that orchestrates Slurm from inside the
  cluster. Duo is never automated; private keys are never shown or logged.
- **Broad workload coverage.** Python (CPU/GPU), R, notebooks, GPU smoke tests, job arrays,
  multi-GPU training, vLLM serving, JupyterLab, conda environments, dependency pipelines, and
  long checkpoint/requeue runs.
- **53 high-level tools** across auth, discovery, projects/files, planning, submission, job
  management, logs, environments, expert controls, and the per-user worker.

## Example

You type intent; RISBridge does the rest:

> *"What's my RISBridge setup status?"*
> *"Set up my SSH key."* → installs the key, one Duo approval
> *"Discover my profile."* → finds your Slurm account and storage workspace
> *"Run `src/train.py` on one H100 for 4 hours."* → preview → confirm → job ID
> *"Why is job 1234567 pending?"* · *"Tail its logs."* · *"Right-size my last 5 runs."*

## The toolset

<details>
<summary><b>All 53 tools, by category</b></summary>

**Setup & authentication** — `ris_setup_wizard`, `ris_auth_status`, `ris_setup_ssh_key`,
`ris_show_public_key`, `ris_generate_ssh_config`, `ris_write_ssh_config`,
`ris_test_key_only_auth`, `ris_open_ssh_master`, `ris_check_ssh_master`, `ris_repair_stale_socket`

**Discovery & configuration** — `ris_discover_profile`, `ris_set_profile`, `ris_show_config`,
`ris_validate_config`, `ris_list_partitions`, `ris_gpu_status`

**Projects, files & environments** — `ris_create_project`, `ris_upload_file`,
`ris_list_project_files`, `ris_ensure_env`, `ris_list_modules`, `ris_list_conda_envs`,
`ris_inspect_conda_env`

**Planning** — `ris_plan_run`, `ris_researcher_wizard`, `ris_estimate_resources`

**Submitting jobs** — `ris_run`, `ris_submit_python_job`, `ris_submit_r_job`,
`ris_submit_notebook_job`, `ris_submit_gpu_smoke_test`, `ris_submit_array_job`,
`ris_submit_multigpu_torch_job`, `ris_submit_jupyter_job`, `ris_submit_vllm_job`,
`ris_submit_conda_env_job`, `ris_create_pipeline`, `ris_generate_sbatch_template`

**Monitoring & lifecycle** — `ris_list_my_jobs`, `ris_job_history`, `ris_explain_job`,
`ris_get_job_logs`, `ris_tail_job_logs`, `ris_cancel_job`, `ris_hold_job`, `ris_release_job`

**Analysis & reproducibility** — `ris_analyze_efficiency`, `ris_compare_runs`,
`ris_get_result_manifest`

**Per-user worker** — `ris_bootstrap_worker`, `ris_worker_enqueue`, `ris_worker_status`,
`ris_worker_cancel`

</details>

## Safety & trust model

| Guarantee | How |
| --- | --- |
| No arbitrary shell | Every remote command is a fixed template built from validated tokens; no raw command tool exists. |
| Injection-resistant | Zod validation on every input; `spawn` with argument arrays; base64-encoded uploads. |
| Confined | Workspace-only paths (no traversal, no data on `/home`). |
| Confirmed | Submissions are dry-run by default and need an explicit confirm. |
| Accountable | Ownership-checked job control; redacted append-only audit log. |
| Private | Duo never automated; passwords never captured; private keys never shown or logged. |

## Requirements

- A WashU RIS account with a Compute2 allocation.
- The WashU network or VPN (login nodes are reachable only on-network) and Duo MFA.
- An MCP client (Claude Desktop or Claude Code). For the source route: Node.js 18.18+ and OpenSSH.

## Getting started

> Use is governed by the [license](#license) — the steps below are for authorized users.

**One-click extension.** Install the `risbridge-mcp.mcpb` Desktop Extension in Claude Desktop
(*Settings → Extensions → Install Extension…*), enter your WashU username, and you're done — it
bundles its own runtime.

**From source.**

```bash
npm install
npm test          # unit tests (no network)
npm run build     # → dist/
node dist/cli.js tools     # list the registered tools
```

Then register the server with your client (for example: `claude mcp add risbridge -- node /abs/path/dist/server.js`), connect to the WashU VPN, and ask RISBridge to set up your SSH key.

## Cluster reference

<details>
<summary><b>Partitions, storage & GPU modes</b></summary>

**Partitions** (there is no plain `general` partition):

| Partition | Use | GPU |
| --- | --- | --- |
| `general-gpu` | Full-throughput GPU work | Full H100 80 GB |
| `general-preempt-gpu` | Free, restartable GPU work | Untyped (preemptible) |
| `general-cpu` | Standard CPU work | — |
| `general-short` | Quick tests / dev | MIG slice (~10 GB) |
| `general-interactive` | Interactive sessions | MIG slice |
| `general-bigmem` | Large-memory CPU | — |

**Storage** — `/home` is small (code only); data, environments, outputs, and checkpoints live
under your `/storage2/fs1/<lab>/Active/...` workspace.

**GPU requests** — typed `--gres=gpu:H100:N` by default; untyped `--gres=gpu:N` is opt-in and
matches more nodes on `general-gpu` (and is required on preemptible GPU queues).

</details>

## Project structure

```
src/
  tools/        53 MCP tools
  core/         sbatch builder (policy chokepoint), ssh/slurm clients, validation, planner
  templates/    12 job templates
  auth/         SSH key + Duo / multiplexing
  worker/       per-user worker daemon
  config.ts     environment-driven configuration
tests/          unit test suite
scripts/        installers + .mcpb packaging
```

## License

**Proprietary — All Rights Reserved.** This software and its source code are proprietary and
confidential. No license or permission is granted to use, copy, modify, or distribute it, in
whole or in part, without the prior written permission of the copyright holder. Viewing this
repository does not grant any such rights. See [LICENSE](./LICENSE).

To request permission, contact **sourabh@wustl.edu**.