From 38055d45a4bde341447ea685d01e7b868a6431dd Mon Sep 17 00:00:00 2001 From: eduardruzga Date: Tue, 20 May 2025 10:02:13 +0300 Subject: [PATCH 1/4] Improve logging around write/edit sizes --- src/tools/edit.ts | 11 +++++++++-- src/tools/filesystem.ts | 5 +++++ 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/src/tools/edit.ts b/src/tools/edit.ts index 98c28027..b7dc06f4 100644 --- a/src/tools/edit.ts +++ b/src/tools/edit.ts @@ -106,8 +106,15 @@ export async function performSearchReplace(filePath: string, block: SearchReplac // Get file extension for telemetry using path module const fileExtension = path.extname(filePath).toLowerCase(); - // Capture file extension in telemetry without capturing the file path - capture('server_edit_block', {fileExtension: fileExtension}); + // Capture file extension and string sizes in telemetry without capturing the file path + capture('server_edit_block', { + fileExtension: fileExtension, + oldStringLength: block.search.length, + oldStringLines: block.search.split('\n').length, + newStringLength: block.replace.length, + newStringLines: block.replace.split('\n').length, + expectedReplacements: expectedReplacements + }); // Read file as plain string const {content} = await readFile(filePath, false, 0, Number.MAX_SAFE_INTEGER); diff --git a/src/tools/filesystem.ts b/src/tools/filesystem.ts index 050958f3..866f66e9 100644 --- a/src/tools/filesystem.ts +++ b/src/tools/filesystem.ts @@ -375,11 +375,16 @@ export async function writeFile(filePath: string, content: string, mode: 'rewrit // Get file extension for telemetry const fileExtension = path.extname(validPath).toLowerCase(); + // Calculate content metrics + const contentBytes = Buffer.from(content).length; + const lineCount = content.split('\n').length; // Capture file extension and operation details in telemetry without capturing the file path capture('server_write_file', { fileExtension: fileExtension, mode: mode, + contentBytes: contentBytes, + lineCount: lineCount }); // Use different fs methods based on mode From 2eb2838768a128886262c101f289b5f3a700ddfb Mon Sep 17 00:00:00 2001 From: eduardruzga Date: Tue, 20 May 2025 10:06:54 +0300 Subject: [PATCH 2/4] Make prompts more readable --- src/server.ts | 247 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 190 insertions(+), 57 deletions(-) diff --git a/src/server.ts b/src/server.ts index d8142b47..acdab454 100644 --- a/src/server.ts +++ b/src/server.ts @@ -81,34 +81,85 @@ server.setRequestHandler(ListToolsRequestSchema, async () => { // Configuration tools { name: "get_config", - description: - `Get the complete server configuration as JSON. Config includes fields for: blockedCommands (array of blocked shell commands), defaultShell (shell to use for commands), allowedDirectories (paths the server can access), fileReadLineLimit (max lines for read_file, default 1000), fileWriteLineLimit (max lines per write_file call, default 50), telemetryEnabled (boolean for telemetry opt-in/out). ${CMD_PREFIX_DESCRIPTION}`, + description: ` + Get the complete server configuration as JSON. Config includes fields for: + - blockedCommands (array of blocked shell commands) + - defaultShell (shell to use for commands) + - allowedDirectories (paths the server can access) + - fileReadLineLimit (max lines for read_file, default 1000) + - fileWriteLineLimit (max lines per write_file call, default 50) + - telemetryEnabled (boolean for telemetry opt-in/out) + + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(GetConfigArgsSchema), }, { name: "set_config_value", - description: - `Set a specific configuration value by key. WARNING: Should be used in a separate chat from file operations and command execution to prevent security issues. Config keys include: blockedCommands (array), defaultShell (string), allowedDirectories (array of paths), fileReadLineLimit (number, max lines for read_file), fileWriteLineLimit (number, max lines per write_file call), telemetryEnabled (boolean). IMPORTANT: Setting allowedDirectories to an empty array ([]) allows full access to the entire file system, regardless of the operating system. ${CMD_PREFIX_DESCRIPTION}`, + description: ` + Set a specific configuration value by key. + + WARNING: Should be used in a separate chat from file operations and + command execution to prevent security issues. + + Config keys include: + - blockedCommands (array) + - defaultShell (string) + - allowedDirectories (array of paths) + - fileReadLineLimit (number, max lines for read_file) + - fileWriteLineLimit (number, max lines per write_file call) + - telemetryEnabled (boolean) + + IMPORTANT: Setting allowedDirectories to an empty array ([]) allows full access + to the entire file system, regardless of the operating system. + + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(SetConfigValueArgsSchema), }, // Filesystem tools { name: "read_file", - description: - `Read the contents of a file from the file system or a URL with optional offset and length parameters. Prefer this over 'execute_command' with cat/type for viewing files. Supports partial file reading with 'offset' (start line, default: 0) and 'length' (max lines to read, default: configurable via 'fileReadLineLimit' setting, initially 1000). When reading from the file system, only works within allowed directories. Can fetch content from URLs when isUrl parameter is set to true (URLs are always read in full regardless of offset/length). Handles text files normally and image files are returned as viewable images. Recognized image types: PNG, JPEG, GIF, WebP. ${PATH_GUIDANCE} ${CMD_PREFIX_DESCRIPTION}`, + description: ` + Read the contents of a file from the file system or a URL with optional offset and length parameters. + + Prefer this over 'execute_command' with cat/type for viewing files. + + Supports partial file reading with: + - 'offset' (start line, default: 0) + - 'length' (max lines to read, default: configurable via 'fileReadLineLimit' setting, initially 1000) + + When reading from the file system, only works within allowed directories. + Can fetch content from URLs when isUrl parameter is set to true + (URLs are always read in full regardless of offset/length). + + Handles text files normally and image files are returned as viewable images. + Recognized image types: PNG, JPEG, GIF, WebP. + + ${PATH_GUIDANCE} + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(ReadFileArgsSchema), }, { name: "read_multiple_files", - description: - `Read the contents of multiple files simultaneously. Each file's content is returned with its path as a reference. Handles text files normally and renders images as viewable content. Recognized image types: PNG, JPEG, GIF, WebP. Failed reads for individual files won't stop the entire operation. Only works within allowed directories. ${PATH_GUIDANCE} ${CMD_PREFIX_DESCRIPTION}`, + description: ` + Read the contents of multiple files simultaneously. + + Each file's content is returned with its path as a reference. + Handles text files normally and renders images as viewable content. + Recognized image types: PNG, JPEG, GIF, WebP. + + Failed reads for individual files won't stop the entire operation. + Only works within allowed directories. + + ${PATH_GUIDANCE} + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(ReadMultipleFilesArgsSchema), }, { name: "write_file", - description: - `Write or append to file contents with a configurable line limit per call (default: 50 lines). THIS IS A STRICT REQUIREMENT. ANY file with more than the configured limit MUST BE written in chunks or IT WILL FAIL. + description: ` + Write or append to file contents with a configurable line limit per call (default: 50 lines). + THIS IS A STRICT REQUIREMENT. ANY file with more than the configured limit MUST BE written in chunks or IT WILL FAIL. NEVER attempt to write more than the configured line limit at once. @@ -121,57 +172,94 @@ server.setRequestHandler(ListToolsRequestSchema, async () => { If asked to continue writing do not restart from beginning, read end of file to see where you stopped and continue from there Files over the line limit (configurable via 'fileWriteLineLimit' setting) WILL BE REJECTED if not broken into chunks as described above. - Only works within allowed directories. ${PATH_GUIDANCE} ${CMD_PREFIX_DESCRIPTION}`, + Only works within allowed directories. + + ${PATH_GUIDANCE} + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(WriteFileArgsSchema), }, { name: "create_directory", - description: - `Create a new directory or ensure a directory exists. Can create multiple nested directories in one operation. Only works within allowed directories. ${PATH_GUIDANCE} ${CMD_PREFIX_DESCRIPTION}`, + description: ` + Create a new directory or ensure a directory exists. + + Can create multiple nested directories in one operation. + Only works within allowed directories. + + ${PATH_GUIDANCE} + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(CreateDirectoryArgsSchema), }, { name: "list_directory", - description: - `Get a detailed listing of all files and directories in a specified path. Use this instead of 'execute_command' with ls/dir commands. Results distinguish between files and directories with [FILE] and [DIR] prefixes. Only works within allowed directories. ${PATH_GUIDANCE} ${CMD_PREFIX_DESCRIPTION}`, + description: ` + Get a detailed listing of all files and directories in a specified path. + + Use this instead of 'execute_command' with ls/dir commands. + Results distinguish between files and directories with [FILE] and [DIR] prefixes. + Only works within allowed directories. + + ${PATH_GUIDANCE} + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(ListDirectoryArgsSchema), }, { name: "move_file", - description: - `Move or rename files and directories. - Can move files between directories and rename them in a single operation. - Both source and destination must be within allowed directories. ${PATH_GUIDANCE} ${CMD_PREFIX_DESCRIPTION}`, + description: ` + Move or rename files and directories. + + Can move files between directories and rename them in a single operation. + Both source and destination must be within allowed directories. + + ${PATH_GUIDANCE} + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(MoveFileArgsSchema), }, { name: "search_files", - description: - `Finds files by name using a case-insensitive substring matching. + description: ` + Finds files by name using a case-insensitive substring matching. + Use this instead of 'execute_command' with find/dir/ls for locating files. - Searches through all subdirectories from the starting path. - Has a default timeout of 30 seconds which can be customized using the timeoutMs parameter. - Only searches within allowed directories. ${PATH_GUIDANCE} ${CMD_PREFIX_DESCRIPTION}`, + Searches through all subdirectories from the starting path. + + Has a default timeout of 30 seconds which can be customized using the timeoutMs parameter. + Only searches within allowed directories. + + ${PATH_GUIDANCE} + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(SearchFilesArgsSchema), }, { name: "search_code", - description: - `Search for text/code patterns within file contents using ripgrep. + description: ` + Search for text/code patterns within file contents using ripgrep. + Use this instead of 'execute_command' with grep/find for searching code content. - Fast and powerful search similar to VS Code search functionality. - Supports regular expressions, file pattern filtering, and context lines. - Has a default timeout of 30 seconds which can be customized. - Only searches within allowed directories. - ${PATH_GUIDANCE} ${CMD_PREFIX_DESCRIPTION}`, + Fast and powerful search similar to VS Code search functionality. + + Supports regular expressions, file pattern filtering, and context lines. + Has a default timeout of 30 seconds which can be customized. + Only searches within allowed directories. + + ${PATH_GUIDANCE} + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(SearchCodeArgsSchema), }, { name: "get_file_info", - description: - `Retrieve detailed metadata about a file or directory including size, creation time, last modified time, - permissions, and type. - Only works within allowed directories. ${PATH_GUIDANCE} ${CMD_PREFIX_DESCRIPTION}`, + description: ` + Retrieve detailed metadata about a file or directory including: + - size + - creation time + - last modified time + - permissions + - type + + Only works within allowed directories. + + ${PATH_GUIDANCE} + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(GetFileInfoArgsSchema), }, // Note: list_allowed_directories removed - use get_config to check allowedDirectories @@ -179,54 +267,99 @@ server.setRequestHandler(ListToolsRequestSchema, async () => { // Text editing tools { name: "edit_block", - description: - `Apply surgical text replacements to files. - BEST PRACTICE: Make multiple small, focused edits rather than one large edit. - Each edit_block call should change only what needs to be changed - include just enough context to uniquely identify the text being modified. - Takes file_path, old_string (text to replace), new_string (replacement text), and optional expected_replacements parameter. - By default, replaces only ONE occurrence of the search text. - To replace multiple occurrences, provide the expected_replacements parameter with the exact number of matches expected. - UNIQUENESS REQUIREMENT: When expected_replacements=1 (default), include the minimal amount of context necessary (typically 1-3 lines) before and after the change point, with exact whitespace and indentation. - When editing multiple sections, make separate edit_block calls for each distinct change rather than one large replacement. - When a close but non-exact match is found, a character-level diff is shown in the format: common_prefix{-removed-}{+added+}common_suffix to help you identify what's different. - Similar to write_file, there is a configurable line limit (fileWriteLineLimit) that warns if the edited file exceeds this limit. If this happens, consider breaking your edits into smaller, more focused changes. - ${PATH_GUIDANCE} ${CMD_PREFIX_DESCRIPTION}`, + description: ` + Apply surgical text replacements to files. + + BEST PRACTICE: Make multiple small, focused edits rather than one large edit. + Each edit_block call should change only what needs to be changed - include just enough + context to uniquely identify the text being modified. + + Takes: + - file_path: Path to the file to edit + - old_string: Text to replace + - new_string: Replacement text + - expected_replacements: Optional parameter for number of replacements + + By default, replaces only ONE occurrence of the search text. + To replace multiple occurrences, provide the expected_replacements parameter with + the exact number of matches expected. + + UNIQUENESS REQUIREMENT: When expected_replacements=1 (default), include the minimal + amount of context necessary (typically 1-3 lines) before and after the change point, + with exact whitespace and indentation. + + When editing multiple sections, make separate edit_block calls for each distinct change + rather than one large replacement. + + When a close but non-exact match is found, a character-level diff is shown in the format: + common_prefix{-removed-}{+added+}common_suffix to help you identify what's different. + + Similar to write_file, there is a configurable line limit (fileWriteLineLimit) that warns + if the edited file exceeds this limit. If this happens, consider breaking your edits into + smaller, more focused changes. + + ${PATH_GUIDANCE} + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(EditBlockArgsSchema), }, // Terminal tools { name: "execute_command", - description: - `Execute a terminal command with timeout. - Command will continue running in background if it doesn't complete within timeout. - NOTE: For file operations, prefer specialized tools like read_file, search_code, list_directory instead of cat, grep, or ls commands. - ${PATH_GUIDANCE} ${CMD_PREFIX_DESCRIPTION}`, + description: ` + Execute a terminal command with timeout. + + Command will continue running in background if it doesn't complete within timeout. + + NOTE: For file operations, prefer specialized tools like read_file, search_code, + list_directory instead of cat, grep, or ls commands. + + ${PATH_GUIDANCE} + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(ExecuteCommandArgsSchema), }, { name: "read_output", - description: `Read new output from a running terminal session. ${CMD_PREFIX_DESCRIPTION}`, + description: ` + Read new output from a running terminal session. + + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(ReadOutputArgsSchema), }, { name: "force_terminate", - description: `Force terminate a running terminal session. ${CMD_PREFIX_DESCRIPTION}`, + description: ` + Force terminate a running terminal session. + + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(ForceTerminateArgsSchema), }, { name: "list_sessions", - description: `List all active terminal sessions. ${CMD_PREFIX_DESCRIPTION}`, + description: ` + List all active terminal sessions. + + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(ListSessionsArgsSchema), }, { name: "list_processes", - description: `List all running processes. Returns process information including PID, command name, CPU usage, and memory usage. ${CMD_PREFIX_DESCRIPTION}`, + description: ` + List all running processes. + + Returns process information including PID, command name, CPU usage, and memory usage. + + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(ListProcessesArgsSchema), }, { name: "kill_process", - description: `Terminate a running process by PID. Use with caution as this will forcefully terminate the specified process. ${CMD_PREFIX_DESCRIPTION}`, + description: ` + Terminate a running process by PID. + + Use with caution as this will forcefully terminate the specified process. + + ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(KillProcessArgsSchema), }, ], From 919d922f786fd94f2d1b7738e4c116b7f944d574 Mon Sep 17 00:00:00 2001 From: eduardruzga Date: Tue, 20 May 2025 10:15:17 +0300 Subject: [PATCH 3/4] Improve file write prompt --- src/server.ts | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/src/server.ts b/src/server.ts index acdab454..0f4c5d53 100644 --- a/src/server.ts +++ b/src/server.ts @@ -161,16 +161,26 @@ server.setRequestHandler(ListToolsRequestSchema, async () => { Write or append to file contents with a configurable line limit per call (default: 50 lines). THIS IS A STRICT REQUIREMENT. ANY file with more than the configured limit MUST BE written in chunks or IT WILL FAIL. - NEVER attempt to write more than the configured line limit at once. - - REQUIRED PROCESS FOR LARGE FILES: + ⚠️ IMPORTANT: PREVENTATIVE CHUNKING REQUIRED in these scenarios: + 1. When content exceeds 2,000 words or 30 lines + 2. When writing MULTIPLE files one after another (each next file is more likely to be truncated) + 3. When the file is the LAST ONE in a series of operations in the same message + + ALWAYS split files writes in to multiple smaller writes PREEMPTIVELY without asking the user in these scenarios. + + REQUIRED PROCESS FOR LARGE NEW FILE WRITES OR REWRITES: 1. FIRST → write_file(filePath, firstChunk, {mode: 'rewrite'}) 2. THEN → write_file(filePath, secondChunk, {mode: 'append'}) 3. THEN → write_file(filePath, thirdChunk, {mode: 'append'}) ... and so on for each chunk - If asked to continue writing do not restart from beginning, read end of file to see where you stopped and continue from there - + HANDLING TRUNCATION ("Continue" prompts): + If user asked to "Continue" after unfinished file write: + 1. First, read the file to find out what content was successfully written + 2. Identify exactly where the content was truncated + 3. Continue writing ONLY the remaining content using {mode: 'append'} + 4. Split the remaining content into smaller chunks (15-20 lines per chunk) + Files over the line limit (configurable via 'fileWriteLineLimit' setting) WILL BE REJECTED if not broken into chunks as described above. Only works within allowed directories. From e711a977fd299a94818b94f806c6659ed0e763d8 Mon Sep 17 00:00:00 2001 From: eduardruzga Date: Thu, 22 May 2025 15:04:55 +0300 Subject: [PATCH 4/4] Improve prompts some more + return messages --- src/server.ts | 3 +++ src/tools/filesystem.ts | 58 ++++++++++++++++++++++++++++++++++++----- 2 files changed, 54 insertions(+), 7 deletions(-) diff --git a/src/server.ts b/src/server.ts index 172f4420..2c1fe5f5 100644 --- a/src/server.ts +++ b/src/server.ts @@ -265,6 +265,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => { - last modified time - permissions - type + - lineCount (for text files) + - lastLine (zero-indexed number of last line, for text files) + - appendPosition (line number for appending, for text files) Only works within allowed directories. diff --git a/src/tools/filesystem.ts b/src/tools/filesystem.ts index 866f66e9..ea9eb777 100644 --- a/src/tools/filesystem.ts +++ b/src/tools/filesystem.ts @@ -318,16 +318,36 @@ export async function readFileFromDisk(filePath: string, offset: number = 0, len const lines = fullContent.split('\n'); const totalLines = lines.length; - // Apply line-based offset and length - const startLine = Math.min(offset, totalLines); - const endLine = Math.min(startLine + length, totalLines); + // Apply line-based offset and length - handle beyond-file-size scenario + let startLine = Math.min(offset, totalLines); + let endLine = Math.min(startLine + length, totalLines); + + // If startLine equals totalLines (reading beyond end), adjust to show some content + // Only do this if we're not trying to read the whole file + if (startLine === totalLines && offset > 0 && length < Number.MAX_SAFE_INTEGER) { + // Show last few lines instead of nothing + const lastLinesCount = Math.min(10, totalLines); // Show last 10 lines or fewer if file is smaller + startLine = Math.max(0, totalLines - lastLinesCount); + endLine = totalLines; + } + const selectedLines = lines.slice(startLine, endLine); const truncatedContent = selectedLines.join('\n'); - // Add an informational message if truncated + // Add an informational message if truncated or adjusted let content = truncatedContent; - if (offset > 0 || endLine < totalLines) { - content = `[Reading ${endLine - startLine} lines from line ${offset} of ${totalLines} total lines]\n\n${truncatedContent}`; + + // Only add informational message for normal reads (not when reading entire file) + const isEntireFileRead = offset === 0 && length >= Number.MAX_SAFE_INTEGER; + + if (!isEntireFileRead) { + if (offset >= totalLines && totalLines > 0) { + // Reading beyond end of file case + content = `[NOTICE: Offset ${offset} exceeds file length (${totalLines} lines). Showing last ${endLine - startLine} lines instead.]\n\n${truncatedContent}`; + } else if (offset > 0 || endLine < totalLines) { + // Normal partial read case + content = `[Reading ${endLine - startLine} lines from line ${startLine} of ${totalLines} total lines]\n\n${truncatedContent}`; + } } return { content, mimeType, isImage }; @@ -509,7 +529,8 @@ export async function getFileInfo(filePath: string): Promise const validPath = await validatePath(filePath); const stats = await fs.stat(validPath); - return { + // Basic file info + const info: Record = { size: stats.size, created: stats.birthtime, modified: stats.mtime, @@ -518,6 +539,29 @@ export async function getFileInfo(filePath: string): Promise isFile: stats.isFile(), permissions: stats.mode.toString(8).slice(-3), }; + + // For text files that aren't too large, also count lines + if (stats.isFile() && stats.size < 10 * 1024 * 1024) { // Limit to 10MB files + try { + // Import the MIME type utilities + const { getMimeType, isImageFile } = await import('./mime-types.js'); + const mimeType = getMimeType(validPath); + + // Only count lines for non-image, likely text files + if (!isImageFile(mimeType)) { + const content = await fs.readFile(validPath, 'utf8'); + const lineCount = content.split('\n').length; + info.lineCount = lineCount; + info.lastLine = lineCount - 1; // Zero-indexed last line + info.appendPosition = lineCount; // Position to append at end + } + } catch (error) { + // If reading fails, just skip the line count + // This could happen for binary files or very large files + } + } + + return info; } // This function has been replaced with configManager.getConfig()