@ebowwa/mcp-terminal 1.0.8 → 1.0.9

package/README.md

@@ -166,10 +166,204 @@ curl -X POST http://localhost:8913/mcp \
   }'
 ```
 
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MCP_PORT` | Port for MCP HTTP server | `8913` |
+| `SSH_KEY_PATH` | Path to SSH private key | `~/.ssh/id_rsa` |
+| `SSH_TIMEOUT` | SSH connection timeout (ms) | `30000` |
+| `TMUX_SOCKET_PATH` | Custom tmux socket path | (system default) |
+| `DEBUG_TERMINAL_MCP` | Enable debug logging | `false` |
+
+## Common Workflows
+
+### SSH Connection Testing
+
+```bash
+# Test if a host is reachable
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "test_connection",
+    "args": {
+      "host": "user@server.com"
+    }
+  }'
+```
+
+Response:
+```json
+{
+  "success": true,
+  "host": "user@server.com",
+  "message": "Connection successful"
+}
+```
+
+### Creating and Managing Sessions
+
+```bash
+# 1. Create a session
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "create_session",
+    "args": {
+      "host": "user@server.com",
+      "type": "ssh",
+      "command": "bash"
+    }
+  }'
+
+# Response includes session_id
+
+# 2. Write commands to the session
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "write_command",
+    "args": {
+      "session_id": "abc123",
+      "command": "ls -la /var/log"
+    }
+  }'
+
+# 3. Close session when done
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "close_session",
+    "args": {
+      "session_id": "abc123"
+    }
+  }'
+```
+
+### Parallel SSH Execution
+
+Execute commands on multiple hosts simultaneously:
+
+```bash
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "exec_ssh_parallel",
+    "args": {
+      "hosts": ["web1.example.com", "web2.example.com", "web3.example.com"],
+      "command": "systemctl status nginx"
+    }
+  }'
+```
+
+### File Transfer Operations
+
+```bash
+# Upload a configuration file
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "upload_file",
+    "args": {
+      "host": "user@server.com",
+      "local_path": "./nginx.conf",
+      "remote_path": "/etc/nginx/nginx.conf"
+    }
+  }'
+
+# Download log files
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "download_file",
+    "args": {
+      "host": "user@server.com",
+      "remote_path": "/var/log/app/error.log",
+      "local_path": "./error.log"
+    }
+  }'
+```
+
+### Tmux Session Management
+
+```bash
+# List all tmux sessions on a remote host
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "list_tmux_sessions",
+    "args": {
+      "host": "user@server.com"
+    }
+  }'
+
+# Create a new tmux session
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "create_tmux_session",
+    "args": {
+      "host": "user@server.com",
+      "session_name": "my-app"
+    }
+  }'
+
+# Send command to tmux pane
+curl -X POST http://localhost:8913/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "send_to_tmux_pane",
+    "args": {
+      "host": "user@server.com",
+      "session_name": "my-app",
+      "command": "npm run dev"
+    }
+  }'
+```
+
+## Error Handling
+
+All tools return structured error responses:
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "SSH_CONNECTION_FAILED",
+    "message": "Failed to connect to host",
+    "details": "Connection refused"
+  }
+}
+```
+
+Common error codes:
+- `SSH_CONNECTION_FAILED`: Could not establish SSH connection
+- `SESSION_NOT_FOUND`: Requested session does not exist
+- `INVALID_ARGUMENTS`: Missing or invalid arguments
+- `COMMAND_FAILED`: Command execution failed
+- `FILE_TRANSFER_FAILED`: SCP operation failed
+
 ## Integration with Claude
 
 This MCP server can be integrated with Claude Code or other MCP-compatible clients to provide terminal management capabilities.
 
+### Claude Desktop Configuration
+
+```json
+{
+  "mcpServers": {
+    "terminal": {
+      "command": "bun",
+      "args": ["run", "/path/to/mcp-terminal/src/index.ts"],
+      "env": {
+        "MCP_PORT": "8913",
+        "DEBUG_TERMINAL_MCP": "false"
+      }
+    }
+  }
+}
+```
+
 ## Dependencies
 
 - `node-ssh`: SSH client functionality

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ebowwa/mcp-terminal",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Terminal session management MCP server with SSH, tmux, and file operations",
   "type": "module",
   "main": "stdio.js",
@@ -10,10 +10,15 @@
   "exports": {
     ".": "./stdio.js"
   },
+  "files": [
+    "stdio.js",
+    "README.md"
+  ],
   "scripts": {
     "dev": "bun --hot stdio.ts",
     "start": "bun stdio.ts",
-    "build": "npx esbuild stdio.ts --bundle --external:@ebowwa/terminal --external:@ebowwa/codespaces-types --external:@modelcontextprotocol/sdk --external:zod --platform=node --format=esm --outfile=stdio.js"
+    "build": "npx esbuild stdio.ts --bundle --external:@ebowwa/terminal --external:@ebowwa/codespaces-types --external:@modelcontextprotocol/sdk --external:zod --platform=node --format=esm --outfile=stdio.js",
+    "test": "bun test"
   },
   "keywords": [
     "mcp",
@@ -26,7 +31,7 @@
   "license": "MIT",
   "dependencies": {
     "@ebowwa/codespaces-types": "^1.1.0",
-    "@ebowwa/terminal": "^0.2.0",
+    "@ebowwa/terminal": "^0.3.9",
     "@modelcontextprotocol/sdk": "^1.0.4",
     "zod": "^3.24.1"
   },
@@ -36,5 +41,13 @@
   },
   "peerDependencies": {
     "bun": ">=1.0.0"
+  },
+  "ownership": {
+    "domain": "mcp",
+    "responsibilities": [
+      "terminal-mcp",
+      "ssh-management",
+      "tmux-operations"
+    ]
   }
 }

package/BUG-ANALYSIS.md

@@ -1,148 +0,0 @@
-# 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

@@ -1,67 +0,0 @@
-# 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