### Get Document Overview (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Illustrates how to retrieve a general overview of a PDF document using the PDFActionInspector. This includes basic information such as the number of pages and whether the document is encrypted. It's a quick way to get essential metadata. ```python overview = inspector.get_document_overview("document.pdf") print(f"Pages: {overview['basic_info']['pages']}") print(f"Encrypted: {overview['basic_info']['encrypted']}") ``` -------------------------------- ### MCP Client Usage for Encrypted PDFs (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Provides an example of using the MCP client to interact with PDF analysis tools, specifically for encrypted PDFs. It shows how to set the PDF password and then extract actions, demonstrating asynchronous tool calls and JSON response parsing. ```python await call_tool("mcp_pdf_action_in_set_pdf_password", { "file_path": "encrypted.pdf", "password": "your_password" }) result = await call_tool("mcp_pdf_action_in_extract_pdf_actions", { "file_path": "encrypted.pdf" }) import json data = json.loads(result.content[0].text) print(f"Total actions found: {data['total_actions']}") ``` -------------------------------- ### Environment Variable Configuration (Bash) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Shows how to set environment variables for configuring the PDF Action Inspector. Examples include setting the cache timeout duration, the logging level, and optionally specifying a custom cache directory. ```bash # Cache timeout (seconds) export PDF_CACHE_TIMEOUT_SECONDS=120 # Logging level export LOG_LEVEL=INFO # Cache directory (optional) export PDF_CACHE_DIR="/tmp/pdf_cache" ``` -------------------------------- ### Get Document Overview (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Retrieves a comprehensive overview of a PDF document, including basic information, structural features, and counts of various elements like forms, annotations, and JavaScript objects. Requires a file path. ```python from src.core.inspector import PDFActionInspector inspector = PDFActionInspector() overview = inspector.get_document_overview("document.pdf") print(f"Document has {overview['basic_info']['pages']} pages and is encrypted: {overview['basic_info']['encrypted']}") ``` -------------------------------- ### GET /inspector/get_document_overview Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Extracts high-level metadata and document information from a PDF file. ```APIDOC ## GET inspector.get_document_overview() ### Description Returns an overview of the PDF document, including basic metadata and page counts. ### Method Python Method ### Parameters #### Arguments - **file_path** (string) - Required - The path to the target PDF file. ### Request Example inspector.get_document_overview("test.pdf") ### Response #### Success Response - **basic_info** (dict) - Contains document metadata such as page count. #### Response Example { "basic_info": { "pages": 5, "author": "John Doe" } } ``` -------------------------------- ### GET /inspector/get_fields_by_name Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Retrieves specific PDF fields by name from a provided file path. ```APIDOC ## GET inspector.get_fields_by_name() ### Description Retrieves specific PDF fields by name. Returns a Python dictionary containing the field data. ### Method Python Method ### Parameters #### Arguments - **file_path** (string) - Required - The path to the target PDF file. - **field_name** (string) - Required - The name of the field to extract. ### Request Example inspector.get_fields_by_name("file.pdf", "name") ### Response #### Success Response - **data** (dict) - A dictionary containing the field information. #### Response Example { "field_name": "name", "value": "example_value" } ``` -------------------------------- ### Development and Testing Commands Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/README.md Standard commands for executing the test suite with coverage reporting and managing project dependencies using the uv package manager. ```bash # Run tests uv run python -m pytest tests/ -v # Run tests with coverage uv run python -m pytest tests/ --cov=pdf_action_inspector --cov-report=html # Add dependencies uv add ``` -------------------------------- ### Runtime Configuration (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Demonstrates how to configure the PDF Action Inspector at runtime using Python. It shows how to import settings and modify parameters like the cache timeout duration, and how to create an inspector instance with custom configurations. ```python from src.core.inspector import PDFActionInspector from src.config.settings import Settings # Configure cache timeout Settings.PDF_CACHE_TIMEOUT_SECONDS = 300 # Create inspector with custom config inspector = PDFActionInspector() ``` -------------------------------- ### Analyze Encrypted PDF Files Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/README.md Demonstrates how to authenticate with a password-protected PDF before performing security analysis or action extraction. Passwords are held in memory only for the duration of the session. ```python # First set the password for the encrypted PDF set_pdf_password("encrypted_document.pdf", "your_password_here") # Then proceed with analysis analyze_pdf_actions_security("encrypted_document.pdf") extract_pdf_actions("encrypted_document.pdf") ``` -------------------------------- ### Handle Encrypted PDFs (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Explains how to work with encrypted PDF files. It demonstrates setting a password for an encrypted PDF using the inspector's cache manager before proceeding with analysis, ensuring secure access to protected documents. ```python if overview['basic_info']['encrypted']: inspector.cache_manager.set_password("encrypted.pdf", "password123") actions = inspector.extract_pdf_actions("encrypted.pdf") ``` -------------------------------- ### Load All Annotations (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Extracts all annotations from a PDF document along with their associated Actions and widget information if applicable. Returns a dictionary with the total number of annotations and a list of annotation details. Requires a file path. ```python from src.core.inspector import PDFActionInspector inspector = PDFActionInspector() annotations_data = inspector.load_all_annotations("document.pdf") print(f"Found {annotations_data['total_annotations']} annotations.") ``` -------------------------------- ### VS Code Extension Usage for Document Overview (TypeScript) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Demonstrates how to call the PDF Action Inspector's document overview functionality through a VS Code extension using TypeScript. It shows an asynchronous tool call and how to parse the JSON response to access document properties like the number of pages. ```typescript const result = await mcp.callTool('mcp_pdf_action_in_get_document_overview', { file_path: '/path/to/document.pdf' }); const overview = JSON.parse(result); console.log(`Document has ${overview.basic_info.pages} pages`); ``` -------------------------------- ### Running Pytest Tests (Bash) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Provides bash commands for executing tests within the project using Pytest. It covers running all tests, targeting specific tests, and running tests with code coverage reporting to generate HTML output. ```bash # Run all tests pytest tests/ -v # Run specific test pytest tests/test_pytest.py::TestPDFActionInspector::test_get_fields_by_name -v # Run with coverage pytest tests/ --cov=src --cov-report=html ``` -------------------------------- ### Create Inspector and Analyze PDF Actions (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Demonstrates how to initialize the PDFActionInspector, extract JavaScript actions from a PDF, and print a warning if JavaScript is detected. It handles basic PDF analysis and security checks. ```python inspector = PDFActionInspector() result = inspector.extract_pdf_actions("suspicious.pdf") if result["has_javascript"]: print("⚠️ Document contains JavaScript") ``` -------------------------------- ### POST /mcp/tools Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Executes PDF inspection tools via the MCP (Model Context Protocol) interface. ```APIDOC ## POST mcp_pdf_action_in_* ### Description Executes specific PDF analysis tools via the MCP layer. These tools return JSON strings for external integration compatibility. ### Method MCP Tool Call ### Parameters #### Arguments - **tool_name** (string) - Required - The specific MCP tool to invoke (e.g., mcp_pdf_action_in_get_fields_by_name). - **args** (object) - Required - Arguments required by the specific tool. ### Request Example await call_tool("mcp_pdf_pdf_action_in_get_fields_by_name", {"file": "file.pdf", "field": "name"}) ### Response #### Success Response - **content** (list) - A list containing the JSON string result. #### Response Example { "content": [{"text": "{\"value\": \"data\"}"}] } ``` -------------------------------- ### Direct Python Usage: Inspector Methods (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Demonstrates how to adapt Python code when inspector core methods now return Python dicts instead of JSON strings. The new version simplifies direct Python integration by removing the need for manual JSON parsing. ```python # Old (v0.0.x) result_json = inspector.get_fields_by_name("file.pdf", "name") result = json.loads(result_json) # New (v0.1.0) result = inspector.get_fields_by_name("file.pdf", "name") # result is already a dict ``` -------------------------------- ### MCP Tool Usage: JSON Serialization (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Illustrates that no changes are needed for MCP tool usage as they continue to return JSON strings. This section confirms that the MCP tools layer handles JSON serialization, maintaining compatibility for external integrations. ```python # No changes needed - MCP tools still return JSON strings result = await call_tool("mcp_pdf_action_in_get_fields_by_name", args) data = json.loads(result.content[0].text) ``` -------------------------------- ### Inspector Core Success and Error Responses (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Illustrates the expected JSON response formats for the Inspector core. It shows a typical success response containing found fields and a common error response indicating a file-not-found issue with relevant details. ```python # Success response (dict) { "field_name": "search_term", "found_fields": [...], "total_found": 2 } # Error response (dict) { "error": "File not found", "error_type": "FileNotFoundError", "file_path": "/path/to/missing.pdf" } ``` -------------------------------- ### Analyze PDF Actions Security (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Generates a comprehensive security analysis prompt based on extracted PDF Actions data. This method is designed for AI systems and returns a multi-section prompt including analysis instructions, strategy, data, and risk guidance. Requires a file path. ```python from src.core.inspector import PDFActionInspector inspector = PDFActionInspector() security_prompt = inspector.analyze_pdf_actions_security("document.pdf") print(security_prompt) ``` -------------------------------- ### Extract PDF Actions (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Extracts all PDF Actions from document, page, annotation, and field levels. Requires a file path as input and returns a dictionary containing various action categories and metadata. ```python from src.core.inspector import PDFActionInspector inspector = PDFActionInspector() result = inspector.extract_pdf_actions("document.pdf") print(f"Total actions found: {result['total_actions']}") ``` -------------------------------- ### Testing Updates: Asserting Dict Returns (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Provides guidance on updating test assertions to reflect the change in return types from JSON strings to Python dictionaries. This ensures tests accurately validate the new data structures returned by the inspector. ```python # Update test assertions for dict returns result = inspector.get_document_overview("test.pdf") assert isinstance(result, dict) # Not JSON string assert result["basic_info"]["pages"] > 0 ``` -------------------------------- ### MCP Tools Error Response Format (JSON) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Shows the JSON structure for error responses returned by MCP tools. This format includes a general error message, an error type, the file path involved, and additional details about the error, aiding in debugging external tool interactions. ```json { "error": "Invalid PDF file", "error_type": "PDFError", "file_path": "/path/to/corrupt.pdf", "details": "Unable to parse PDF structure" } ``` -------------------------------- ### MCP Tool Definition (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Defines an asynchronous tool function within the MCP server framework. It uses a decorator to register the tool and expects arguments of type `ToolArguments`, returning a list of `TextContent` which typically wraps a JSON string of the processed data. ```python @server.call_tool async def mcp_pdf_action_in_extract_pdf_actions(arguments: ToolArguments) -> List[TextContent]: # Process arguments # Call Inspector core method # Return JSON string wrapped in TextContent ``` -------------------------------- ### Find Form Fields by Name (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Searches for form fields within a PDF document by their name, supporting fuzzy matching. It returns a dictionary containing the searched name, a list of found fields with their details (name, type, value, page, actions, rect), and the total count. Requires file path and field name. ```python from src.core.inspector import PDFActionInspector inspector = PDFActionInspector() result = inspector.get_fields_by_name("document.pdf", "signature") print(f"Found {result['total_found']} signature fields") ``` -------------------------------- ### Find Form Fields by Name (Python) Source: https://github.com/foxitsoftware/pdfactioninspector/blob/develop/docs/API_DOCUMENTATION.md Shows how to use the PDFActionInspector to find specific form fields within a PDF by their name. It iterates through the found fields and prints their names and values. This is useful for extracting data from form-based PDFs. ```python fields = inspector.get_fields_by_name("form.pdf", "price") for field in fields["found_fields"]: print(f"Field: {field['name']}, Value: {field['value']}") ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.