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

## セットアップ

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

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

```json
{
  "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
    }
  }
}
```

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

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

### Codex の設定例

玄界上で Codex を使う場合:

```toml
[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 を設定します。

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

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

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

```json
{
  "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` に渡した場合だけ、保存された操作を一度実行します。ジョブスクリプトがプレビュー後に変更された場合、投入は拒否されます。

## 構造化ジョブの例

```json
{
  "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 は通常バッチジョブのみです。対話型、ステップ、バルク、予約ジョブ、利用申請ポータル操作は対象外です。

## 開発

```bash
npm run check
npm test
npm run build
```

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

## 参考資料

- [玄界: ジョブの利用法](https://www.cc.kyushu-u.ac.jp/scp/usage/job/)
- [玄界: リソースグループ](https://www.cc.kyushu-u.ac.jp/scp/usage/resource_groups/)
- [玄界: SSH ログイン](https://www.cc.kyushu-u.ac.jp/scp/usage/login/login_unix/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)