@prmichaelsen/acp-mcp 0.5.1 → 0.7.0

package/src/tools/acp-remote-execute-command.ts

@@ -4,7 +4,7 @@ import { logger } from '../utils/logger.js';
 
 export const acpRemoteExecuteCommandTool: Tool = {
   name: 'acp_remote_execute_command',
-  description: 'Execute a shell command on the remote machine via SSH',
+  description: 'Execute a shell command on the remote machine via SSH. Supports real-time progress streaming if client provides progressToken.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -18,7 +18,7 @@ export const acpRemoteExecuteCommandTool: Tool = {
       },
       timeout: {
         type: 'number',
-        description: 'Timeout in seconds (default: 30)',
+        description: 'Timeout in seconds (default: 30). Ignored if progress streaming is used.',
         default: 30,
       },
     },
@@ -37,27 +37,38 @@ interface ExecuteCommandResult {
   stderr: string;
   exitCode: number;
   timedOut: boolean;
+  streamed?: boolean;
 }
 
 /**
  * Handle the acp_remote_execute_command tool invocation
  * Executes a shell command on the remote machine via SSH
+ * Supports progress streaming when progressToken is provided
  * 
  * @param args - Tool arguments containing command, cwd, and timeout
  * @param sshConnection - SSH connection manager for remote operations
+ * @param extra - Optional extra parameters including progressToken
+ * @param server - Server instance for sending progress notifications (optional)
  */
 export async function handleAcpRemoteExecuteCommand(
   args: any,
-  sshConnection: SSHConnectionManager
+  sshConnection: SSHConnectionManager,
+  extra?: any,
+  server?: any
 ): Promise<{ content: Array<{ type: string; text: string }> }> {
   const { command, cwd, timeout = 30 } = args as ExecuteCommandArgs;
+  const progressToken = extra?._meta?.progressToken;
 
-  logger.debug('Executing remote command', { command, cwd, timeout });
+  logger.debug('Executing remote command', { command, cwd, timeout, hasProgressToken: !!progressToken });
 
   try {
-    // Build command with working directory if specified
-    const fullCommand = cwd ? `cd ${cwd} && ${command}` : command;
+    // If progress token provided and server available, use streaming
+    if (progressToken && server) {
+      return await executeWithProgress(command, cwd, sshConnection, progressToken, server);
+    }
     
+    // Otherwise, use existing timeout-based execution (fallback)
+    const fullCommand = cwd ? `cd ${cwd} && ${command}` : command;
     const result = await sshConnection.execWithTimeout(fullCommand, timeout);
     
     logger.debug('Command execution result', {
@@ -67,7 +78,6 @@ export async function handleAcpRemoteExecuteCommand(
       stderrLength: result.stderr.length,
     });
     
-    // Format output as JSON for structured response
     const output: ExecuteCommandResult = {
       stdout: result.stdout,
       stderr: result.stderr,
@@ -101,3 +111,102 @@ export async function handleAcpRemoteExecuteCommand(
     };
   }
 }
+
+/**
+ * Execute command with progress streaming
+ * Sends real-time progress notifications as output is received
+ * 
+ * @param command - Command to execute
+ * @param cwd - Working directory
+ * @param sshConnection - SSH connection
+ * @param progressToken - Token for progress notifications
+ * @param server - Server instance for sending notifications
+ */
+async function executeWithProgress(
+  command: string,
+  cwd: string | undefined,
+  sshConnection: SSHConnectionManager,
+  progressToken: string | number,
+  server: any
+): Promise<{ content: Array<{ type: string; text: string }> }> {
+  logger.debug('Starting streaming execution', { command, cwd, progressToken });
+  
+  const { stream, stderr: stderrStream, exitCode } = await sshConnection.execStream(command, cwd);
+  
+  let stdout = '';
+  let stderr = '';
+  let bytesReceived = 0;
+  let lastProgressTime = 0;
+  const MIN_PROGRESS_INTERVAL = 100; // 100ms rate limiting
+
+  // Stream stdout with progress notifications
+  stream.on('data', (chunk: Buffer) => {
+    const text = chunk.toString();
+    stdout += text;
+    bytesReceived += chunk.length;
+    
+    // Rate limiting: only send progress if enough time elapsed
+    const now = Date.now();
+    if (now - lastProgressTime >= MIN_PROGRESS_INTERVAL) {
+      try {
+        server.notification({
+          method: 'notifications/progress',
+          params: {
+            progressToken,
+            progress: bytesReceived,
+            total: undefined, // Unknown total for streaming
+            message: text,
+          },
+        });
+        lastProgressTime = now;
+        logger.debug('Progress notification sent', { 
+          progressToken, 
+          bytes: bytesReceived,
+          chunkSize: chunk.length 
+        });
+      } catch (error) {
+        logger.warn('Failed to send progress notification', {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+  });
+
+  // Collect stderr (no progress for errors)
+  stderrStream.on('data', (chunk: Buffer) => {
+    stderr += chunk.toString();
+  });
+
+  // Handle stream errors
+  stream.on('error', (error: Error) => {
+    logger.error('Stream error during execution', {
+      command,
+      error: error.message
+    });
+  });
+
+  // Wait for completion
+  const finalExitCode = await exitCode;
+  
+  logger.debug('Streaming execution completed', { 
+    command, 
+    exitCode: finalExitCode,
+    stdoutBytes: stdout.length,
+    stderrBytes: stderr.length,
+  });
+
+  const output: ExecuteCommandResult = {
+    stdout,
+    stderr,
+    exitCode: finalExitCode,
+    timedOut: false,
+    streamed: true, // Indicate this was streamed
+  };
+
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(output, null, 2),
+    }],
+  };
+}

package/src/tools/acp-remote-list-files.ts

@@ -1,9 +1,10 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { SSHConnectionManager } from '../utils/ssh-connection.js';
+import { FileEntry } from '../types/file-entry.js';
 
 export const acpRemoteListFilesTool: Tool = {
   name: 'acp_remote_list_files',
-  description: 'List files and directories in a specified path on the remote machine via SSH',
+  description: 'List files and directories in a specified path on the remote machine via SSH. Returns comprehensive metadata including permissions, timestamps, size, and ownership. Includes hidden files by default.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -16,6 +17,11 @@ export const acpRemoteListFilesTool: Tool = {
         description: 'Whether to list files recursively',
         default: false,
       },
+      includeHidden: {
+        type: 'boolean',
+        description: 'Whether to include hidden files (starting with .)',
+        default: true,
+      },
     },
     required: ['path'],
   },
@@ -24,6 +30,7 @@ export const acpRemoteListFilesTool: Tool = {
 interface ListFilesArgs {
   path: string;
   recursive?: boolean;
+  includeHidden?: boolean;
 }
 
 /**
@@ -37,16 +44,19 @@ export async function handleAcpRemoteListFiles(
   args: any,
   sshConnection: SSHConnectionManager
 ): Promise<{ content: Array<{ type: string; text: string }> }> {
-  const { path, recursive = false } = args as ListFilesArgs;
+  const { path, recursive = false, includeHidden = true } = args as ListFilesArgs;
 
   try {
-    const files = await listRemoteFiles(sshConnection, path, recursive);
+    const entries = await listRemoteFiles(sshConnection, path, recursive, includeHidden);
+    
+    // Format as JSON for structured output
+    const output = JSON.stringify(entries, null, 2);
     
     return {
       content: [
         {
           type: 'text',
-          text: files.join('\n'),
+          text: output,
         },
       ],
     };
@@ -65,30 +75,26 @@ export async function handleAcpRemoteListFiles(
 
 /**
  * Recursively list files in a remote directory via SSH
- * Returns absolute paths for compatibility with acp_remote_read_file
+ * Returns FileEntry objects with comprehensive metadata
  */
 async function listRemoteFiles(
   ssh: SSHConnectionManager,
   dirPath: string,
-  recursive: boolean
-): Promise<string[]> {
-  const entries = await ssh.listFiles(dirPath);
-  const files: string[] = [];
+  recursive: boolean,
+  includeHidden: boolean
+): Promise<FileEntry[]> {
+  const entries = await ssh.listFiles(dirPath, includeHidden);
+  const allEntries: FileEntry[] = [...entries];
 
-  for (const entry of entries) {
-    // Construct absolute path by combining dirPath with entry name
-    const fullPath = `${dirPath}/${entry.name}`.replace(/\/+/g, '/');
-    
-    if (entry.isDirectory) {
-      files.push(`${fullPath}/`);  // Return absolute path with trailing slash
-      if (recursive) {
-        const subFiles = await listRemoteFiles(ssh, fullPath, recursive);
-        files.push(...subFiles);  // Sub-files already have absolute paths
+  // Recursively list subdirectories if requested
+  if (recursive) {
+    for (const entry of entries) {
+      if (entry.type === 'directory') {
+        const subEntries = await listRemoteFiles(ssh, entry.path, recursive, includeHidden);
+        allEntries.push(...subEntries);
       }
-    } else {
-      files.push(fullPath);  // Return absolute path
     }
   }
 
-  return files.sort();
+  return allEntries;
 }

package/src/types/file-entry.ts

@@ -0,0 +1,123 @@
+/**
+ * Comprehensive file entry with metadata
+ */
+export interface FileEntry {
+  /** Filename (without path) */
+  name: string;
+  
+  /** Absolute path to file */
+  path: string;
+  
+  /** File type */
+  type: 'file' | 'directory' | 'symlink' | 'other';
+  
+  /** File size in bytes */
+  size: number;
+  
+  /** File permissions */
+  permissions: {
+    /** Octal mode (e.g., 0o644) */
+    mode: number;
+    
+    /** Human-readable string (e.g., "rw-r--r--") */
+    string: string;
+    
+    /** Owner permissions */
+    owner: {
+      read: boolean;
+      write: boolean;
+      execute: boolean;
+    };
+    
+    /** Group permissions */
+    group: {
+      read: boolean;
+      write: boolean;
+      execute: boolean;
+    };
+    
+    /** Others permissions */
+    others: {
+      read: boolean;
+      write: boolean;
+      execute: boolean;
+    };
+  };
+  
+  /** File ownership */
+  owner: {
+    /** User ID */
+    uid: number;
+    
+    /** Group ID */
+    gid: number;
+  };
+  
+  /** File timestamps */
+  timestamps: {
+    /** Last access time (ISO 8601) */
+    accessed: string;
+    
+    /** Last modification time (ISO 8601) */
+    modified: string;
+  };
+}
+
+/**
+ * Convert Unix mode to human-readable permission string
+ * @param mode - Unix file mode (e.g., 33188 for -rw-r--r--)
+ * @returns Permission string (e.g., "rw-r--r--")
+ */
+export function modeToPermissionString(mode: number): string {
+  const perms = [
+    (mode & 0o400) ? 'r' : '-',
+    (mode & 0o200) ? 'w' : '-',
+    (mode & 0o100) ? 'x' : '-',
+    (mode & 0o040) ? 'r' : '-',
+    (mode & 0o020) ? 'w' : '-',
+    (mode & 0o010) ? 'x' : '-',
+    (mode & 0o004) ? 'r' : '-',
+    (mode & 0o002) ? 'w' : '-',
+    (mode & 0o001) ? 'x' : '-',
+  ];
+  return perms.join('');
+}
+
+/**
+ * Parse Unix mode into structured permissions object
+ * @param mode - Unix file mode
+ * @returns Structured permissions object
+ */
+export function parsePermissions(mode: number) {
+  return {
+    mode,
+    string: modeToPermissionString(mode),
+    owner: {
+      read: (mode & 0o400) !== 0,
+      write: (mode & 0o200) !== 0,
+      execute: (mode & 0o100) !== 0,
+    },
+    group: {
+      read: (mode & 0o040) !== 0,
+      write: (mode & 0o020) !== 0,
+      execute: (mode & 0o010) !== 0,
+    },
+    others: {
+      read: (mode & 0o004) !== 0,
+      write: (mode & 0o002) !== 0,
+      execute: (mode & 0o001) !== 0,
+    },
+  };
+}
+
+/**
+ * Determine file type from SFTP stats
+ * @param stats - SFTP file stats
+ * @returns File type string
+ */
+export function getFileType(stats: any): 'file' | 'directory' | 'symlink' | 'other' {
+  if (stats.isDirectory()) return 'directory';
+  if (stats.isFile()) return 'file';
+  if (stats.isSymbolicLink()) return 'symlink';
+  return 'other';
+}

package/src/utils/ssh-connection.ts

@@ -1,5 +1,6 @@
 import { Client, SFTPWrapper } from 'ssh2';
 import { SSHConfig } from '../types/ssh-config.js';
+import { FileEntry, parsePermissions, getFileType } from '../types/file-entry.js';
 import { logger } from './logger.js';
 
 /**
@@ -159,6 +160,72 @@ export class SSHConnectionManager {
     }
   }
 
+  /**
+   * Execute a command on the remote server with streaming output
+   * Returns streams instead of buffered output for real-time progress
+   *
+   * @param command - Shell command to execute
+   * @param cwd - Optional working directory
+   * @returns Object with stdout stream, stderr stream, and exit code promise
+   */
+  async execStream(
+    command: string,
+    cwd?: string
+  ): Promise<{
+    stream: NodeJS.ReadableStream;
+    stderr: NodeJS.ReadableStream;
+    exitCode: Promise<number>;
+  }> {
+    if (!this.connected) {
+      await this.connect();
+    }
+
+    const fullCommand = cwd ? `cd "${cwd}" && ${command}` : command;
+    const startTime = Date.now();
+    logger.sshCommand(fullCommand, cwd);
+
+    return new Promise((resolve, reject) => {
+      this.client.exec(fullCommand, (err, stream) => {
+        if (err) {
+          logger.error('SSH exec failed', {
+            command: fullCommand,
+            error: err.message
+          });
+          reject(err);
+          return;
+        }
+
+        logger.debug('SSH stream started', { command: fullCommand });
+
+        const exitCodePromise = new Promise<number>((resolveExit) => {
+          stream.on('close', (code: number) => {
+            const duration = Date.now() - startTime;
+            logger.debug('SSH stream closed', {
+              command: fullCommand,
+              exitCode: code,
+              duration: `${duration}ms`
+            });
+            resolveExit(code);
+          });
+        });
+
+        // Handle stream errors
+        stream.on('error', (error: Error) => {
+          logger.error('SSH stream error', {
+            command: fullCommand,
+            error: error.message
+          });
+        });
+
+        resolve({
+          stream: stream,
+          stderr: stream.stderr,
+          exitCode: exitCodePromise,
+        });
+      });
+    });
+  }
+
   /**
    * Get SFTP wrapper for file operations
    */
@@ -179,24 +246,141 @@ export class SSHConnectionManager {
   }
 
   /**
-   * List files in a directory using SFTP
+   * List files in a directory with comprehensive metadata
+   * Uses hybrid approach: shell ls for filenames (includes hidden), SFTP stat for metadata
+   *
+   * @param path - Directory path to list
+   * @param includeHidden - Whether to include hidden files (default: true)
+   * @returns Array of FileEntry objects with complete metadata
    */
-  async listFiles(path: string): Promise<Array<{ name: string; isDirectory: boolean }>> {
+  async listFiles(path: string, includeHidden: boolean = true): Promise<FileEntry[]> {
+    const startTime = Date.now();
+    logger.debug('Listing files', { path, includeHidden });
+
+    try {
+      // Step 1: Use shell command to get ALL filenames (including hidden)
+      const lsFlag = includeHidden ? '-A' : '';
+      const command = `ls ${lsFlag} -1 "${path}" 2>/dev/null`;
+      const result = await this.execWithTimeout(command, 10);
+
+      if (result.exitCode !== 0) {
+        throw new Error(`ls command failed: ${result.stderr}`);
+      }
+
+      const filenames = result.stdout
+        .split('\n')
+        .map(f => f.trim())
+        .filter(f => f !== '' && f !== '.' && f !== '..');
+
+      logger.debug('Filenames retrieved via shell', {
+        path,
+        count: filenames.length,
+        method: 'shell',
+      });
+
+      // Step 2: Get rich metadata for each file using SFTP stat()
+      const sftp = await this.getSFTP();
+      const entries: FileEntry[] = [];
+
+      for (const filename of filenames) {
+        const fullPath = `${path}/${filename}`.replace(/\/+/g, '/');
+
+        try {
+          const stats = await new Promise<any>((resolve, reject) => {
+            sftp.stat(fullPath, (err, stats) => {
+              if (err) reject(err);
+              else resolve(stats);
+            });
+          });
+
+          entries.push({
+            name: filename,
+            path: fullPath,
+            type: getFileType(stats),
+            size: stats.size,
+            permissions: parsePermissions(stats.mode),
+            owner: {
+              uid: stats.uid,
+              gid: stats.gid,
+            },
+            timestamps: {
+              accessed: new Date(stats.atime * 1000).toISOString(),
+              modified: new Date(stats.mtime * 1000).toISOString(),
+            },
+          });
+        } catch (error) {
+          // Skip files we can't stat (permissions, race conditions, etc.)
+          logger.warn('Failed to stat file, skipping', {
+            path: fullPath,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+
+      const duration = Date.now() - startTime;
+      logger.debug('Files listed successfully', {
+        path,
+        count: entries.length,
+        duration: `${duration}ms`,
+        method: 'hybrid',
+      });
+
+      return entries;
+    } catch (error) {
+      // Fallback to SFTP readdir if shell command fails
+      logger.warn('Shell ls command failed, falling back to SFTP readdir', {
+        path,
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      return this.listFilesViaSFTP(path, includeHidden);
+    }
+  }
+
+  /**
+   * Fallback method: List files using SFTP readdir (may miss hidden files)
+   * @private
+   */
+  private async listFilesViaSFTP(path: string, includeHidden: boolean): Promise<FileEntry[]> {
     const sftp = await this.getSFTP();
 
     return new Promise((resolve, reject) => {
       sftp.readdir(path, (err, list) => {
         if (err) {
+          logger.error('SFTP readdir failed', { path, error: err.message });
           reject(err);
           return;
         }
 
-        const files = list.map((item) => ({
+        let entries = list.map((item) => ({
           name: item.filename,
-          isDirectory: item.attrs.isDirectory(),
+          path: `${path}/${item.filename}`.replace(/\/+/g, '/'),
+          type: getFileType(item.attrs),
+          size: item.attrs.size,
+          permissions: parsePermissions(item.attrs.mode),
+          owner: {
+            uid: item.attrs.uid,
+            gid: item.attrs.gid,
+          },
+          timestamps: {
+            accessed: new Date(item.attrs.atime * 1000).toISOString(),
+            modified: new Date(item.attrs.mtime * 1000).toISOString(),
+          },
         }));
 
-        resolve(files);
+        // SFTP readdir doesn't return hidden files, so filter if requested
+        if (!includeHidden) {
+          entries = entries.filter(e => !e.name.startsWith('.'));
+        }
+
+        logger.debug('Files listed via SFTP fallback', {
+          path,
+          count: entries.length,
+          method: 'sftp',
+          note: 'Hidden files may be missing (SFTP limitation)',
+        });
+
+        resolve(entries);
       });
     });
   }