Metadata-Version: 2.4
Name: joblet-mcp-server
Version: 1.1.4
Summary: MCP (Model Context Protocol) server for Joblet job orchestration system
Author: Jay Ehsaniara
License: MIT
Project-URL: Homepage, https://github.com/ehsaniara/joblet-mcp-server
Project-URL: Repository, https://github.com/ehsaniara/joblet-mcp-server
Project-URL: Documentation, https://github.com/ehsaniara/joblet-mcp-server/blob/main/README.md
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.8.0
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: joblet-sdk-python>=2.5.2
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Dynamic: license-file

# 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
