# Joblet MCP Server

MCP server for [Joblet](https://github.com/ehsaniara/joblet) job orchestration - enables AI assistants to manage distributed computing jobs through the Joblet platform.

## Quick Start

```bash
# Install
pip install joblet-mcp-server

# Configure (~/.rnx/rnx-config.yml)
mkdir -p ~/.rnx
cp sample_config.yaml ~/.rnx/rnx-config.yml
# Edit with your Joblet server credentials

# Run
joblet-mcp-server
```

## Features

- **Jobs** - Run, monitor, and manage compute jobs (logs, metrics, telematics)
- **Runtimes** - List, inspect, test, build, and validate runtime environments
- **Storage** - Create and manage persistent volumes
- **Networks** - Configure isolated networks
- **Monitoring** - Real-time metrics and GPU status

> Workflow orchestration is not provided — it was extracted to a separate project
> and is not part of the Joblet gRPC API / SDK this server uses.

## Architecture

The MCP server is one of three client paths to a Joblet server. It lets an **AI
assistant** drive Joblet, while the `rnx` CLI serves human operators and
`joblet-sdk-python` serves other Python programs. All paths converge on the same
gRPC/mTLS API (`:50051`) and share the same `~/.rnx/rnx-config.yml` credentials.

```mermaid
flowchart TB
    AI["AI Assistant<br/>(Claude, OpenAI, etc.)"]
    USER["Human operator"]
    APP["Other Python apps"]
    MCP["joblet-mcp-server<br/>(this project)"]
    SDKLIB["joblet-sdk-python<br/>(gRPC client library)"]
    RNX["rnx CLI"]
    JOBLET["Joblet Server<br/>:50051"]
    AI -->|" MCP protocol (stdio) "| MCP
    MCP -->|" imports "| SDKLIB
    USER -->|" shell "| RNX
    APP -->|" imports "| SDKLIB
    SDKLIB -->|" gRPC / mTLS "| JOBLET
    RNX -->|" gRPC / mTLS "| JOBLET
```

The MCP server reaches Joblet through `joblet-sdk-python` — a single gRPC hop
over mTLS, the same API the `rnx` CLI uses for human operators.

## Usage

```bash
# Run with the default config (~/.rnx/rnx-config.yml)
joblet-mcp-server

# Use a specific config file or node, or enable debug logging
joblet-mcp-server --config /path/to/config.yml --node viewer --debug
```

The server communicates with the Joblet server over direct gRPC via
[joblet-sdk-python](https://github.com/ehsaniara/joblet-sdk-python), which is
installed automatically as a dependency.

## Configuration

Create `~/.rnx/rnx-config.yml`:

```yaml
version: "3.0"
nodes:
  default:
    address: "joblet-server.com:50051"
    cert: |
      -----BEGIN CERTIFICATE-----
      # Your client certificate
      -----END CERTIFICATE-----
    key: |
      -----BEGIN PRIVATE KEY-----
      # Your private key
      -----END PRIVATE KEY-----
    ca: |
      -----BEGIN CERTIFICATE-----
      # Your CA certificate
      -----END CERTIFICATE-----
```

## Compatibility

The MCP server reaches Joblet through `joblet-sdk-python`, so its **proto major**
is determined by the SDK it pulls — proto v1.x and v2.x do **not** interoperate.

| MCP Server            | via SDK           | joblet-proto | Joblet server (= RNX) |
|-----------------------|-------------------|--------------|-----------------------|
| **v1.1.3+** (current) | SDK ≥ 2.1.1 (2.x) | **v2.x**     | v5.0.2 – v5.6.11      |
| v1.1.0 – v1.1.2       | SDK ≥ 1.1.4 (1.x) | v1.x         | v4.5.0 – v5.0.1       |

Latest stack: MCP **v1.1.3** ↔ SDK **v2.5.1** ↔ Joblet/RNX **v5.6.11** (all proto
v2). See [COMPATIBILITY.md](COMPATIBILITY.md) for the full matrix and feature floors.

## Requirements

- Python 3.10+
- [Joblet server](https://github.com/ehsaniara/joblet) with TLS certificates
- Configuration file at `~/.rnx/rnx-config.yml`
- [joblet-sdk-python](https://github.com/ehsaniara/joblet-sdk-python) >= 2.0.0 (installed automatically as a dependency)
- gRPC/mTLS access to the Joblet server (port 50051)

## Documentation

- [Sample Config](sample_config.yaml)
- [Usage Examples](examples/usage_examples.md)

## License

MIT