MCP Adapter

@ai-zen/socket-pty/mcp provides a set of MCP servers (stdio transport) that expose terminal operations as MCP tools.

Positioning: the MCP adapter layer is the manager and relay between an agent and multiple socket-pty processes:

• Does not hold socket-pty processes / does not hold ptys.
• Stateless externally: every tool carries an address (socket address); self-contained, no defaults, no discovery.
• Internal connection-pool reuse: spawn only creates orphan processes; subsequent tools are relayed through the ConnectionPool (connections reused per address).

Registering in an MCP host

{
  "mcpServers": {
    "socket-pty": {
      "command": "npx",
      "args": ["@ai-zen/socket-pty", "mcp"]
    }
  }
}

Tools

Tool	Params	Return
spawn	command, cwd?, cols?, rows?	address (string)
read	address, top?/bottom?/start?+end?	screen text
write	address, action	write success (with byte count)
wait	address, match?, timeout?	match result + screen
resize	address, cols, rows	success/failure
status	address	{ running, exitCode, pid }
kill	address	success/failure

spawn's command and platform

spawn's command follows the same contracts as the CLI / programmatic interface and respects platform constraints:

• On Windows, pass powershell.exe / cmd.exe (with the .exe suffix); passing powershell / bash fails to start (node-pty does not do PATH lookup for bare command names on Windows).

Where spawn's address comes from

spawn has the MCP manager self-allocate a local temporary endpoint and returns that address in the tool result:

• Unix: unix:/tmp/pty-mcp-<pid>-<timestamp>-<random>.sock
• Windows: tcp:127.0.0.1:<port> (probe and allocate a free port first)

That address is allocated and returned by the manager and used as the address parameter for subsequent tools. The session is an orphan process (detached + unref), resident until it is killed; the manager / agent exiting does not affect its lifetime.

spawn's auto-allocation exists only inside MCP — the manager both allocates the address and owns its use, so the address is always within its control. External endpoints (serve / createSocketPty) must be explicitly addressed.

Programmatic use

import { serveMCP, MCPManager, ConnectionPool } from "@ai-zen/socket-pty/mcp";

• serveMCP(): starts a standard MCP server (stdio) and connects to the host.
• MCPManager: provides spawn / read / write / wait / resize / status / kill methods, dispatched via the internal ConnectionPool (connections reused per address, JSON-RPC 2.0) to the corresponding serve process.
• ConnectionPool: a socket connection pool that caches active connections by address, handles JSON-RPC 2.0 envelope framing, dispatch by id, and a timeout fallback (default 15000ms).

You can also start it directly from the CLI: socket-pty mcp (stdio transport, does not talk to anything outside the host).

Related documentation

• Getting Started
• API Reference