@prmichaelsen/acp-mcp 0.5.1 → 0.7.0

package/agent/tasks/milestone-4-progress-streaming-server/task-7-implement-progress-streaming.md

@@ -0,0 +1,191 @@
+# Task 7: Implement Progress Streaming in Execute Command
+
+**Milestone**: M4 - Progress Streaming - Server Implementation
+**Estimated Time**: 4-5 hours
+**Dependencies**: Task 6 (SSH stream execution)
+**Status**: Not Started
+**Priority**: High
+
+---
+
+## Objective
+
+Update `acp_remote_execute_command` tool to support progress streaming when client provides a `progressToken`. Implement graceful fallback to timeout mode when no progress token is provided.
+
+## Context
+
+**Design Reference**: [`agent/design/local.progress-streaming.md`](../../design/local.progress-streaming.md)
+
+**Current State**: Tool uses `execWithTimeout()` and returns all output at once
+
+**Desired State**: Tool detects `progressToken`, streams output with progress notifications, maintains backward compatibility
+
+---
+
+## Steps
+
+### 1. Update Handler Signature
+
+**File**: `src/tools/acp-remote-execute-command.ts`
+
+**Actions**:
+- Add `extra?: { progressToken?: string | number }` parameter
+- Import server instance for sending notifications
+- Add type definitions for progress params
+
+### 2. Add Progress Detection Logic
+
+**Actions**:
+- Check if `extra?.progressToken` exists
+- If yes: call `executeWithProgress()`
+- If no: use existing `execWithTimeout()` (fallback)
+
+### 3. Implement executeWithProgress() Function
+
+**Actions**:
+- Call `sshConnection.execStream()`
+- Set up stdout data handler
+- Send progress notification for each chunk
+- Collect full output for final result
+- Handle stderr separately (no progress)
+- Wait for exit code
+- Return structured result
+
+**Code Pattern**:
+```typescript
+async function executeWithProgress(
+  command: string,
+  cwd: string | undefined,
+  sshConnection: SSHConnectionManager,
+  progressToken: string | number
+): Promise<{ content: Array<{ type: string; text: string }> }> {
+  const { stream, stderr: stderrStream, exitCode } = await sshConnection.execStream(command, cwd);
+  
+  let stdout = '';
+  let stderr = '';
+  let bytesReceived = 0;
+
+  stream.on('data', (chunk: Buffer) => {
+    const text = chunk.toString();
+    stdout += text;
+    bytesReceived += chunk.length;
+    
+    // Send progress notification
+    server.notification({
+      method: 'notifications/progress',
+      params: {
+        progressToken,
+        progress: bytesReceived,
+        total: undefined,
+        message: text,
+      },
+    });
+  });
+
+  stderrStream.on('data', (chunk: Buffer) => {
+    stderr += chunk.toString();
+  });
+
+  const finalExitCode = await exitCode;
+
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        stdout,
+        stderr,
+        exitCode: finalExitCode,
+        timedOut: false,
+        streamed: true,
+      }, null, 2),
+    }],
+  };
+}
+```
+
+### 4. Add Rate Limiting
+
+**Actions**:
+- Limit progress notifications to max 10/second
+- Batch small chunks
+- Track last notification time
+- Only send if enough time elapsed
+
+**Code Pattern**:
+```typescript
+let lastProgressTime = 0;
+const MIN_PROGRESS_INTERVAL = 100; // 100ms
+
+stream.on('data', (chunk: Buffer) => {
+  stdout += chunk.toString();
+  bytesReceived += chunk.length;
+  
+  const now = Date.now();
+  if (now - lastProgressTime >= MIN_PROGRESS_INTERVAL) {
+    server.notification({ /* ... */ });
+    lastProgressTime = now;
+  }
+});
+```
+
+### 5. Add Error Handling
+
+**Actions**:
+- Handle stream errors
+- Handle connection loss
+- Send error via progress notification
+- Return error in final result
+
+### 6. Update Tool Schema
+
+**Actions**:
+- Update description to mention progress support
+- Note that timeout is ignored when streaming
+- Add examples of progress usage
+
+### 7. Test Implementation
+
+**Actions**:
+- Build project
+- Test with progressToken (streaming mode)
+- Test without progressToken (fallback mode)
+- Test with long-running command
+- Test with command that fails
+- Test error scenarios
+
+---
+
+## Verification
+
+- [ ] Handler accepts `extra` parameter
+- [ ] Detects `progressToken` correctly
+- [ ] Calls `executeWithProgress()` when token provided
+- [ ] Falls back to `execWithTimeout()` when no token
+- [ ] Sends progress notifications for stdout chunks
+- [ ] Rate limiting prevents notification spam
+- [ ] Collects full output for final result
+- [ ] Handles errors gracefully
+- [ ] TypeScript compiles without errors
+- [ ] Build completes successfully
+- [ ] Both modes tested and working
+
+---
+
+## Expected Output
+
+### Files Modified
+- `src/tools/acp-remote-execute-command.ts` - Progress streaming implementation
+
+### New Function
+```typescript
+async function executeWithProgress(
+  command: string,
+  cwd: string | undefined,
+  sshConnection: SSHConnectionManager,
+  progressToken: string | number
+): Promise<{ content: Array<{ type: string; text: string }> }>
+```
+
+---
+
+**Next Task**: [Task 8: Update Server Request Handlers](task-8-update-server-handlers.md)

package/agent/tasks/milestone-4-progress-streaming-server/task-8-update-server-handlers.md

@@ -0,0 +1,109 @@
+# Task 8: Update Server Request Handlers
+
+**Milestone**: M4 - Progress Streaming - Server Implementation
+**Estimated Time**: 1-2 hours
+**Dependencies**: Task 7 (Progress streaming implementation)
+**Status**: Not Started
+**Priority**: Medium
+
+---
+
+## Objective
+
+Update server request handlers in both `server.ts` and `server-factory.ts` to pass the `extra` parameter (containing `progressToken`) to tool handlers.
+
+## Context
+
+**Design Reference**: [`agent/design/local.progress-streaming.md`](../../design/local.progress-streaming.md)
+
+**Current State**: Handlers don't pass `extra` parameter to tools
+
+**Desired State**: Handlers pass `extra` to `acp_remote_execute_command` handler
+
+---
+
+## Steps
+
+### 1. Update server.ts Handler
+
+**File**: `src/server.ts`
+
+**Actions**:
+- Modify `CallToolRequestSchema` handler signature to accept `extra` parameter
+- Pass `extra` to `handleAcpRemoteExecuteCommand()`
+- Keep other tool handlers unchanged (they don't need progress)
+
+**Code Pattern**:
+```typescript
+server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+  const startTime = Date.now();
+  logger.toolInvoked(request.params.name, request.params.arguments);
+  
+  try {
+    let result;
+    
+    if (request.params.name === 'acp_remote_execute_command') {
+      result = await handleAcpRemoteExecuteCommand(
+        request.params.arguments,
+        sshConnection,
+        extra  // Pass extra with progressToken
+      );
+    } else if (request.params.name === 'acp_remote_list_files') {
+      result = await handleAcpRemoteListFiles(request.params.arguments, sshConnection);
+    }
+    // ... other tools
+    
+    return result;
+  } catch (error) {
+    logger.toolFailed(request.params.name, error as Error, request.params.arguments);
+    throw error;
+  }
+});
+```
+
+### 2. Update server-factory.ts Handler
+
+**File**: `src/server-factory.ts`
+
+**Actions**:
+- Same changes as server.ts
+- Ensure consistency between both files
+
+### 3. Verify No Breaking Changes
+
+**Actions**:
+- Confirm other tools still work
+- Verify `extra` parameter is optional
+- Test that undefined `extra` doesn't break anything
+
+### 4. Test Both Server Modes
+
+**Actions**:
+- Build project
+- Test standalone server (server.ts)
+- Test factory server (server-factory.ts)
+- Verify both pass `extra` correctly
+
+---
+
+## Verification
+
+- [ ] server.ts handler updated
+- [ ] server-factory.ts handler updated
+- [ ] `extra` parameter passed to execute_command handler
+- [ ] Other tools unaffected
+- [ ] TypeScript compiles without errors
+- [ ] Build completes successfully
+- [ ] Both server modes tested
+
+---
+
+## Expected Output
+
+### Files Modified
+- `src/server.ts` - Pass `extra` to handler
+- `src/server-factory.ts` - Pass `extra` to handler
+
+---
+
+**Next Task**: [Task 9: Testing and Documentation](task-9-testing-documentation.md)

package/agent/tasks/milestone-4-progress-streaming-server/task-9-testing-documentation.md

@@ -0,0 +1,192 @@
+# Task 9: Testing and Documentation
+
+**Milestone**: M4 - Progress Streaming - Server Implementation
+**Estimated Time**: 3-4 hours
+**Dependencies**: Tasks 6, 7, 8 (All implementation complete)
+**Status**: Not Started
+**Priority**: High
+
+---
+
+## Objective
+
+Add comprehensive tests for progress streaming functionality and update all documentation for v0.7.0 release.
+
+## Context
+
+**Design Reference**: [`agent/design/local.progress-streaming.md`](../../design/local.progress-streaming.md)
+
+**Current State**: Implementation complete, needs testing and documentation
+
+**Desired State**: Full test coverage, updated documentation, ready for v0.7.0 release
+
+---
+
+## Steps
+
+### 1. Write Unit Tests
+
+**File**: Create `src/utils/ssh-connection.test.ts` (if doesn't exist)
+
+**Actions**:
+- Test `execStream()` returns correct types
+- Test stream emits data events
+- Test exit code promise resolves
+- Test error handling
+- Mock SSH client for tests
+
+### 2. Write Integration Tests
+
+**File**: Create `src/tools/acp-remote-execute-command.test.ts`
+
+**Actions**:
+- Test with `progressToken` (streaming mode)
+- Test without `progressToken` (fallback mode)
+- Test progress notifications are sent
+- Test rate limiting works
+- Test error scenarios
+- Use real SSH connection (or mock)
+
+### 3. Manual Testing
+
+**Actions**:
+- Test with simple command: `echo "test"`
+- Test with long command: `for i in 1 2 3 4 5; do echo "Line $i"; sleep 0.5; done`
+- Test with failing command
+- Test with very long output
+- Test connection loss scenario
+
+### 4. Update README.md
+
+**File**: `README.md`
+
+**Actions**:
+- Add section on progress streaming support
+- Document that progress requires MCP SDK v1.26.0+
+- Add examples of progress usage
+- Note client requirements
+- Update tool description for `acp_remote_execute_command`
+
+**Example Addition**:
+```markdown
+### Progress Streaming (v0.7.0+)
+
+`acp_remote_execute_command` supports real-time progress streaming for long-running commands. When a client provides a `progressToken`, the tool will send progress notifications with live output.
+
+**Requirements**:
+- MCP SDK v1.26.0+ (server and client)
+- Client must provide `progressToken` in request
+- Client must handle `onprogress` callback
+
+**Example** (client-side):
+\`\`\`typescript
+const result = await client.request({
+  method: 'tools/call',
+  params: {
+    name: 'acp_remote_execute_command',
+    arguments: { command: 'npm run build' }
+  }
+}, {
+  progressToken: 'build-123',
+  onprogress: (progress) => {
+    console.log(progress.message); // Live output
+  }
+});
+\`\`\`
+
+**Fallback**: If no `progressToken` provided, uses timeout-based execution (backward compatible).
+```
+
+### 5. Update CHANGELOG.md
+
+**File**: `CHANGELOG.md`
+
+**Actions**:
+- Add v0.7.0 section
+- Document progress streaming feature
+- Note backward compatibility
+- List all changes
+
+**Example Entry**:
+```markdown
+## [0.7.0] - 2026-02-24
+
+### Added
+- **Progress Streaming** for `acp_remote_execute_command` tool
+  - Real-time output streaming for long-running commands
+  - Uses MCP SDK's native progress notification system
+  - Graceful fallback to timeout mode for clients without progress support
+  - Rate limiting prevents notification spam (max 10/second)
+  - Supports commands like `npm run build`, `npm run dev`, `npm test`
+
+### Changed
+- `acp_remote_execute_command` now accepts optional `progressToken` parameter
+- Added `execStream()` method to SSHConnectionManager
+- Server handlers now pass `extra` parameter to tool handlers
+
+### Technical Details
+- Requires MCP SDK v1.26.0+ for progress support
+- Progress notifications sent via `notifications/progress` method
+- Backward compatible - existing clients unaffected
+- No breaking changes to API
+```
+
+### 6. Update package.json
+
+**File**: `package.json`
+
+**Actions**:
+- Bump version to 0.7.0
+- Verify dependencies are correct
+
+### 7. Build and Verify
+
+**Actions**:
+- Run `npm run build`
+- Verify TypeScript compiles
+- Run tests: `npm test`
+- Verify all tests pass
+- Check for any warnings
+
+---
+
+## Verification
+
+- [ ] Unit tests written and passing
+- [ ] Integration tests written and passing
+- [ ] Manual testing completed successfully
+- [ ] README.md updated with progress documentation
+- [ ] CHANGELOG.md updated for v0.7.0
+- [ ] package.json version bumped to 0.7.0
+- [ ] TypeScript compiles without errors
+- [ ] Build completes successfully
+- [ ] All tests pass
+- [ ] No warnings or errors
+
+---
+
+## Expected Output
+
+### Files Created
+- `src/utils/ssh-connection.test.ts` - Unit tests (if doesn't exist)
+- `src/tools/acp-remote-execute-command.test.ts` - Integration tests (if doesn't exist)
+
+### Files Modified
+- `README.md` - Progress streaming documentation
+- `CHANGELOG.md` - v0.7.0 entry
+- `package.json` - Version bump to 0.7.0
+
+### Test Results
+```
+✓ SSH stream execution tests (5 passed)
+✓ Progress streaming tests (8 passed)
+✓ Fallback mode tests (3 passed)
+✓ Error handling tests (4 passed)
+
+Total: 20 tests passed
+```
+
+---
+
+**Next Milestone**: M5 - Progress Streaming - Wrapper Integration (mcp-auth)
+**Related Design**: [`agent/design/local.progress-streaming.md`](../../design/local.progress-streaming.md)

package/agent/tasks/task-5-fix-incomplete-directory-listings.md

@@ -0,0 +1,170 @@
+# Task 5: Fix Incomplete Directory Listings (GitHub Issue #2)
+
+**Milestone**: M3 - Bug Fixes and Enhancements
+**Estimated Time**: 3-4 hours
+**Dependencies**: None
+**Status**: In Progress
+**Priority**: 🚨 CRITICAL
+**GitHub Issue**: [#2](https://github.com/prmichaelsen/acp-mcp/issues/2)
+
+---
+
+## Objective
+
+Fix the critical bug where `acp_remote_list_files` returns incomplete directory listings, missing hidden files and directories. Implement comprehensive file listing with full metadata (permissions, timestamps, size, etc.) using a hybrid approach.
+
+## Context
+
+**Problem**: SFTP `readdir()` filters out hidden files (starting with `.`) by default, causing incomplete listings.
+
+**Root Cause**: SFTP protocol behavior, not a library bug. SFTP `readdir()` excludes hidden files per protocol specification.
+
+**Solution**: Use shell `ls` command to get ALL filenames (including hidden), then SFTP `stat()` to get rich metadata for each file.
+
+**Design Reference**: See [`agent/reports/github-issue-2-incomplete-directory-listings.md`](../reports/github-issue-2-incomplete-directory-listings.md)
+
+---
+
+## Steps
+
+### 1. Update FileEntry Interface
+
+Create comprehensive interface for file metadata.
+
+**File**: `src/types/file-entry.ts` (create new)
+
+**Actions**:
+- Define `FileEntry` interface with all metadata fields
+- Include permissions, timestamps, size, ownership
+- Export helper functions for permission conversion
+
+### 2. Update SSHConnectionManager.listFiles()
+
+Implement hybrid approach: shell + SFTP.
+
+**File**: `src/utils/ssh-connection.ts`
+
+**Actions**:
+- Add `includeHidden` parameter (default: `true`)
+- Use shell `ls -A` to get all filenames
+- Use SFTP `stat()` to get metadata for each file
+- Return comprehensive `FileEntry[]` with all metadata
+- Add fallback to SFTP `readdir()` if shell fails
+- Add comprehensive logging
+
+### 3. Update Tool Schema
+
+Add `includeHidden` parameter to tool.
+
+**File**: `src/tools/acp-remote-list-files.ts`
+
+**Actions**:
+- Add `includeHidden` to input schema
+- Update tool description
+- Pass parameter to `listFiles()`
+- Update recursive listing to use parameter
+
+### 4. Update Tool Output Format
+
+Return structured JSON with metadata.
+
+**File**: `src/tools/acp-remote-list-files.ts`
+
+**Actions**:
+- Change output from simple text to structured JSON
+- Include all file metadata in response
+- Format for easy parsing by agents
+
+### 5. Update Documentation
+
+Document new functionality and parameters.
+
+**Files**: `README.md`, `CHANGELOG.md`
+
+**Actions**:
+- Document `includeHidden` parameter
+- Document new output format with metadata
+- Add examples of usage
+- Update CHANGELOG for v0.6.0
+
+### 6. Test Implementation
+
+Verify fix works correctly.
+
+**Actions**:
+- Build project: `npm run build`
+- Test with hidden files directory
+- Verify all files returned
+- Verify metadata is correct
+- Test recursive listing
+- Test with `includeHidden=false`
+
+---
+
+## Verification
+
+- [ ] `FileEntry` interface created with all fields
+- [ ] `SSHConnectionManager.listFiles()` updated with hybrid approach
+- [ ] `includeHidden` parameter added to tool schema
+- [ ] Tool returns structured JSON with metadata
+- [ ] README.md updated with new parameter
+- [ ] CHANGELOG.md updated for v0.6.0
+- [ ] TypeScript compiles without errors
+- [ ] Build completes successfully
+- [ ] Manual testing shows all files including hidden
+- [ ] Metadata fields populated correctly
+- [ ] Recursive listing works with hidden files
+- [ ] Fallback to SFTP works if shell fails
+
+---
+
+## Expected Output
+
+### Files Created
+- `src/types/file-entry.ts` - FileEntry interface and helpers
+
+### Files Modified
+- `src/utils/ssh-connection.ts` - Hybrid listing implementation
+- `src/tools/acp-remote-list-files.ts` - Updated schema and output
+- `README.md` - Documentation updates
+- `CHANGELOG.md` - v0.6.0 entry
+- `package.json` - Version bump to 0.6.0
+
+---
+
+## Implementation Details
+
+### FileEntry Interface
+```typescript
+export interface FileEntry {
+  name: string;
+  path: string;
+  type: 'file' | 'directory' | 'symlink' | 'other';
+  size: number;
+  permissions: {
+    mode: number;
+    string: string;
+    owner: { read: boolean; write: boolean; execute: boolean };
+    group: { read: boolean; write: boolean; execute: boolean };
+    others: { read: boolean; write: boolean; execute: boolean };
+  };
+  owner: {
+    uid: number;
+    gid: number;
+  };
+  timestamps: {
+    accessed: string;
+    modified: string;
+  };
+}
+```
+
+### Hybrid Approach
+1. Execute `ls -A -1` to get all filenames (including hidden)
+2. For each filename, call SFTP `stat()` to get metadata
+3. Construct `FileEntry` objects with complete information
+4. Return structured array
+
+---
+
+**Next Task**: Task 6 - Deploy v0.6.0 to npm