Uspto Pfw Mcp

USPTO Patent File Wrapper MCP Server

A high-performance Model Context Protocol (MCP) server for the USPTO Patent File Wrapper API with token saving context reduction capabilities, smart field mapping, and secure browser-accessible downloads.

[]() []() []() [](LICENSE)

📚 Documentation

| Document | Description | |----------|-------------| | [📥 Installation Guide](INSTALL.md) | Complete cross-platform setup with automated scripts | | [🔑 API Key Guide](APIKEYGUIDE.md) | Step-by-step instructions for obtaining USPTO and Mistral API keys with screenshots | | [📖 Usage Examples](USAGEEXAMPLES.md) | Function examples, workflows, and integration patterns | | [🎯 Prompt Templates](PROMPTS.md) | Detailed guide to sophisticated prompt templates for legal & research workflows | | [⚙️ Field Customization](CUSTOMIZATION.md) | Comprehensive guidance on customizing field sets for the minimal and balanced tools | | [🔒 Security Guidelines](SECURITYGUIDELINES.md) | Comprehensive security best practices | | [🛡️ Security Scanning](SECURITY_SCANNING.md) | Automated secret detection and prompt injection protection guide | | [🧪 Testing Guide](tests/README.md) | Test suite documentation and API key setup | | [⚖️ License](LICENSE) | MIT License terms and conditions |

⚡Quick Start

Windows Install

Run PowerShell as Administrator, then:

# Navigate to your user profile
cd $env:USERPROFILE

# If git is installed:
git clone https://github.com/john-walkoe/uspto_pfw_mcp.git
cd uspto_pfw_mcp

# If git is NOT installed:
# Download and extract the repository to C:\Users\YOUR_USERNAME\uspto_pfw_mcp
# Then navigate to the folder:
# cd C:\Users\YOUR_USERNAME\uspto_pfw_mcp

# The script detects if uv is installed and if it is not it will install uv - https://docs.astral.sh/uv

# Run setup script (sets execution policy for this session only):
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process
.\deploy\windows_setup.ps1

# View INSTALL.md for sample script output.
# Close Powershell Window.
# If choose option to "configure Claude Desktop integration" during the script then restart Claude Desktop

The PowerShell script will:

• ✅ Check for and auto-install uv (via winget or PowerShell script)
• ✅ Install dependencies and create executable
• ✅ Prompt for USPTO API key (required) and Mistral API key (optional) or Detect if you had installed the developer's other USPTO MCPs and ask if want to use existing keys from those installation.
• 🔒 If entering in API keys, the script will automatically store API keys securely using Windows DPAPI encryption
• ✅ Ask if you want Claude Desktop integration configured
• 🔒 Offer secure configuration method (recommended) or traditional method (API keys in plain text in the MCP JSON file)
• ✅ Backups and then automatically merge with existing Claude Desktop config (preserves other MCP servers)
• ✅ Provide installation summary and next steps

Claude Desktop Configuration - Manual installs

{
  "mcpServers": {
    "uspto_pfw": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Users/YOUR_USERNAME/uspto_pfw_mcp",
        "run",
        "patent-filewrapper-mcp"
      ],
      "env": {
        "USPTO_API_KEY": "your_actual_USPTO_api_key_here",
        "MISTRAL_API_KEY": "your_mistral_api_key_here_OPTIONAL",
        "PROXY_PORT": "8080"
      }
    }
  }
}

For detailed installation, manual setup, and troubleshooting, see [INSTALL.md](./INSTALL.md)

🎯Key Benefits

• 🔒 Secure API Key Storage - Windows DPAPI encryption for API keys (secure storage option during setup)
• 🗺️ Smart Field Mapping - Use simple names like "inventionTitle" instead of "applicationMetaData.inventionTitle"
• ⚙️ User-Customizable Fields - Configure field sets through YAML without code changes
• 🎯 Context Reduction - Get focused responses instead of massive API dumps
• 🔍 Multi-Strategy Search - Comprehensive, fuzzy, and exact inventor searches
• ⚡ Convenience Parameters - Attorney-friendly search parameters (artunit, examinername, applicant_name, etc.) eliminate need for complex query syntax
• 🏛️ Professional-Grade Fields - additional fields for patent prosecution, international work, and analytics

• 🔄 Circuit Breaker Resilience - Automatic retry logic with exponential backoff prevents API failures
• 📊 Progressive Disclosure - context reduction through optimized minimal → balanced → detailed workflows
• 🔗 Cross-MCP Integration - Purpose-built for multi-database patent research with Developer's other PTAB, FPD, Citations, and Pinecone (Assistant or RAG) MCPs
• 🆕 Centralized Document Hub - PFW proxy now serves as unified download infrastructure for all USPTO MCPs (accepts FPD document registrations)
• 📝 Attorney-Focused Prompt Templates - 10+ sophisticated workflow templates for legal research, litigation, and due diligence

• ✨ Intelligent Document Extraction - Auto-optimized hybrid extraction (free PyPDF2 → Mistral OCR fallback) + secure browser downloads
• 🌐 Secure Browser Downloads - Click proxy URLs to download PDFs directly while keeping API keys secure
• 👁️ Advanced OCR Capabilities - Extract text for LLM use from scanned PDFs, formulas, diagrams, and complex layouts
• 📁 Document Bag Integration - Full prosecution document access (Abstract, Claims, NOA, etc.) alongside XML content analysis of patents/applications
• 💰 Mistral OCR Cost Transparency - Real-time cost calculation (~$0.001-$0.003 per patent document) when using Mistral OCR
• 🚀 High Performance - Optimized for AI workflows with targeted field selection + retry logic with exponential backoff
• 🛡️ Production Ready - Enhanced error handling, structured logging with request IDs, and comprehensive security guidelines
• 💻 Cross-Platform - Works seamlessly on Linux and Windows
• 📋 Complete API Coverage - All USPTO Patent File Wrapper endpoints supported

🔍 Tool Search Optimization (Claude Code v2.1.7+)

NEW: PFW MCP now supports Claude Code's built-in tool search optimization, reducing context window usage by 65-75% through dynamic tool discovery.

How It Works

• Automatic Activation: When MCP tools exceed 10% of context, tool search activates automatically
• Smart Discovery: Claude loads only essential tools upfront, discovering others on-demand via MCPSearch
• Token Savings: ~8-12K tokens → ~2-3K tokens (saves 5-10K tokens for actual work)
• Zero Configuration: Works out of the box with Claude Code v2.1.7+

Entry Point Tools (Always Available)

These 3 tools are loaded immediately for fast access:

1. search_applications_minimal - Primary discovery for patent applications
2. PFW_get_guidance - Workflow guidance and documentation
3. getapplicationdocuments - Document lists for patent applications

Progressive Tool Discovery

Claude discovers additional tools as needed:

• Tier 1 (Minimal): Fast, essential fields only (~10 fields)
• Tier 2 (Balanced): Common use cases (~25 fields)
• Tier 3 (Complete): All available data (~50+ fields)

Enable Tool Search

If tool search isn't activating automatically:

Windows:

$env:ENABLE_TOOL_SEARCH = "true"
claude

Linux/Mac:

export ENABLE_TOOL_SEARCH=true
claude

Verify It's Working

Run /context in Claude Code:

MCP tools: loaded on-demand (N servers)  ← Tool search IS working

For complete documentation, see [PFWTOOLSEARCHCONFIG.md](../ClaudeDocuments/PFWTOOLSEARCH_CONFIG.md).

---

Workflow Design - All preformed by the LLM with Minimal User Guidance

User Requests the following:

• "Look for patents about LCD TV technology related to QLED"
• "Show me Apple's patent applications filed in 2024"
• "Get me PDFs download links for the patent "Integrated delivery and protection device for digital objects"
• "I need you to look at the patent details of 7971071 and summarize it for me"
• "Research this IPR case IPR2025-00562 and compare it to the original prosecution" -* Requires that the USPTO Patent Trial and Appeal Board (PTAB) be installed - usptoptabmcp and also recommended to ask LLM to perform a pfwgetguidance tool call prior to this or any cross MCP prompt (see quick reference chart for section selection, additional details in [Usage Examples](USAGEEXAMPLES.md))

LLM Performs these steps:

Step 1: Discovery minimal → Step 2: Selection (and searches balanced - Optional) → Step 3: Content Analysis → Step 4 (Optional): Select additional prosecution documents for examination → Step 5 (Optional): Retrieve doc_id(s) of the selected from documentBag → Step 6 (Optional): Document Extraction for LLM use and/or Download Links of PDFs for user's use

The field configuration supports an optimized research progression:

1. Discovery searches minimal return 20-50 applications efficiently without prosecution document bloat
2. Selection (and searches balanced - Optional) from the retrieved select likely application(s)/patent(s). Optional balanced search(es) performed if needed in advanced workflows and/or USPTO PTAB (Patent Trial and Appeal Board) MCP cross workflows
3. Content analysis via XML retrieval for selected patents with structured data for LLM's use in analysis
4. Select additional prosecution documents for examination (Optional) e.g. Notice of Allowance, Applicant Citations (disclosed prior art), Examiner's Office Action Rejections, etc.
5. Retrieve docid(s) of the selected from documentBag (Optional) use get application documents tool to get the docid(s)
6. Document Extraction for LLM use and/or Download Links of PDFs for user's use (Optional) Document extraction via intelligent hybrid tool that auto-optimizes for cost and quality and Downloads of the documents as PDFs uses URLs from a HTTP proxy that obscures the USPTO's API key from chat history

🎯 Prompt Templates

This MCP server includes sophisticated AI-optimized prompt templates for complex patent workflows. For detailed documentation on all templates, features, and usage examples, see [PROMPTS.md](PROMPTS.md).

Quick Template Overview

| Category | Templates | Purpose | |----------|-----------|---------| | Legal Analysis | /patent_search, /patent_explanation_for_attorneys, /patent_invalidity_analysis_defense_pinecone_PTAB | Patent discovery, technical translation, defensive litigation | | Research & Prosecution | /art_unit_quality_assessment_FPD, /litigation_research_setup_PTAB_FPD, /technology_landscape_mapping_PTAB | Examiner analysis, litigation prep, competitive intelligence | | Document Management | /complete_patent_package, /document_filtering_assistant, /inventor_portfolio_analysis | Organized retrieval, smart filtering, portfolio mapping |

Key Features Across All Templates:

• Enhanced Input Processing - Flexible identifier support (patent numbers, application numbers, title keywords)
• Smart Validation - Automatic format detection and guidance
• Cross-MCP Integration - Seamless workflows with PTAB, FPD, Citations, and Pinecone MCPs
• Context Optimization - token reduction through progressive disclosure

📊Available Functions

Search Functions (6 Focused Tools)

| Function (Display Name) | Context Reduction | Use Case | |----------|------------------|----------| | pfw_search_applications (Search applications custom) | Variable | Custom patent search with user-defined fields | | pfw_search_inventor (Search inventor custom) | Variable | Smart inventor search with multiple strategies | | pfw_search_applications_minimal (Search applications minimal) | typical 95-99% | Ultra-fast search (user-customizable minimal fields) | | pfw_search_applications_balanced (Search applications balanced) | typical 85-95% | Key fields for discovery (no documentBag) | | pfw_search_inventor_minimal (Search inventor minimal) | typical 95-99% | Ultra-fast inventor search (user-customizable) | | pfw_search_inventor_balanced (Search inventor balanced) | typical 85-95% | Balanced inventor search (no documentBag) |

Search Strategies

Inventor Search Strategies

• exact - Exact name matching only
• fuzzy - Multiple name format variations
• comprehensive - All strategies + partial matching

Query Examples

# Exact strategy
"applicationMetaData.inventorBag.inventorNameText:\"John Smith\""

# Comprehensive strategy
[
  "applicationMetaData.inventorBag.inventorNameText:\"John Smith\"",
  "applicationMetaData.inventorBag.inventorNameText:\"Smith, John\"",
  "applicationMetaData.inventorBag.inventorNameText:Smith*",
  "applicationMetaData.inventorBag.inventorNameText:*Smith*"
]

Document Processing Functions

| Function (Display Name) | Purpose | Requirements | | ------------------------------------------------------------ | ------------------------------------------------------------ | -------------------------------------------------- | | pfw_get_patent_or_application_xml (Get patent or application xml) | Get structured XML content for patents/applications for LLM use with 91-99% token reduction via include_raw_xml=False (recommended) and optional include_fields for selective extraction | USPTOAPIKEY | | pfw_get_granted_patent_documents_download (Get granted patent documents download) | Get complete granted patent package (Abstract, Drawings, Specification, Claims) in one call as secure browser-accessible download URLs | USPTOAPIKEY | | pfw_get_application_documents (Get application documents) | Get prosecution documents' docid from documentBag with advanced filtering (documentcode, directioncategory) | USPTOAPIKEY | | pfw_get_document_content (PFW get document content with mistral ocr) | For LLM readability of non ORC scanned prosecution documents uses intelligent document extraction with cost transparency | USPTOAPIKEY (+ MISTRALAPIKEY for OCR fallback) | | pfw_get_document_download (PFW get document download) | Secure browser-accessible download URLs | USPTOAPI_KEY | | pfw_get_guidance (PFW get guidance) | RECOMMENDED: Context-efficient selective guidance sections (95-99% token reduction) | None |

Document Processing Capabilities

• XML Content Tier (pfw_get_patent_or_application_xml): Structured patent/application content with extreme context optimization
• 🎯 RECOMMENDED: include_raw_xml=False - Removes ~50K token raw XML overhead (91% token reduction!)
• Selective field extraction (include_fields) - Request only needed fields for 95-99% token reduction
• Default optimized response - Returns abstract, claims, description (~5K tokens with include_raw_xml=False)
• Ultra-efficient modes - Claims only (~1.5K tokens), Citations only (569 tokens), Inventors only (428 tokens)
• Intelligent patent-to-application mapping - Automatically finds applications for granted patents
• Auto-detection - Automatically determines patent vs application from identifier
• LLM-optimized parsing - Extracts abstract, claims, inventors, classifications, citations on demand
• Dual XML support - Handles both PTGRXML (granted patents) and APPXML (applications)
• Data limitation - Only available for patents/applications filed after January 1, 2001
• **Complete Patent Package Tier (`pfwgetgranted_pat

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: john-walkoe
• Source: john-walkoe/usptopfw_mcp
• License: MIT

Install and usage instructions live in the source repository linked above.