ftp-mcp 1.3.0 → 1.4.0

package/README.md

@@ -9,7 +9,8 @@ An enterprise-grade Model Context Protocol (MCP) server providing sophisticated
 - **Security & Authorization**: Native support for SSH Key exchanges (both direct and Agent-forwarding), Pass-phrase authentication, and explicit `readOnly: true` config profiling to sandbox dangerous modifications.
 - **Smart Directory Syncing**: Deep hash-and-size sync algorithms for minimal network payload deployments, complete with `--dryRun` toggling that logs differences back to the LLM without modifying live directories.
 - **Git & Node Aware**: Automatically unpacks `.gitignore` and `.ftpignore` environments. Semantically evaluates `package.json` for smart context summarization.
-- **Interactive Initializer**: Simple scaffolding of configurations natively via the CLI.
+- **AI-Guided Initialization**: A dedicated "AI-First" configuration track (`--init`) that provides highly verbose instruction context during setup, ensuring AI assistants absorb server capabilities and operational constraints directly into their working memory.
+- **Interactive Initializer**: Simple scaffolding of configurations natively via the CLI for human users.
 - **Audit Logging**: Robust instrumentation generating structured `.ftp-mcp-audit.log` traces on all filesystem mutations.
 - **Comprehensive E2E Testing**: Guaranteed operational functionality validated continuously by Node-based MCP IO test orchestration.
 

package/index.js

@@ -5,6 +5,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { Client as FTPClient } from "basic-ftp";
 import SFTPClient from "ssh2-sftp-client";
@@ -25,8 +27,41 @@ import crypto from "crypto";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+// AI-First Semantic Icons
+const ICON = {
+  DIR: "📂",
+  FILE: "📄",
+  PKG: "📦",
+  CONFIG: "⚙️",
+  SECRET: "🔒",
+  BACKUP: "🕰️",
+  HINT: "💡",
+  ERROR: "❌"
+};
+
+/**
+ * AI-First: Generate context-aware suggestions for troubleshooting and next steps.
+ * This helper ensures the LLM receives actionable, backticked commands.
+ */
+function getAISuggestion(type, context = {}) {
+  switch (type) {
+    case 'error_enoent':
+      return `[AI: Path not found. Suggested fix: Check your CWD with \`ftp_list "."\` or verify the path exists with \`ftp_exists "${context.path}"\`]`;
+    case 'error_permission':
+      return `[AI: Permission denied. Suggested fix: Verify user rights with \`ftp_stat "${context.path}"\` or check if the server supports \`ftp_chmod\`]`;
+    case 'hint_connected':
+      return `[HINT: Connection active. Suggested next step: Run \`ftp_analyze_workspace "."\` to understand the project architecture.]`;
+    case 'hint_list_config':
+      return `[HINT: Found project manifests. Suggested next step: Read \`package.json\` using \`ftp_get_contents "package.json"\` to see dependencies.]`;
+    case 'hint_destructive_readonly':
+      return `[AI: Server is in READ-ONLY mode. Use \`ftp_sync --dryRun\` to simulate this deployment instead.]`;
+    default:
+      return null;
+  }
+}
+
 // Read version from package.json to avoid version drift (CODE-1)
-let SERVER_VERSION = "1.3.0";
+let SERVER_VERSION = "1.4.0";
 try {
   const pkg = JSON.parse(readFileSync(path.join(__dirname, 'package.json'), 'utf8'));
   SERVER_VERSION = pkg.version || SERVER_VERSION;
@@ -42,27 +77,50 @@ if (process.argv.includes("--init")) {
 
     intro('🚀 Welcome to FTP-MCP Initialization Wizard');
 
+    const setupType = await select({
+      message: 'Who is running this setup wizard?',
+      options: [
+        { value: 'ai', label: '1. AI Agent Install (Provides verbose context on how to use the server)', hint: 'Detailed instructions for LLMs' },
+        { value: 'human', label: '2. Human Install (Standard Setup)', hint: 'Concise standard setup for human users' }
+      ]
+    });
+    if (isCancel(setupType)) { outro('Setup cancelled.'); process.exit(0); }
+
+    const isAI = setupType === 'ai';
+
     const host = await text({
-      message: 'Enter your FTP/SFTP Host (e.g. sftp://ftp.example.com)',
+      message: isAI
+        ? '[AI INSTRUCTION] Provide the remote FTP/SFTP Host address. (e.g. sftp://ftp.example.com or ftp://1.2.3.4). Note: This tool brokers remote filesystem access as an MCP server.'
+        : 'Enter your FTP/SFTP Host (e.g. sftp://ftp.example.com)',
       placeholder: 'sftp://127.0.0.1',
-      validate: (val) => val.length === 0 ? "Host is required!" : undefined,
+      validate: (val) => (!val || val.length === 0) ? "Host is required!" : undefined,
     });
     if (isCancel(host)) { outro('Setup cancelled.'); process.exit(0); }
 
     const user = await text({
-      message: 'Enter your Username',
-      validate: (val) => val.length === 0 ? "User is required!" : undefined,
+      message: isAI
+        ? '[AI INSTRUCTION] Provide the remote server username. This credential will be used for all subsequent tool calls in this session.'
+        : 'Enter your Username',
+      validate: (val) => (!val || val.length === 0) ? "User is required!" : undefined,
     });
     if (isCancel(user)) { outro('Setup cancelled.'); process.exit(0); }
 
     const pass = await promptPassword({
-      message: 'Enter your Password (optional if using keys)',
+      message: isAI
+        ? '[AI INSTRUCTION] Provide the password for the connection. If you are using SSH key authentication for SFTP, you may leave this field empty.'
+        : 'Enter your Password (optional if using keys)',
     });
     if (isCancel(pass)) { outro('Setup cancelled.'); process.exit(0); }
 
     const port = await text({
-      message: 'Enter port (optional, defaults to 21 for FTP, 22 for SFTP)',
-      placeholder: '22'
+      message: isAI
+        ? '[AI INSTRUCTION] Provide the specific port for the connection. Default is 21 for FTP and 22 for SFTP. If the user has not specified a custom port, you should leave this blank.'
+        : 'Enter port (optional, defaults to 21 for FTP, 22 for SFTP)',
+      placeholder: '22',
+      validate: (val) => {
+        if (val && isNaN(parseInt(val, 10))) return "Port must be a number!";
+        return undefined;
+      }
     });
     if (isCancel(port)) { outro('Setup cancelled.'); process.exit(0); }
 
@@ -70,10 +128,17 @@ if (process.argv.includes("--init")) {
     let privateKey = '';
 
     if (isSFTP) {
-      const usesKey = await confirm({ message: 'Are you using an SSH Private Key instead of a password?' });
-      if (!isCancel(usesKey) && usesKey) {
+      const usesKey = await confirm({
+        message: isAI
+          ? '[AI INSTRUCTION] An SFTP protocol was detected. Is the user employing an SSH Private Key instead of a traditional password? (Recommended for production)'
+          : 'Are you using an SSH Private Key instead of a password?'
+      });
+      if (isCancel(usesKey)) { outro('Setup cancelled.'); process.exit(0); }
+      if (usesKey) {
         privateKey = await text({
-          message: 'Path to your private key (e.g. ~/.ssh/id_rsa)',
+          message: isAI
+            ? '[AI INSTRUCTION] Provide the absolute local filesystem path to the SSH private key (e.g. ~/.ssh/id_rsa). This path must be accessible from the environment where the MCP server is running.'
+            : 'Path to your private key (e.g. ~/.ssh/id_rsa)',
         });
         if (isCancel(privateKey)) { outro('Setup cancelled.'); process.exit(0); }
       }
@@ -92,9 +157,26 @@ if (process.argv.includes("--init")) {
 
     await fs.writeFile(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf8');
 
-    note(`✅ Successfully generated config file at:\n${CONFIG_FILE}`, 'Success');
+    if (isAI) {
+      note(
+        "AI CONTEXT ESTABLISHED: The `.ftpconfig` file has been generated.\n" +
+        "You now have access to this MCP server's tools.\n\n" +
+        "Important capabilities:\n" +
+        "- Content-rich operations: `ftp_list`, `ftp_download`, `ftp_upload`.\n" +
+        "- Batched operations: `ftp_batch_upload`, `ftp_batch_download` (Highly recommended for speed).\n" +
+        "- Safe regex searches: `ftp_search`.\n" +
+        "- Transparent paths: All remote operations are relative to the server root.\n\n" +
+        "You may now proceed with the user's tasks.",
+        "Configuration Success"
+      );
+    } else {
+      note(`✅ Successfully generated config file at:\n${CONFIG_FILE}`, 'Success');
+    }
 
-    outro("You're ready to deploy with MCP! Ask your AI to 'list remote files'");
+    outro(isAI
+      ? "Deployment complete. You are now configured to manage the remote filesystem."
+      : "You're ready to deploy with MCP! Ask your AI to 'list remote files'"
+    );
   } catch (err) {
     console.error(`❌ Init failed: ${err.message}`);
   }
@@ -104,6 +186,7 @@ if (process.argv.includes("--init")) {
 
 let currentConfig = null;
 let currentProfile = null;
+let sessionHintShown = false;
 
 const DEFAULT_IGNORE_PATTERNS = [
   'node_modules/**',
@@ -739,11 +822,12 @@ function generateSemanticPreview(filesToChange) {
 const server = new Server(
   {
     name: "ftp-mcp-server",
-    version: SERVER_VERSION, // CODE-1: reads from package.json at startup
+    version: SERVER_VERSION,
   },
   {
     capabilities: {
       tools: {},
+      resources: {},
     },
   }
 );
@@ -753,17 +837,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     tools: [
       {
         name: "ftp_connect",
-        description: "Connect to a named FTP profile from .ftpconfig",
+        description: "Establish or switch the active connection to a specific remote server profile defined in your .ftpconfig (e.g., 'production', 'staging'). This is the first step before performing any remote operations.",
         inputSchema: {
           type: "object",
           properties: {
             profile: {
               type: "string",
-              description: "Profile name from .ftpconfig (e.g., 'production', 'staging')"
+              description: "The named profile key from your .ftpconfig file."
             },
             useEnv: {
               type: "boolean",
-              description: "Force use of environment variables instead of .ftpconfig",
+              description: "If true, bypasses .ftpconfig and connects using global environment variables (FTPMCP_HOST, etc.)",
               default: false
             }
           }
@@ -771,13 +855,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_deploy",
-        description: "Run a named deployment preset from .ftpconfig",
+        description: "Execute a pre-defined deployment preset from .ftpconfig. This typically maps a specific local folder to a remote target with pre-configured exclusion rules.",
         inputSchema: {
           type: "object",
           properties: {
             deployment: {
               type: "string",
-              description: "Deployment name from .ftpconfig deployments (e.g., 'deploy-frontend', 'deploy-api')"
+              description: "The name of the deployment preset (e.g., 'web-app', 'api-server')."
             }
           },
           required: ["deployment"]
@@ -793,23 +877,23 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_list",
-        description: "List files and directories in a remote FTP/SFTP path",
+        description: "List files and directories in a remote path. Use 'limit' and 'offset' for pagination when dealing with directories containing hundreds of files to avoid context overflow.",
         inputSchema: {
           type: "object",
           properties: {
             path: {
               type: "string",
-              description: "Remote path to list (defaults to current directory)",
+              description: "Remote directory path (defaults to current working directory).",
               default: "."
             },
             limit: {
               type: "number",
-              description: "Maximum number of files to return",
+              description: "Maximum results to return in this chunk.",
               default: 100
             },
             offset: {
               type: "number",
-              description: "Number of files to skip over",
+              description: "Starting position in the file list for pagination.",
               default: 0
             }
           }
@@ -817,21 +901,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_get_contents",
-        description: "Read file content directly from FTP/SFTP without downloading",
+        description: "Read the source text of a remote file. CRITICAL: For large files, use 'startLine' and 'endLine' to extract specific chunks and prevent hitting the LLM context limit.",
         inputSchema: {
           type: "object",
           properties: {
             path: {
               type: "string",
-              description: "Remote file path to read"
+              description: "Absolute or relative remote path to the file."
             },
             startLine: {
               type: "number",
-              description: "Optional start line for reading chunk (1-indexed)"
+              description: "Optional: The first line to include in the output (1-indexed)."
             },
             endLine: {
               type: "number",
-              description: "Optional end line for reading chunk (inclusive, 1-indexed)"
+              description: "Optional: The last line to include (inclusive, 1-indexed)."
             }
           },
           required: ["path"]
@@ -839,25 +923,25 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_patch_file",
-        description: "Apply a Unified Diff patch to a remote file",
+        description: "Apply a Unified Diff patch to a remote file. RECOMMENDED: Use this instead of ftp_put_contents for updating existing files to minimize bandwidth and ensure atomic-like updates. For new files, use ftp_put_contents.",
         inputSchema: {
           type: "object",
           properties: {
             path: {
               type: "string",
-              description: "Remote file path to patch"
+              description: "Remote path to the existing file to be patched."
             },
             patch: {
               type: "string",
-              description: "Unified diff string containing the changes"
+              description: "The Unified Diff formatted string containing your local changes."
             },
             expectedHash: {
               type: "string",
-              description: "Optional MD5 hash of the file before patching to prevent drift"
+              description: "Optional (but recommended): The SHA-256 hash of the remote file before patching to prevent race conditions (drift protection)."
             },
             createBackup: {
               type: "boolean",
-              description: "Create a .bak file before patching",
+              description: "Generate a .bak copy of the remote file before applying the changes.",
               default: true
             }
           },
@@ -866,13 +950,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_analyze_workspace",
-        description: "Semantically analyze a remote directory to detect project type and dependencies",
+        description: "Introspect the remote directory to identify technical environments (e.g., Node.js, PHP, Python) and read dependency manifests. Use this to gain architectural context of a new codebase.",
         inputSchema: {
           type: "object",
           properties: {
             path: {
               type: "string",
-              description: "Remote directory path to analyze (defaults to current)",
+              description: "Remote directory to analyze (defaults to current server root).",
               default: "."
             }
           }
@@ -880,17 +964,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_put_contents",
-        description: "Write content directly to FTP/SFTP file without local file",
+        description: "Write raw text directly to a remote destination. Best for creating NEW files. For modifying existing files, prefer ftp_patch_file.",
         inputSchema: {
           type: "object",
           properties: {
             path: {
               type: "string",
-              description: "Remote file path to write"
+              description: "Remote destination path."
             },
             content: {
               type: "string",
-              description: "Content to write to the file"
+              description: "The full string content to write."
             }
           },
           required: ["path", "content"]
@@ -898,13 +982,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_stat",
-        description: "Get file metadata (size, modified date, permissions)",
+        description: "Retrieve comprehensive metadata for a remote property, including size, modification timestamps, and UNIX permissions.",
         inputSchema: {
           type: "object",
           properties: {
             path: {
               type: "string",
-              description: "Remote file path"
+              description: "Remote file or directory path."
             }
           },
           required: ["path"]
@@ -912,13 +996,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_exists",
-        description: "Check if file or folder exists on FTP/SFTP server",
+        description: "Check for the existence of a file or folder without performing heavy file operations. Use this for conditional logic workflows.",
         inputSchema: {
           type: "object",
           properties: {
             path: {
               type: "string",
-              description: "Remote path to check"
+              description: "Remote target path."
             }
           },
           required: ["path"]
@@ -926,18 +1010,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_tree",
-        description: "Get recursive directory listing (entire structure at once)",
+        description: "Generate a complete recursive directory map. Use this to visualize project structure, but be cautious with 'maxDepth' in very large remote repositories to avoid excessive network payload.",
         inputSchema: {
           type: "object",
           properties: {
             path: {
               type: "string",
-              description: "Remote path to start tree from",
+              description: "Remote directory path to start mapping from (defaults to root).",
               default: "."
             },
             maxDepth: {
               type: "number",
-              description: "Maximum depth to recurse",
+              description: "Maximum recursion depth to prevent infinite loops or huge payloads.",
               default: 10
             }
           }
@@ -945,40 +1029,40 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_search",
-        description: "Advanced remote search: find files by name, content, or type",
+        description: "Advanced remote file search. Supports finding files by name (wildcards), extension, or content regex (grep-like). Use this to find specific code patterns across the remote workspace.",
         inputSchema: {
           type: "object",
           properties: {
             pattern: {
               type: "string",
-              description: "Filename search pattern (supports wildcards like *.js)"
+              description: "File name pattern (e.g. `*.js`, `db_*`)."
             },
             contentPattern: {
               type: "string",
-              description: "Regex pattern to search inside file contents (grep)"
+              description: "Regex pattern to search inside file contents. Highly efficient for finding variable usage or specific logic."
             },
             extension: {
               type: "string",
-              description: "Filter by file extension (e.g., '.js', '.php')"
+              description: "Restrict search to specific file extensions (e.g. `.css`)."
             },
             findLikelyConfigs: {
               type: "boolean",
-              description: "If true, prioritizes finding config, auth, and build files",
+              description: "Prioritize searching for project manifests and config files (package.json, .env, etc.)",
               default: false
             },
             path: {
               type: "string",
-              description: "Remote path to search in",
+              description: "Remote directory to start the recursive search in.",
               default: "."
             },
             limit: {
               type: "number",
-              description: "Maximum results to return",
+              description: "Maximum matches to return.",
               default: 50
             },
             offset: {
               type: "number",
-              description: "Results to skip over",
+              description: "Skip initial matches for pagination.",
               default: 0
             }
           }
@@ -986,17 +1070,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_copy",
-        description: "Duplicate files on server (SFTP only)",
+        description: "Directly duplicate a file on the remote server without downloading and re-uploading. CRITICAL: Only supported on SFTP connections.",
         inputSchema: {
           type: "object",
           properties: {
             sourcePath: {
               type: "string",
-              description: "Source file path"
+              description: "Qualified remote source path."
             },
             destPath: {
               type: "string",
-              description: "Destination file path"
+              description: "Target remote destination path."
             }
           },
           required: ["sourcePath", "destPath"]
@@ -1004,18 +1088,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_batch_upload",
-        description: "Upload multiple files at once",
+        description: "Upload a collection of local files to remote destinations in a single operation. HIGHLY RECOMMENDED for multiple files to minimize connection handshaking overhead and drastically improve performance.",
         inputSchema: {
           type: "object",
           properties: {
             files: {
               type: "array",
-              description: "Array of {localPath, remotePath} objects",
+              description: "A list of objects, each defining a local source and a remote destination.",
               items: {
                 type: "object",
                 properties: {
-                  localPath: { type: "string" },
-                  remotePath: { type: "string" }
+                  localPath: { type: "string", description: "Source path on your local machine." },
+                  remotePath: { type: "string", description: "Target path on the remote server." }
                 },
                 required: ["localPath", "remotePath"]
               }
@@ -1026,18 +1110,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_batch_download",
-        description: "Download multiple files at once",
+        description: "Download a selection of remote files to local destinations. HIGHLY RECOMMENDED for bulk downloads to leverage stable socket persistence.",
         inputSchema: {
           type: "object",
           properties: {
             files: {
               type: "array",
-              description: "Array of {remotePath, localPath} objects",
+              description: "A list of objects mapping remote sources to local destinations.",
               items: {
                 type: "object",
                 properties: {
-                  remotePath: { type: "string" },
-                  localPath: { type: "string" }
+                  remotePath: { type: "string", description: "Source path on the remote server." },
+                  localPath: { type: "string", description: "Destination path on your local machine." }
                 },
                 required: ["remotePath", "localPath"]
               }
@@ -1048,33 +1132,32 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_sync",
-        description: "Smart sync local ↔ remote (only changed files)",
+        description: "Deploy entire project folders using smart synchronization. Analyzes local and remote directory trees and only transfers files that have changed in size or modification date. Automatically respects .gitignore and .ftpignore.",
         inputSchema: {
           type: "object",
           properties: {
             localPath: {
               type: "string",
-              description: "Local directory path"
+              description: "The source directory on your local machine."
             },
             remotePath: {
               type: "string",
-              description: "Remote directory path"
+              description: "The target destination directory on the remote server."
             },
             direction: {
               type: "string",
-              // QUAL-2: Only 'upload' is implemented; removed 'download'/'both' to avoid silent no-ops
-              description: "Sync direction: currently only 'upload' is supported",
+              description: "Sync direction. Currently only 'upload' is implemented for safety.",
               enum: ["upload"],
               default: "upload"
             },
             dryRun: {
               type: "boolean",
-              description: "If true, simulates the sync without transferring files",
+              description: "If true, logs exactly which files would be changed without performing any actual transfers.",
               default: false
             },
             useManifest: {
               type: "boolean",
-              description: "Use local manifest cache for faster deploys (drift-aware)",
+              description: "Enables the local manifest cache for extremely fast delta detection on subsequent syncs.",
               default: true
             }
           },
@@ -1083,13 +1166,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_disk_space",
-        description: "Check available space on server (SFTP only)",
+        description: "Query the remote server for available disk space. CRITICAL: Only available on SFTP connections.",
         inputSchema: {
           type: "object",
           properties: {
             path: {
               type: "string",
-              description: "Remote path to check",
+              description: "Remote filesystem path to check (defaults to server root).",
               default: "."
             }
           }
@@ -1097,17 +1180,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_upload",
-        description: "Upload a file to the FTP/SFTP server",
+        description: "Standard single-file transport to the remote server. For bulk transfers, favor ftp_batch_upload.",
         inputSchema: {
           type: "object",
           properties: {
             localPath: {
               type: "string",
-              description: "Local file path to upload"
+              description: "Source path on your local machine."
             },
             remotePath: {
               type: "string",
-              description: "Remote destination path"
+              description: "Target location on the remote server."
             }
           },
           required: ["localPath", "remotePath"]
@@ -1115,17 +1198,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_download",
-        description: "Download a file from the FTP/SFTP server",
+        description: "Standard single-file transport from the remote server. For bulk downloads, favor ftp_batch_download.",
         inputSchema: {
           type: "object",
           properties: {
             remotePath: {
               type: "string",
-              description: "Remote file path to download"
+              description: "Source file location on the remote server."
             },
             localPath: {
               type: "string",
-              description: "Local destination path"
+              description: "Destination location on your local machine."
             }
           },
           required: ["remotePath", "localPath"]
@@ -1133,13 +1216,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_delete",
-        description: "Delete a file from the FTP/SFTP server",
+        description: "Permanently remove a file from the remote server. Use with caution.",
         inputSchema: {
           type: "object",
           properties: {
             path: {
               type: "string",
-              description: "Remote file path to delete"
+              description: "The remote file path to be destroyed."
             }
           },
           required: ["path"]
@@ -1147,13 +1230,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_mkdir",
-        description: "Create a directory on the FTP/SFTP server",
+        description: "Create a new directory structure on the remote server. Supports nested creation (mkdir -p).",
         inputSchema: {
           type: "object",
           properties: {
             path: {
               type: "string",
-              description: "Remote directory path to create"
+              description: "The remote directory path to create."
             }
           },
           required: ["path"]
@@ -1161,17 +1244,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_rmdir",
-        description: "Remove a directory from the FTP/SFTP server",
+        description: "Delete a directory from the remote server.",
         inputSchema: {
           type: "object",
           properties: {
             path: {
               type: "string",
-              description: "Remote directory path to remove"
+              description: "The remote directory path to remove."
             },
             recursive: {
               type: "boolean",
-              description: "Remove directory recursively",
+              description: "If true, deletes all files and subdirectories within the target directory.",
               default: false
             }
           },
@@ -1180,17 +1263,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_chmod",
-        description: "Change file permissions on the FTP/SFTP server (SFTP only)",
+        description: "Change remote file permissions. CRITICAL: Only supported on SFTP connections.",
         inputSchema: {
           type: "object",
           properties: {
             path: {
               type: "string",
-              description: "Remote file path"
+              description: "Remote file path to modify."
             },
             mode: {
               type: "string",
-              description: "Permission mode in octal (e.g., '755', '644')"
+              description: "Standard octal permission string (e.g., '755' for executable, '644' for read-write)."
             }
           },
           required: ["path", "mode"]
@@ -1198,17 +1281,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_rename",
-        description: "Rename or move a file on the FTP/SFTP server",
+        description: "Move or rename files and directories on the remote server.",
         inputSchema: {
           type: "object",
           properties: {
             oldPath: {
               type: "string",
-              description: "Current file path"
+              description: "Current remote location."
             },
             newPath: {
               type: "string",
-              description: "New file path"
+              description: "New desired remote location."
             }
           },
           required: ["oldPath", "newPath"]
@@ -1216,13 +1299,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_rollback",
-        description: "Rollback a previous transaction using its snapshot",
+        description: "Undo a previous file mutation by restoring it from a system-generated snapshot. This provides safety during complex refactoring tasks.",
         inputSchema: {
           type: "object",
           properties: {
             transactionId: {
               type: "string",
-              description: "Transaction ID to rollback (e.g., tx_1234567890_abcd)"
+              description: "Specific ID associated with the snapshot (e.g., 'tx_12345'). Get this from ftp_list_transactions."
             }
           },
           required: ["transactionId"]
@@ -1230,7 +1313,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_list_transactions",
-        description: "List available rollback transactions",
+        description: "Expose all recent mutations currently stored in the system's SnapshotManager. Essential for planning rollbacks.",
         inputSchema: {
           type: "object",
           properties: {}
@@ -1238,13 +1321,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_probe_capabilities",
-        description: "Probe the server to detect supported features (chmod, symlinks, disk space, etc.)",
+        description: "Scan the remote server to determine supported filesystem features (e.g., chmod availability, symlink support, disk space querying). Helpful for troubleshooting capabilities.",
         inputSchema: {
           type: "object",
           properties: {
             testPath: {
               type: "string",
-              description: "A safe remote directory to run tests in (defaults to current directory)",
+              description: "A safe, ephemeral directory to run capability benchmarks in.",
               default: "."
             }
           }
@@ -1252,7 +1335,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ftp_telemetry",
-        description: "Get connection health and performance telemetry",
+        description: "Retrieve internal performance metrics, including average latency, connection pool health, and total processed bytes.",
         inputSchema: {
           type: "object",
           properties: {}
@@ -1262,6 +1345,51 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
   };
 });
 
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  return {
+    resources: [
+      {
+        uri: "mcp://instruction/server-state",
+        name: "Active Server Instruction & Context",
+        description: "Provides a real-time summary of the active connection profile, security constraints, and operational hints to optimize agent behavior.",
+        mimeType: "text/markdown"
+      }
+    ]
+  };
+});
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  if (request.params.uri === "mcp://instruction/server-state") {
+    const isReadOnly = currentConfig?.readOnly || false;
+    const protocol = currentConfig?.host?.startsWith('sftp://') ? 'SFTP' : 'FTP';
+    
+    const content = `# ftp-mcp Server Context (Agent Guide)
+**Current Version:** ${SERVER_VERSION}
+**Active Profile:** ${currentProfile || 'Environment Variables'}
+**Connection Mode:** ${protocol}
+**Security Status:** ${isReadOnly ? 'READ-ONLY (Destructive operations disabled)' : 'READ-WRITE'}
+
+## 💡 Operational Recommendations:
+1. **Prefer Patches**: Use \`ftp_patch_file\` instead of \`ftp_put_contents\` for existing files to minimize token usage and bandwidth.
+2. **Batch for Speed**: Use \`ftp_batch_upload\` and \`ftp_batch_download\` for multi-file operations.
+3. **Workspace Context**: If this is a new codebase, run \`ftp_analyze_workspace "."\` to identify framework patterns.
+4. **Safety**: Server uses automatic SHA-256 drift protection in snapshots. Use \`ftp_rollback\` if a refactor goes wrong.
+
+[END OF SYSTEM INSTRUCTION]`;
+
+    return {
+      contents: [
+        {
+          uri: request.params.uri,
+          mimeType: "text/markdown",
+          text: content
+        }
+      ]
+    };
+  }
+  throw new Error(`Resource not found: ${request.params.uri}`);
+});
+
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   if (request.params.name === "ftp_list_deployments") {
     try {
@@ -1397,10 +1525,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         warning = "\n⚠️ SECURITY WARNING: You are connecting to a production profile using insecure FTP. SFTP is strongly recommended.";
       }
 
+      let hint = "";
+      if (!sessionHintShown) {
+        hint = `\n\n${getAISuggestion('hint_connected')}`;
+        sessionHintShown = true;
+      }
+
       return {
         content: [{
           type: "text",
-          text: `Connected to profile: ${profile || currentProfile || 'environment variables'}\nHost: ${currentConfig.host}${warning}`
+          text: `Connected to profile: ${profile || currentProfile || 'environment variables'}\nHost: ${currentConfig.host}${warning}${hint}`
         }]
       };
     } catch (error) {
@@ -1479,14 +1613,26 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           const sliced = files.slice(offset, offset + limit);
 
           const formatted = sliced.map(f => {
-            const type = (useSFTP ? f.type === 'd' : f.isDirectory) ? 'DIR ' : 'FILE';
+            const isDir = (useSFTP ? f.type === 'd' : f.isDirectory);
+            const icon = isDir ? ICON.DIR : ICON.FILE;
+            const label = isDir ? '[DIR] ' : '[FILE]';
+            
+            let marker = "";
+            const nameLower = f.name.toLowerCase();
+            if (['package.json', 'composer.json', 'requirements.txt', 'pyproject.toml', 'go.mod'].includes(nameLower)) marker = ` ${ICON.PKG}`;
+            else if (nameLower.includes('config') || nameLower.endsWith('.conf') || nameLower.endsWith('.yaml') || nameLower.endsWith('.yml')) marker = ` ${ICON.CONFIG}`;
+            else if (isSecretFile(f.name)) marker = ` ${ICON.SECRET}`;
+            else if (nameLower.endsWith('.bak') || nameLower.endsWith('.tmp') || nameLower.startsWith('~')) marker = ` ${ICON.BACKUP}`;
+
             const rights = useSFTP && f.rights ? `, ${f.rights.user || ''}${f.rights.group || ''}${f.rights.other || ''}` : '';
-            return `${type} ${f.name} (${f.size} bytes${rights})`;
+            return `${icon}${marker} ${label} ${f.name} (${f.size} bytes${rights})`;
           }).join('\n');
 
           const paginationInfo = `\n\nShowing ${offset + 1} to ${Math.min(offset + limit, total)} of ${total} items.`;
+          const hint = total > 0 && sliced.some(f => f.name === 'package.json') ? `\n\n${getAISuggestion('hint_list_config')}` : "";
+
           return {
-            content: [{ type: "text", text: (formatted || "Empty directory") + (total > limit ? paginationInfo : '') }]
+            content: [{ type: "text", text: (formatted || "Empty directory") + (total > limit ? paginationInfo : '') + hint }]
           };
         }
 
@@ -1804,8 +1950,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           }
 
           const paginationInfo = `\n\nShowing ${offset + 1} to ${Math.min(offset + limit, total)} of ${total} matches.`;
+          const hint = total === 0 ? `\n\n[AI: No matches found. Suggested fix: Try a broader wildcard pattern like \`*\` or verify your current \`path\` is correct.]` : "";
           return {
-            content: [{ type: "text", text: (formatted || "No matches found") + (total > limit ? paginationInfo : '') }]
+            content: [{ type: "text", text: (formatted || "No matches found") + (total > limit ? paginationInfo : '') + hint }]
           };
         }
 
@@ -2361,8 +2508,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     return response;
   } catch (error) {
     console.error(`[Fatal Tool Error] ${request.params.name}:`, error);
+    let suggestion = "";
+    const nameLower = error.message.toLowerCase();
+    if (nameLower.includes('enoent') || nameLower.includes('not found')) {
+      suggestion = `\n\n${getAISuggestion('error_enoent', { path: request.params.arguments?.path || request.params.arguments?.remotePath || 'target' })}`;
+    } else if (nameLower.includes('permission') || nameLower.includes('eacces')) {
+      suggestion = `\n\n${getAISuggestion('error_permission', { path: request.params.arguments?.path || request.params.arguments?.remotePath || 'target' })}`;
+    }
+
     return {
-      content: [{ type: "text", text: `Error: ${error.message}` }],
+      content: [{ type: "text", text: `Error: ${error.message}${suggestion}` }],
       isError: true
     };
   } finally {

package/package.json

@@ -1,122 +1,122 @@
-{
-  "name": "ftp-mcp",
-  "version": "1.3.0",
-  "description": "Enterprise-grade MCP server providing heavily optimized FTP/SFTP operations with smart sync, patch/chunk streaming, caching, and explicit read-only security mappings for AI code assistants.",
-  "type": "module",
-  "main": "index.js",
-  "bin": {
-    "ftp-mcp": "./index.js",
-    "ftp-mcp-server": "./index.js"
-  },
-  "files": [
-    "index.js",
-    "policy-engine.js",
-    "snapshot-manager.js",
-    "sync-manifest.js",
-    "README.md",
-    "LICENSE",
-    ".ftpconfig.example"
-  ],
-  "scripts": {
-    "start": "node index.js",
-    "test": "vitest run"
-  },
-  "keywords": [
-    "mcp",
-    "mcp-protocol",
-    "model-context-protocol",
-    "ftp",
-    "ftp-client",
-    "sftp",
-    "sftp-client",
-    "ssh",
-    "ssh2",
-    "scp",
-    "ssh-agent",
-    "rsync",
-    "file-transfer",
-    "file-manager",
-    "sync",
-    "diff",
-    "patch",
-    "git",
-    "gitignore",
-    "deploy",
-    "deployment",
-    "devops",
-    "continuous-deployment",
-    "automation",
-    "ai",
-    "ai-tools",
-    "llm",
-    "assistant",
-    "agentic",
-    "code-assistant",
-    "tool-call",
-    "json-rpc",
-    "server",
-    "tools",
-    "claude",
-    "claude-mcp",
-    "claude-ftp",
-    "cline",
-    "cline-mcp",
-    "cline-ftp",
-    "cursor",
-    "cursor-mcp",
-    "cursor-ftp",
-    "windsurf",
-    "windsurf-mcp",
-    "roo",
-    "roo-code",
-    "roo-mcp",
-    "copilot",
-    "github-copilot",
-    "amp",
-    "amp-mcp",
-    "openai",
-    "anthropic",
-    "gemini",
-    "gemini-mcp",
-    "mcp-server",
-    "mcp-tools",
-    "server-tool",
-    "remote",
-    "remote-fs",
-    "vfs"
-  ],
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "author": {
-    "name": "Kynlo Akari",
-    "url": "https://github.com/Kynlos/"
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Kynlos/ftp-mcp.git"
-  },
-  "homepage": "https://github.com/Kynlos/ftp-mcp#readme",
-  "bugs": {
-    "url": "https://github.com/Kynlos/ftp-mcp/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@clack/prompts": "^1.2.0",
-    "@modelcontextprotocol/sdk": "^1.0.4",
-    "basic-ftp": "^5.0.5",
-    "diff": "^8.0.4",
-    "dotenv": "^17.4.0",
-    "ignore": "^7.0.5",
-    "minimatch": "^10.0.3",
-    "ssh2-sftp-client": "^11.0.0",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "ftp-srv": "^4.6.3",
-    "vitest": "^4.1.2"
-  }
-}
+{
+  "name": "ftp-mcp",
+  "version": "1.4.0",
+  "description": "Enterprise-grade MCP server providing heavily optimized FTP/SFTP operations with smart sync, patch/chunk streaming, caching, and explicit read-only security mappings for AI code assistants.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "ftp-mcp": "./index.js",
+    "ftp-mcp-server": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "policy-engine.js",
+    "snapshot-manager.js",
+    "sync-manifest.js",
+    "README.md",
+    "LICENSE",
+    ".ftpconfig.example"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-protocol",
+    "model-context-protocol",
+    "ftp",
+    "ftp-client",
+    "sftp",
+    "sftp-client",
+    "ssh",
+    "ssh2",
+    "scp",
+    "ssh-agent",
+    "rsync",
+    "file-transfer",
+    "file-manager",
+    "sync",
+    "diff",
+    "patch",
+    "git",
+    "gitignore",
+    "deploy",
+    "deployment",
+    "devops",
+    "continuous-deployment",
+    "automation",
+    "ai",
+    "ai-tools",
+    "llm",
+    "assistant",
+    "agentic",
+    "code-assistant",
+    "tool-call",
+    "json-rpc",
+    "server",
+    "tools",
+    "claude",
+    "claude-mcp",
+    "claude-ftp",
+    "cline",
+    "cline-mcp",
+    "cline-ftp",
+    "cursor",
+    "cursor-mcp",
+    "cursor-ftp",
+    "windsurf",
+    "windsurf-mcp",
+    "roo",
+    "roo-code",
+    "roo-mcp",
+    "copilot",
+    "github-copilot",
+    "amp",
+    "amp-mcp",
+    "openai",
+    "anthropic",
+    "gemini",
+    "gemini-mcp",
+    "mcp-server",
+    "mcp-tools",
+    "server-tool",
+    "remote",
+    "remote-fs",
+    "vfs"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": {
+    "name": "Kynlo Akari",
+    "url": "https://github.com/Kynlos/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Kynlos/ftp-mcp.git"
+  },
+  "homepage": "https://github.com/Kynlos/ftp-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/Kynlos/ftp-mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "basic-ftp": "^5.0.5",
+    "diff": "^8.0.4",
+    "dotenv": "^17.4.0",
+    "ignore": "^7.0.5",
+    "minimatch": "^10.0.3",
+    "ssh2-sftp-client": "^11.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "ftp-srv": "^4.6.3",
+    "vitest": "^4.1.2"
+  }
+}