@coscientist/mcp-toolbox

Minimal MCP toolbox for Co-Scientist. Provides two tools:

• submit_slurm_job
• get_job_details
• cancel_job
• list_jobs
• jobs_register
• jobs_unwatch
• jobs_watch_list
• events_list
• events_watch
• remote_write_file
• remote_read_file

Install

npm install -g @coscientist/mcp-toolbox

Or run once:

npx -y @coscientist/mcp-toolbox

Or bunx:

bunx @coscientist/mcp-toolbox

MCP Config

.mcp.json:

{
  "mcpServers": {
    "cosci": {
      "command": "npx",
      "args": ["-y", "@coscientist/mcp-toolbox@latest"]
    }
  }
}

Inputs

submit_slurm_job:

{
  "job": {
    "script": "path/to/job.sh",
    "sbatch_args": ["--partition=default", "--time=01:00:00"],
    "chdir": "."
  }
}

submit_slurm_job (SSH mode):

{
  "job": {
    "script": "path/to/local/job.sh",
    "connection": {
      "mode": "ssh",
      "ssh": {
        "host": "hpc.example.edu",
        "user": "you",
        "private_key_path": "~/.ssh/id_ed25519",
        "remote_dir": "/scratch/you/cosci"
      }
    }
  }
}

submit_slurm_job (SSH mode, inline script):

{
  "job": {
    "script_content": "#!/bin/bash\nsrun hostname",
    "connection": {
      "mode": "ssh",
      "ssh": {
        "host": "hpc.example.edu",
        "user": "you"
      }
    }
  }
}

get_job_details:

{
  "job_id": "123456"
}

get_job_details (SSH mode):

{
  "job_id": "123456",
  "connection": {
    "mode": "ssh",
    "ssh": {
      "host": "hpc.example.edu",
      "user": "you"
    }
  }
}

cancel_job:

{
  "job_id": "123456"
}

list_jobs:

{
  "user": "you",
  "limit": 20
}

jobs_register:

{
  "job_id": "123456",
  "note": "long run",
  "connection": {
    "mode": "ssh",
    "ssh": { "host": "hpc.example.edu", "user": "you" }
  }
}

events_list:

{
  "cursor": 0,
  "limit": 50
}

events_watch:

{
  "cursor": 0,
  "timeout_ms": 60000
}

jobs_watch_list:

{}

remote_write_file:

{
  "path": "/scratch/you/input.txt",
  "content": "hello cluster",
  "connection": {
    "mode": "ssh",
    "ssh": { "host": "hpc.example.edu", "user": "you" }
  }
}

remote_read_file:

{
  "path": "/scratch/you/input.txt",
  "offset": 0,
  "max_bytes": 10000,
  "connection": {
    "mode": "ssh",
    "ssh": { "host": "hpc.example.edu", "user": "you" }
  }
}

Note: remote_* tools are SSH-only and require connection.mode=ssh. max_bytes is capped to prevent large reads.

Notes

• Requires sbatch, sacct, and/or squeue on PATH.
• Uses execFile (no shell).
• SSH mode uses ssh2 with a persistent connection pool.

SSH Config (Env)

You can set defaults via env:

export COSCI_CLUSTER_MODE=ssh
export COSCI_SSH_HOST=hpc.example.edu
export COSCI_SSH_USER=you
export COSCI_SSH_KEY_PATH=~/.ssh/id_ed25519
export COSCI_SSH_PASSWORD=your_password   # optional (not recommended)
export COSCI_SSH_REMOTE_DIR=/scratch/you/cosci
export COSCI_SSH_KEEPALIVE_INTERVAL=10000
export COSCI_SSH_KEEPALIVE_COUNT=3
export COSCI_SSH_CONNECT_RETRIES=3
export COSCI_SSH_CONNECT_BACKOFF_MS=500
export COSCI_SSH_IDLE_TIMEOUT_MS=300000

Password auth is supported but discouraged; prefer keys or agent.

Event Bridge (Project Storage)

By default, events are stored under the project:

• .opencode/cosci-events.jsonl
• .opencode/cosci-events-state.json

Overrides:

export COSCI_PROJECT_DIR=/path/to/project
export COSCI_EVENTS_PATH=/path/to/events.jsonl
export COSCI_EVENTS_STATE_PATH=/path/to/events-state.json
export COSCI_EVENTS_POLL_MS=30000
export COSCI_EVENTS_WATCH_TIMEOUT_MS=60000
export COSCI_EVENTS_WATCH_INTERVAL_MS=1000
export COSCI_EVENTS_MAX_BYTES=262144
export COSCI_EVENTS_AUTO_UNWATCH=true

Host key pinning (optional):

export COSCI_SSH_HOSTKEY=SHA256:BASE64_FINGERPRINT

Strict host key checking (default: true):

export COSCI_SSH_STRICT_HOSTKEY=true
export COSCI_SSH_KNOWN_HOSTS=~/.ssh/known_hosts