ns-hpc — Namespaced HPC MCP Server

Name: ns-hpc
Author: li-yq

Ein Python-basierter Model Context Protocol (MCP) Server, der eine sichere, isolierte Schnittstelle für LLM-Agenten zur Interaktion mit einem HPC-Cluster bereitstellt. Der Kernmechanismus der Isolierung ist bubblewrap (bwrap) für die Isolierung von nicht privilegierten Benutzer-Namespaces.

Architektur

LLM Agent (Claude, etc.)
    │  MCP over STDIO (SSH)
    ▼
┌─────────────────────────────┐
│      ns-hpc MCP Server      │
│  ┌───────────────────────┐  │
│  │   Managed MCP Proxy   │──┼──► child MCP servers (filesystem, git, …)
│  └───────────────────────┘  │       inside bwrap container
│  ┌───────────────────────┐  │
│  │    Instance Manager   │──┼──► ~/mcp_instances/{id}/workspace/
│  └───────────────────────┘  │       + metadata.json + audit.log
│  ┌───────────────────────┐  │
│  │      Task Manager     │──┼──► local (Popen + bwrap)
│  │                       │  │    or Slurm (sbatch + bwrap)
│  └───────────────────────┘  │
└─────────────────────────────┘

Anforderungen

Python ≥ 3.11
bubblewrap (bwrap) — Installation: apt install bubblewrap oder dnf install bubblewrap
Benutzer-Namespaces aktiviert — sysctl kernel.unprivileged_userns_clone=1
Slurm (optional) — zum Einreichen von Jobs an den Cluster

Schnellstart

# Install ns-hpc
cd ns-hpc
uv sync

# Run diagnostics
uv run ns-hpc doctor

# Start the MCP server (over STDIO — connect via SSH)
uv run ns-hpc run

CLI

ns-hpc run       # Start the MCP server over STDIO
ns-hpc doctor    # Check bwrap, namespaces, and Slurm availability
ns-hpc --version # Show version

Konfiguration

Bearbeiten Sie config.toml zur Anpassung:

namespace_defaults — bwrap-Flags (schreibgeschützte Verzeichnisse, dev/proc/tmpfs, Umgebung)
proxied_mcps — untergeordnete MCP-Server, die innerhalb von bwrap-Containern gestartet werden
resource_defaults — Slurm-Standardwerte für Walltime, CPUs und Arbeitsspeicher
data_dir — Speicherort der Instanz-Arbeitsbereiche (Standard: ~/mcp_instances)
context_dir — Verzeichnis mit Markdown-Dokumentationsdateien

MCP-Tools

Tool	Beschreibung
`create_instance`	Erstellt einen bwrap-isolierten Arbeitsbereich
`destroy_instance`	Entfernt einen Arbeitsbereich und alle zugehörigen Daten
`list_instances`	Listet alle aktiven Instanzen auf
`read_audit_log`	Liest das Audit-Protokoll für eine Instanz
`run_command`	Führt einen Befehl innerhalb von bwrap aus (lokal oder Slurm)
`get_task`	Fragt den Aufgabenstatus und die Ausgabe ab
`list_tasks`	Listet Aufgaben für eine Instanz auf
`cancel_task`	Bricht eine laufende Aufgabe ab
`list_context_files`	Listet verfügbare HPC-Dokumentation auf
`read_context_file`	Liest eine Dokumentationsdatei

Sicherheit

Alle Befehle werden innerhalb eines bwrap-Benutzer-Namespaces ausgeführt — keine Root-Rechte erforderlich.
Das Audit-Protokoll wird vom Host-Prozess geschrieben, niemals aus der Sandbox heraus.
Das Netzwerk ist standardmäßig deaktiviert (--unshare-net).
Instanz-Isolierung durch instanzspezifische Verzeichnisse mit Workspace-Bind-Mounts.

Projektstruktur

ns-hpc/
├── config.toml              # Main configuration
├── context/                 # HPC documentation (exposed as MCP resources)
├── pyproject.toml           # Project metadata & dependencies
└── src/ns_hpc/
    ├── __init__.py
    ├── __main__.py
    ├── cli.py               # CLI entry point (run, doctor)
    ├── config.py            # Pydantic config models + TOML loader
    ├── server.py            # MCP server with all tool handlers + proxy
    └── core/
        ├── bwrap_builder.py  # bwrap argument list construction
        ├── instance_manager.py # Workspace CRUD + audit log
        └── task_manager.py  # Local & Slurm task execution

ns-hpc

ns-hpc — Namespaced HPC MCP Server

Architektur

Anforderungen

Schnellstart

CLI

Konfiguration

MCP-Tools

Sicherheit

Projektstruktur

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API