USPTO Final Petition Decisions MCP Server

Instructions

# Denied petitions for company
fpd_search_petitions_minimal(applicant_name="TechCorp Inc.", decision_type="DENIED", limit=50)

# Hybrid: keywords + convenience
fpd_search_petitions_minimal(query="machine learning", decision_type="DENIED", limit=50)

Implementation Reference

• src/fpd_mcp/main.py:372-511 (handler)

  Primary handler for Search_petitions_minimal tool. Includes @mcp.tool registration decorator. Validates inputs, builds Lucene query from 9 convenience parameters, calls FPDClient.search_petitions with petitions_minimal fields, filters response with FieldManager, adds metadata and LLM guidance.

  @mcp.tool(name="Search_petitions_minimal")
  @async_tool_error_handler("minimal_search")
  async def fpd_search_petitions_minimal(
      query: str = "",
      limit: int = 50,
      offset: int = 0,
  
      # NEW: Minimal tier convenience parameters (9 total)
      # Core Identity & Party
      applicant_name: Optional[str] = None,         # e.g., "Apple Inc.", "TechCorp"
      application_number: Optional[str] = None,     # e.g., "17896175"
      patent_number: Optional[str] = None,          # e.g., "11788453"
  
      # Decision Filters
      decision_type: Optional[str] = None,          # e.g., "GRANTED", "DENIED", "DISMISSED"
      deciding_office: Optional[str] = None,        # e.g., "OFFICE OF PETITIONS"
  
      # Date Ranges
      petition_date_start: Optional[str] = None,    # e.g., "2024-01-01" (YYYY-MM-DD)
      petition_date_end: Optional[str] = None,      # e.g., "2024-12-31" (YYYY-MM-DD)
      decision_date_start: Optional[str] = None,    # e.g., "2024-01-01" (YYYY-MM-DD)
      decision_date_end: Optional[str] = None       # e.g., "2024-12-31" (YYYY-MM-DD)
  ) -> Dict[str, Any]:
      """Ultra-fast discovery search for Final Petition Decisions (50-100 results).
  
  **NEW: Minimal tier convenience parameters (9 total) - no query syntax needed!**
  
  Use for: High-volume petition discovery, finding petitions by applicant, decision type, or date range.
  Returns: 8 essential fields - petition ID, application number, patent number, applicant name,
  decision type, petition mail date, decision date, deciding office.
  
  **Convenience Parameters:**
  - `applicant_name`: Company/party name (e.g., 'Apple Inc.')
  - `application_number`: Application number (e.g., '17896175')
  - `patent_number`: Patent number if granted (e.g., '11788453')
  - `decision_type`: Outcome (e.g., 'GRANTED', 'DENIED', 'DISMISSED')
  - `deciding_office`: Office that decided (e.g., 'OFFICE OF PETITIONS')
  - `petition_date_start/end`: Filing date range (YYYY-MM-DD)
  - `decision_date_start/end`: Decision date range (YYYY-MM-DD)
  
  **Examples:**
  ```python
  # Denied petitions for company
  fpd_search_petitions_minimal(applicant_name="TechCorp Inc.", decision_type="DENIED", limit=50)
  
  # Hybrid: keywords + convenience
  fpd_search_petitions_minimal(query="machine learning", decision_type="DENIED", limit=50)
  ```
  
  **Progressive Disclosure Workflow:**
  1. Use THIS TOOL for discovery with minimal params (50-100 results)
  2. Present top results to user for selection
  3. Use fpd_search_petitions_balanced for detailed analysis (10-20 selected)
     - Balanced tier adds: petition_type_code, art_unit, technology_center, prosecution_status, entity_status
  4. Use fpd_get_petition_details for complete petition data
  
  **Cross-MCP Integration:**
  - {QueryFieldNames.APPLICATION_NUMBER} -> Links to Patent File Wrapper MCP
  - {QueryFieldNames.PATENT_NUMBER} -> Links to PTAB MCP for post-grant challenges
  - Use balanced tier to get {QueryFieldNames.ART_UNIT} for PFW cross-reference"""
      # Input validation
      if limit < api_constants.MIN_SEARCH_LIMIT or limit > api_constants.MAX_SEARCH_LIMIT:
          raise ValidationError(f"Limit must be between {api_constants.MIN_SEARCH_LIMIT} and {api_constants.MAX_SEARCH_LIMIT}", generate_request_id())
      if offset < 0:
          raise ValidationError("Offset must be non-negative", generate_request_id())
  
      # Build query from convenience parameters
      final_query, convenience_params_used = _build_convenience_query(
          query=query,
          applicant_name=applicant_name,
          application_number=application_number,
          patent_number=patent_number,
          decision_type=decision_type,
          deciding_office=deciding_office,
          petition_date_start=petition_date_start,
          petition_date_end=petition_date_end,
          decision_date_start=decision_date_start,
          decision_date_end=decision_date_end,
          allow_balanced_params=False  # Minimal tier only
      )
  
      # Additional query length validation
      if len(final_query) > 2000:
          raise ValidationError("Combined query too long (max 2000 characters)", generate_request_id())
  
      # Get fields from field manager
      fields = field_manager.get_fields("petitions_minimal")
  
      # Search petitions
      result = await api_client.search_petitions(
          query=final_query,
          fields=fields,
          limit=limit,
          offset=offset
      )
  
      # Check for errors
      if "error" in result:
          return result
  
      # Filter response using field manager
      filtered_result = field_manager.filter_response(result, "petitions_minimal")
  
      # Add query metadata
      filtered_result["query_info"] = {
          "final_query": final_query,
          "convenience_parameters_used": convenience_params_used,
          "tier": "minimal",
          "available_parameters": [
              "applicant_name", "application_number", "patent_number",
              "decision_type", "deciding_office",
              "petition_date_start", "petition_date_end",
              "decision_date_start", "decision_date_end"
          ]
      }
  
      # Add usage guidance
      filtered_result["llm_guidance"] = {
          "workflow": "Discovery -> User Selection -> Balanced Analysis -> Cross-MCP Integration",
          "parameter_guidance": {
              "current_tier": "minimal (9 convenience parameters available)",
              "next_tier": "Use fpd_search_petitions_balanced for 5 additional parameters: petition_type_code, art_unit, technology_center, prosecution_status, entity_status",
              "progressive_disclosure": "Start here for discovery, advance to balanced for analysis"
          },
          "next_steps": [
              "Present top results to user for selection",
              "Use fpd_search_petitions_balanced for detailed analysis of selected petitions",
              "Use fpd_search_petitions_by_application to get all petitions for specific application",
              "Cross-reference with PFW using applicationNumberText for prosecution history",
              "Cross-reference with PTAB using patentNumber for post-grant challenges"
          ],
          "red_flags": {
              "revival_petitions": "Look for ruleBag containing '37 CFR 1.137' (abandoned applications)",
              "examiner_disputes": "Look for ruleBag containing '37 CFR 1.181' (supervisory review)",
              "denied_petitions": "decisionTypeCodeDescriptionText: 'DENIED' indicates potential quality issues"
          }
      }
  
      return filtered_result

• src/fpd_mcp/main.py:372-372 (registration)

  MCP tool registration decorator specifying the exact tool name 'Search_petitions_minimal'.

  @mcp.tool(name="Search_petitions_minimal")

• src/fpd_mcp/config/field_manager.py:52-63 (schema)

  Output schema definition for minimal field set (8 essential fields). Used by field_manager.get_fields('petitions_minimal') and filter_response to reduce context by 95-99%.

  "petitions_minimal": {
      "description": "Essential fields for petition discovery",
      "fields": [
          "petitionDecisionRecordIdentifier",
          "applicationNumberText",
          "patentNumber",
          "firstApplicantName",
          "decisionTypeCodeDescriptionText",
          "petitionMailDate",
          "decisionDate",
          "finalDecidingOfficeName"
      ]

• src/fpd_mcp/api/field_constants.py:11-142 (schema)

  Type definitions and constants for all input query fields and output response fields used in the tool.

  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"
  
  
  class QueryFieldNames:
      """
      Field names as they appear in Lucene/search queries.
  
      Use these for building search queries with convenience parameters.
      """
      # Core search fields
      APPLICATION_NUMBER = "applicationNumberText"
      PATENT_NUMBER = "patentNumber"
      APPLICANT_NAME = "firstApplicantName"
  
      # Classification search
      ART_UNIT = "groupArtUnitNumber"
      TECHNOLOGY_CENTER = "technologyCenter"
  
      # Date search
      PETITION_MAIL_DATE = "petitionMailDate"
      DECISION_DATE = "decisionDate"
  
      # Decision search
      DECISION_TYPE = "decisionTypeCodeDescriptionText"
      PETITION_TYPE = "decisionPetitionTypeCodeDescriptionText"
  
      # Status search
      PROSECUTION_STATUS = "prosecutionStatusCodeDescriptionText"
      BUSINESS_ENTITY = "businessEntityStatusCategory"
  
      # Legal search
      RULE = "ruleBag"  # Search for CFR rules
      STATUTE = "statuteBag"  # Search for statutes
  
      # Metadata search
      INVENTION_TITLE = "inventionTitle"
  
  
  # === RED FLAG RULES FOR PETITION QUALITY ASSESSMENT ===
  class PetitionRedFlags:
      """
      Common petition types and rules that indicate potential quality issues.
  
      Use these constants when analyzing petition patterns for red flags.
      """
      # Revival petitions (application was abandoned)
      RULE_REVIVAL = "37 CFR 1.137"
  
      # Petitions for supervisory review (examiner disputes)
      RULE_SUPERVISORY_REVIEW = "37 CFR 1.181"
  
      # Petitions for reconsideration (restriction issues)
      RULE_RECONSIDERATION = "37 CFR 1.182"
  
      # Special petitions
      RULE_SPECIAL_PETITION = "37 CFR 1.183"
  
      # Decision outcomes
      DECISION_DENIED = "DENIED"
      DECISION_GRANTED = "GRANTED"

• src/fpd_mcp/services/fpd_service.py:37-95 (helper)

  Supporting service method with caching and performance monitoring. Similar logic to tool handler but with added cache_manager and structured logging.

  async def search_petitions_minimal(
      self,
      query: str,
      limit: int = 50,
      offset: int = 0
  ) -> Dict[str, Any]:
      """
      Perform minimal petition search with context reduction and caching
  
      Args:
          query: Search query
          limit: Number of results to return
          offset: Offset for pagination
  
      Returns:
          Filtered search results
      """
      with PerformanceTimer(self.structured_logger, "search_petitions_minimal", {"query_length": len(query), "limit": limit, "offset": offset}):
          # Check cache first
          cache_key_args = (query, limit, offset)
          cached_result = self.cache_manager.get("search_petitions_minimal", *cache_key_args)
          if cached_result is not None:
              self.structured_logger.log_cache_event(
                  cache_key=str(hash(cache_key_args)),
                  hit=True,
                  method_name="search_petitions_minimal",
                  ttl_seconds=300
              )
              return cached_result
  
          # Log cache miss
          self.structured_logger.log_cache_event(
              cache_key=str(hash(cache_key_args)),
              hit=False,
              method_name="search_petitions_minimal"
          )
  
          # Get minimal field set
          fields = self.field_manager.get_fields("petitions_minimal")
  
          # Perform search
          result = await self.api_client.search_petitions(
              query=query,
              fields=fields,
              limit=limit,
              offset=offset
          )
  
          # Check for errors
          if "error" in result:
              return result
  
          # Filter response using field manager
          filtered_result = self.field_manager.filter_response(result, "petitions_minimal")
  
          # Cache successful results
          self.cache_manager.set("search_petitions_minimal", filtered_result, *cache_key_args)
  
          return filtered_result