docx-mcp

Instructions

Implementation Reference

• src/docx_mcp/server.py:393-432 (handler)

  The handler function 'fill_merge_fields' iterates through document paragraphs and runs, replacing placeholders of the form {{field_name}} with values provided in the data dictionary.

  def fill_merge_fields(filepath: str, data: dict[str, str]) -> dict[str, Any]:
      """
      Fill merge fields in a document with provided data.
  
      Args:
          filepath: Path to the document or template
          data: Dictionary mapping field names to values
  
      Returns:
          Dictionary with status and modified document info
      """
      logger.info("Filling merge fields", extra={"tool": "fill_merge_fields", "filepath": filepath})
  
      try:
          doc = safe_open_document(filepath)
          fields_filled = 0
  
          # Simple merge field filling by replacing in text
          for paragraph in doc.paragraphs:
              for run in paragraph.runs:
                  for field_name, field_value in data.items():
                      if f"{{{{{field_name}}}}}" in run.text:
                          run.text = run.text.replace(f"{{{{{field_name}}}}}", str(field_value))
                          fields_filled += 1
  
          safe_save_document(doc, filepath)
          logger.info(f"Filled {fields_filled} merge fields", extra={"filepath": filepath})
  
          return {
              "status": "success",
              "filepath": filepath,
              "fields_filled": fields_filled,
              "message": f"Filled {fields_filled} merge fields",
          }
      except DocxMcpError as e:
          logger.warning(e.message, extra={"tool": "fill_merge_fields", "error_code": e.error_code})
          return {"status": "error", "error": e.message, "error_code": e.error_code}
      except Exception as e:
          logger.error(f"Unexpected error filling merge fields: {str(e)}")
          return {"status": "error", "error": str(e)}

• src/docx_mcp/server.py:392-433 (registration)

  The tool is registered using the @app.tool() decorator immediately preceding the function definition (implied by the structure).

  @app.tool()
  def fill_merge_fields(filepath: str, data: dict[str, str]) -> dict[str, Any]:
      """
      Fill merge fields in a document with provided data.
  
      Args:
          filepath: Path to the document or template
          data: Dictionary mapping field names to values
  
      Returns:
          Dictionary with status and modified document info
      """
      logger.info("Filling merge fields", extra={"tool": "fill_merge_fields", "filepath": filepath})
  
      try:
          doc = safe_open_document(filepath)
          fields_filled = 0
  
          # Simple merge field filling by replacing in text
          for paragraph in doc.paragraphs:
              for run in paragraph.runs:
                  for field_name, field_value in data.items():
                      if f"{{{{{field_name}}}}}" in run.text:
                          run.text = run.text.replace(f"{{{{{field_name}}}}}", str(field_value))
                          fields_filled += 1
  
          safe_save_document(doc, filepath)
          logger.info(f"Filled {fields_filled} merge fields", extra={"filepath": filepath})
  
          return {
              "status": "success",
              "filepath": filepath,
              "fields_filled": fields_filled,
              "message": f"Filled {fields_filled} merge fields",
          }
      except DocxMcpError as e:
          logger.warning(e.message, extra={"tool": "fill_merge_fields", "error_code": e.error_code})
          return {"status": "error", "error": e.message, "error_code": e.error_code}
      except Exception as e:
          logger.error(f"Unexpected error filling merge fields: {str(e)}")
          return {"status": "error", "error": str(e)}