add_picture

Instructions

Implementation Reference

• word_document_server/tools/content_tools.py:162-219 (handler)

  The core handler function that implements the logic to add a picture to a Word document: validates inputs, checks file permissions, loads document, inserts image with optional width scaling, saves changes, and provides detailed error handling.

  async def add_picture(filename: str, image_path: str, width: Optional[float] = None) -> str:
      """Add an image to a Word document.
      
      Args:
          filename: Path to the Word document
          image_path: Path to the image file
          width: Optional width in inches (proportional scaling)
      """
      filename = ensure_docx_extension(filename)
      
      # Validate document existence
      if not os.path.exists(filename):
          return f"Document {filename} does not exist"
      
      # Get absolute paths for better diagnostics
      abs_filename = os.path.abspath(filename)
      abs_image_path = os.path.abspath(image_path)
      
      # Validate image existence with improved error message
      if not os.path.exists(abs_image_path):
          return f"Image file not found: {abs_image_path}"
      
      # Check image file size
      try:
          image_size = os.path.getsize(abs_image_path) / 1024  # Size in KB
          if image_size <= 0:
              return f"Image file appears to be empty: {abs_image_path} (0 KB)"
      except Exception as size_error:
          return f"Error checking image file: {str(size_error)}"
      
      # Check if file is writeable
      is_writeable, error_message = check_file_writeable(abs_filename)
      if not is_writeable:
          return f"Cannot modify document: {error_message}. Consider creating a copy first or creating a new document."
      
      try:
          doc = Document(abs_filename)
          # Additional diagnostic info
          diagnostic = f"Attempting to add image ({abs_image_path}, {image_size:.2f} KB) to document ({abs_filename})"
          
          try:
              if width:
                  doc.add_picture(abs_image_path, width=Inches(width))
              else:
                  doc.add_picture(abs_image_path)
              doc.save(abs_filename)
              return f"Picture {image_path} added to {filename}"
          except Exception as inner_error:
              # More detailed error for the specific operation
              error_type = type(inner_error).__name__
              error_msg = str(inner_error)
              return f"Failed to add picture: {error_type} - {error_msg or 'No error details available'}\nDiagnostic info: {diagnostic}"
      except Exception as outer_error:
          # Fallback error handling
          error_type = type(outer_error).__name__
          error_msg = str(outer_error)
          return f"Document processing error: {error_type} - {error_msg or 'No error details available'}"

• word_document_server/main.py:712-715 (registration)

  MCP tool registration using FastMCP @mcp.tool() decorator. Defines the tool interface with parameters and docstring (serving as schema), and delegates execution to the implementation in content_tools.add_picture.

  @mcp.tool()
  async def add_picture(filename: str, image_path: str, width: Optional[float] = None):
      """Add an image to a Word document."""
      return await content_tools.add_picture(filename, image_path, width)

• word_document_server/tools/__init__.py:16-20 (helper)

  Imports the add_picture function from content_tools.py, making it available for use in the main server registration.

  from word_document_server.tools.content_tools import (
      add_heading, add_paragraph, add_table, add_picture,
      add_page_break, add_table_of_contents, delete_paragraph,
      search_and_replace
  )