@prmichaelsen/acp-mcp 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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).
 
+## [0.3.0] - 2026-02-22
+
+### Added
+- `acp_remote_execute_command` tool for executing arbitrary shell commands on remote machines
+- `acp_remote_read_file` tool for reading file contents from remote machines
+- `acp_remote_write_file` tool for writing file contents to remote machines
+- Timeout support for command execution (default: 30 seconds)
+- File size limits for read operations (default: 1MB, configurable)
+- Atomic file writes with temp file + rename pattern
+- Optional backup functionality for file writes
+- Optional parent directory creation for file writes
+- Comprehensive error handling for all tools
+
+### Changed
+- All tools now return structured JSON responses for better parsing
+- Enhanced SSHConnectionManager with readFile and writeFile methods
+- Updated README with complete tool documentation
+
+### Technical Details
+- Added `execWithTimeout()` method to SSHConnectionManager
+- Added `readFile()` method with size validation
+- Added `writeFile()` method with atomic writes and backup support
+- All 4 core tools now fully implemented and tested
+- TypeScript compilation successful
+- Build generates proper .d.ts files
+
 ## [0.2.0] - 2026-02-22
 
 ### Added

package/README.md

@@ -60,6 +60,26 @@ const server = await createServer({
   - `path` (required): The directory path to list files from
   - `recursive` (optional): Whether to list files recursively (default: false)
 
+- **acp_remote_execute_command** - Execute a shell command on the remote machine
+  - `command` (required): Shell command to execute
+  - `cwd` (optional): Working directory for command execution
+  - `timeout` (optional): Timeout in seconds (default: 30)
+  - Returns: `{ stdout, stderr, exitCode, timedOut }`
+
+- **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 }`
+
 ## Configuration
 
 ### Standalone Server Configuration

package/agent/design/acp-mcp-core-tools.md

@@ -0,0 +1,382 @@
+# Design: ACP MCP Core Tools
+
+**Concept**: Core MCP tools for remote machine operations via SSH
+**Created**: 2026-02-22
+**Status**: Design Specification
+
+---
+
+## Overview
+
+This design document specifies the core tools for the acp-mcp server, which provides remote machine access capabilities through SSH. These tools enable users to interact with remote development environments through the agentbase.me platform.
+
+## Problem Statement
+
+Users need to perform common development operations on remote machines:
+- Execute arbitrary shell commands
+- Read and write files
+- List directory contents
+- Manage remote development environments
+
+Currently, only file listing is implemented. We need a complete set of tools for full remote development capabilities.
+
+## Solution
+
+Implement four core tools that cover the essential remote operations:
+
+1. **acp_remote_list_files** (✅ Implemented)
+2. **acp_remote_execute_command** (🔨 To Implement)
+3. **acp_remote_read_file** (🔨 To Implement)
+4. **acp_remote_write_file** (🔨 To Implement)
+
+---
+
+## Tool Specifications
+
+### 1. acp_remote_list_files
+
+**Status**: ✅ Implemented (v0.2.0)
+
+**Purpose**: List files and directories in a specified path on the remote machine
+
+**Input Schema**:
+```typescript
+{
+  path: string;        // Required: Directory path to list
+  recursive: boolean;  // Optional: List recursively (default: false)
+}
+```
+
+**Output**: Newline-separated list of files/directories
+- Directories end with `/`
+- Recursive listings show relative paths (e.g., `subdir/file.txt`)
+- Sorted alphabetically
+
+**Implementation**: Uses SSH SFTP to list directory contents
+
+**Example**:
+```
+Input: { path: "/home/user/project", recursive: false }
+Output:
+src/
+package.json
+README.md
+tsconfig.json
+```
+
+---
+
+### 2. acp_remote_execute_command
+
+**Status**: 🔨 To Implement
+
+**Purpose**: Execute arbitrary shell commands on the remote machine
+
+**Input Schema**:
+```typescript
+{
+  command: string;     // Required: Shell command to execute
+  cwd?: string;        // Optional: Working directory (default: home directory)
+  timeout?: number;    // Optional: Timeout in seconds (default: 30)
+}
+```
+
+**Output**: 
+```typescript
+{
+  stdout: string;      // Standard output
+  stderr: string;      // Standard error
+  exitCode: number;    // Exit code (0 = success)
+  timedOut: boolean;   // Whether command timed out
+}
+```
+
+**Implementation Details**:
+- Use `SSHConnectionManager.exec()` method
+- Set timeout to prevent hanging
+- Capture both stdout and stderr
+- Return exit code for error handling
+- Support working directory changes
+
+**Security Considerations**:
+- Commands run with SSH user's permissions
+- No shell injection protection needed (SSH handles this)
+- Timeout prevents resource exhaustion
+- Consider rate limiting in production
+
+**Example**:
+```
+Input: { command: "git status", cwd: "/home/user/project" }
+Output: {
+  stdout: "On branch main\nnothing to commit, working tree clean",
+  stderr: "",
+  exitCode: 0,
+  timedOut: false
+}
+```
+
+**Use Cases**:
+- `git status`, `git commit`, `git push`
+- `npm install`, `npm run build`
+- `ls -la`, `pwd`, `whoami`
+- Any shell command the user needs
+
+---
+
+### 3. acp_remote_read_file
+
+**Status**: 🔨 To Implement
+
+**Purpose**: Read file contents from the remote machine
+
+**Input Schema**:
+```typescript
+{
+  path: string;        // Required: Absolute path to file
+  encoding?: string;   // Optional: File encoding (default: 'utf-8')
+  maxSize?: number;    // Optional: Max file size in bytes (default: 1MB)
+}
+```
+
+**Output**: 
+```typescript
+{
+  content: string;     // File contents
+  size: number;        // File size in bytes
+  encoding: string;    // Encoding used
+}
+```
+
+**Implementation Details**:
+- Use SSH SFTP to read file
+- Check file size before reading (prevent memory issues)
+- Support different encodings (utf-8, ascii, base64)
+- Return error if file doesn't exist or is too large
+- Stream large files if needed
+
+**Security Considerations**:
+- Limit max file size (default 1MB, configurable)
+- Only read files user has permission to access
+- Don't read binary files as text (check extension or use base64)
+
+**Error Handling**:
+- File not found → Clear error message
+- Permission denied → Clear error message
+- File too large → Suggest using execute_command with `head` or `tail`
+
+**Example**:
+```
+Input: { path: "/home/user/project/package.json" }
+Output: {
+  content: "{\n  \"name\": \"my-project\",\n  \"version\": \"1.0.0\"\n}",
+  size: 58,
+  encoding: "utf-8"
+}
+```
+
+---
+
+### 4. acp_remote_write_file
+
+**Status**: 🔨 To Implement
+
+**Purpose**: Write file contents to the remote machine
+
+**Input Schema**:
+```typescript
+{
+  path: string;        // Required: Absolute path to file
+  content: string;     // Required: File contents to write
+  encoding?: string;   // Optional: File encoding (default: 'utf-8')
+  createDirs?: boolean; // Optional: Create parent directories (default: false)
+  backup?: boolean;    // Optional: Backup existing file (default: false)
+}
+```
+
+**Output**: 
+```typescript
+{
+  success: boolean;    // Whether write succeeded
+  bytesWritten: number; // Number of bytes written
+  backupPath?: string; // Path to backup file (if created)
+}
+```
+
+**Implementation Details**:
+- Use SSH SFTP to write file
+- Optionally create parent directories (mkdir -p)
+- Optionally backup existing file before overwriting
+- Support different encodings
+- Atomic write (write to temp file, then rename)
+
+**Security Considerations**:
+- Only write files user has permission to write
+- Validate path (no directory traversal attacks)
+- Limit file size (prevent disk exhaustion)
+- Consider rate limiting writes
+
+**Error Handling**:
+- Permission denied → Clear error message
+- Directory doesn't exist → Suggest using createDirs: true
+- Disk full → Clear error message
+
+**Example**:
+```
+Input: { 
+  path: "/home/user/project/.env", 
+  content: "API_KEY=secret\nDEBUG=true",
+  backup: true
+}
+Output: {
+  success: true,
+  bytesWritten: 28,
+  backupPath: "/home/user/project/.env.backup"
+}
+```
+
+---
+
+## Implementation Plan
+
+### Phase 1: Execute Command (Highest Priority)
+- Most versatile tool
+- Enables git operations, npm commands, etc.
+- Unblocks many use cases
+
+### Phase 2: Read File
+- Essential for viewing remote files
+- Needed for code review, debugging
+
+### Phase 3: Write File
+- Completes CRUD operations
+- Enables remote file editing
+
+---
+
+## Technical Architecture
+
+### SSH Connection Management
+
+All tools use the existing `SSHConnectionManager`:
+
+```typescript
+class SSHConnectionManager {
+  async exec(command: string): Promise<string>
+  async getSFTP(): Promise<SFTPWrapper>
+  async listFiles(path: string): Promise<FileEntry[]>
+  // Add new methods as needed
+}
+```
+
+### Tool Registration
+
+Tools are registered in `server.ts` and `server-factory.ts`:
+
+```typescript
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    acpRemoteListFilesTool,
+    acpRemoteExecuteCommandTool,
+    acpRemoteReadFileTool,
+    acpRemoteWriteFileTool,
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  switch (request.params.name) {
+    case 'acp_remote_list_files':
+      return await handleAcpRemoteListFiles(args, sshConnection);
+    case 'acp_remote_execute_command':
+      return await handleAcpRemoteExecuteCommand(args, sshConnection);
+    case 'acp_remote_read_file':
+      return await handleAcpRemoteReadFile(args, sshConnection);
+    case 'acp_remote_write_file':
+      return await handleAcpRemoteWriteFile(args, sshConnection);
+    default:
+      throw new Error(`Unknown tool: ${request.params.name}`);
+  }
+});
+```
+
+### File Organization
+
+```
+src/tools/
+├── acp-remote-list-files.ts       (✅ Exists)
+├── acp-remote-execute-command.ts  (🔨 Create)
+├── acp-remote-read-file.ts        (🔨 Create)
+└── acp-remote-write-file.ts       (🔨 Create)
+```
+
+---
+
+## Benefits
+
+1. **Complete Remote Operations**: Users can perform all essential file and command operations
+2. **Flexible**: Execute command enables any shell operation
+3. **Safe**: Proper error handling and security considerations
+4. **Consistent**: All tools follow same patterns and conventions
+5. **Well-Documented**: Clear input/output schemas and examples
+
+---
+
+## Trade-offs
+
+### Execute Command vs Specialized Tools
+
+**Decision**: Use `execute_command` for git operations instead of specialized git tools
+
+**Rationale**:
+- More flexible (handles any git command)
+- Fewer tools to maintain
+- Users may need other commands beyond git
+- Simpler architecture
+
+**Trade-off**: Less type safety for git operations, but more flexibility
+
+### File Size Limits
+
+**Decision**: Limit file read/write to 1MB by default
+
+**Rationale**:
+- Prevents memory exhaustion
+- Most source files are < 1MB
+- Large files can use execute_command with streaming tools
+
+**Trade-off**: Can't directly read/write very large files, but this is acceptable for typical use cases
+
+---
+
+## Future Enhancements
+
+1. **File Upload/Download**: Binary file transfer
+2. **Directory Operations**: Create, delete, move directories
+3. **File Permissions**: chmod, chown operations
+4. **Process Management**: Start/stop long-running processes
+5. **Port Forwarding**: Tunnel connections through SSH
+6. **SFTP Batch Operations**: Multiple file operations in one call
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+- Mock SSH connections
+- Test each tool handler independently
+- Test error conditions
+
+### Integration Tests
+- Test against real SSH server
+- Verify file operations work correctly
+- Test timeout handling
+- Test permission errors
+
+### End-to-End Tests
+- Test through mcp-auth wrapper
+- Test with agentbase.me platform
+- Verify JWT authentication flow
+
+---
+
+**Status**: Design Specification
+**Recommendation**: Implement tools in order: execute_command → read_file → write_file

package/agent/milestones/milestone-1-core-tools-implementation.md

@@ -0,0 +1,50 @@
+# Milestone 1: Core Tools Implementation
+
+**Goal**: Implement the remaining core MCP tools for remote machine operations
+**Duration**: 1-2 weeks
+**Dependencies**: None (foundation already complete)
+**Status**: Not Started
+
+---
+
+## Overview
+
+Complete the implementation of core acp-mcp tools to enable full remote development capabilities. The SSH infrastructure and first tool (`acp_remote_list_files`) are already implemented. This milestone focuses on adding the three remaining essential tools.
+
+## Deliverables
+
+- ✅ `acp_remote_list_files` - Already implemented
+- 🔨 `acp_remote_execute_command` - Execute shell commands remotely
+- 🔨 `acp_remote_read_file` - Read file contents from remote machine
+- 🔨 `acp_remote_write_file` - Write file contents to remote machine
+
+## Success Criteria
+
+- [ ] All four core tools implemented and tested
+- [ ] TypeScript compiles without errors
+- [ ] Build completes successfully
+- [ ] Tools work correctly with SSH connections
+- [ ] Error handling implemented for all tools
+- [ ] Documentation updated (README, CHANGELOG)
+- [ ] Version bumped to 0.3.0
+- [ ] Ready for deployment with mcp-auth wrapper
+
+## Key Files to Create
+
+- `src/tools/acp-remote-execute-command.ts`
+- `src/tools/acp-remote-read-file.ts`
+- `src/tools/acp-remote-write-file.ts`
+
+## Key Files to Modify
+
+- `src/server.ts` - Register new tools
+- `src/server-factory.ts` - Register new tools
+- `src/utils/ssh-connection.ts` - Add helper methods if needed
+- `README.md` - Document new tools
+- `CHANGELOG.md` - Document changes
+- `package.json` - Version bump
+
+---
+
+**Next Milestone**: Deployment and Integration (M2)
+**Blockers**: None

package/agent/progress.yaml

@@ -1,33 +1,104 @@
 project:
   name: acp-mcp
-  version: 0.1.0
+  version: 0.3.0
   started: 2026-02-22
   status: in_progress
+  current_milestone: M1
   description: |
-    Support remote machine development using ACP methodology
+    MCP server for remote machine operations via SSH.
+    Provides core tools for executing commands, reading/writing files,
+    and listing directories on remote development environments.
 
-milestones: []
+milestones:
+  - id: M1
+    name: Core Tools Implementation
+    status: in_progress
+    progress: 100%
+    started: 2026-02-22
+    completed: 2026-02-22
+    estimated_weeks: 1-2
+    tasks_completed: 3
+    tasks_total: 3
+    notes: |
+      SSH infrastructure and first tool (acp_remote_list_files) complete.
+      Three remaining tools to implement: execute_command, read_file, write_file.
 
-tasks: {}
+tasks:
+  milestone_1:
+    - id: task-1
+      name: Implement acp_remote_execute_command Tool
+      status: completed
+      file: agent/tasks/milestone-1-core-tools-implementation/task-1-implement-acp-remote-execute-command.md
+      estimated_hours: 3-4
+      actual_hours: null
+      completed_date: 2026-02-22
+      priority: high
+      notes: |
+        Most versatile tool - enables git, npm, and any CLI operations.
+        Completed with timeout support and proper error handling.
+        
+    - id: task-2
+      name: Implement acp_remote_read_file Tool
+      status: completed
+      file: agent/tasks/milestone-1-core-tools-implementation/task-2-implement-acp-remote-read-file.md
+      estimated_hours: 2-3
+      actual_hours: null
+      completed_date: 2026-02-22
+      priority: medium
+      notes: |
+        Essential for viewing remote files and debugging.
+        Completed with file size limits and encoding support.
+        
+    - id: task-3
+      name: Implement acp_remote_write_file Tool
+      status: completed
+      file: agent/tasks/milestone-1-core-tools-implementation/task-3-implement-acp-remote-write-file.md
+      estimated_hours: 3-4
+      actual_hours: null
+      completed_date: 2026-02-22
+      priority: medium
+      notes: |
+        Completes CRUD operations for remote file management.
+        Completed with atomic writes, backup, and createDirs support.
 
 documentation:
-  design_documents: 0
-  milestone_documents: 0
+  design_documents: 1
+  milestone_documents: 1
   pattern_documents: 0
-  task_documents: 0
+  task_documents: 3
 
 progress:
-  planning: 0
-  implementation: 0
-  overall: 0
+  planning: 100%
+  implementation: 100%
+  overall: 100%
 
-recent_work: []
+recent_work:
+  - date: 2026-02-22
+    description: Initial project setup and SSH infrastructure
+    items:
+      - ✅ Created MCP server scaffold with TypeScript and esbuild
+      - ✅ Integrated ssh2 library for SSH connectivity
+      - ✅ Implemented SSHConnectionManager utility class
+      - ✅ Implemented acp_remote_list_files tool (first core tool)
+      - ✅ Added TypeScript declaration file generation
+      - ✅ Created comprehensive design document for all core tools
+      - ✅ Planned milestone and tasks for remaining implementation
+      - ✅ Implemented acp_remote_execute_command tool with timeout support
+      - ✅ Implemented acp_remote_read_file tool with size limits
+      - ✅ Implemented acp_remote_write_file tool with atomic writes
+      - ✅ All 4 core tools complete
+      - 📋 Milestone 1 complete - ready for v0.3.0
 
 next_steps:
-  - Define project requirements in agent/design/requirements.md
-  - Plan milestones and tasks with @acp.plan
-  - Start development with @acp.proceed
+  - Update CHANGELOG.md for v0.3.0 release
+  - Commit all changes with version bump
+  - Deploy with mcp-auth wrapper for agentbase.me integration
+  - Test end-to-end with agentbase.me platform
 
-notes: []
+notes:
+  - Project designed for Task 128 (ACP Remote Development Integration)
+  - Will be wrapped by /home/prmichaelsen/mcp-auth for JWT authentication
+  - Consumed by agentbase.me platform for remote development features
+  - SSH credentials provided by mcp-auth wrapper from user configuration
 
 current_blockers: []