@ellery/terminal-mcp 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ellery Familia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+<p align="center">
+  <img src="logo.png" alt="Terminal MCP" width="600">
+</p>
+
+<p align="center">
+  A headless terminal emulator exposed via MCP (Model Context Protocol), enabling AI assistants to interact with terminal applications programmatically.
+</p>
+
+## Quick Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/elleryfamilia/terminal-mcp/main/install.sh | bash
+```
+
+## Features
+
+- **Full Terminal Emulation**: Uses xterm.js headless for accurate VT100/ANSI emulation
+- **Cross-Platform PTY**: Native pseudo-terminal support via node-pty (macOS, Linux, Windows)
+- **MCP Protocol**: Implements Model Context Protocol for AI assistant integration
+- **Simple API**: Four intuitive tools for complete terminal control
+
+## Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+```
+
+## Usage
+
+### MCP Configuration
+
+Add to your MCP client settings:
+
+```json
+{
+  "mcpServers": {
+    "terminal": {
+      "command": "terminal-mcp"
+    }
+  }
+}
+```
+
+With custom options:
+
+```json
+{
+  "mcpServers": {
+    "terminal": {
+      "command": "terminal-mcp",
+      "args": ["--cols", "100", "--rows", "30", "--shell", "/bin/zsh"]
+    }
+  }
+}
+```
+
+### Command-Line Options
+
+```
+terminal-mcp [OPTIONS]
+
+Options:
+  --cols <number>   Terminal width in columns (default: 120)
+  --rows <number>   Terminal height in rows (default: 40)
+  --shell <path>    Shell to use (default: $SHELL or bash)
+  --help, -h        Show help message
+```
+
+## MCP Tools
+
+### `type`
+Send text input to the terminal.
+
+```json
+{
+  "name": "type",
+  "arguments": {
+    "text": "echo hello"
+  }
+}
+```
+
+### `sendKey`
+Send special keys or key combinations.
+
+```json
+{
+  "name": "sendKey",
+  "arguments": {
+    "key": "Enter"
+  }
+}
+```
+
+Supported keys:
+- Basic: `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`
+- Arrow: `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`
+- Navigation: `Home`, `End`, `PageUp`, `PageDown`, `Insert`
+- Function: `F1` through `F12`
+- Control: `Ctrl+A` through `Ctrl+Z`, `Ctrl+C`, `Ctrl+D`, etc.
+
+### `getContent`
+Get the terminal buffer as plain text.
+
+```json
+{
+  "name": "getContent",
+  "arguments": {
+    "visibleOnly": false
+  }
+}
+```
+
+### `takeScreenshot`
+Capture the terminal state with cursor position and dimensions.
+
+```json
+{
+  "name": "takeScreenshot",
+  "arguments": {}
+}
+```
+
+## Architecture
+
+```
+MCP Client (Claude Code, etc.)
+    │ STDIO (JSON-RPC)
+    ▼
+Terminal MCP Server (Node.js)
+    ├── MCP SDK (@modelcontextprotocol/sdk)
+    ├── Terminal Emulator (@xterm/headless)
+    └── PTY Manager (node-pty)
+            │
+            ▼
+        Shell Process (bash, zsh, etc.)
+```
+
+## Example Session
+
+```bash
+# Type a command
+{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"type","arguments":{"text":"ls -la"}}}
+
+# Send Enter key
+{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"sendKey","arguments":{"key":"Enter"}}}
+
+# Get the output
+{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"getContent","arguments":{}}}
+```
+
+## Development
+
+### Project Structure
+
+```
+terminal-mcp/
+├── src/
+│   ├── index.ts              # Entry point with CLI
+│   ├── server.ts             # MCP server setup
+│   ├── terminal/
+│   │   ├── index.ts          # Exports
+│   │   ├── session.ts        # PTY + xterm integration
+│   │   └── manager.ts        # Session lifecycle
+│   ├── tools/
+│   │   ├── index.ts          # Tool registry
+│   │   ├── type.ts           # type tool
+│   │   ├── sendKey.ts        # sendKey tool
+│   │   ├── getContent.ts     # getContent tool
+│   │   └── screenshot.ts     # takeScreenshot tool
+│   └── utils/
+│       └── keys.ts           # Key code mappings
+├── docs/                     # Documentation
+├── package.json
+└── tsconfig.json
+```
+
+### Building
+
+```bash
+npm run build    # Compile TypeScript
+npm run dev      # Run with tsx (development)
+```
+
+## Documentation
+
+See the [docs](./docs/) folder for detailed documentation:
+
+- [Overview](./docs/index.md)
+- [Installation](./docs/installation.md)
+- [Tools Reference](./docs/tools.md)
+- [Configuration](./docs/configuration.md)
+- [Examples](./docs/examples.md)
+- [Architecture](./docs/architecture.md)
+
+## Requirements
+
+- Node.js 18.0.0 or later
+- Build tools for native module compilation (node-pty)
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,5 @@
+/**
+ * MCP Client Mode - connects to existing terminal socket and serves MCP over stdio
+ */
+export declare function startMcpClientMode(socketPath: string): Promise<void>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAoBA;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoL1E"}

package/dist/client.js

@@ -0,0 +1,185 @@
+import * as net from "net";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * MCP Client Mode - connects to existing terminal socket and serves MCP over stdio
+ */
+export async function startMcpClientMode(socketPath) {
+    // Connect to the interactive terminal's socket
+    const socket = await connectToSocket(socketPath);
+    // Create MCP server
+    const server = new Server({
+        name: "terminal-mcp",
+        version: "0.1.0",
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Request ID counter
+    let requestId = 0;
+    // Pending requests waiting for responses
+    const pendingRequests = new Map();
+    // Buffer for incoming data
+    let buffer = "";
+    // Handle responses from the interactive terminal
+    socket.on("data", (data) => {
+        buffer += data.toString();
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+            if (line.trim()) {
+                try {
+                    const response = JSON.parse(line);
+                    const pending = pendingRequests.get(response.id);
+                    if (pending) {
+                        pendingRequests.delete(response.id);
+                        if (response.error) {
+                            pending.reject(new Error(response.error.message));
+                        }
+                        else {
+                            pending.resolve(response.result);
+                        }
+                    }
+                }
+                catch {
+                    // Ignore parse errors
+                }
+            }
+        }
+    });
+    socket.on("error", (error) => {
+        console.error("Socket error:", error.message);
+        process.exit(1);
+    });
+    socket.on("close", () => {
+        console.error("Socket closed");
+        process.exit(1);
+    });
+    // Helper to send request to interactive terminal
+    async function sendRequest(method, params) {
+        const id = ++requestId;
+        const request = { id, method, params };
+        return new Promise((resolve, reject) => {
+            pendingRequests.set(id, { resolve, reject });
+            socket.write(JSON.stringify(request) + "\n", (error) => {
+                if (error) {
+                    pendingRequests.delete(id);
+                    reject(error);
+                }
+            });
+        });
+    }
+    // Define tools that proxy to the interactive terminal
+    const tools = [
+        {
+            name: "type",
+            description: "Type text into the terminal",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    text: {
+                        type: "string",
+                        description: "The text to type",
+                    },
+                },
+                required: ["text"],
+            },
+        },
+        {
+            name: "sendKey",
+            description: "Send a special key to the terminal (e.g., enter, tab, ctrl+c)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    key: {
+                        type: "string",
+                        description: "The key to send (e.g., enter, tab, escape, up, down, left, right, ctrl+c, ctrl+d)",
+                    },
+                },
+                required: ["key"],
+            },
+        },
+        {
+            name: "getContent",
+            description: "Get the current content of the terminal buffer",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    visibleOnly: {
+                        type: "boolean",
+                        description: "If true, only return visible content (default: false)",
+                    },
+                },
+            },
+        },
+        {
+            name: "takeScreenshot",
+            description: "Take a screenshot of the terminal showing current screen and cursor position",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+        {
+            name: "clear",
+            description: "Clear the terminal screen",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+    ];
+    // Register list tools handler
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools,
+    }));
+    // Register call tool handler - proxy to socket
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            const result = await sendRequest(name, args);
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Connect MCP server to stdio
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+/**
+ * Connect to the interactive terminal's socket
+ */
+function connectToSocket(socketPath) {
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection(socketPath, () => {
+            resolve(socket);
+        });
+        socket.on("error", (error) => {
+            if (error.code === "ENOENT") {
+                reject(new Error(`No tmcp session found at ${socketPath}.\n` +
+                    `Start an interactive session first by running: tmcp`));
+            }
+            else if (error.code === "ECONNREFUSED") {
+                reject(new Error(`Connection refused to ${socketPath}.\n` +
+                    `The tmcp session may have crashed. Try restarting it.`));
+            }
+            else {
+                reject(error);
+            }
+        });
+    });
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { startMcpClientMode } from "./client.js";
+import { TerminalManager } from "./terminal/index.js";
+import { createToolProxyServer } from "./transport/index.js";
+import { printBanner, printInfo, isInfoCommand } from "./ui/index.js";
+import { getStats, resetStats } from "./utils/stats.js";
+// Default socket path
+const DEFAULT_SOCKET_PATH = path.join(os.tmpdir(), "terminal-mcp.sock");
+// Parse command line arguments
+const args = process.argv.slice(2);
+const options = {};
+for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const next = args[i + 1];
+    switch (arg) {
+        case "--cols":
+            if (next) {
+                options.cols = parseInt(next, 10);
+                i++;
+            }
+            break;
+        case "--rows":
+            if (next) {
+                options.rows = parseInt(next, 10);
+                i++;
+            }
+            break;
+        case "--shell":
+            if (next) {
+                options.shell = next;
+                i++;
+            }
+            break;
+        case "--socket":
+            if (next) {
+                options.socket = next;
+                i++;
+            }
+            break;
+        case "--help":
+        case "-h":
+            console.log(`
+terminal-mcp - A headless terminal emulator exposed via MCP
+
+Usage: terminal-mcp [options]
+
+Options:
+  --cols <number>     Terminal width in columns (default: auto or 120)
+  --rows <number>     Terminal height in rows (default: auto or 40)
+  --shell <path>      Shell to use (default: $SHELL or bash)
+  --socket <path>     Unix socket path for MCP (default: ${DEFAULT_SOCKET_PATH})
+  --help, -h          Show this help message
+
+Mode Detection:
+  - If stdin is a TTY: Interactive mode (gives you a shell, exposes socket)
+  - If stdin is not a TTY: MCP client mode (connects to socket, serves MCP)
+
+Interactive Mode (run in your terminal):
+  terminal-mcp
+
+  This gives you an interactive shell. AI can observe/interact via MCP.
+  Type /info for the MCP configuration to add to your MCP client.
+
+MCP Client Mode (add to your MCP client config):
+  {
+    "mcpServers": {
+      "terminal": {
+        "command": "terminal-mcp"
+      }
+    }
+  }
+`);
+            process.exit(0);
+    }
+}
+async function main() {
+    const socketPath = options.socket || DEFAULT_SOCKET_PATH;
+    const isInteractive = process.stdin.isTTY;
+    if (isInteractive) {
+        // Interactive mode: Shell on stdin/stdout, tool proxy on Unix socket
+        await startInteractiveMode(socketPath);
+    }
+    else {
+        // MCP client mode: Connect to socket, serve MCP over stdio
+        await startMcpClientMode(socketPath);
+    }
+}
+async function startInteractiveMode(socketPath) {
+    // Initialize stats
+    resetStats();
+    // Get terminal size from environment or use defaults
+    const cols = options.cols ?? (process.stdout.columns || 120);
+    const rows = options.rows ?? (process.stdout.rows || 40);
+    const shell = options.shell || process.env.SHELL || "/bin/bash";
+    // Print startup banner
+    printBanner({ socketPath, cols, rows, shell });
+    // Create terminal manager (prompt customization handled in session.ts)
+    const manager = new TerminalManager({
+        cols,
+        rows,
+        shell: options.shell,
+    });
+    // Get the session and set up interactive I/O
+    const session = manager.getSession();
+    // Pipe PTY output to stdout
+    session.onData((data) => {
+        process.stdout.write(data);
+    });
+    // Handle PTY exit
+    session.onExit((code) => {
+        console.log(`\n[terminal-mcp] Shell exited with code ${code}`);
+        cleanup();
+        process.exit(code);
+    });
+    // Set up raw mode for stdin if it's a TTY
+    if (process.stdin.isTTY) {
+        process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+    // Buffer for detecting /info command
+    let inputBuffer = "";
+    // Pipe stdin to PTY, with /info command detection
+    process.stdin.on("data", (data) => {
+        const str = data.toString();
+        // Check for /info command (detect when user types /info and presses enter)
+        // In raw mode, we need to buffer input to detect the command
+        for (const char of str) {
+            if (char === "\r" || char === "\n") {
+                // Check if buffer is /info command
+                if (isInfoCommand(inputBuffer)) {
+                    // Print info and clear the line
+                    process.stdout.write("\r\n");
+                    printInfo(socketPath, cols, rows, shell, getStats());
+                    inputBuffer = "";
+                    // Write newline to shell to maintain prompt
+                    session.write("\n");
+                    continue;
+                }
+                inputBuffer = "";
+                session.write(char);
+            }
+            else if (char === "\x7f" || char === "\b") {
+                // Backspace
+                inputBuffer = inputBuffer.slice(0, -1);
+                session.write(char);
+            }
+            else {
+                inputBuffer += char;
+                session.write(char);
+            }
+        }
+    });
+    // Handle terminal resize
+    process.stdout.on("resize", () => {
+        const newCols = process.stdout.columns || cols;
+        const newRows = process.stdout.rows || rows;
+        session.resize(newCols, newRows);
+    });
+    // Start tool proxy socket server
+    const socketServer = createToolProxyServer(socketPath, manager);
+    // Cleanup function
+    function cleanup() {
+        manager.dispose();
+        socketServer.close();
+        try {
+            fs.unlinkSync(socketPath);
+        }
+        catch {
+            // Ignore
+        }
+    }
+    // Handle signals
+    process.on("SIGINT", () => {
+        // Pass Ctrl+C to the shell instead of exiting
+        session.write("\x03");
+    });
+    process.on("SIGTERM", () => {
+        cleanup();
+        process.exit(0);
+    });
+    process.on("exit", () => {
+        cleanup();
+    });
+}
+main().catch((error) => {
+    console.error("Failed to start:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/prompts/index.d.ts

@@ -0,0 +1,3 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare function registerPrompts(server: Server): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/prompts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AA+DnE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAwBpD"}