tcs-mcp

九州大学スーパーコンピュータ「玄界」で採用されている Fujitsu Technical Computing Suite (TCS/PJM) を、Codex などの MCP クライアントから操作するための個人利用向け stdio サーバーです。

次の2方式を同じツールインターフェースで利用できます。

• direct: 玄界のログインノード上で pjstat、pjsub、pjdel、pjshowrsc を直接実行
• ssh: 手元の PC で MCP サーバーを起動し、OpenSSH 経由で玄界を操作・ファイル転送

必要環境

• Node.js 20 以降
• direct モード: TCS コマンドを利用できる玄界ログインノード
• SSH モード: ssh と scp、設定済みの known_hosts、パスフレーズを保持した ssh-agent

SSH の秘密鍵やパスフレーズを MCP の設定ファイルへ保存しないでください。SSH モードは非対話実行のため BatchMode=yes を使用します。

セットアップ

npm install
npm run build
cp tcs-mcp.config.example.json tcs-mcp.config.json

tcs-mcp.config.json の許可ルートを実際のプロジェクトディレクトリへ変更します。設定ファイルを指定しない場合は、起動ディレクトリだけを許可する direct プロファイルになります。

{
  "defaultProfile": "genkai-direct",
  "profiles": {
    "genkai-direct": {
      "mode": "direct",
      "remoteRoots": ["/home/GROUP/USER/work"],
      "allowedCommands": ["make", "cmake", "ninja", "gcc", "g++", "gfortran", "python3"],
      "commandTimeoutSeconds": 600,
      "maxOutputBytes": 1048576
    }
  }
}

複数プロジェクトやアカウントはプロファイルを分け、起動時に選択します。

TCS_MCP_CONFIG=/absolute/path/tcs-mcp.config.json \
TCS_MCP_PROFILE=genkai-direct \
node /absolute/path/dist/index.js

Codex の設定例

玄界上で Codex を使う場合:

[mcp_servers.tcs]
command = "/absolute/path/to/tcs_mcp_codex/dist/index.js"
env = { TCS_MCP_CONFIG = "/absolute/path/to/tcs_mcp_codex/tcs-mcp.config.json", TCS_MCP_PROFILE = "genkai-direct" }

手元 PC から SSH モードを使う場合は、先に OpenSSH の alias を設定します。

Host genkai
    HostName genkai.hpc.kyushu-u.ac.jp
    User kuXXXXXXXX
    IdentityFile ~/.ssh/genkai/id_rsa
    IdentitiesOnly yes

ssh-add ~/.ssh/genkai/id_rsa
ssh genkai true

MCP プロファイルは次のようにします。

{
  "mode": "ssh",
  "host": "genkai",
  "remoteRoots": ["/home/GROUP/USER/work"],
  "localRoots": ["/Users/you/projects"],
  "allowedCommands": ["make", "cmake", "ninja", "gcc", "g++", "gfortran", "python3"]
}

MCP ツール

参照専用:

• system_status: 接続、TCS コマンド、プロファイル、許可ルートを診断
• list_jobs, get_job, get_job_stats: 現在のジョブ、365日以内の履歴、統計を取得
• list_resources: リソースグループの空き状況とユーザー制限を取得
• list_modules: Environment Modules を一覧・検索
• list_files, read_file, search_files: 許可ルート内のファイルを参照
• validate_job, render_job: 通常バッチジョブを検証・生成

更新操作:

• submit_job, cancel_job: 通常バッチジョブを投入・取消
• run_command: allowlist または許可ルート内の実行ファイルをログインノードで実行
• write_file, manage_files: ファイル作成、追記、コピー、移動、削除
• transfer_files: SSH モードで upload/download
• confirm_action: プレビュー済み操作を実行

更新ツールの初回呼び出しは何も変更せず、内容と5分間有効な確認トークンを返します。そのトークンを confirm_action に渡した場合だけ、保存された操作を一度実行します。ジョブスクリプトがプレビュー後に変更された場合、投入は拒否されます。

構造化ジョブの例

{
  "definition": {
    "name": "omp-test",
    "workdir": "/home/GROUP/USER/work/example",
    "resourceGroup": "a-batch",
    "vnodeCores": 30,
    "elapsed": "01:00:00",
    "modules": ["intel/2025.1.3"],
    "env": { "OMP_NUM_THREADS": "30" },
    "commands": [{ "executable": "./a.out", "args": ["input.dat"] }],
    "joinOutput": true,
    "stats": "basic",
    "restart": false
  }
}

玄界固有の A/B/C リソース上限を事前検証しますが、実際の利用可否はアカウントの ACL と投入時点の TCS 設定が優先されます。ジョブは /home または /fast 配下の、設定で明示的に許可したルートから投入してください。

安全上の制約

• 許可ルートは realpath で評価し、.. やシンボリックリンクによる逸脱を拒否します。
• stdout/stderr、ファイル読取り、検索結果、実行時間には上限があります。
• run_command はシェル文字列を受け付けず、実行ファイルと引数を分離します。
• CPU/GPU を多く使う処理を run_command で実行せず、必ず submit_job を使用してください。
• run_command、ジョブスクリプト、Python などは任意コードを実行できます。本サーバーの制限は誤操作防止であり、悪意あるコードに対するサンドボックスではありません。
• v1 の専用 API は通常バッチジョブのみです。対話型、ステップ、バルク、予約ジョブ、利用申請ポータル操作は対象外です。

開発

npm run check
npm test
npm run build

テストでは PJM 出力パース、玄界の資源検証、パス境界、タイムアウト、確認トークン、更新前プレビュー、MCP tool discovery を検証します。実環境に対する自動テストは参照専用に限定し、ジョブ投入や取消は行いません。

参考資料

• 玄界: ジョブの利用法
• 玄界: リソースグループ
• 玄界: SSH ログイン
• MCP TypeScript SDK