ns-hpc — 네임스페이스 기반 HPC MCP 서버

LLM 에이전트가 HPC 클러스터와 상호 작용할 수 있도록 안전한 샌드박스 인터페이스를 제공하는 Python 기반 Model Context Protocol (MCP) 서버입니다. 핵심 격리 메커니즘은 비권한 사용자 네임스페이스 격리를 위한 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 월타임(walltime), 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 사용자 네임스페이스 내부에서 실행되므로 루트 권한이 필요하지 않습니다.
감사 로그는 호스트 프로세스에 의해 작성되며, 샌드박스 내부에서는 절대 작성되지 않습니다.
네트워크는 기본적으로 비활성화되어 있습니다 (--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