@ebowwa/mcp-terminal 1.0.8

package/BUG-ANALYSIS.md

@@ -0,0 +1,148 @@
+# Terminal MCP Recursive Loop Bug Analysis
+
+## Date: 2026-02-05
+## Team: terminal-mcp-fix
+## Status: Analysis Complete
+
+---
+
+## Bug Description
+
+The `execSSHTool` function in `/packages/src/terminal/mcp/stdio.ts` has a **parameter order mismatch** causing recursive loop behavior.
+
+### Location of Bug
+
+**File:** `/packages/src/terminal/mcp/stdio.ts`
+**Line:** 223-225
+
+```typescript
+async function execSSHTool(host: string, command: string, options?: Partial<SSHOptions>): Promise<string> {
+  try {
+    const result = await execSSH(host, command, options);  // ❌ WRONG PARAMETER ORDER
+    return result.stdout || result.stderr || "Command executed";
+```
+
+### Root Cause
+
+**Function Signature Mismatch:**
+
+The `execSSH` function from `client.ts` expects:
+```typescript
+export async function execSSH(
+  command: string,        // 1st param: command string
+  options: SSHOptions,    // 2nd param: SSH options including host
+): Promise<string>
+```
+
+But `execSSHTool` calls it with:
+```typescript
+execSSH(host, command, options)  // ❌ WRONG
+```
+
+### Impact
+
+1. **Wrong command execution:** The `host` string is executed as a shell command
+2. **Options misinterpretation:** The actual `command` is treated as SSH options
+3. **Potential recursion:** If options contain objects that trigger re-execution
+4. **Silent failures:** Errors may be masked by fallback return values
+
+---
+
+## Fix Required
+
+### Option 1: Fix the call (RECOMMENDED)
+
+```typescript
+async function execSSHTool(host: string, command: string, options?: Partial<SSHOptions>): Promise<string> {
+  try {
+    const result = await execSSH(command, {  // ✅ CORRECT ORDER
+      ...options,
+      host,
+    });
+    return result.stdout || result.stderr || "Command executed";
+  } catch (error) {
+    throw new Error(`SSH command failed: ${error}`);
+  }
+}
+```
+
+### Option 2: Change function signature (ALTERNATIVE)
+
+```typescript
+async function execSSHTool(command: string, options: SSHOptions): Promise<string> {
+  try {
+    const result = await execSSH(command, options);  // ✅ MATCHES SIGNATURE
+    return result.stdout || result.stderr || "Command executed";
+  } catch (error) {
+    throw new Error(`SSH command failed: ${error}`);
+  }
+}
+```
+
+---
+
+## Test Coverage
+
+### Test Suite Location
+
+`/packages/src/terminal/mcp/test-fix.sh`
+
+### Test Cases
+
+1. **Server Startup:** Verify MCP server starts without errors
+2. **No Recursion:** Execute safe commands and detect infinite loops
+3. **Memory Leaks:** Monitor memory growth over multiple executions
+4. **Parameter Validation:** Test missing/invalid parameter handling
+5. **Tool Discovery:** Verify `exec_ssh` appears in tools list
+
+### Safe Test Commands
+
+```bash
+echo 'test'     # Safe echo
+whoami         # Current user
+pwd            # Current directory
+uname -m       # Machine architecture
+date +%s       # Unix timestamp
+```
+
+---
+
+## Risk Assessment
+
+### Severity: HIGH
+
+- **Impact:** Can execute hostnames as shell commands
+- **Scope:** Affects all `exec_ssh` tool calls via MCP
+- **Exploitability:** High if user-provided hosts are not validated
+
+### Mitigation
+
+1. Apply fix immediately to `stdio.ts`
+2. Add unit tests for parameter validation
+3. Add integration tests for exec_ssh tool
+4. Review all MCP tool implementations for similar issues
+
+---
+
+## Related Files
+
+- `/packages/src/terminal/mcp/stdio.ts` - **NEEDS FIX**
+- `/packages/src/terminal/mcp/index.ts` - May have same issue
+- `/packages/src/terminal/client.ts` - Reference implementation
+- `/packages/src/terminal/mcp/test-fix.sh` - Test suite
+
+---
+
+## Next Steps
+
+1. ✅ Analysis complete
+2. ⏳ Fixers implementing fix
+3. ⏳ Testers running test suite
+4. ⏳ Verify no regression
+5. ⏳ Deploy to production
+
+---
+
+**Author:** Test Engineer
+**Reviewed by:** team-lead
+**Priority:** CRITICAL

package/FIX-QUICK-REF.md

@@ -0,0 +1,67 @@
+# Terminal MCP Fix - Quick Reference
+
+## TL;DR
+
+**File:** `stdio.ts` line 225
+**Bug:** Wrong parameter order to `execSSH()`
+**Fix:** Swap parameters to match function signature
+
+---
+
+## The Fix
+
+### BEFORE (Line 223-225):
+```typescript
+async function execSSHTool(host: string, command: string, options?: Partial<SSHOptions>): Promise<string> {
+  try {
+    const result = await execSSH(host, command, options);  // ❌ WRONG
+```
+
+### AFTER:
+```typescript
+async function execSSHTool(host: string, command: string, options?: Partial<SSHOptions>): Promise<string> {
+  try {
+    const result = await execSSH(command, {  // ✅ CORRECT
+      ...options,
+      host,
+    });
+```
+
+---
+
+## Why This Works
+
+The `execSSH` function signature is:
+```typescript
+execSSH(command: string, options: SSHOptions)
+```
+
+So we need to pass:
+1. `command` as first parameter
+2. Object with `host` field merged with `options` as second parameter
+
+---
+
+## Same Issue in index.ts
+
+**File:** `index.ts` line 215
+
+Same fix needed there too!
+
+---
+
+## Testing
+
+After fix, run:
+```bash
+cd /Users/ebowwa/Desktop/codespaces/packages/src/terminal/mcp
+./test-fix.sh
+```
+
+---
+
+## Status
+
+- ✅ Analysis complete
+- ⏳ Fix pending
+- ⏳ Test suite ready

package/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