@prmichaelsen/acp-mcp 0.2.0 → 0.3.0

package/agent/tasks/milestone-1-core-tools-implementation/task-1-implement-acp-remote-execute-command.md

@@ -0,0 +1,149 @@
+# Task 1: Implement acp_remote_execute_command Tool
+
+**Milestone**: Milestone 1 - Core Tools Implementation
+**Estimated Time**: 3-4 hours
+**Dependencies**: None (SSH infrastructure complete)
+**Status**: Not Started
+**Priority**: High (Most versatile tool)
+
+---
+
+## Objective
+
+Implement the `acp_remote_execute_command` tool to execute arbitrary shell commands on remote machines via SSH. This is the most important tool as it enables git operations, npm commands, and any other CLI operations users need.
+
+## Context
+
+**Design Reference**: See [`agent/design/acp-mcp-core-tools.md`](../../design/acp-mcp-core-tools.md#2-acp_remote_execute_command)
+
+**Why This Tool**:
+- Most versatile - handles any shell command
+- Enables git operations (status, commit, push)
+- Enables package management (npm, pip, cargo)
+- Enables system operations (ls, pwd, whoami)
+- Replaces need for specialized git tools
+
+**Current State**:
+- SSH infrastructure complete (`SSHConnectionManager`)
+- `SSHConnectionManager.exec()` method already exists
+- Just need to create tool wrapper and register it
+
+---
+
+## Steps
+
+### 1. Create Tool File
+
+Create `src/tools/acp-remote-execute-command.ts`
+
+**Actions**:
+- Define tool schema with MCP Tool interface
+- Input: command (string), cwd (optional string), timeout (optional number)
+- Output: stdout, stderr, exitCode, timedOut
+- Export tool definition and handler function
+
+### 2. Implement Handler Function
+
+**Actions**:
+- Accept args and SSHConnectionManager
+- Extract command, cwd, timeout from args
+- Handle working directory changes (cd && command)
+- Call `sshConnection.exec()` with timeout
+- Capture stdout, stderr, exit code
+- Handle timeout errors
+- Return formatted response
+
+### 3. Add Timeout Support to SSHConnectionManager
+
+**Actions**:
+- Update `SSHConnectionManager.exec()` to support timeout parameter
+- Implement timeout logic with Promise.race()
+- Return timedOut flag in response
+
+### 4. Register Tool in Servers
+
+**Actions**:
+- Import tool in `src/server.ts`
+- Add to ListToolsRequestSchema handler
+- Add case to CallToolRequestSchema handler
+- Repeat for `src/server-factory.ts`
+
+### 5. Update Documentation
+
+**Actions**:
+- Add tool to README.md Available Tools section
+- Include example usage
+- Document parameters and output
+
+### 6. Test Tool
+
+**Actions**:
+- Build project (`npm run build`)
+- Test TypeScript compilation
+- Manual test with simple command (e.g., `pwd`)
+- Test with working directory
+- Test timeout behavior
+- Test error handling
+
+---
+
+## Verification
+
+- [ ] Tool file created with proper schema
+- [ ] Handler function implemented
+- [ ] Timeout support added to SSHConnectionManager
+- [ ] Tool registered in both server files
+- [ ] README.md updated
+- [ ] TypeScript compiles without errors
+- [ ] Build completes successfully
+- [ ] Manual testing successful
+- [ ] Error handling works correctly
+- [ ] Timeout behavior works correctly
+
+---
+
+## Expected Output
+
+### Files Created
+- `src/tools/acp-remote-execute-command.ts`
+
+### Files Modified
+- `src/utils/ssh-connection.ts` (timeout support)
+- `src/server.ts` (tool registration)
+- `src/server-factory.ts` (tool registration)
+- `README.md` (documentation)
+
+---
+
+## Example Implementation
+
+**Tool Schema**:
+```typescript
+export const acpRemoteExecuteCommandTool: Tool = {
+  name: 'acp_remote_execute_command',
+  description: 'Execute a shell command on the remote machine via SSH',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      command: {
+        type: 'string',
+        description: 'Shell command to execute',
+      },
+      cwd: {
+        type: 'string',
+        description: 'Working directory (optional)',
+      },
+      timeout: {
+        type: 'number',
+        description: 'Timeout in seconds (default: 30)',
+        default: 30,
+      },
+    },
+    required: ['command'],
+  },
+};
+```
+
+---
+
+**Next Task**: [Task 2: Implement acp_remote_read_file](task-2-implement-acp-remote-read-file.md)

package/agent/tasks/milestone-1-core-tools-implementation/task-2-implement-acp-remote-read-file.md

@@ -0,0 +1,152 @@
+# Task 2: Implement acp_remote_read_file Tool
+
+**Milestone**: Milestone 1 - Core Tools Implementation
+**Estimated Time**: 2-3 hours
+**Dependencies**: None (SSH infrastructure complete)
+**Status**: Not Started
+**Priority**: Medium
+
+---
+
+## Objective
+
+Implement the `acp_remote_read_file` tool to read file contents from remote machines via SSH. Essential for viewing remote files, code review, and debugging.
+
+## Context
+
+**Design Reference**: See [`agent/design/acp-mcp-core-tools.md`](../../design/acp-mcp-core-tools.md#3-acp_remote_read_file)
+
+**Why This Tool**:
+- View remote file contents
+- Code review and debugging
+- Read configuration files
+- Inspect logs
+
+**Current State**:
+- SSH infrastructure complete (`SSHConnectionManager`)
+- SFTP support available via `getSFTP()`
+- Need to create tool wrapper
+
+---
+
+## Steps
+
+### 1. Create Tool File
+
+Create `src/tools/acp-remote-read-file.ts`
+
+**Actions**:
+- Define tool schema with MCP Tool interface
+- Input: path (string), encoding (optional), maxSize (optional)
+- Output: content, size, encoding
+- Export tool definition and handler function
+
+### 2. Implement Handler Function
+
+**Actions**:
+- Accept args and SSHConnectionManager
+- Extract path, encoding, maxSize from args
+- Get SFTP connection
+- Check file exists and get stats
+- Validate file size (default max: 1MB)
+- Read file contents
+- Handle encoding (utf-8, ascii, base64)
+- Return formatted response with content, size, encoding
+
+### 3. Add SFTP Read Helper to SSHConnectionManager
+
+**Actions**:
+- Add `readFile(path, encoding, maxSize)` method
+- Use SFTP to read file
+- Return file contents and metadata
+
+### 4. Register Tool in Servers
+
+**Actions**:
+- Import tool in `src/server.ts`
+- Add to ListToolsRequestSchema handler
+- Add case to CallToolRequestSchema handler
+- Repeat for `src/server-factory.ts`
+
+### 5. Update Documentation
+
+**Actions**:
+- Add tool to README.md Available Tools section
+- Include example usage
+- Document parameters and output
+- Note file size limits
+
+### 6. Test Tool
+
+**Actions**:
+- Build project (`npm run build`)
+- Test TypeScript compilation
+- Test reading text file
+- Test file size limit
+- Test non-existent file error
+- Test permission denied error
+
+---
+
+## Verification
+
+- [ ] Tool file created with proper schema
+- [ ] Handler function implemented
+- [ ] SFTP read helper added to SSHConnectionManager
+- [ ] Tool registered in both server files
+- [ ] README.md updated
+- [ ] TypeScript compiles without errors
+- [ ] Build completes successfully
+- [ ] Can read text files
+- [ ] File size limit enforced
+- [ ] Error handling works correctly
+
+---
+
+## Expected Output
+
+### Files Created
+- `src/tools/acp-remote-read-file.ts`
+
+### Files Modified
+- `src/utils/ssh-connection.ts` (readFile helper)
+- `src/server.ts` (tool registration)
+- `src/server-factory.ts` (tool registration)
+- `README.md` (documentation)
+
+---
+
+## Example Implementation
+
+**Tool Schema**:
+```typescript
+export const acpRemoteReadFileTool: Tool = {
+  name: 'acp_remote_read_file',
+  description: 'Read file contents from the remote machine via SSH',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Absolute path to file',
+      },
+      encoding: {
+        type: 'string',
+        description: 'File encoding (default: utf-8)',
+        default: 'utf-8',
+        enum: ['utf-8', 'ascii', 'base64'],
+      },
+      maxSize: {
+        type: 'number',
+        description: 'Max file size in bytes (default: 1MB)',
+        default: 1048576,
+      },
+    },
+    required: ['path'],
+  },
+};
+```
+
+---
+
+**Next Task**: [Task 3: Implement acp_remote_write_file](task-3-implement-acp-remote-write-file.md)

package/agent/tasks/milestone-1-core-tools-implementation/task-3-implement-acp-remote-write-file.md

@@ -0,0 +1,165 @@
+# Task 3: Implement acp_remote_write_file Tool
+
+**Milestone**: Milestone 1 - Core Tools Implementation
+**Estimated Time**: 3-4 hours
+**Dependencies**: None (SSH infrastructure complete)
+**Status**: Not Started
+**Priority**: Medium
+
+---
+
+## Objective
+
+Implement the `acp_remote_write_file` tool to write file contents to remote machines via SSH. Completes CRUD operations and enables remote file editing.
+
+## Context
+
+**Design Reference**: See [`agent/design/acp-mcp-core-tools.md`](../../design/acp-mcp-core-tools.md#4-acp_remote_write_file)
+
+**Why This Tool**:
+- Edit remote files
+- Create configuration files
+- Write code changes
+- Update documentation
+
+**Current State**:
+- SSH infrastructure complete (`SSHConnectionManager`)
+- SFTP support available via `getSFTP()`
+- Need to create tool wrapper
+
+---
+
+## Steps
+
+### 1. Create Tool File
+
+Create `src/tools/acp-remote-write-file.ts`
+
+**Actions**:
+- Define tool schema with MCP Tool interface
+- Input: path, content, encoding (optional), createDirs (optional), backup (optional)
+- Output: success, bytesWritten, backupPath (optional)
+- Export tool definition and handler function
+
+### 2. Implement Handler Function
+
+**Actions**:
+- Accept args and SSHConnectionManager
+- Extract path, content, encoding, createDirs, backup from args
+- Get SFTP connection
+- Optionally backup existing file
+- Optionally create parent directories
+- Write to temp file first (atomic write)
+- Rename temp file to target (atomic operation)
+- Return formatted response
+
+### 3. Add SFTP Write Helper to SSHConnectionManager
+
+**Actions**:
+- Add `writeFile(path, content, options)` method
+- Support createDirs option (mkdir -p)
+- Support backup option
+- Implement atomic write (temp file + rename)
+- Return bytes written and backup path
+
+### 4. Register Tool in Servers
+
+**Actions**:
+- Import tool in `src/server.ts`
+- Add to ListToolsRequestSchema handler
+- Add case to CallToolRequestSchema handler
+- Repeat for `src/server-factory.ts`
+
+### 5. Update Documentation
+
+**Actions**:
+- Add tool to README.md Available Tools section
+- Include example usage
+- Document parameters and output
+- Note security considerations
+
+### 6. Test Tool
+
+**Actions**:
+- Build project (`npm run build`)
+- Test TypeScript compilation
+- Test writing new file
+- Test overwriting existing file
+- Test backup functionality
+- Test createDirs functionality
+- Test permission denied error
+
+---
+
+## Verification
+
+- [ ] Tool file created with proper schema
+- [ ] Handler function implemented
+- [ ] SFTP write helper added to SSHConnectionManager
+- [ ] Atomic write implemented (temp + rename)
+- [ ] Backup functionality works
+- [ ] Create directories functionality works
+- [ ] Tool registered in both server files
+- [ ] README.md updated
+- [ ] TypeScript compiles without errors
+- [ ] Build completes successfully
+- [ ] Can write files
+- [ ] Error handling works correctly
+
+---
+
+## Expected Output
+
+### Files Created
+- `src/tools/acp-remote-write-file.ts`
+
+### Files Modified
+- `src/utils/ssh-connection.ts` (writeFile helper)
+- `src/server.ts` (tool registration)
+- `src/server-factory.ts` (tool registration)
+- `README.md` (documentation)
+
+---
+
+## Example Implementation
+
+**Tool Schema**:
+```typescript
+export const acpRemoteWriteFileTool: Tool = {
+  name: 'acp_remote_write_file',
+  description: 'Write file contents to the remote machine via SSH',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Absolute path to file',
+      },
+      content: {
+        type: 'string',
+        description: 'File contents to write',
+      },
+      encoding: {
+        type: 'string',
+        description: 'File encoding (default: utf-8)',
+        default: 'utf-8',
+      },
+      createDirs: {
+        type: 'boolean',
+        description: 'Create parent directories (default: false)',
+        default: false,
+      },
+      backup: {
+        type: 'boolean',
+        description: 'Backup existing file (default: false)',
+        default: false,
+      },
+    },
+    required: ['path', 'content'],
+  },
+};
+```
+
+---
+
+**Next Task**: Version bump and deployment preparation