add_footnote_to_document

Instructions

Implementation Reference

• word_document_server/tools/footnote_tools.py:21-88 (handler)

  Core handler function that implements the logic for adding a footnote to a specified paragraph in a Word document. Includes input validation, document loading, attempted native footnote addition with fallback to manual superscript and footnote section creation, and error handling.

  async def add_footnote_to_document(filename: str, paragraph_index: int, footnote_text: str) -> str:
      """Add a footnote to a specific paragraph in a Word document.
      
      Args:
          filename: Path to the Word document
          paragraph_index: Index of the paragraph to add footnote to (0-based)
          footnote_text: Text content of the footnote
      """
      filename = ensure_docx_extension(filename)
      
      # Ensure paragraph_index is an integer
      try:
          paragraph_index = int(paragraph_index)
      except (ValueError, TypeError):
          return "Invalid parameter: paragraph_index must be an integer"
      
      if not os.path.exists(filename):
          return f"Document {filename} does not exist"
      
      # Check if file is writeable
      is_writeable, error_message = check_file_writeable(filename)
      if not is_writeable:
          return f"Cannot modify document: {error_message}. Consider creating a copy first."
      
      try:
          doc = Document(filename)
          
          # Validate paragraph index
          if paragraph_index < 0 or paragraph_index >= len(doc.paragraphs):
              return f"Invalid paragraph index. Document has {len(doc.paragraphs)} paragraphs (0-{len(doc.paragraphs)-1})."
          
          paragraph = doc.paragraphs[paragraph_index]
          
          # In python-docx, we'd use paragraph.add_footnote(), but we'll use a more robust approach
          try:
              footnote = paragraph.add_run()
              footnote.text = ""
              
              # Create the footnote reference
              reference = footnote.add_footnote(footnote_text)
              
              doc.save(filename)
              return f"Footnote added to paragraph {paragraph_index} in {filename}"
          except AttributeError:
              # Fall back to a simpler approach if direct footnote addition fails
              last_run = paragraph.add_run()
              last_run.text = "¹"  # Unicode superscript 1
              last_run.font.superscript = True
              
              # Add a footnote section at the end if it doesn't exist
              found_footnote_section = False
              for p in doc.paragraphs:
                  if p.text.startswith("Footnotes:"):
                      found_footnote_section = True
                      break
              
              if not found_footnote_section:
                  doc.add_paragraph("\n").add_run()
                  doc.add_paragraph("Footnotes:").bold = True
              
              # Add footnote text
              footnote_para = doc.add_paragraph("¹ " + footnote_text)
              footnote_para.style = "Footnote Text" if "Footnote Text" in doc.styles else "Normal"
              
              doc.save(filename)
              return f"Footnote added to paragraph {paragraph_index} in {filename} (simplified approach)"
      except Exception as e:
          return f"Failed to add footnote: {str(e)}"

• word_document_server/main.py:784-788 (registration)

  Tool registration using FastMCP's @mcp.tool() decorator. Defines the tool interface with type annotations and docstring (used for JSON schema generation), and delegates execution to the core implementation in footnote_tools.py.

  @mcp.tool()
  async def add_footnote_to_document(filename: str, paragraph_index: int, footnote_text: str):
      """Add a footnote to a specific paragraph in a Word document."""
      return await footnote_tools.add_footnote_to_document(filename, paragraph_index, footnote_text)

• word_document_server/main.py:785-787 (schema)

  The function signature and docstring in the registration provide the input schema (parameters: filename:str, paragraph_index:int, footnote_text:str) and description for the MCP tool.

  async def add_footnote_to_document(filename: str, paragraph_index: int, footnote_text: str):
      """Add a footnote to a specific paragraph in a Word document."""
      return await footnote_tools.add_footnote_to_document(filename, paragraph_index, footnote_text)