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"