ns-hpc — MCP-сервер для HPC с использованием пространств имен

Сервер Model Context Protocol (MCP) на базе Python, который предоставляет безопасный изолированный интерфейс для LLM-агентов для взаимодействия с HPC-кластером. Основным механизмом изоляции является bubblewrap (bwrap) для изоляции пространств имен непривилегированных пользователей.

Архитектура

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

Требования

Python ≥ 3.11
bubblewrap (bwrap) — установка: apt install bubblewrap или dnf install bubblewrap
Включенные пространства имен пользователей — sysctl kernel.unprivileged_userns_clone=1
Slurm (опционально) — для отправки заданий в кластер

Быстрый старт

# 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

Конфигурация

Отредактируйте config.toml для настройки:

namespace_defaults — флаги bwrap (директории только для чтения, dev/proc/tmpfs, переменные окружения)
proxied_mcps — дочерние MCP-серверы, запускаемые внутри контейнеров bwrap
resource_defaults — значения по умолчанию для Slurm (время выполнения, CPU, память)
data_dir — место хранения рабочих пространств экземпляров (по умолчанию: ~/mcp_instances)
context_dir — директория с файлами документации в формате Markdown

Инструменты MCP

Инструмент	Описание
`create_instance`	Создать рабочее пространство, изолированное через bwrap
`destroy_instance`	Удалить рабочее пространство и все его данные
`list_instances`	Список всех активных экземпляров
`read_audit_log`	Прочитать журнал аудита для экземпляра
`run_command`	Выполнить команду внутри bwrap (локально или через Slurm)
`get_task`	Запросить статус и вывод задачи
`list_tasks`	Список задач для экземпляра
`cancel_task`	Отменить выполняемую задачу
`list_context_files`	Список доступной документации по HPC
`read_context_file`	Прочитать файл документации

Безопасность

Все команды выполняются внутри пространства имен пользователей bwrap — права root не требуются.
Журнал аудита записывается хост-процессом, никогда изнутри «песочницы».
Сеть по умолчанию отключена (--unshare-net).
Изоляция экземпляров осуществляется через директории для каждого экземпляра с монтированием рабочих пространств.

Структура проекта

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 — MCP-сервер для HPC с использованием пространств имен

Архитектура

Требования

Быстрый старт

CLI

Конфигурация

Инструменты MCP

Безопасность

Структура проекта

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API