Metadata-Version: 2.5
Name: jobstate
Version: 0.1.1
Summary: Submit, watch and report on Slurm jobs from AI agents: an MCP server and CLI for JSC's JUPITER, JURECA, JUWELS and JUSUF
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,hpc,jupiter,jureca,jusuf,juwels,mcp,slurm
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.12
Requires-Dist: mcp<3,>=2.3
Requires-Dist: pyyaml>=6
Description-Content-Type: text/markdown

# jobstate

Tools for AI agents to submit, watch and report on Slurm jobs on the JSC supercomputers JUPITER, JURECA, JUWELS and JUSUF: an
[MCP](https://modelcontextprotocol.io) server (`jobstate-mcp`) and a command-line tool (`jobstate`).

Instead of polling `squeue` turn after turn, an agent waits for its jobs with one tool call, or is notified when
they end; a long job costs one model turn at the end. Submissions go through a dry run and a separate confirmation,
under limits and budget guards the server enforces itself.

## Install

```sh
pip install jobstate
```

Or with [uv](https://docs.astral.sh/uv/): `uv tool install jobstate`.

On a JSC login node, check the setup and add the server to Claude Code:

```sh
jobstate check
claude mcp add -s user jobstate -- jobstate-mcp
```

From your own machine the server reaches the cluster over ssh:

```sh
jobstate check --cluster jupiter --host <your ssh config name>
claude mcp add -s user jobstate-jupiter -- jobstate-mcp --cluster jupiter --host <your ssh config name>
```

## Tools

`job_status`, `list_jobs`, `job_summary`, `tail_log`, `job_report` (GPU efficiency from LLview), `watch_job`,
`wait_for_jobs`, `cluster_info`, and, unless configured read-only, `submit_job` (a dry run), `confirm_submit` and
`cancel_job`. End-of-job events carry exit code, run time against the limit, busy cores, peak memory, I/O and
node-hours from Slurm accounting.

Configuration (allowed accounts, tighter limits, read-only mode, ntfy or webhook notifications) goes into
`~/.config/jobstate-mcp/config.yaml`. Python 3.12 or later.
