Terminal Controller for MCP

Instructions

Write content to a file

Args:
    path: Path to the file
    content: Content to write (string or JSON object)
    mode: Write mode ('overwrite' or 'append')

Returns:
    Operation result information

Implementation Reference

• terminal_controller.py:255-321 (handler)

  The handler function for the 'write_file' tool. It serializes non-string content to JSON, determines file open mode based on 'overwrite' or 'append', ensures directories exist, writes the content with UTF-8 encoding, verifies the file was created, and returns a status message with file size or error details.

  async def write_file(path: str, content: str, mode: str = "overwrite") -> str:
      """
      Write content to a file
      
      Args:
          path: Path to the file
          content: Content to write (string or JSON object)
          mode: Write mode ('overwrite' or 'append')
      
      Returns:
          Operation result information
      """
      try:
          # Handle different content types
          if not isinstance(content, str):
              try:
                  import json
                  # Advanced JSON serialization with better handling of complex objects
                  content = json.dumps(content, 
                                      indent=4, 
                                      sort_keys=False, 
                                      ensure_ascii=False, 
                                      default=lambda obj: str(obj) if hasattr(obj, '__dict__') else repr(obj))
              except Exception as e:
                  # Try a more aggressive approach if standard serialization fails
                  try:
                      # Convert object to dictionary first if it has __dict__
                      if hasattr(content, '__dict__'):
                          import json
                          content = json.dumps(content.__dict__, 
                                             indent=4, 
                                             sort_keys=False, 
                                             ensure_ascii=False)
                      else:
                          # Last resort: convert to string representation
                          content = str(content)
                  except Exception as inner_e:
                      return f"Error: Unable to convert complex object to writable string: {str(e)}, then tried alternative method and got: {str(inner_e)}"
          
          # Choose file mode based on the specified writing mode
          file_mode = "w" if mode.lower() == "overwrite" else "a"
          
          # Ensure content ends with a newline if it doesn't already
          if content and not content.endswith('\n'):
              content += '\n'
          
          # Ensure directory exists
          directory = os.path.dirname(os.path.abspath(path))
          if directory and not os.path.exists(directory):
              os.makedirs(directory, exist_ok=True)
              
          with open(path, file_mode, encoding="utf-8") as file:
              file.write(content)
          
          # Verify the write operation was successful
          if os.path.exists(path):
              file_size = os.path.getsize(path)
              return f"Successfully wrote {file_size} bytes to '{path}' in {mode} mode."
          else:
              return f"Write operation completed, but unable to verify file exists at '{path}'."
      
      except FileNotFoundError:
          return f"Error: The directory in path '{path}' does not exist and could not be created."
      except PermissionError:
          return f"Error: No permission to write to file '{path}'."
      except Exception as e:
          return f"Error writing to file: {str(e)}"

• terminal_controller.py:254-254 (registration)

  The @mcp.tool() decorator registers the write_file function as an available MCP tool, automatically generating schema from type hints and docstring.

  @mcp.tool()

• terminal_controller.py:255-266 (schema)

  Input schema defined by function parameters (path: str required, content: str required, mode: str optional default 'overwrite') and docstring. Output is str describing the operation result.

  async def write_file(path: str, content: str, mode: str = "overwrite") -> str:
      """
      Write content to a file
      
      Args:
          path: Path to the file
          content: Content to write (string or JSON object)
          mode: Write mode ('overwrite' or 'append')
      
      Returns:
          Operation result information
      """