PDF Redaction MCP Server

Instructions

Implementation Reference

• src/redact_mcp/server.py:83-204 (handler)

  The primary handler function for the 'redact_text' MCP tool, decorated with @mcp.tool for registration. It performs text search and redaction annotation addition on loaded PDF documents using PyMuPDF (fitz). Includes input schema via Annotated types, tracks previous redactions to avoid duplicates, and returns a detailed summary.
  @mcp.tool async def redact_text( pdf_path: Annotated[str, Field(description="Path to the loaded PDF file")], texts_to_redact: Annotated[list[str], Field(description="List of text strings to search for and redact")], 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 specific texts in a loaded PDF. This tool searches for all instances of the specified texts in the PDF and adds redaction annotations over them. The redactions are not yet applied to the document - use save_redacted_pdf to apply and save. Only texts that haven't been previously redacted will be processed. Args: pdf_path: Path to the PDF file (must be already loaded) texts_to_redact: List of text strings to search for and redact fill_color: RGB color tuple (0-1 range) for the redaction box. Default is black. ctx: MCP context for logging Returns: Summary of redaction operations Raises: ToolError: If the PDF is not loaded or redaction fails """ try: path = Path(pdf_path).resolve() path_str = str(path) await ctx.info(f"Redacting texts 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] # Initialize redaction tracking for this PDF if not exists if path_str not in _applied_redactions: _applied_redactions[path_str] = [] # 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") # Filter out already redacted texts already_redacted = [] new_texts = [] for text in texts_to_redact: if text in _applied_redactions[path_str]: already_redacted.append(text) else: new_texts.append(text) if not new_texts: skipped_msg = f"All {len(texts_to_redact)} text(s) have already been redacted. No new redactions added." await ctx.info(skipped_msg) return skipped_msg total_redactions = 0 text_summaries = [] # Process each text to redact for text_to_redact in new_texts: text_redaction_count = 0 page_redactions = [] # Search and redact on each page for page_num, page in enumerate(doc, start=1): # Search for the text text_instances = page.search_for(text_to_redact) if text_instances: # Add redaction annotations for each instance for inst in text_instances: page.add_redact_annot(inst, fill=fill_color) text_redaction_count += 1 total_redactions += 1 page_redactions.append(f"Page {page_num}: {len(text_instances)} instance(s)") if text_redaction_count > 0: # Track this redaction _applied_redactions[path_str].append(text_to_redact) text_summaries.append( f" '{text_to_redact}': {text_redaction_count} instance(s) across {len(page_redactions)} page(s)" ) else: text_summaries.append(f" '{text_to_redact}': No instances found") if total_redactions == 0: msg = f"No instances of the provided texts found in the PDF" await ctx.warning(msg) return msg summary_parts = [f"Added {total_redactions} redaction(s) for {len(new_texts)} text(s):"] summary_parts.extend(text_summaries) if already_redacted: summary_parts.append(f"\nSkipped {len(already_redacted)} text(s) already redacted: {', '.join(repr(t) for t in already_redacted)}") summary_parts.append( "\nNote: Redactions are marked but not yet applied. " "Use save_redacted_pdf to apply and save the changes." ) summary = "\n".join(summary_parts) await ctx.info(f"Added {total_redactions} redaction annotations for {len(new_texts)} new text(s)") return summary except ToolError: raise except Exception as e: await ctx.error(f"Failed to redact text: {str(e)}") raise ToolError(f"Failed to redact text: {str(e)}")
• src/redact_mcp/server.py:85-90 (schema)

  Input schema definition for the redact_text tool using Pydantic's Annotated and Field for parameter descriptions, types, and defaults.
  pdf_path: Annotated[str, Field(description="Path to the loaded PDF file")], texts_to_redact: Annotated[list[str], Field(description="List of text strings to search for and redact")], 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
• src/redact_mcp/server.py:83-83 (registration)

  FastMCP decorator that registers the redact_text function as an MCP tool.
  @mcp.tool