USPTO Final Petition Decisions MCP Server

Instructions

Implementation Reference

• src/fpd_mcp/main.py:896-989 (handler)

  MCP tool handler and registration for 'Get_petition_details'. Validates input, fetches data via FPDClient.get_petition_by_id, adds LLM guidance, handles errors.
  @mcp.tool(name="Get_petition_details") @async_tool_error_handler("petition_details") async def fpd_get_petition_details( petition_id: str, include_documents: bool = True ) -> Dict[str, Any]: """Get complete details for a specific petition by petition ID (UUID). **⚠️ CRITICAL: Proxy URLs in documentBag require proxy server to be running!** **MANDATORY WORKFLOW when include_documents=True:** 1. Call fpd_get_petition_details(petition_id=X, include_documents=True) 2. Call fpd_get_document_download(petition_id=X, document_identifier=DOC1) - starts proxy 3. NOW provide all document download links to user - proxy is ready **Use for:** Deep dive into specific petition, document metadata access, full legal context review. **Returns:** - All petition fields (no filtering) - Document metadata if include_documents=True (file names, page counts, identifiers) - Full legal context (all issues, CFR rules, statutes cited) - Complete timeline (petition filed → decision issued) **Document access:** - Use documentIdentifier from documentBag with fpd_get_document_download for browser access - Typical documents: Petition PDF, Decision PDF, supporting exhibits **Parameters:** - petition_id: Petition decision record identifier (UUID from search results) - include_documents: Include documentBag with file metadata (default True)""" try: # Input validation if not petition_id or len(petition_id.strip()) == 0: return format_error_response("Petition ID cannot be empty", 400) # Use API client's get_petition_by_id method result = await api_client.get_petition_by_id( petition_id=petition_id, include_documents=include_documents ) # Check for errors if "error" in result: return result # Add detailed guidance for petition analysis result["llm_guidance"] = { "workflow": "Petition Details -> Document Access -> Cross-MCP Context", "document_access": { "description": "Use documentIdentifier from documentBag to download PDFs", "example": "fpd_get_document_download(petition_id='{petition_id}', document_identifier='ABC123')", "typical_documents": [ "Petition PDF - Original petition filed by applicant/agent", "Decision PDF - Director's decision (GRANTED/DENIED/DISMISSED)", "Supporting exhibits - Additional documents filed with petition" ] }, "legal_analysis": { "cfr_rules": "Check ruleBag for CFR citations (e.g., 37 CFR 1.137, 1.181, 1.182)", "statutes": "Check statuteBag for statutory basis (e.g., 35 USC 134)", "issues": "Review petitionIssueConsideredTextBag for specific issues raised", "outcome_significance": { "GRANTED": "Director agreed with petitioner - examiner/office action modified", "DENIED": "Director upheld examiner/office - petition unsuccessful", "DISMISSED": "Petition withdrawn or moot - no substantive decision" } }, "cross_mcp_context": { "prosecution_history": "Use applicationNumberText with PFW to see full prosecution timeline", "timeline_correlation": "Compare petitionMailDate with office action dates in PFW", "ptab_risk": "If DENIED petition + later patented, check PTAB for challenges", "examiner_analysis": "Get examiner name from PFW, check if pattern of petitions against this examiner" }, "next_steps": [ "Review decision outcome and legal basis (ruleBag, statuteBag)", "Use fpd_get_document_download to access petition/decision PDFs if needed", "Cross-reference with PFW prosecution timeline for context", "Assess red flag significance based on petition type and outcome" ] } return result except ValueError as e: logger.warning(f"Validation error in get petition details: {str(e)}") return format_error_response(str(e), 400) except httpx.HTTPStatusError as e: logger.error(f"API error in get petition details: {e.response.status_code} - {e.response.text}") return format_error_response(f"API error: {e.response.text}", e.response.status_code) except httpx.TimeoutException as e: logger.error(f"API timeout in get petition details: {str(e)}") return format_error_response("Request timeout - please try again", 408) except Exception as e: logger.error(f"Unexpected error in get petition details: {str(e)}") return format_error_response(f"Internal error: {str(e)}", 500)
• src/fpd_mcp/api/fpd_client.py:307-338 (helper)

  Core API client helper that performs the HTTP GET request to the USPTO FPD API endpoint /{petition_id} to retrieve full petition details, with optional documents.
  async def get_petition_by_id( self, petition_id: str, include_documents: bool = False ) -> Dict[str, Any]: """ Get specific petition by UUID Args: petition_id: Petition decision record identifier (UUID) include_documents: Whether to include document bag Returns: Dict containing petition details """ try: # Build query parameters params = {} if include_documents: params["includeDocuments"] = "true" # Make GET request to specific petition endpoint return await self._make_request( f"{petition_id}", method="GET", params=params ) except Exception as e: logger.error(f"Error in get_petition_by_id: {str(e)}") return format_error_response(str(e), 500, generate_request_id())
• src/fpd_mcp/api/field_constants.py:10-84 (schema)

  Defines all USPTO FPD API field constants used for input/output schemas, queries, and response filtering. Serves as schema reference for petition details structure.
  class FPDFields: """ Constants for USPTO Final Petition Decisions API field names. These constants represent the exact field names used by the USPTO API. Use these instead of hardcoded strings to enable: - IDE autocomplete - Easier refactoring - Catching typos at development time """ # === TOP-LEVEL FIELDS === PETITION_DECISION_DATA_BAG = "petitionDecisionDataBag" # === CORE IDENTIFICATION FIELDS === PETITION_DECISION_RECORD_IDENTIFIER = "petitionDecisionRecordIdentifier" # UUID APPLICATION_NUMBER_TEXT = "applicationNumberText" # Links to PFW MCP PATENT_NUMBER = "patentNumber" # Links to PTAB MCP # === APPLICANT/INVENTOR FIELDS === FIRST_APPLICANT_NAME = "firstApplicantName" INVENTOR_BAG = "inventorBag" CUSTOMER_NUMBER = "customerNumber" FIRST_INVENTOR_TO_FILE_INDICATOR = "firstInventorToFileIndicator" # AIA indicator # === DECISION FIELDS === DECISION_TYPE_CODE_DESCRIPTION_TEXT = "decisionTypeCodeDescriptionText" # GRANTED/DENIED/DISMISSED PETITION_MAIL_DATE = "petitionMailDate" # When petition filed DECISION_DATE = "decisionDate" # When Director decided DECISION_MAIL_DATE = "decisionMailDate" # When decision mailed FINAL_DECIDING_OFFICE_NAME = "finalDecidingOfficeName" # Deciding office # === PETITION TYPE FIELDS === DECISION_PETITION_TYPE_CODE = "decisionPetitionTypeCode" # Type code (551, etc.) DECISION_PETITION_TYPE_CODE_DESCRIPTION_TEXT = "decisionPetitionTypeCodeDescriptionText" # === CLASSIFICATION FIELDS === GROUP_ART_UNIT_NUMBER = "groupArtUnitNumber" # Art unit (→ PFW cross-ref) TECHNOLOGY_CENTER = "technologyCenter" # TC # === STATUS FIELDS === PROSECUTION_STATUS_CODE = "prosecutionStatusCode" PROSECUTION_STATUS_CODE_DESCRIPTION_TEXT = "prosecutionStatusCodeDescriptionText" BUSINESS_ENTITY_STATUS_CATEGORY = "businessEntityStatusCategory" # Small/Undiscounted # === LEGAL CONTEXT FIELDS (ARRAYS) === PETITION_ISSUE_CONSIDERED_TEXT_BAG = "petitionIssueConsideredTextBag" # Issues raised RULE_BAG = "ruleBag" # CFR rules cited (e.g., "37 CFR 1.137") STATUTE_BAG = "statuteBag" # Statutes cited # === COURT INFORMATION === COURT_ACTION_INDICATOR = "courtActionIndicator" # Boolean ACTION_TAKEN_BY_COURT_NAME = "actionTakenByCourtName" # === INVENTION DETAILS === INVENTION_TITLE = "inventionTitle" # === METADATA === LAST_INGESTION_DATE_TIME = "lastIngestionDateTime" # Data freshness # === DOCUMENT FIELDS === DOCUMENT_BAG = "documentBag" DOCUMENT_IDENTIFIER = "documentIdentifier" DOCUMENT_CODE = "documentCode" DOCUMENT_CODE_DESCRIPTION_TEXT = "documentCodeDescriptionText" DOCUMENT_FILE_NAME = "documentFileName" PAGE_COUNT = "pageCount" # === DOWNLOAD FIELDS === DOWNLOAD_OPTION_BAG = "downloadOptionBag" MIME_TYPE_IDENTIFIER = "mimeTypeIdentifier" # PDF, etc. DOWNLOAD_URL = "downloadUrl" PAGE_TOTAL_QUANTITY = "pageTotalQuantity"