redact_area

Instructions

Implementation Reference

• src/redact_mcp/server.py:207-285 (handler)

  The core handler function for the 'redact_area' MCP tool. It adds a redaction annotation to a specified rectangular area on a given page of a loaded PDF using PyMuPDF's fitz library. The @mcp.tool decorator handles both registration and schema definition via Annotated type hints and Field descriptions.

  @mcp.tool
  async def redact_area(
      pdf_path: Annotated[str, Field(description="Path to the loaded PDF file")],
      page_number: Annotated[int, Field(description="Page number (1-indexed)", ge=1)],
      x0: Annotated[float, Field(description="Left x coordinate")],
      y0: Annotated[float, Field(description="Top y coordinate")],
      x1: Annotated[float, Field(description="Right x coordinate")],
      y1: Annotated[float, Field(description="Bottom y coordinate")],
      fill_color: Annotated[tuple[float, float, float], Field(
          description="RGB color for redaction (values 0-1). Default is black (0,0,0)"
      )] = (0, 0, 0),
      ctx: Context = None
  ) -> str:
      """Redact a specific rectangular area on a PDF page.
      
      This tool adds a redaction annotation for a specific rectangular area
      defined by coordinates. The redactions are not yet applied to the document -
      use save_redacted_pdf to apply and save.
      
      Args:
          pdf_path: Path to the PDF file (must be already loaded)
          page_number: Page number to redact (1-indexed)
          x0: Left x coordinate of the rectangle
          y0: Top y coordinate of the rectangle
          x1: Right x coordinate of the rectangle
          y1: Bottom y coordinate of the rectangle
          fill_color: RGB color tuple (0-1 range) for the redaction box. Default is black.
          ctx: MCP context for logging
          
      Returns:
          Confirmation message
          
      Raises:
          ToolError: If the PDF is not loaded, page doesn't exist, or redaction fails
      """
      try:
          path = Path(pdf_path).resolve()
          path_str = str(path)
          
          await ctx.info(f"Redacting area on page {page_number} in: {path}")
          
          # Check if PDF is loaded
          if path_str not in _loaded_pdfs:
              raise ToolError(
                  f"PDF not loaded. Please load it first using load_pdf: {path}"
              )
          
          doc = _loaded_pdfs[path_str]
          
          # Validate page number
          if page_number < 1 or page_number > len(doc):
              raise ToolError(
                  f"Invalid page number {page_number}. PDF has {len(doc)} pages."
              )
          
          # Validate color values
          if not all(0 <= c <= 1 for c in fill_color):
              raise ToolError("RGB color values must be between 0 and 1")
          
          # Get the page (0-indexed internally)
          page = doc[page_number - 1]
          
          # Create rectangle and add redaction
          rect = fitz.Rect(x0, y0, x1, y1)
          page.add_redact_annot(rect, fill=fill_color)
          
          await ctx.info(f"Added area redaction on page {page_number}")
          
          return (
              f"Added redaction for area ({x0}, {y0}, {x1}, {y1}) on page {page_number}.\n"
              + "Note: Redaction is marked but not yet applied. "
              + "Use save_redacted_pdf to apply and save the changes."
          )
          
      except ToolError:
          raise
      except Exception as e:
          await ctx.error(f"Failed to redact area: {str(e)}")
          raise ToolError(f"Failed to redact area: {str(e)}")

• src/redact_mcp/server.py:209-217 (schema)

  Input schema defined using Pydantic's Annotated and Field for the redact_area tool parameters, including descriptions, constraints (e.g., ge=1 for page_number), and default value for fill_color.

  pdf_path: Annotated[str, Field(description="Path to the loaded PDF file")],
  page_number: Annotated[int, Field(description="Page number (1-indexed)", ge=1)],
  x0: Annotated[float, Field(description="Left x coordinate")],
  y0: Annotated[float, Field(description="Top y coordinate")],
  x1: Annotated[float, Field(description="Right x coordinate")],
  y1: Annotated[float, Field(description="Bottom y coordinate")],
  fill_color: Annotated[tuple[float, float, float], Field(
      description="RGB color for redaction (values 0-1). Default is black (0,0,0)"
  )] = (0, 0, 0),

• src/redact_mcp/server.py:207-207 (registration)

  The @mcp.tool decorator from FastMCP registers the redact_area function as an MCP tool, automatically using the function name, docstring, and type hints for tool metadata.

  @mcp.tool