@ebowwa/terminal 0.2.0

package/mcp/README.md

@@ -0,0 +1,181 @@
+# Terminal MCP Server
+
+Model Context Protocol server for terminal session management, SSH operations, tmux integration, and file operations.
+
+## Features
+
+- **Session Management**: Create, list, manage terminal sessions
+- **SSH Operations**: Execute commands, test connections, manage SSH pool
+- **Tmux Integration**: List and manage tmux sessions
+- **File Operations**: List, upload, download files via SCP
+- **PTY Operations**: Create and manage PTY sessions
+
+## Installation
+
+```bash
+bun install
+```
+
+## Usage
+
+### Start the MCP Server
+
+```bash
+# Default port 8913
+bun run mcp
+
+# Custom port
+MCP_PORT=8914 bun run mcp
+
+# Dev mode (with port 8913)
+bun run mcp-dev
+```
+
+### Available Tools
+
+#### Session Management
+
+| Tool | Description | Arguments |
+|------|-------------|------------|
+| `list_sessions` | List all active terminal sessions | none |
+| `get_session_info` | Get detailed info about a session | `session_id` |
+| `create_session` | Create a new terminal session | `host`, `type?`, `command?` |
+| `write_command` | Write a command to a session | `session_id`, `command` |
+| `resize_session` | Resize a session terminal | `session_id`, `rows`, `cols` |
+| `close_session` | Close a terminal session | `session_id` |
+
+#### SSH Operations
+
+| Tool | Description | Arguments |
+|------|-------------|------------|
+| `exec_ssh` | Execute command via SSH | `host`, `command`, `options?` |
+| `test_connection` | Test SSH connection | `host` |
+
+#### Tmux Operations
+
+| Tool | Description | Arguments |
+|------|-------------|------------|
+| `list_tmux_sessions` | List all tmux sessions | none |
+
+#### File Operations
+
+| Tool | Description | Arguments |
+|------|-------------|------------|
+| `list_files` | List files on remote host | `host`, `path?` |
+| `upload_file` | Upload file via SCP | `host`, `local_path`, `remote_path` |
+| `download_file` | Download file via SCP | `host`, `remote_path`, `local_path` |
+
+#### Connection Management
+
+| Tool | Description | Arguments |
+|------|-------------|------------|
+| `get_active_connections` | Get active SSH connections | none |
+
+## API Endpoints
+
+### Health Check
+
+```bash
+curl http://localhost:8913/health
+```
+
+Response:
+```json
+{
+  "status": "ok",
+  "port": 8913,
+  "service": "terminal-mcp"
+}
+```
+
+### List Available Tools
+
+```bash
+curl http://localhost:8913/mcp
+```
+
+### Execute Tool
+
+```bash
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "list_sessions",
+    "args": {}
+  }'
+```
+
+## Examples
+
+### List All Sessions
+
+```bash
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"tool": "list_sessions"}'
+```
+
+### Create SSH Session
+
+```bash
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "create_session",
+    "args": {
+      "host": "user@server.com",
+      "type": "ssh"
+    }
+  }'
+```
+
+### Execute SSH Command
+
+```bash
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "exec_ssh",
+    "args": {
+      "host": "user@server.com",
+      "command": "ls -la"
+    }
+  }'
+```
+
+### List Tmux Sessions
+
+```bash
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"tool": "list_tmux_sessions"}'
+```
+
+### Upload File
+
+```bash
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "upload_file",
+    "args": {
+      "host": "user@server.com",
+      "local_path": "/local/file.txt",
+      "remote_path": "/remote/file.txt"
+    }
+  }'
+```
+
+## Integration with Claude
+
+This MCP server can be integrated with Claude Code or other MCP-compatible clients to provide terminal management capabilities.
+
+## Dependencies
+
+- `node-ssh`: SSH client functionality
+- `hono`: HTTP server framework
+- `zod`: Schema validation
+
+## License
+
+MIT

package/mcp/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@ebowwa/terminal-mcp",
+  "version": "1.0.0",
+  "description": "Terminal session management MCP server with SSH, tmux, and file operations",
+  "type": "module",
+  "main": "stdio.ts",
+  "bin": {
+    "terminal-mcp": "stdio.ts"
+  },
+  "scripts": {
+    "dev": "bun --hot stdio.ts",
+    "start": "bun stdio.ts"
+  },
+  "keywords": [
+    "mcp",
+    "terminal",
+    "ssh",
+    "tmux",
+    "session-management"
+  ],
+  "author": "ebowwa",
+  "license": "MIT",
+  "dependencies": {
+    "node-ssh": "^13.2.1",
+    "hono": "^4.11.3",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0"
+  }
+}

package/mcp/test-fix.sh

@@ -0,0 +1,273 @@
+#!/usr/bin/env bash
+#
+# Terminal MCP Fix Test Suite
+# ===========================
+# Tests the recursive loop bug fix for exec_ssh tool
+#
+# BUG DESCRIPTION:
+# The execSSHTool function was calling execSSH with wrong parameter order:
+# - WRONG: execSSH(host, command, options)
+# - RIGHT: execSSH(command, options)
+# - The options parameter must include the 'host' field
+#
+# Author: Test Engineer (team-lead request)
+# Date: 2026-02-05
+#
+
+set -euo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Test configuration
+TEST_TIMEOUT=10  # seconds
+MEMORY_LIMIT_MB=500
+TEST_PORT=8913
+
+# Test results
+TESTS_PASSED=0
+TESTS_FAILED=0
+
+# Safe test commands (read-only, non-destructive)
+SAFE_COMMANDS=(
+    "echo 'test'"
+    "whoami"
+    "pwd"
+    "uname -m"
+    "date +%s"
+)
+
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $*"
+}
+
+log_success() {
+    echo -e "${GREEN}[PASS]${NC} $*"
+    ((TESTS_PASSED++))
+}
+
+log_error() {
+    echo -e "${RED}[FAIL]${NC} $*"
+    ((TESTS_FAILED++))
+}
+
+log_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $*"
+}
+
+# Test 1: Verify MCP server starts correctly
+test_server_startup() {
+    log_info "Test 1: Starting MCP server on port $TEST_PORT..."
+
+    # Start server in background
+    cd /Users/ebowwa/Desktop/codespaces/packages/src/terminal/mcp
+    MCP_PORT=$TEST_PORT bun stdio.ts &
+    SERVER_PID=$!
+
+    # Wait for server to start
+    sleep 2
+
+    # Check if process is still running
+    if ps -p $SERVER_PID > /dev/null 2>&1; then
+        log_success "MCP server started successfully (PID: $SERVER_PID)"
+        echo $SERVER_PID > /tmp/terminal-mcp-test.pid
+        return 0
+    else
+        log_error "MCP server failed to start"
+        return 1
+    fi
+}
+
+# Test 2: Verify no infinite recursion on exec_ssh calls
+test_no_recursion() {
+    log_info "Test 2: Testing for recursive loop bug..."
+
+    # Test each safe command
+    for cmd in "${SAFE_COMMANDS[@]}"; do
+        log_info "  Testing command: $cmd"
+
+        # Create test request
+        cat > /tmp/test_request.json <<EOF
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "exec_ssh",
+    "arguments": {
+      "host": "localhost",
+      "command": "$cmd"
+    }
+  }
+}
+EOF
+
+        # Execute with timeout to catch infinite loops
+        timeout $TEST_TIMEOUT cat /tmp/test_request.json | \
+            MCP_PORT=$TEST_PORT bun stdio.ts > /tmp/test_response.json 2>&1 || {
+            log_error "Command timed out or failed: $cmd"
+            cat /tmp/test_response.json
+            return 1
+        }
+
+        # Check response
+        if grep -q '"result"' /tmp/test_response.json; then
+            log_success "Command executed without recursion: $cmd"
+        else
+            log_error "Invalid response for command: $cmd"
+            cat /tmp/test_response.json
+            return 1
+        fi
+    done
+
+    return 0
+}
+
+# Test 3: Memory leak detection
+test_memory_leak() {
+    log_info "Test 3: Testing for memory leaks..."
+
+    # Get initial memory
+    local initial_mem=$(ps -o rss= -p $SERVER_PID 2>/dev/null || echo "0")
+
+    # Execute multiple commands
+    for i in {1..50}; do
+        echo "echo 'iteration-$i'" | \
+            MCP_PORT=$TEST_PORT bun stdio.ts > /dev/null 2>&1
+    done
+
+    # Get final memory
+    local final_mem=$(ps -o rss= -p $SERVER_PID 2>/dev/null || echo "0")
+
+    # Calculate memory growth (in MB)
+    local mem_growth=$(( ($final_mem - $initial_mem) / 1024 ))
+
+    log_info "  Memory growth: ${mem_growth}MB"
+
+    if [ $mem_growth -lt $MEMORY_LIMIT_MB ]; then
+        log_success "Memory usage within acceptable limits"
+        return 0
+    else
+        log_error "Excessive memory growth detected: ${mem_growth}MB"
+        return 1
+    fi
+}
+
+# Test 4: Parameter validation
+test_parameter_validation() {
+    log_info "Test 4: Testing parameter validation..."
+
+    # Test with missing host parameter
+    cat > /tmp/test_invalid.json <<EOF
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/call",
+  "params": {
+    "name": "exec_ssh",
+    "arguments": {
+      "command": "echo test"
+    }
+  }
+}
+EOF
+
+    timeout 5 cat /tmp/test_invalid.json | \
+        MCP_PORT=$TEST_PORT bun stdio.ts > /tmp/test_invalid_response.json 2>&1
+
+    if grep -q '"error"' /tmp/test_invalid_response.json || \
+       grep -q 'required' /tmp/test_invalid_response.json; then
+        log_success "Parameter validation working correctly"
+        return 0
+    else
+        log_warning "Parameter validation may not be working"
+        return 1
+    fi
+}
+
+# Test 5: List available tools
+test_list_tools() {
+    log_info "Test 5: Listing available tools..."
+
+    cat > /tmp/test_list.json <<EOF
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/list"
+}
+EOF
+
+    timeout 5 cat /tmp/test_list.json | \
+        MCP_PORT=$TEST_PORT bun stdio.ts > /tmp/test_list_response.json 2>&1
+
+    if grep -q '"tools"' /tmp/test_list_response.json && \
+       grep -q '"exec_ssh"' /tmp/test_list_response.json; then
+        log_success "Tools list includes exec_ssh"
+        return 0
+    else
+        log_error "Tools list incomplete"
+        cat /tmp/test_list_response.json
+        return 1
+    fi
+}
+
+# Cleanup function
+cleanup() {
+    log_info "Cleaning up..."
+
+    # Kill server if running
+    if [ -f /tmp/terminal-mcp-test.pid ]; then
+        SERVER_PID=$(cat /tmp/terminal-mcp-test.pid)
+        if ps -p $SERVER_PID > /dev/null 2>&1; then
+            kill $SERVER_PID 2>/dev/null || true
+            log_info "Killed MCP server (PID: $SERVER_PID)"
+        fi
+        rm -f /tmp/terminal-mcp-test.pid
+    fi
+
+    # Clean up test files
+    rm -f /tmp/test_*.json
+
+    # Display results
+    echo ""
+    echo "==================================="
+    echo "Test Results Summary"
+    echo "==================================="
+    echo -e "Passed: ${GREEN}${TESTS_PASSED}${NC}"
+    echo -e "Failed: ${RED}${TESTS_FAILED}${NC}"
+    echo "==================================="
+
+    if [ $TESTS_FAILED -eq 0 ]; then
+        echo -e "${GREEN}All tests passed!${NC}"
+        exit 0
+    else
+        echo -e "${RED}Some tests failed!${NC}"
+        exit 1
+    fi
+}
+
+# Trap cleanup on exit
+trap cleanup EXIT
+
+# Main test execution
+main() {
+    log_info "Terminal MCP Fix Test Suite"
+    log_info "=============================="
+    echo ""
+
+    # Run tests
+    test_server_startup || exit 1
+    test_list_tools || true
+    test_no_recursion || true
+    test_memory_leak || true
+    test_parameter_validation || true
+
+    # Cleanup will be called by trap
+}
+
+# Run main function
+main "$@"

package/package.json

@@ -0,0 +1,118 @@
+{
+  "name": "@ebowwa/terminal",
+  "version": "0.2.0",
+  "description": "Terminal session management with tmux integration, SSH client, WebSocket support, and MCP interface",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./sessions": {
+      "types": "./dist/sessions.d.ts",
+      "default": "./dist/sessions.js"
+    },
+    "./tmux": {
+      "types": "./dist/tmux.d.ts",
+      "default": "./dist/tmux.js"
+    },
+    "./manager": {
+      "types": "./dist/manager.d.ts",
+      "default": "./dist/manager.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "default": "./dist/api.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
+    "./pool": {
+      "types": "./dist/pool.d.ts",
+      "default": "./dist/pool.js"
+    },
+    "./exec": {
+      "types": "./dist/exec.d.ts",
+      "default": "./dist/exec.js"
+    },
+    "./pty": {
+      "types": "./dist/pty.d.ts",
+      "default": "./dist/pty.js"
+    },
+    "./files": {
+      "types": "./dist/files.d.ts",
+      "default": "./dist/files.js"
+    },
+    "./scp": {
+      "types": "./dist/scp.d.ts",
+      "default": "./dist/scp.js"
+    },
+    "./fingerprint": {
+      "types": "./dist/fingerprint.d.ts",
+      "default": "./dist/fingerprint.js"
+    },
+    "./tmux-exec": {
+      "types": "./dist/tmux-exec.d.ts",
+      "default": "./dist/tmux-exec.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./network-error-detector": {
+      "types": "./dist/network-error-detector.d.ts",
+      "default": "./dist/network-error-detector.js"
+    },
+    "./mcp": {
+      "types": "./src/mcp/index.ts",
+      "default": "./dist/mcp/index.js"
+    }
+  },
+  "scripts": {
+    "mcp": "bun run src/mcp/index.ts",
+    "mcp-dev": "MCP_PORT=8913 bun run src/mcp/index.ts",
+    "mcp-stdio": "bun run src/mcp/stdio.ts"
+  },
+  "keywords": [
+    "terminal",
+    "tmux",
+    "ssh",
+    "session",
+    "websocket",
+    "mcp",
+    "pty",
+    "cli",
+    "remote"
+  ],
+  "author": "Ebowwa Labs <labs@ebowwa.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/ebowwa/terminal#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ebowwa/terminal.git",
+    "directory": "/"
+  },
+  "bugs": {
+    "url": "https://github.com/ebowwa/terminal/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@ebowwa/codespaces-types": "^1.1.0",
+    "node-ssh": "^13.2.1",
+    "hono": "^4.11.3",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node-ssh": "^11.0.0"
+  }
+}