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のウォールタイム、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