@prmichaelsen/acp-mcp 0.7.1 → 1.0.0

package/CHANGELOG.md

@@ -5,6 +5,63 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0] - 2026-02-24
+
+### Removed
+- **BREAKING**: Removed `acp_remote_list_files`, `acp_remote_read_file`, and `acp_remote_write_file` tools
+  - All SFTP-based tools had fundamental issues with path expansion (didn't expand `~`)
+  - SFTP implementation was unreliable, complex, and had multiple edge cases
+  - `acp_remote_execute_command` with shell commands is more reliable and flexible
+  - Single tool approach is simpler and more maintainable
+
+### Migration Guide
+
+**Before (v0.x)**:
+```typescript
+// List files
+acp_remote_list_files({ path: "~/project", recursive: false })
+
+// Read file
+acp_remote_read_file({ path: "~/project/package.json" })
+
+// Write file
+acp_remote_write_file({ path: "~/project/file.txt", content: "hello" })
+```
+
+**After (v1.0.0)**:
+```typescript
+// List files - use ls, find, or tree
+acp_remote_execute_command({ command: "ls -la ~/project" })
+acp_remote_execute_command({ command: "find ~/project -type f" })
+acp_remote_execute_command({ command: "tree ~/project" })
+
+// Read file - use cat
+acp_remote_execute_command({ command: "cat ~/project/package.json" })
+
+// Write file - use echo or tee
+acp_remote_execute_command({ command: "echo 'hello' > ~/project/file.txt" })
+// Or for multi-line:
+acp_remote_execute_command({ command: "cat > ~/project/file.txt << 'EOF'\nhello\nworld\nEOF" })
+```
+
+**Benefits of single-tool approach**:
+- ✅ Properly expands `~` and all environment variables
+- ✅ More flexible (use any shell commands and flags)
+- ✅ Can use any installed tools (cat, echo, sed, awk, etc.)
+- ✅ Much simpler codebase (only one tool to maintain)
+- ✅ More reliable (uses shell directly, no SFTP edge cases)
+- ✅ Consistent behavior with interactive SSH sessions
+
+### Technical Details
+- Removed `src/tools/acp-remote-list-files.ts`
+- Removed `src/tools/acp-remote-read-file.ts`
+- Removed `src/tools/acp-remote-write-file.ts`
+- Removed `src/types/file-entry.ts`
+- Removed all SFTP methods from SSHConnectionManager (getSFTP, readFile, writeFile, listFiles)
+- Removed SFTPWrapper import from ssh2
+- Now provides only 1 core tool: execute_command
+- Dramatically simplified codebase and reduced maintenance burden
+
 ## [0.7.1] - 2026-02-23
 
 ### Fixed

package/README.md

@@ -1,16 +1,17 @@
 # ACP MCP
 
-MCP server for a remote machine MCP server that will be wrapped by /home/prmichaelsen/mcp-auth.
+MCP server for remote machine operations via SSH. Provides a single, powerful tool for executing any shell command on remote machines with real-time progress streaming.
 
 ## Installation
 
 ```bash
-npm install
+npm install @prmichaelsen/acp-mcp
 ```
 
 ## Development
 
 ```bash
+npm install
 npm run dev
 ```
 
@@ -56,45 +57,124 @@ const server = await createServer({
 
 ## Available Tools
 
-- **acp_remote_list_files** - List files and directories with comprehensive metadata
-  - `path` (required): The directory path to list files from
-  - `recursive` (optional): Whether to list files recursively (default: false)
-  - `includeHidden` (optional): Whether to include hidden files starting with `.` (default: true)
-  - **Returns**: JSON array of file entries with metadata (permissions, timestamps, size, ownership)
-  - **Metadata includes**: name, path, type, size, permissions (mode, string, owner/group/others), owner (uid, gid), timestamps (accessed, modified)
-  - **Note**: Uses hybrid approach (shell `ls` + SFTP `stat()`) to get all files including hidden ones with rich metadata
-
-- **acp_remote_execute_command** - Execute a shell command on the remote machine with optional progress streaming
-  - `command` (required): Shell command to execute
-  - `cwd` (optional): Working directory for command execution
-  - `timeout` (optional): Timeout in seconds (default: 30, ignored if progress streaming)
-  - **Returns**: `{ stdout, stderr, exitCode, timedOut, streamed? }`
-  - **Shell Environment** (v0.7.1+): Automatically sources shell configuration files
-    - Sources `~/.zshrc`, `~/.bashrc`, or `~/.profile` before executing commands
-    - Ensures `$PATH` and environment variables are properly loaded
-    - Enables user-installed tools (nvm, homebrew, etc.) to work correctly
-    - Gracefully handles missing config files
-  - **Progress Streaming** (v0.7.0+): Supports real-time output streaming when client provides `progressToken`
-    - Requires MCP SDK v1.26.0+ (server and client)
-    - Client must provide `progressToken` in request `_meta`
-    - Client must handle progress notifications via `onprogress` callback
-    - Graceful fallback to timeout mode if no `progressToken` provided
-    - Rate limited to max 10 notifications/second
-    - Ideal for long-running commands: `npm run build`, `npm test`, `npm run dev`
-
-- **acp_remote_read_file** - Read file contents from the remote machine
-  - `path` (required): Absolute path to file
-  - `encoding` (optional): File encoding - utf-8, ascii, or base64 (default: utf-8)
-  - `maxSize` (optional): Max file size in bytes (default: 1MB)
-  - Returns: `{ content, size, encoding }`
-
-- **acp_remote_write_file** - Write file contents to the remote machine
-  - `path` (required): Absolute path to file
-  - `content` (required): File contents to write
-  - `encoding` (optional): File encoding (default: utf-8)
-  - `createDirs` (optional): Create parent directories (default: false)
-  - `backup` (optional): Backup existing file before overwriting (default: false)
-  - Returns: `{ success, bytesWritten, backupPath }`
+**acp-mcp v1.0.0** provides a single, powerful tool for all remote operations:
+
+### acp_remote_execute_command
+
+Execute any shell command on the remote machine with optional progress streaming.
+
+**Parameters**:
+- `command` (required): Shell command to execute
+- `cwd` (optional): Working directory for command execution
+- `timeout` (optional): Timeout in seconds (default: 30, ignored if progress streaming)
+
+**Returns**: `{ stdout, stderr, exitCode, timedOut, streamed? }`
+
+**Features**:
+
+1. **Shell Environment** (v0.7.1+): Automatically sources shell configuration files
+   - Sources `~/.zshrc`, `~/.bashrc`, or `~/.profile` before executing commands
+   - Ensures `$PATH` and environment variables are properly loaded
+   - Enables user-installed tools (nvm, homebrew, etc.) to work correctly
+   - Gracefully handles missing config files
+
+2. **Progress Streaming** (v0.7.0+): Real-time output for long-running commands
+   - Requires MCP SDK v1.26.0+ (server and client)
+   - Client must provide `progressToken` in request `_meta`
+   - Client must handle progress notifications via `onprogress` callback
+   - Graceful fallback to timeout mode if no `progressToken` provided
+   - Rate limited to max 10 notifications/second
+   - Ideal for: `npm run build`, `npm test`, `npm run dev`
+
+## Common Operations
+
+### List Files
+```bash
+# Basic listing
+acp_remote_execute_command({ command: "ls -la ~/project" })
+
+# Recursive listing
+acp_remote_execute_command({ command: "find ~/project -type f" })
+
+# With tree (if installed)
+acp_remote_execute_command({ command: "tree ~/project" })
+
+# Only directories
+acp_remote_execute_command({ command: "ls -d */ ~/project" })
+```
+
+### Read Files
+```bash
+# Read entire file
+acp_remote_execute_command({ command: "cat ~/project/package.json" })
+
+# Read first 100 lines
+acp_remote_execute_command({ command: "head -n 100 ~/project/large-file.txt" })
+
+# Read last 50 lines
+acp_remote_execute_command({ command: "tail -n 50 ~/project/log.txt" })
+
+# Search in file
+acp_remote_execute_command({ command: "grep 'pattern' ~/project/file.txt" })
+```
+
+### Write Files
+```bash
+# Write simple content
+acp_remote_execute_command({ command: "echo 'hello world' > ~/project/file.txt" })
+
+# Write multi-line content
+acp_remote_execute_command({ 
+  command: "cat > ~/project/file.txt << 'EOF'\nline 1\nline 2\nline 3\nEOF" 
+})
+
+# Append to file
+acp_remote_execute_command({ command: "echo 'new line' >> ~/project/file.txt" })
+
+# Create directories
+acp_remote_execute_command({ command: "mkdir -p ~/project/new/nested/dir" })
+```
+
+### File Operations
+```bash
+# Copy files
+acp_remote_execute_command({ command: "cp ~/source.txt ~/dest.txt" })
+
+# Move files
+acp_remote_execute_command({ command: "mv ~/old.txt ~/new.txt" })
+
+# Delete files
+acp_remote_execute_command({ command: "rm ~/file.txt" })
+
+# Change permissions
+acp_remote_execute_command({ command: "chmod 755 ~/script.sh" })
+```
+
+### Development Operations
+```bash
+# Git operations
+acp_remote_execute_command({ command: "git status", cwd: "~/project" })
+acp_remote_execute_command({ command: "git commit -m 'message'", cwd: "~/project" })
+
+# Package management
+acp_remote_execute_command({ command: "npm install", cwd: "~/project" })
+acp_remote_execute_command({ command: "npm run build", cwd: "~/project" })
+
+# Process management
+acp_remote_execute_command({ command: "ps aux | grep node" })
+acp_remote_execute_command({ command: "kill -9 12345" })
+```
+
+## Why Single Tool?
+
+**v1.0.0 removed specialized tools** (`list_files`, `read_file`, `write_file`) in favor of `execute_command`:
+
+✅ **Properly expands `~` and environment variables** - SFTP-based tools didn't
+✅ **Maximum flexibility** - Use any shell command or tool
+✅ **Simpler codebase** - One tool instead of four
+✅ **More reliable** - No SFTP edge cases or limitations
+✅ **Consistent behavior** - Works exactly like interactive SSH
+✅ **Easier to maintain** - Single code path to test and debug
 
 ## Configuration
 

package/agent/progress.yaml

@@ -1,14 +1,14 @@
 project:
   name: acp-mcp
-  version: 0.7.1
+  version: 1.0.0
   started: 2026-02-22
   status: in_progress
   current_milestone: M4
   description: |
     MCP server for remote machine operations via SSH.
-    Provides core tools for executing commands, reading/writing files,
-    and listing directories on remote development environments.
+    Provides single powerful tool (execute_command) for all remote operations.
     Supports real-time progress streaming for long-running commands.
+    Shell-based approach is more reliable than SFTP for all operations.
 
 milestones:
   - id: M1
@@ -209,6 +209,29 @@ progress:
   overall: 80%
 
 recent_work:
+  - date: 2026-02-24
+    description: Removed ALL specialized tools - v1.0.0 single-tool approach
+    items:
+      - 🔥 **BREAKING CHANGE**: Removed all SFTP-based tools (list_files, read_file, write_file)
+      - ✅ Root cause: All SFTP tools don't expand ~ or environment variables
+      - ✅ SFTP implementation was unreliable, complex, and had multiple edge cases
+      - ✅ Single execute_command tool is more reliable and flexible for ALL operations
+      - ✅ Removed src/tools/acp-remote-list-files.ts
+      - ✅ Removed src/tools/acp-remote-read-file.ts
+      - ✅ Removed src/tools/acp-remote-write-file.ts
+      - ✅ Removed src/types/file-entry.ts
+      - ✅ Removed ALL SFTP methods from SSHConnectionManager (getSFTP, readFile, writeFile, listFiles)
+      - ✅ Removed SFTPWrapper import from ssh2
+      - ✅ Updated server.ts and server-factory.ts (single tool registration)
+      - ✅ Updated CHANGELOG.md with v1.0.0 breaking change and migration guide
+      - ✅ Updated README.md with comprehensive usage examples
+      - ✅ Version bumped to 1.0.0 (major breaking change)
+      - ✅ Build successful - TypeScript compiles without errors
+      - 📋 Now provides ONLY 1 tool: execute_command
+      - 📋 Use shell commands for all operations (ls, cat, echo, etc.)
+      - 📋 Much simpler, more reliable, and easier to maintain
+      - 📋 Migration guide provided in CHANGELOG.md
+      
   - date: 2026-02-23
     description: Fixed shell environment not loading - v0.7.1 patch
     items:
@@ -337,10 +360,11 @@ recent_work:
       - ✅ Version bumped to v0.4.1
 
 next_steps:
-  - Deploy v0.7.1 to npm registry (includes shell environment fix)
+  - Deploy v1.0.0 to npm registry (breaking change - removed list_files tool)
+  - Update mcp-auth wrapper to use v1.0.0
+  - Update agentbase.me to use execute_command for file listing
   - Test shell environment fix with user-installed tools (npm, node, git)
   - Test progress streaming with real clients (Claude Desktop, mcp-auth)
-  - Close GitHub Issue #2 after production verification
   - Start M5: Progress Streaming - Wrapper Integration (mcp-auth)
   - Start M6: Progress Streaming - Client Integration (agentbase.me)
   - Consider ACP update to v3.12.0 (experimental features system)