Terminal Controller for MCP

Instructions

Implementation Reference

• terminal_controller.py:639-790 (handler)

  The primary handler function for the 'update_file_content' tool. It handles updating file content either by replacing entire lines at specified row indices, replacing specific substrings within lines, or overwriting the entire file content. Includes input validation, JSON serialization for non-string content, file I/O operations, and comprehensive error handling. Registered via @mcp.tool() decorator for FastMCP integration.
  @mcp.tool() async def update_file_content(path: str, content: str, row: int = None, rows: list = None, substring: str = None) -> str: """ Update content at specific row(s) in a file Args: path: Path to the file content: New content to place at the specified row(s) row: Row number to update (0-based, optional) rows: List of row numbers to update (0-based, optional) substring: If provided, only replace this substring within the specified row(s), not the entire row Returns: Operation result information """ try: # Handle different content types if not isinstance(content, str): try: import json content = json.dumps(content, indent=4, sort_keys=False, ensure_ascii=False, default=str) except Exception as e: return f"Error: Unable to convert content to JSON string: {str(e)}" if not os.path.exists(path): return f"Error: File '{path}' does not exist." if not os.path.isfile(path): return f"Error: '{path}' is not a file." with open(path, 'r', encoding='utf-8', errors='replace') as file: lines = file.readlines() total_lines = len(lines) updated_rows = [] # Ensure content ends with a newline if replacing a full line and doesn't already have one if substring is None and content and not content.endswith('\n'): content += '\n' # Prepare lines for update content_lines = content.splitlines(True) if substring is None else [content] # Handle updating multiple rows if rows is not None: if not isinstance(rows, list): return "Error: 'rows' parameter must be a list of integers." for r in rows: if not isinstance(r, int) or r < 0: return "Error: Row numbers must be non-negative integers." if r < total_lines: # If substring is provided, only replace that part if substring is not None: # Only update if substring exists in the line if substring in lines[r]: original_line = lines[r] lines[r] = lines[r].replace(substring, content) # Ensure line ends with newline if original did if original_line.endswith('\n') and not lines[r].endswith('\n'): lines[r] += '\n' updated_rows.append(r) else: # Otherwise, replace the entire line # If we have multiple content lines, use them in sequence if len(content_lines) > 1: content_index = r % len(content_lines) lines[r] = content_lines[content_index] else: # If we have only one content line, use it for all rows lines[r] = content_lines[0] if content_lines else "\n" updated_rows.append(r) # Write back to the file with open(path, 'w', encoding='utf-8') as file: file.writelines(lines) if not updated_rows: if substring is not None: return f"No occurrences of substring '{substring}' found in the specified rows (file has {total_lines} lines)." else: return f"No rows were within range to update (file has {total_lines} lines)." if substring is not None: return f"Successfully updated substring in {len(updated_rows)} rows ({updated_rows}) in '{path}'." else: return f"Successfully updated {len(updated_rows)} rows ({updated_rows}) in '{path}'." # Handle updating a single row elif row is not None: if not isinstance(row, int) or row < 0: return "Error: Row number must be a non-negative integer." if row >= total_lines: return f"Error: Row {row} is out of range (file has {total_lines} lines)." # If substring is provided, only replace that part if substring is not None: # Only update if substring exists in the line if substring in lines[row]: original_line = lines[row] lines[row] = lines[row].replace(substring, content) # Ensure line ends with newline if original did if original_line.endswith('\n') and not lines[row].endswith('\n'): lines[row] += '\n' else: return f"Substring '{substring}' not found in row {row}." else: # Otherwise, replace the entire line lines[row] = content_lines[0] if content_lines else "\n" # Write back to the file with open(path, 'w', encoding='utf-8') as file: file.writelines(lines) if substring is not None: return f"Successfully updated substring in row {row} in '{path}'." else: return f"Successfully updated row {row} in '{path}'." # If neither row nor rows specified, update the entire file else: if substring is not None: # Replace substring throughout the file updated_count = 0 for i in range(len(lines)): if substring in lines[i]: original_line = lines[i] lines[i] = lines[i].replace(substring, content) # Ensure line ends with newline if original did if original_line.endswith('\n') and not lines[i].endswith('\n'): lines[i] += '\n' updated_count += 1 with open(path, 'w', encoding='utf-8') as file: file.writelines(lines) if updated_count == 0: return f"Substring '{substring}' not found in any line of '{path}'." return f"Successfully updated substring in {updated_count} lines in '{path}'." else: # Replace entire file content with open(path, 'w', encoding='utf-8') as file: file.write(content) return f"Successfully updated all content in '{path}'." except PermissionError: return f"Error: No permission to modify file '{path}'." except Exception as e: return f"Error updating content: {str(e)}"
• terminal_controller.py:640-653 (schema)

  Function signature and docstring defining the input parameters (path, content, optional row/rows/substring) and return type (str describing operation result). Serves as the schema for tool invocation in MCP.
  async def update_file_content(path: str, content: str, row: int = None, rows: list = None, substring: str = None) -> str: """ Update content at specific row(s) in a file Args: path: Path to the file content: New content to place at the specified row(s) row: Row number to update (0-based, optional) rows: List of row numbers to update (0-based, optional) substring: If provided, only replace this substring within the specified row(s), not the entire row Returns: Operation result information """
• terminal_controller.py:11-11 (registration)

  Initialization of the FastMCP server instance. All @mcp.tool() decorated functions, including update_file_content, are automatically registered as tools on this server instance.
  mcp = FastMCP("terminal-controller", log_level="INFO")