aiterm-mcp 0.1.0 → 0.2.0

package/README.ja.md

@@ -6,6 +6,8 @@
 
 [![CI](https://github.com/kitepon-rgb/aiterm-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kitepon-rgb/aiterm-mcp/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
+[![node](https://img.shields.io/node/v/aiterm-mcp)](https://nodejs.org)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 > *(English: [README.md](README.md))*
 
@@ -13,6 +15,21 @@
 
 `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` の 6 ツールだけ。バックエンドは tmux なので、MCP サーバや AI クライアントが再起動してもセッションは生き残る。
 
+## インストール
+
+npm に公開済み。clone もビルドも不要:
+
+```bash
+# Claude Code — 推奨（インストール不要、npx が毎回取得して起動）
+claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
+
+# またはグローバル導入してコマンド名で登録
+npm i -g aiterm-mcp
+claude mcp add --scope user --transport stdio aiterm -- aiterm-mcp
+```
+
+**Node ≥ 18** と **tmux** が必要（Windows ネイティブでは WSL とその中の tmux。下の「要件」参照）。他の MCP クライアントは stdio で `npx -y aiterm-mcp` を起動するだけ（詳細は下の「インストール / 登録」）。
+
 ## なぜ
 
 AI にコマンドを 1 個ずつ投げて結果を受け取る往復は、SSH では毎回「接続→認証→切断」を繰り返し遅く、トークンも食う。aiterm は **1 個の PTY を永続的に握り**、その中で `ssh host` や `docker exec -it x bash` と打って入る（ネスト）。セッション種別をツールで区別しない。
@@ -50,6 +67,8 @@ flowchart LR
 
 - **Node.js >= 18**
 - **tmux**（実行時の前提。`tmux -V` で確認。未導入なら `apt install tmux` / `brew install tmux`）
+  - **macOS / Linux / WSL2** は tmux を直接使う。
+  - **Windows ネイティブ**には tmux が無いため、aiterm は裏で **WSL の中の tmux** を透過的に使う。[WSL](https://learn.microsoft.com/ja-jp/windows/wsl/) を導入・初期化し、**WSL のディストリ内に tmux を入れる**こと（`sudo apt install tmux`）。`wsl tmux -V` で確認できる。セッション・ソケット・人の `attach` はすべて WSL 側にあり、AI は Windows 側のコマンドから操作するだけ。（Windows のツールは SSH と同じく入れ子で握る: `pty_send "powershell.exe …"` で PowerShell に入る。）
 - 任意: [`rtk`](https://github.com/rtk-ai/rtk) バイナリ（`pty_send` の `rtk: true` 委譲で使う。無くても動く）
 
 ## インストール / 登録
@@ -57,7 +76,7 @@ flowchart LR
 Claude Code（CLI）にユーザースコープ（全プロジェクトで利用可）で登録する例:
 
 ```bash
-# 公開後（npm）
+# 推奨: インストール不要、npx が毎回取得して起動
 claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
 
 # またはグローバルインストールしてコマンド名で
@@ -106,7 +125,7 @@ claude mcp add --scope user --transport stdio aiterm -- aiterm-mcp
 
 ## 人が覗く
 
-セッションは共有 tmux ソケット上にある。`pty_open` の戻り値に表示される `tmux -S … attach -t <id>` で人間が同じ端末に入って介入できる（抜けるのは `Ctrl-b d`）。
+セッションは共有 tmux ソケット上にある。`pty_open` の戻り値に表示される `tmux -S … attach -t <id>` で人間が同じ端末に入って介入できる（抜けるのは `Ctrl-b d`）。Windows ネイティブではセッションが WSL 内にあるため、表示は WSL 形（`wsl tmux -S … attach -t <id>`）になる。
 
 ## 開発
 

package/README.md

@@ -6,6 +6,8 @@
 
 [![CI](https://github.com/kitepon-rgb/aiterm-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kitepon-rgb/aiterm-mcp/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
+[![node](https://img.shields.io/node/v/aiterm-mcp)](https://nodejs.org)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 > *(日本語: [README.ja.md](README.ja.md))*
 
@@ -13,6 +15,21 @@
 
 Just six tools — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list`. The backend is **tmux**, so sessions survive even if the MCP server or the AI client restarts.
 
+## Install
+
+It's on npm — no clone, no build:
+
+```bash
+# Claude Code — recommended (no install; npx fetches it each run)
+claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
+
+# or install globally, then register the command name
+npm i -g aiterm-mcp
+claude mcp add --scope user --transport stdio aiterm -- aiterm-mcp
+```
+
+Needs **Node ≥ 18** and **tmux** (on native Windows: WSL with tmux inside it — see [Requirements](#requirements)). Other MCP clients: just run `npx -y aiterm-mcp` over stdio. More detail in [Install / register](#install--register) below.
+
 ## Why
 
 Sending an AI one command at a time and reading back the result means, over SSH, repeating connect → authenticate → disconnect every round — slow, and it burns tokens. aiterm **holds one PTY persistently** and you type `ssh host` or `docker exec -it x bash` *inside it* (nesting). Session kind is never a tool-level distinction.
@@ -50,6 +67,8 @@ One PTY is the only primitive. Everything else — SSH, containers, REPLs — is
 
 - **Node.js >= 18**
 - **tmux** (runtime prerequisite; check with `tmux -V`. Install with `apt install tmux` / `brew install tmux`)
+  - **macOS / Linux / WSL2** run tmux directly.
+  - **Native Windows** has no tmux, so aiterm transparently runs tmux **inside WSL**. It needs [WSL](https://learn.microsoft.com/windows/wsl/) installed and initialized, with **tmux installed inside your WSL distro** (`sudo apt install tmux`); verify with `wsl tmux -V`. Sessions, the socket, and human `attach` all live on the WSL side — the AI just drives them from the Windows-side command. (You reach Windows tools the same way you reach SSH: `pty_send "powershell.exe …"` nests into PowerShell.)
 - Optional: the [`rtk`](https://github.com/rtk-ai/rtk) binary (used by `pty_send`'s `rtk: true` delegation; works fine without it)
 
 ## Install / register
@@ -57,7 +76,7 @@ One PTY is the only primitive. Everything else — SSH, containers, REPLs — is
 Register with Claude Code (CLI) at user scope (available in every project):
 
 ```bash
-# After publishing (npm)
+# Recommended — no install, npx fetches it each run
 claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
 
 # Or install globally and use the command name
@@ -106,7 +125,7 @@ Before sending, `pty_send` blocks destructive commands (`rm -rf /`, `mkfs`, `dd
 
 ## A human can watch
 
-Sessions live on a shared tmux socket. The `tmux -S … attach -t <id>` line printed by `pty_open` lets a human attach to the same terminal and intervene (`Ctrl-b d` to detach).
+Sessions live on a shared tmux socket. The `tmux -S … attach -t <id>` line printed by `pty_open` lets a human attach to the same terminal and intervene (`Ctrl-b d` to detach). On native Windows the printed line is the WSL form — `wsl tmux -S … attach -t <id>` — since the session lives inside WSL.
 
 ## Development
 

package/dist/core.js

@@ -10,9 +10,22 @@
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import * as os from "node:os";
+import { createHash } from "node:crypto";
 import * as rtk from "./rtk.js";
-const SOCKDIR = path.join(process.env.TMPDIR ?? "/tmp", "claude-tmux-sockets");
-const SOCK = path.join(SOCKDIR, "claude.sock");
+// Windows ネイティブには tmux が無い。その場合だけ全 tmux 呼び出しを WSL 経由へ橋渡しする
+// （POSIX = Linux/WSL2/macOS は従来どおり tmux を直接叩く）。
+const isWin = process.platform === "win32";
+// .log/.offset/.lastcmd を置くディレクトリ（Node が直接読み書きする）。
+// POSIX は従来どおり。Windows は TMPDIR→TEMP→os.tmpdir() の順で Windows 側の一時領域に置く。
+const SOCKDIR = path.join(process.env.TMPDIR ?? (isWin ? process.env.TEMP ?? os.tmpdir() : "/tmp"), "claude-tmux-sockets");
+// tmux -S に渡すソケットパス。POSIX はログと同じツリーに置く。
+// Windows は tmux が WSL 内で動くため、ソケットは WSL ネイティブ fs に置く必要がある
+// （/mnt drvfs(9p) 上では AF_UNIX 非対応）。SOCKDIR から短い安定名を導出し、
+// TMPDIR ごとの隔離（テスト）と再起動跨ぎ再接続を両立する。
+const SOCK = isWin
+    ? `/tmp/aiterm-${createHash("sha1").update(SOCKDIR).digest("hex").slice(0, 12)}.sock`
+    : path.join(SOCKDIR, "claude.sock");
 // 完了検出
 export const DEFAULT_TIMEOUT = 10.0;
 const POLL = 0.25;
@@ -55,10 +68,47 @@ export class AitermError extends Error {
         this.code = code;
     }
 }
+// Windows のドライブパス (C:\a\b) を WSL から見える /mnt/c/a/b へ変換する。
+// 一時領域は常にドライブ直下なので UNC は想定外＝弾く（黙って壊れた //server パスを作らない）。
+export function toWslPath(p) {
+    const m = /^([A-Za-z]):\/(.*)$/.exec(p.replace(/\\/g, "/"));
+    if (!m)
+        throw new AitermError(`WSL へ橋渡しできない一時パスです（ドライブ直下のみ対応）: ${p}`, 2);
+    return `/mnt/${m[1].toLowerCase()}/${m[2]}`;
+}
+// Windows で最初の tmux 呼び出し前に一度だけ WSL+tmux の可用性を確かめ、失敗は原因別に投げる。
+// -e（ログインシェル非経由）＋短い timeout で、初回セットアップ未完了の wsl によるハングも防ぐ。
+let winBridgeOk = false;
+function ensureWinBridge() {
+    if (winBridgeOk)
+        return;
+    const r = spawnSync("wsl.exe", ["-e", "tmux", "-V"], { encoding: "utf8", timeout: 10000 });
+    if (r.error) {
+        const code = r.error.code;
+        if (code === "ETIMEDOUT")
+            throw new AitermError("WSL が応答しません（初回セットアップ未完了の可能性）。一度 `wsl` を起動してから再実行してください。", 2);
+        if (code === "ENOENT")
+            throw new AitermError("wsl.exe が見つかりません。Windows では WSL 上の tmux 経由で動作します。WSL と tmux を導入してください。", 2);
+        throw new AitermError(`wsl.exe を起動できませんでした（${code ?? "unknown"}）。`, 2);
+    }
+    // wsl.exe は System32 にあるので「起動」は成功するが、ディストリ未導入や distro 内に tmux が無いと
+    // 非ゼロで終わる。両方を区別せず（wsl の出力は UTF-16 で文字化けし得るため）正直に表す。
+    if (r.status !== 0)
+        throw new AitermError("WSL 経由で tmux を起動できませんでした。WSL のディストリ未導入、または distro 内に tmux が無い可能性があります。`wsl tmux -V` が通るか確認してください（tmux 導入例: sudo apt install tmux）。", 2);
+    winBridgeOk = true;
+}
 function tmux(...args) {
     // maxBuffer は既定 1MiB。capture-pane（大きなスクロールバック）や多セッションの list-sessions で
     // 頭打ちになり stdout が切れる/空になる。Python の subprocess.run は無制限だったので 64MiB へ広げる。
-    const r = spawnSync("tmux", ["-S", SOCK, ...args], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    // Windows は同じ tmux を WSL 経由（-e でログインシェル非経由＝$ 展開やクオート崩れを防ぐ）で叩く。
+    let r;
+    if (isWin) {
+        ensureWinBridge();
+        r = spawnSync("wsl.exe", ["-e", "tmux", "-S", SOCK, ...args], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    }
+    else {
+        r = spawnSync("tmux", ["-S", SOCK, ...args], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    }
     // ENOBUFS（出力が 64MiB 超）を「code=1 の失敗」へ握り潰すと部分/空 stdout を正常扱いしてしまう。区別して投げる。
     // EXPECTED-FAILURE: 外部システム境界（tmux 出力過大）
     if (r.error && r.error.code === "ENOBUFS") {
@@ -73,6 +123,12 @@ function paneCurrentCommand(name) {
     const r = tmux("display-message", "-p", "-t", name, "#{pane_current_command}");
     return r.code === 0 ? r.stdout.trim() : "";
 }
+// session 名はファイルパス（logpath 等）と pipe-pane の /bin/sh 文字列へ流れる。英数 _ - のみ・64字に
+// 限定し、パストラバーサル（../）とシェルインジェクション（' でのクオート破り・$・; 等）を全入口で断つ。
+function assertSessionName(name) {
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(name))
+        throw new AitermError(`session 名は英数字と _ - のみ・64文字以内にしてください: ${JSON.stringify(name)}`, 2);
+}
 function logpath(name) {
     return path.join(SOCKDIR, name + ".log");
 }
@@ -111,8 +167,10 @@ function readLastcmd(name) {
     }
 }
 export function attachHint(name) {
+    // Windows は WSL 内 tmux なので、人が打つのは wsl 経由（SOCK は WSL パス）。
+    const cmd = isWin ? `wsl tmux -S ${SOCK} attach -t ${name}` : `tmux -S ${SOCK} attach -t ${name}`;
     return (`このセッションを自分の目で見る/介入する:\n` +
-        `  tmux -S ${SOCK} attach -t ${name}\n` +
+        `  ${cmd}\n` +
         `  （抜けるには Ctrl-b d）`);
 }
 // ---------------------------------------------------------------- 出力削減
@@ -204,6 +262,25 @@ function captureScreen(name, lines) {
     return r.code === 0 ? r.stdout : "";
 }
 const sleep = (ms) => new Promise((res) => setTimeout(res, ms));
+// Windows 専用: pipe-pane のログは /mnt/c (9p) 境界を越えて書かれるため、tmux が完了/セッション
+// 消滅を報告した後も最後の数百バイトが少し遅れて現れる。完了と判定する直前にログサイズが
+// 伸びなくなるまで待ち、readOutput が末尾欠けの出力を返さないようにする（POSIX は同一fsゆえ不要）。
+async function settleWinLog(name) {
+    let prev = -1;
+    for (let i = 0; i < 8; i++) {
+        let sz = 0;
+        try {
+            sz = fs.statSync(logpath(name)).size;
+        }
+        catch {
+            sz = 0;
+        }
+        if (sz === prev)
+            return;
+        prev = sz;
+        await sleep(POLL * 1000);
+    }
+}
 /** 完了境界の4層: dead / until 一致 / (出力静止 ∧ シェルに戻った) / timeout。 */
 async function waitCompletion(name, untilRe, timeout) {
     // 締切は単調時計で測る。Date.now() は NTP 補正やサスペンドで巻き戻り、長時間待ちで誤判定する（Python は time.monotonic）。
@@ -227,12 +304,18 @@ async function waitCompletion(name, untilRe, timeout) {
             if (until.test(stripControl(neu)))
                 return [true, "until"];
         }
-        if (!alive)
+        if (!alive) {
+            if (isWin)
+                await settleWinLog(name);
             return [true, "dead"];
+        }
         if (size === lastSize) {
             stable++;
-            if (stable >= STABLE_POLLS && SHELLS.has(paneCurrentCommand(name)))
+            if (stable >= STABLE_POLLS && SHELLS.has(paneCurrentCommand(name))) {
+                if (isWin)
+                    await settleWinLog(name);
                 return [true, "quiescent"];
+            }
         }
         else {
             stable = 0;
@@ -247,7 +330,10 @@ function rtkRewrite(text) {
     if (text.trim().includes("\n"))
         return text;
     // timeout 無しだと rtk がハングしたとき send() ごと凍結する。Python は timeout=5。
-    const r = spawnSync("rtk", ["rewrite", text], { encoding: "utf8", timeout: 5000, maxBuffer: 1024 * 1024 });
+    // Windows はコマンドが WSL 内で走るので rtk も WSL 側（-e）で評価する。不在は素通し。
+    const r = isWin
+        ? spawnSync("wsl.exe", ["-e", "rtk", "rewrite", text], { encoding: "utf8", timeout: 5000, maxBuffer: 1024 * 1024 })
+        : spawnSync("rtk", ["rewrite", text], { encoding: "utf8", timeout: 5000, maxBuffer: 1024 * 1024 });
     if (r.error)
         return text; // rtk 不在（ENOENT）・タイムアウト（ETIMEDOUT）等は元テキストへ素通し
     if ((r.status === 0 || r.status === 3) && (r.stdout ?? "").trim())
@@ -258,17 +344,24 @@ function rtkRewrite(text) {
 export function openSession(name, shell = "bash") {
     fs.mkdirSync(SOCKDIR, { recursive: true });
     const nm = name || autoName();
+    assertSessionName(nm);
     if (sessionExists(nm))
         throw new AitermError(`session '${nm}' は既に存在します（list で確認）`, 2);
     const r = tmux("new-session", "-d", "-s", nm, "-f", "/dev/null", shell);
     if (r.code !== 0)
         throw new AitermError("tmux new-session 失敗: " + r.stderr.trim(), 2);
     fs.closeSync(fs.openSync(logpath(nm), "a")); // touch
-    tmux("pipe-pane", "-t", nm, "-o", `cat >> ${logpath(nm)}`);
+    // pipe-pane の引数は tmux 内部の /bin/sh -c で再解釈される（argv ではない）。パスは単一引用符で包み、
+    // パス自身の ' は '\'' イディオムでエスケープする（名前は検証済みだが、Windows ユーザー名 O'Brien 等が
+    // 一時パスに ' を持ち込み redirect を壊すのを防ぐ。空白対策も兼ねる）。Windows は WSL から見える /mnt/c 形へ。
+    const pipeTarget = isWin ? toWslPath(logpath(nm)) : logpath(nm);
+    const quoted = `'${pipeTarget.replace(/'/g, "'\\''")}'`;
+    tmux("pipe-pane", "-t", nm, "-o", `cat >> ${quoted}`);
     writeOffset(nm, 0);
     return [nm, attachHint(nm)];
 }
 export function send(name, text, o = {}) {
+    assertSessionName(name);
     const enter = o.enter ?? true;
     if (!sessionExists(name))
         throw new AitermError(`session '${name}' が無い（open してください）`, 2);
@@ -295,6 +388,7 @@ export function send(name, text, o = {}) {
     return `sent ${[...text].length} chars to ${name}` + (enter ? " (+Enter)" : "");
 }
 export function sendKey(name, key) {
+    assertSessionName(name);
     if (!sessionExists(name))
         throw new AitermError(`session '${name}' が無い`, 2);
     const k = KEYMAP[key.toLowerCase()] ?? key;
@@ -302,6 +396,7 @@ export function sendKey(name, key) {
     return `sent key ${k} to ${name}`;
 }
 export async function readOutput(name, o = {}) {
+    assertSessionName(name);
     const timeout = o.timeout ?? DEFAULT_TIMEOUT;
     if (!sessionExists(name) && !fs.existsSync(logpath(name)))
         throw new AitermError(`session '${name}' が無い`, 2);
@@ -333,7 +428,11 @@ export async function readOutput(name, o = {}) {
         }
     }
     else {
-        const off = readOffset(name);
+        let off = readOffset(name);
+        // WSL 再起動等でログが作り直されると、Windows 側に残った旧 offset が新ログ長を超え、
+        // subarray が空を返して「何も読めない」状態になる。末尾越えは先頭から読み直す（POSIX では no-op）。
+        if (off > data.length)
+            off = 0;
         text = data.subarray(off).toString("utf8");
         if (o.lines)
             text = text.split("\n").slice(-o.lines).join("\n");
@@ -373,6 +472,7 @@ export function listSessions() {
     return "(セッション無し)";
 }
 export function closeSession(name) {
+    assertSessionName(name);
     tmux("kill-session", "-t", name);
     for (const p of [logpath(name), offsetpath(name), lastcmdpath(name)]) {
         try {

package/dist/index.js

@@ -12,7 +12,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import * as core from "./core.js";
-const server = new McpServer({ name: "aiterm", version: "0.1.0" });
+const server = new McpServer({ name: "aiterm", version: "0.2.0" });
 function ok(s) {
     return { content: [{ type: "text", text: s }] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "AI-driven persistent terminal as a local stdio MCP server (tmux-backed). Holds one local PTY; SSH and containers are just commands you send into it. Token-reducing reads.",
   "keywords": [
     "mcp",