Skip to main content
Glama

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 を使用します。

Related MCP server: jlab-mcp

セットアップ

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 を検証します。実環境に対する自動テストは参照専用に限定し、ジョブ投入や取消は行いません。

参考資料

Available Tools

18 tools
cancel_jobPrepare PJM job cancellationA
Destructive

Preview cancellation of a current owned job and return a confirmation token.

Inputs: jobId (required), reason.

confirm_actionConfirm prepared TCS actionA
Destructive

Execute exactly one previously previewed action using its short-lived, single-use token.

Inputs: token (required).

get_jobGet PJM jobA
Read-onlyIdempotent

Get details and output paths for one current or historical job.

Inputs: jobId (required).

get_job_statsGet PJM job statisticsA
Read-onlyIdempotent

Get basic or node-level statistics for a completed job.

Inputs: jobId (required), detailed.

list_filesList remote filesB
Read-onlyIdempotent

List one directory inside configured remote roots.

Inputs: path (required), limit.

list_jobsList PJM jobsC
Read-onlyIdempotent

List this account's current jobs or completed job history in structured form.

Inputs: limit, states, historyDays, resourceGroup, +1 more.

list_modulesList environment modulesA
Read-onlyIdempotent

List or search Environment Modules available on the login node.

Inputs: query.

list_resourcesList Genkai resourcesA
Read-onlyIdempotent

Read PJM resource-group availability and this account's scheduler limits.

Inputs: no named parameters.

manage_filesPrepare remote file operationB
Destructive

Preview mkdir, copy, move, or delete inside configured remote roots.

Inputs: source (required), operation (required), recursive, destination.

read_fileRead remote text fileA
Read-onlyIdempotent

Read the beginning of a text file, or tail a requested number of lines, inside configured roots.

Inputs: path (required), maxBytes, tailLines.

render_jobRender Genkai job scriptB
Read-onlyIdempotent

Render and validate a structured normal-batch job definition without writing it.

Inputs: elapsed (required), workdir (required), commands (required), resourceGroup (required), +11 more.

run_commandPrepare login-node commandC
Destructive

Preview a constrained build or pre/post-processing command. Heavy computation must be submitted as a job.

Inputs: cwd (required), executable (required), env, args, +2 more.

search_filesSearch remote filesB
Read-onlyIdempotent

Search text with ripgrep under a configured remote root.

Inputs: path (required), pattern (required), glob, limit.

submit_jobPrepare PJM job submissionB
Destructive

Preview a normal-batch pjsub operation and return a confirmation token. Does not submit until confirm_action.

Inputs: definition, scriptPath.

system_statusTCS system statusA
Read-onlyIdempotent

Check the selected profile, connection, runtime, TCS commands, and configured path limits.

Inputs: no named parameters.

transfer_filesPrepare Genkai file transferC
Destructive

Preview an SSH-mode upload or download between configured local and remote roots.

Inputs: source (required), direction (required), destination (required), overwrite, +1 more.

validate_jobValidate Genkai jobA
Read-onlyIdempotent

Validate either an existing PJM script or a structured normal-batch job definition without submitting it.

Inputs: definition, scriptPath.

write_filePrepare remote file writeC
Destructive

Preview writing or appending a UTF-8 text file inside configured remote roots.

Inputs: path (required), content (required), append, overwrite.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 18 tools

    Disambiguation4/5

    Most tools have distinct purposes (jobs, files, resources, modules, etc.). However, validate_job and render_job both handle structured job definitions, creating minor ambiguity about which to use for validation only. submit_job also performs a preview, but its confirmation token makes its role clear.

    Naming Consistency4/5

    The vast majority of tools follow a clear verb_noun pattern (list_jobs, get_job, submit_job, read_file, etc.). The only outlier is 'system_status', which uses noun_noun instead of a verb-based name, breaking the otherwise consistent convention.

    Tool Count4/5

    With 18 tools, the set is slightly above the ideal 3-15 range, but the breadth of functionality (job management, file operations, system status, and the preview/confirm flow) justifies the count. It is not bloated to the point of being overwhelming.

    Completeness4/5

    The tool surface covers the core HPC workflow: job submission/validation/cancellation/statistics, file reading/writing/searching/transfer, resource and module queries, and system status. Minor gaps exist, such as no direct job output/error viewing (though read_file can access output paths) and no job modification (update/alter), but these are workable.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A server implementing Model Coupling Protocol for HDF5 file operations, Slurm job management, hardware monitoring, and data compression.
      MIT
    • F
      license
      A
      quality
      C
      maintenance
      An MCP server that enables LLMs to execute Python code on GPU-accelerated compute nodes within SLURM-managed HPC environments. It bridges local clients to remote clusters by launching JupyterLab sessions via SLURM jobs to facilitate high-performance notebook-based computation.
      7
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for the Fugaku supercomputer that enables natural language job submission, monitoring, file transfer, and command execution via AI agents like Claude Code.
      5
      MIT