ns-hpc — Servidor MCP para HPC con Namespaces

Name: ns-hpc
Author: li-yq

Un servidor Model Context Protocol (MCP) basado en Python que proporciona una interfaz segura y aislada para que los agentes de LLM interactúen con un clúster HPC. El mecanismo de aislamiento principal es bubblewrap (bwrap) para el aislamiento de espacios de nombres de usuario sin privilegios.

Arquitectura

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)
│  └───────────────────────┘  │
└─────────────────────────────┘

Requisitos

Python ≥ 3.11
bubblewrap (bwrap) — instalar: apt install bubblewrap o dnf install bubblewrap
Espacios de nombres de usuario habilitados — sysctl kernel.unprivileged_userns_clone=1
Slurm (opcional) — para enviar trabajos al clúster

Inicio rápido

# 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

Configuración

Edite config.toml para personalizar:

namespace_defaults — flags de bwrap (directorios de solo lectura, dev/proc/tmpfs, entorno)
proxied_mcps — servidores MCP secundarios para ejecutar dentro de contenedores bwrap
resource_defaults — valores predeterminados de Slurm para tiempo de ejecución (walltime), CPUs y memoria
data_dir — dónde se almacenan los espacios de trabajo de las instancias (predeterminado: ~/mcp_instances)
context_dir — directorio con archivos de documentación en Markdown

Herramientas MCP

Herramienta	Descripción
`create_instance`	Crear un espacio de trabajo aislado con bwrap
`destroy_instance`	Eliminar un espacio de trabajo y todos sus datos
`list_instances`	Listar todas las instancias activas
`read_audit_log`	Leer el registro de auditoría de una instancia
`run_command`	Ejecutar un comando dentro de bwrap (local o Slurm)
`get_task`	Consultar el estado y la salida de una tarea
`list_tasks`	Listar las tareas de una instancia
`cancel_task`	Cancelar una tarea en ejecución
`list_context_files`	Listar la documentación de HPC disponible
`read_context_file`	Leer un archivo de documentación

Seguridad

Todos los comandos se ejecutan dentro de un espacio de nombres de usuario de bwrap — no se requiere root.
El registro de auditoría es escrito por el proceso anfitrión, nunca desde dentro del sandbox.
La red está deshabilitada por defecto (--unshare-net).
Aislamiento de instancias mediante directorios por instancia con montajes bind del espacio de trabajo.

Estructura del proyecto

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 — Servidor MCP para HPC con Namespaces

Arquitectura

Requisitos

Inicio rápido

CLI

Configuración

Herramientas MCP

Seguridad

Estructura del proyecto

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API