Menager MCP Server

Part of the HeLa MCP Ecosystem — This server is HeLa Ribosome (hela-ribosome) — the PTY Harness component of the HeLa cellular architecture. See the ecosystem docs for profiles, workflows, and multi-client setup.

menager is a TypeScript-based Model Context Protocol (MCP) server designed for inter-session terminal orchestration. It enables an AI agent session (or human operator) to act as a master control plane capable of spawning, monitoring, driving, and hooking into child terminal harnesses (CLI tools, secondary AI agents, interactive shells, or polyglot runtimes) via standard POSIX pseudo-terminals (pty).

Table of Contents

• Features

• Installation

• Usage

  • Starting the Server

• Available Tools

  • Generic PTY

  • OpenCode Native Orchestration

• Configuring with AI Assistants

Related MCP server: pty-mcp

Features

• Polyglot Harness Multiplexing: Drive interactive processes written in any language via standard POSIX pseudo-terminals.

• Simulated Human Typing: Inject text, control sequences (SIGINT, EOF, Ctrl+C), and raw keystrokes seamlessly into child stdin.

• Predictable Event Interception: Provide non-blocking regex hooks with timeout guarantees and optional immediate auto-responses.

• Memory-Bounded Observability: Maintain dedicated circular buffers per session (default 5,000 lines) with real-time ANSI-stripping for token-efficient LLM context consumption.

• Strict Asynchrony & Resource Discipline: Event handling remains purely event-driven using Node.js event emitters and promises; buffer bounds are strictly enforced to prevent memory leaks.

Installation

Manual Installation

# Clone the repository
git clone <your-repo-url>
cd menager

# Install dependencies (requires build-essential/g++ for node-pty native bindings)
npm install

# Build the project
npm run build

Usage

Starting the Server

The server runs via Stdio transport, intended to be executed directly by MCP clients.

# Start the server (standard mode)
npm start

# Or run the built file directly
node build/index.js

Available Tools

Generic PTY

session_spawn

Spawns a new child PTY session.

• command (string): Target binary or executable (e.g., bash, python3). Required.

• args (string[]): Command line arguments.

• cwd (string): Working directory path.

• env (object): Additional environment variables.

• maxBufferLines (number): Rolling line limit for memory buffers (default 5000).

• terminalType (string): Terminal emulation type ("dumb" or "xterm-256color", default "xterm-256color").

• name (string): Optional logical name/label for the session.

• cols (number): Terminal columns (default 80).

• rows (number): Terminal rows (default 24).

session_wait

Blocks and waits for a session to exit gracefully, returning its final exit code.

• sessionId (string): Target session ID. Required.

• timeoutMs (number): Optional timeout in milliseconds.

session_write

Injects keystrokes, commands, or escape sequences into the session's standard input.

• sessionId (string): Target session ID. Required.

• payload (string): String or control character sequence. Required.

• pressEnter (boolean): Append \n to the payload (default false - Breaking Change in v4).

• pressKey (string): Special key injection (Ctrl+C, Ctrl+D, Enter, Tab, Escape, ArrowUp, ArrowDown).

session_read

Reads buffered output from the target session.

• sessionId (string): Target session ID. Required.

• tailLines (number): Number of trailing lines to retrieve (default 100).

• stripAnsi (boolean): Return sanitized text without ANSI codes (default true).

• clearBuffer (boolean): Flush internal buffers after read (default false).

• offsetLines (number): Read lines starting from this absolute index offset (replaces tailLines).

• grepPattern (string): Pre-filter buffer lines via Regex string matching.

session_hook

Awaits a specific regex pattern on the session stream with optional automated reply.

• sessionId (string): Target session ID. Required.

• pattern (string): Regular expression string to observe. Required.

• timeoutMs (number): Milliseconds before timing out (default 30000).

• autoResponse (string): Optional string to immediately write on match.

• triggerPayload (string): Write payload after hook registers (prevents concurrency deadlock).

session_resize

Resizes the target PTY terminal dimensions.

• sessionId (string): Target session ID. Required.

• cols (number): Terminal columns. Required.

• rows (number): Terminal rows. Required.

session_signal

Sends a POSIX signal to the target session (with recursive process-tree termination).

• sessionId (string): Target session ID. Required.

• signal (string): Signal to deliver (SIGINT, SIGTERM, SIGKILL). Required.

session_close

Force kills the session's process tree and deletes memory buffers immediately.

• sessionId (string): Target session ID. Required.

session_prune

Force deletes sessions to free memory.

• status (string): Only delete sessions with this status ("running" or "exited"). Defaults to "exited".

session_info

Returns a single session's live metadata and metrics.

• sessionId (string): Target session ID. Required.

session_list

Lists all active and completed sessions managed by the server. No parameters required.

OpenCode Native Orchestration

Native opencode CLI integration (see CLI docs) for agent routing and multi-session orchestration. Each spawned agent lives in its own PTY session with meta.kind: "agent" tracking (agent, model, dir, resolved opencode session id).

Deliberately excluded: tui (interactive), auth login/logout (interactive secrets), upgrade/uninstall (host-destructive), github/plugin/pr (repo admin — run directly).

Set a custom binary via OPENCODE_BIN env (default opencode). Prompts are capped at 8000 chars; agent/model values are strictly validated (agent alphanumerics, model as provider/model); all subprocesses spawn with shell: false (no shell injection).

HeLa session quotas & run linkage (P0-B4, all opt-in overrides)

session_spawn/agent_spawn accept optional run_id/step_id linking the session to a Mitosis RunStore run; the ids are also inherited from HELA_RUN_ID/HELA_STEP_ID env and propagated to child processes. linkRun attaches a run id to an existing session.

Configuring with AI Assistants

Configuring with Roo Code or Cline

1. Open the MCP settings file (usually cline_mcp_settings.json or config.json).

2. Add the following configuration for standard stdio mode:

{
  "mcpServers": {
    "menager-mcp": {
      "command": "node",
      "args": ["/path/to/menager-mcp/build/index.js"],
      "env": {}
    }
  }
}

Configuring with Claude Desktop

1. Open claude_desktop_config.json.

2. Add the following configuration:

{
  "mcpServers": {
    "menager-mcp": {
      "command": "node",
      "args": ["/path/to/menager-mcp/build/index.js"],
      "env": {}
    }
  }
}