ns-hpc — 命名空间 HPC MCP 服务器

Name: ns-hpc
Author: li-yq

一个基于 Python 的 Model Context Protocol (MCP) 服务器，为 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 — 在 bwrap 容器内生成的子 MCP 服务器
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 — 命名空间 HPC MCP 服务器

架构

要求

快速开始

命令行界面 (CLI)

配置

MCP 工具

安全性

项目结构

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API