uspto pfw MCP

USPTO专利文件包装MCP服务器

用于USPTO专利文件包装器API的具有令牌保存功能的高性能模型上下文协议（MCP）服务器 上下文缩减 能力、智能现场测绘，以及 安全的浏览器可访问下载.

   

📚 文档

⚡快速开始

Windows安装

以管理员身份运行PowerShell那么：

# 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

PowerShell脚本将：

• ✅ 检查并自动安装uv（通过winget或PowerShell脚本）
• ✅ 安装依赖项并创建可执行文件
• ✅ 提示输入USPTO API密钥（必需）和Mistral API密钥（可选）或检测是否已安装开发人员的其他USPTO MCP，并询问是否要使用这些安装中的现有密钥。
• 🔒 如果输入API密钥，脚本将自动使用Windows DPAPI加密安全地存储API密钥
• ✅ 询问是否要配置Claude Desktop集成
• 🔒 提供安全的配置方法（推荐）或传统方法（MCP JSON文件中的纯文本API密钥）
• ✅ 备份，然后自动与现有的Claude Desktop配置合并（保留其他MCP服务器）
• ✅ 提供安装摘要和后续步骤

Claude桌面配置-手动安装

{
  "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"
      }
    }
  }
}

用于详细的安装、手动设置和故障排除，请参阅 安装.md

🎯主要优势

• 🔒 安全的API密钥存储 -API密钥的Windows DPAPI加密（安装过程中的安全存储选项）

• 🗺️ 智能现场测绘 -使用简单的名称，如 "inventionTitle" 而不是 "applicationMetaData.inventionTitle"

• ⚙️ 用户可自定义字段 -通过YAML配置字段集，无需更改代码

• 🎯 上下文缩减 -获得集中的响应，而不是大量的API转储

• 🔍 多策略搜索 -全面、模糊和精确的发明人搜索

• ⚡ 便利性参数 -律师友好的搜索参数（art_unit、examiner_name、applicant_name等）消除了对复杂查询语法的需求

• 🏛️ 专业级领域 -专利申请、国际工作和分析的其他领域

• 🔄 断路器弹性 -具有指数退避的自动重试逻辑可防止API失败

• 📊 渐进式披露 -通过优化最小值减少上下文→ 平衡的→ 详细的工作流程

• 🔗 跨MCP集成 -专为与开发商的其他PTAB、FPD、Citations和Pinecone（助理或RAG）MCP进行多数据库专利研究而设计

- 🆕 集中式文档中心 -PFW代理现在可以作为所有USPTO MCP的统一下载基础设施（接受FPD文档注册）

• 📝 以律师为中心的提示模板 -10多个用于法律研究、诉讼和尽职调查的复杂工作流程模板

• ✨ 智能文档提取 -自动优化混合提取（免费PyPDF2→ Mistral OCR回退）+安全浏览器下载

• 🌐 安全浏览器下载 -单击代理URL可直接下载PDF，同时确保API密钥的安全

• 👁️ 高级OCR功能 -从扫描的PDF、公式、图表和复杂布局中提取文本以供LLM使用

• 📁 文件袋集成 -完整的起诉文件访问权限（摘要、权利要求、NOA等）以及专利/申请的XML内容分析

• 💰 Mistral OCR成本透明度 -使用Mistral OCR时的实时成本计算（每份专利文件约0.001-0.003美元）

• 🚀 高性能 -针对AI工作流程进行了优化，具有目标字段选择+指数回退的重试逻辑

• 🛡️ 生产就绪 -增强的错误处理、带请求ID的结构化日志记录和全面的安全指南

• 💻 交叉平台的 -在Linux和Windows上无缝工作

• 📋 API全面覆盖 -支持所有USPTO专利文件包装器端点

🔍 工具搜索优化（Claude Code v2.1.7+）

新：PFW MCP现在支持Claude Code的内置工具搜索优化，通过以下方式减少上下文窗口的使用 65-75% 通过动态工具发现。

运作原理

• 自动激活：当MCP工具超过上下文的10%时，工具搜索会自动激活
• 智能发现：Claude只预先加载基本工具，通过MCPSearch按需发现其他工具
• 代币节省：约8-12K代币→ ~2-3K代币（为实际工作节省5-10K代币）
• 零配置：与Claude Code v2.1.7一起开箱即用+

入口点工具（始终可用）

这3个工具会立即加载，以便快速访问：

1. search_applications_minimal -专利申请的主要发现
2. PFW_get_guidance -工作流程指导和文件
3. 获取应用程序文档 -专利申请文件清单

渐进式工具发现

Claude根据需要发现其他工具：

• 第1级（最低）：仅限快速、基本字段（~10个字段）
• 第2级（平衡）：常见用例（~25个字段）
• 第3级（完整）：所有可用数据（~50+个字段）

启用工具搜索

如果工具搜索未自动激活：

视窗:

$env:ENABLE_TOOL_SEARCH = "true"
claude

Linux/Mac:

export ENABLE_TOOL_SEARCH=true
claude

验证它是否正常工作

跑 /context 克劳德代码：

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

有关完整文档，请参阅 PFW_TOOL_SEARCH_CONFIG.md.

______________________________________________________________________

工作流程设计-所有工作流程均由LLM在最少的用户指导下完成

用户请求如下：

• *“寻找与QLED相关的液晶电视技术专利”*
• *“给我看看苹果在2024年提交的专利申请”*
• *“为我获取专利“数字对象集成交付和保护设备”的PDF下载链接”*
• *“我需要你查看7971071的专利细节，并为我总结一下”*

LLM执行以下步骤：

第一步：发现最少 → 步骤2：选择（和搜索平衡-可选） → 步骤3：内容分析 → 步骤4（可选）：选择其他起诉文件进行审查 → 步骤5（可选）：从documentBag中检索所选文件的doc_id → 步骤6（可选）：用于LLM的文档提取和/或用户使用的PDF下载链接

现场配置支持优化的研究进展：

1. 发现搜索最少 高效返回20-50份申请，无需起诉文件膨胀
2. 选择（和搜索平衡-可选） 从检索到的选择可能的申请/专利中。如果需要，在高级工作流程和/或USPTO PTAB（专利审判和上诉委员会）MCP交叉工作流程中执行可选的平衡搜索
3. 内容分析 通过XML检索选定的专利，并使用结构化数据进行LLM分析
4. 选择其他起诉文件进行审查 （可选）例如许可通知、申请人引用（披露的现有技术）、审查员审查意见通知书驳回等。
5. 从documentBag中检索所选文件的doc_id （可选）使用获取应用程序文档工具获取doc_id
6. LLM使用的文档提取和/或用户使用的PDF下载链接 （可选）通过智能混合工具提取文档，该工具自动优化成本和质量，并在PDF使用HTTP代理的URL时下载文档，该代理会从聊天历史记录中屏蔽USPTO的API密钥

🎯 提示模板

此MCP服务器包括用于复杂专利工作流程的复杂AI优化提示模板。有关所有模板、功能和使用示例的详细文档，请参阅 PROMPTS.md.

快速模板概述

所有模板的主要功能：

• 增强的输入处理 -灵活的标识符支持（专利号、申请号、标题关键字）
• 智能验证 -自动格式检测和引导
• 跨MCP集成 -使用PTAB、FPD、Citations和Pinecone MCP实现无缝工作流程
• 上下文优化 -通过逐步披露减少代币

📊可用功能

搜索功能（6个重点工具）

搜索策略

发明人搜索策略

• exact -仅精确匹配名称
• fuzzy -多种名称格式变体
• comprehensive -所有策略+部分匹配

查询示例

# 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*"
]

文档处理功能

文档处理能力

• XML内容层(pfw_get_patent_or_application_xml)：结构化专利/申请内容 极端上下文优化

- 🎯 推荐： include_raw_xml=False -删除约50K令牌原始XML开销（令牌减少91%！） - 选择性场提取(include_fields) -仅请求95-99%令牌减少所需的字段 - 默认优化响应 -返回摘要、声明、描述（约5K个标记 include_raw_xml=False) - 超高效模式 -仅声明（约1.5K代币），仅引用（569代币），只发明人（428代币） - 智能专利到应用映射 -自动查找已授予专利的申请 - 自动检测 -根据标识符自动确定专利与申请 - LLM优化解析 -按需摘录摘要、权利要求、发明人、分类、引用 - 双重XML支持 -处理PTGRXML（已授予专利）和APPXML（应用程序） - 数据限制 -仅适用于2001年1月1日之后提交的专利/申请

• 完整的专利包层(pfw_get_granted_patent_documents_download)：单次授权专利检索

- 一体化便利 -在一次调用中检索摘要、图纸、规范、权利要求（替换4个单独的调用） - 智能元件选择 -自动选择原始索赔与授权索赔，可选图纸 - 有组织的下载链接 -返回包含所有组件的代理下载URL的结构化元数据 - 非常适合律师 -非常适合尽职调查、诉讼准备、投资组合审查、硬拷贝生成 - 高效的工作流程 -用于“给我专利”请求，而不是手动文档搜索 - 优雅降级 -如果4个组件中有3个可用，则成功，清楚地表明缺少项目 - LLM优化指导 -可点击标记链接的内置格式说明 - 总页数 -预先显示总体文档大小以供规划（通常为40-80页）

• 起诉文件级别(pfw_get_application_documents)：-从documentBag中有针对性地访问文档

- 代币高效设计 -仅在需要时获取起诉文件（无搜索膨胀） - 高级过滤 -筛选条件 document_code （NOA、CTFR、892等）以及 direction_category （传入/传出/内部） - 上下文缩减 -对于诉讼严重的申请（200多个文档），实现98.6%的减少→ 1-2 docs) - 智能文档过滤 -关注关键文件（ABST、CLM、SPEC、NOA等） - 工作流程优化 -发现后搜索特定应用程序 - 文件指导 -智能摘要和下载建议 - 替换搜索中的documentBag -防止发现工作流中的100倍令牌爆炸

• ✨ 智能提取层(pfw_get_document_content)：-混合自动优化提取

- 智能方法选择 -自动首先尝试PyPDF2（免费），需要时返回到Mistral OCR（需要API密钥） - 成本优化 -仅在PyPDF2提取未通过质量检查时支付OCR费用 - 质量检测 -自动确定提取是否可用或是否需要OCR - 使用Mistral API密钥-始终有效 -保证任何USPTO文件的文本提取（无空白结果） - 透明的报告 -显示使用了哪种方法和相关成本 - 统一接口 -单一工具可处理所有文档类型（消除工具混淆） - 高性能 -从扫描的文档、公式、图表、复杂布局中提取文本 - 成本 -基于文本的PDF免费，使用Mistral扫描OCR的每份文档约0.001-0.003美元

• 浏览器下载层(pfw_get_document_download)：安全代理下载

- 点击下载 直接在任何浏览器中工作的URL - API密钥安全 -USPTO API凭证从未在聊天历史记录或浏览器中公开 - 速率限制合规性 -自动执行美国专利商标局每10秒5次下载 - 增强的文件名 -PFW和FPD文档的专业、人类可读的文件名： - PFW： APP-{app_number}_PAT-{patent_number}_{invention_title}_{type}.pdf - FPD： PET-{date}_APP-{app}_PAT-{patent}_{description}.pdf - 混合服务器架构 -HTTP代理与MCP服务器一起运行 - 可调TCP端口 -HTTP代理的TCP端口可以通过环境变量进行调整 - 🆕 集中式代理中心 -PFW代理（端口8080）现在接受FPD MCP的文档注册，以便在USPTO MCP之间获得统一的下载体验。（计划中的未来PTAB集中式代理中心）

中使用的增强文件名格式 pfw_get_document_download 和 pfw_get_granted_patent_documents_download

系统使用应用程序元数据自动生成描述性文件名：

对于PFW文件-授予的专利：

APP-11752072_PAT-7971071_INTEGRATED_DELIVERY_AND_PROTECTION_ABST.pdf
APP-14171705_PAT-9049188_HYBRID_DEVICE_HAVING_A_PERSONAL_DIGITAL_CLM.pdf

PFW文件-待处理申请：

APP-17896175_COMMUNICATION_METHOD_AND_APPARATUS_SPEC.pdf
APP-16543210_MACHINE_LEARNING_OPTIMIZATION_SYSTEM_DRW.pdf

FPD文件-请愿决定：

PET-2025-09-03_APP-18462633_PAT-8803593_PATENT_PROSECUTION_HIGHWAY_DECISION.pdf
PET-2024-05-15_APP-17414168_REVIVAL_PETITION_DECISION.pdf

特征：

• 应用程序- 用于明确应用程序编号标识的前缀
• 帕特- 前缀显示授予的专利号（如果可用）
• 聚酯食品包装材料 带有决定日期的FPD申请文件前缀
• 40个字符的标题 为了更好的可读性（PFW）或 40个字符描述 （FPD）
• 文档类型代码 （PFW：ABST、CLM、SPEC、DRW；FPD：决策等）
• 按时间顺序排序 -FPD文件名以日期开头，便于时间线导航
• 跨平台保险箱 字符和长度限制
• 投资组合友好 专利律师组织

LLM指导功能

情境高效引导系统

新 pfw_get_guidance 工具 -通过选择性指导部分解决MCP资源可见性问题：

🎯 快速参考图表 -确切地知道该调用哪个部分：

• 🔍 “按发明人/公司/艺术单位查找专利”→ pfw_get_guidance("fields")
• 📄 “获取完整的专利包/文件”→ pfw_get_guidance("documents")
• 🔖 解码文档代码（NOA、CTFR、892等）→ pfw_get_guidance("document_codes")
• 🤝 “研究知识产权与起诉模式”→ pfw_get_guidance("workflows_ptab")
• 🚩 “分析请愿红旗+起诉”→ pfw_get_guidance("workflows_fpd")
• 📊 “考官行为引文分析”→ pfw_get_guidance("workflows_citations")
• 🧠 “基于域的RAG法律框架（§101、§103、§112）”→ pfw_get_guidance("workflows_pinecone")
• 🏢 “完成公司尽职调查”→ pfw_get_guidance("workflows_complete")
• ⚙️ “便利性参数搜索”→ pfw_get_guidance("tools")
• ❌ “搜索错误或下载问题”→ pfw_get_guidance("errors")
• 💰 “降低API成本”→ pfw_get_guidance("cost")

智能现场测绘

将复杂的API字段名称转换为用户友好的替代名称：

#  User-friendly (automatically mapped)
fields = [
    "applicationNumberText",    # Direct passthrough
    "inventionTitle",           # applicationMetaData.inventionTitle
    "patentNumber",             # applicationMetaData.patentNumber
    "filingDate",               # applicationMetaData.filingDate
    "parentPatentNumber"        # parentContinuityBag.parentPatentNumber
]

#  Advanced API paths (still supported)
fields = [
    "applicationMetaData.inventionTitle",
    "applicationMetaData.examinerNameText",
    "parentContinuityBag.parentApplicationNumberText"
]

支持的字段映射

*完整地图，提供30多个字段 src/patent_filewrapper_mcp/api/helpers.py*

💻 使用示例和集成工作流

有关综合使用示例，包括：

• 便利性参数搜索 （艺术单位、审查员、申请人、日期）
• 高级文档过滤 （文档代码、方向类别、上下文简化）
• 跨MCP集成工作流程 （PFW+PTAB+FPD+松果）
• 完整的生命周期尽职调查 示例
• 诉讼研究模式
• 艺术单元质量评估
• 成本优化策略

查看详情 用法_示例.md 文档。

🔧 现场定制

MCP服务器通过YAML配置支持用户自定义字段集，以实现最佳的上下文缩减。您可以在不更改任何代码的情况下修改字段集！

配置文件： field_configs.yaml （以项目根为单位）

有关完整的定制指导，包括渐进式工作流策略、令牌优化和高级字段选择模式，请参阅 定制.md.

🔗 跨MCP集成

该MCP旨在与其他三个USPTO MCP无缝协作，以进行全面的专利生命周期分析：

相关USPTO MCP服务器

集成概述

这 专利文件包装器（PFW）MCP 作为专利研究的基础，提供起诉历史和文件访问。当与其他MCP结合使用时，它能够：

• PFW+PTAB：将PTAB程序与起诉历史进行交叉引用，以进行诉讼研究
• PFW+丰富的引用：基于人工智能的审查员引文分析和现有技术研究模式
• PFW+FPD：了解起诉期间的请愿历史和程序问题
• PFW+FPD+PTAB：完成从申请到授权后挑战的专利生命周期跟踪
• PFW+松果（助理或RAG）：在提取昂贵的起诉文件之前，研究MPEP指南

关键集成模式

交叉引用字段：

• applicationNumberText -将PTAB程序与PFW起诉联系起来的主要关键
• groupArtUnitNumber -所有MCP的艺术单元分析
• examinerNameText -考官行为模式和质量评估
• firstApplicantName / inventorBag -跨MCP的派对匹配

渐进式工作流程：

1. 发现 （PFW）：使用方便参数的最小搜索查找申请/专利
2. 引文分析 （丰富引用）：分析审查员引用模式和现有技术参考文献
3. 请愿书检查 （FPD）：审查起诉程序历史
4. 挑战评估 （PTAB）：检查拨款后的挑战
5. 知识研究 （松果）：研究MPEP指南（如有）（助理MCP： assistant_context /RAG MCP： semantic_search)
6. 文件分析 （PFW）：提取有针对性的起诉文件

有关详细的集成工作流、交叉引用示例和完整用例，请参阅 用法_示例.md.

📈性能比较

🧪测试

快速测试

# Basic functionality test (most essential)
uv run python tests/test_fields_fix.py

预期产量：

✅ ALL TESTS PASSED - Fields fix is working correctly!

有关包括代理服务器、文档提取、工具反射和API密钥设置说明在内的全面测试，请参阅 测试指导.

📁项目结构

uspto_pfw_mcp/
├── field_configs.yaml             # Root-level field customization
├── launcher.py                     # Entry point launcher
├── .security/                      # Security scanning components
│   ├── patent_prompt_injection_detector.py # Enhanced prompt injection detection
│   ├── check_prompt_injections.py # Standalone scanning script with baseline support
│   └── .prompt_injections.baseline # Baseline tracking for prompt injection findings
├── src/
│   └── patent_filewrapper_mcp/
│       ├── main.py                 # MCP server with 11+ tools
│       ├── __init__.py
│       ├── __main__.py
│       ├── exceptions.py
│       ├── secure_storage.py       # Windows DPAPI secure storage
│       ├── shared_secure_storage.py
│       ├── config/
│       │   ├── field_manager.py   # Configuration management
│       │   ├── tool_reflections.py # Migration notices (guidance moved to pfw_get_guidance)
│       │   └── log_config.py      # 🆕 Logging configuration with file-based rotation
│       ├── api/
│       │   ├── enhanced_client.py  # Enhanced client with field mapping
│       │   ├── field_constants.py # Field constant definitions
│       │   ├── helpers.py         # Field mapping & utilities
│       │   └── ppubs/             # Patent publication client
│       ├── models/
│       │   ├── constants.py       # System constants
│       │   └── search_params.py   # Search parameter models
│       ├── prompts/               # AI prompt templates
│       │   ├── patent_search.py
│       │   ├── patent_explanation_for_attorneys.py
│       │   ├── patent_invalidity_analysis_defense_Pinecone_PTAB_FPD_Citations.py
│       │   ├── litigation_research_setup_PTAB_FPD.py
│       │   ├── technology_landscape_mapping_PTAB.py
│       │   ├── art_unit_quality_assessment_FPD.py
│       │   ├── complete_patent_package_retrieval_PTAB_FPD.py
│       │   ├── document_filtering_assistant.py
│       │   ├── inventor_portfolio_analysis.py
│       │   ├── examiner_behavior_intelligence_CITATION.py
│       │   └── prior_art_analysis_CITATION.py
│       ├── proxy/
│       │   ├── server.py          # HTTP proxy for secure downloads
│       │   ├── rate_limiter.py    # USPTO rate limiting compliance
│       │   ├── secure_link_cache.py
│       │   ├── models.py
│       │   ├── fpd_document_store.py
│       │   └── ptab_document_store.py
│       ├── reflections/           # Reflection system (legacy)
│       │   ├── base_reflection.py
│       │   ├── pfw_reflections.py
│       │   └── reflection_manager.py
│       ├── services/
│       │   └── ocr_service.py     # OCR quality detection and processing
│       ├── shared/
│       │   ├── internal_auth.py   # Shared authentication
│       │   ├── log_sanitizer.py   # 🆕 Automatic sensitive data sanitization
│       │   └── safe_logger.py     # 🆕 Safe logger with auto-sanitization
│       ├── util/
│       │   ├── database.py
│       │   ├── dpapi_utils.py
│       │   ├── error_handlers.py
│       │   ├── identifier_normalization.py
│       │   ├── input_processing.py
│       │   ├── logging.py         # Enhanced logging utilities
│       │   ├── package_manager.py
│       │   └── security_logger.py
│       └── json/
│           └── search_query.json  # Sample JSON structures
├── deploy/
│   ├── linux_setup.sh            # Linux deployment script
│   ├── deploy_linux.sh
│   ├── windows_setup.ps1         # PowerShell deployment script
│   ├── manage_api_keys.ps1       # API key management utilities
│   ├── Validation-Helpers.psm1   # PowerShell validation module
│   └── validation_helpers.sh     # Bash validation helpers
├── tests/                         # Current test files
│   ├── README.md                  # Testing documentation
│   ├── test_fields_fix.py        # Core functionality test
│   ├── test_proxy_simple.py      # Proxy server test
│   ├── test_mcp_server.py        # MCP server startup test
│   ├── test_quality_detection.py # OCR quality detection test
│   ├── test_unified_key_management.py # Secure key storage test
│   ├── test_download.py
│   ├── test_enhanced_filename.py
│   ├── test_fpd_integration.py
│   ├── test_granted_patent_documents_download.py
│   ├── test_include_fields.py
│   ├── test_mistral_key_logic.py
│   ├── test_optional_mistral.py
│   ├── test_placeholder_detection.py
│   ├── test_ptab_integration.py
│   ├── test_resilience_features.py
│   ├── test_tool_reflections.py
│   ├── simple_test.py
│   └── test_utils.py
├── reference/
│   ├── README.md
│   ├── Document_Descriptions_List.csv
│   └── PatentFileWrapper_swagger.yaml
├── logs/
│   └── security.log              # Security logging output
├── pyproject.toml                 # Package configuration
├── uv.lock                        # uv lockfile
├── README.md                      # This file
├── INSTALL.md                     # Comprehensive installation guide
├── USAGE_EXAMPLES.md             # Function examples and workflows
├── CUSTOMIZATION.md              # Field configuration and optimization guide
├── PROMPTS.md                    # Prompt templates documentation
├── SECURITY_GUIDELINES.md       # Security best practices
└── SECURITY_SCANNING.md         # Automated secret detection guide

🔍故障排除

常见问题

API关键问题

• 对于Claude Desktop： 配置文件中的API密钥足够
• 对于测试脚本： 必须设置环境变量

正在设置USPTO API密钥：

• Windows命令提示符： set USPTO_API_KEY=your_key
• Windows PowerShell： $env:USPTO_API_KEY="your_key"
• Linux/macOS： export USPTO_API_KEY=your_key

设置Mistral API密钥（用于OCR）：

• Windows命令提示符： set MISTRAL_API_KEY=your_key
• Windows PowerShell： $env:MISTRAL_API_KEY="your_key"
• Linux/macOS： export MISTRAL_API_KEY=your_key

uv与pip问题

• 紫外线优势： 更好的依赖关系解决方案，更快的安装
• 混合安装： 两者都可以使用 uv sync 和 pip install -e .
• 测试： 使用 uv run uv管理项目的前缀

不返回数据的字段

• 原因： 字段名不在映射中
• 解决方案： 添加到 field_mapping 在 helpers.py 或使用完整的API字段名称

身份验证错误

• 原因： API密钥丢失或无效
• 解决方案： 验证 USPTO_API_KEY 环境变量或Claude Desktop配置

MCP服务器无法启动

• 原因： 缺少依赖关系或路径不正确
• 解决方案： 重新运行安装脚本，重新启动所有PowerShell窗口，重新启动Claude Desktop（或其他MCP客户端）并验证配置
• 如果问题仍然存在： 重置MCP安装（请参阅下面的“重置MCP安装”）

虚拟环境问题（Windows安装程序）

• 症状： 期间出现“无pyvenv.cfg文件”错误 windows_setup.ps1
• 原因： 克劳德桌面锁 .venv 运行时文件，阻止正确创建虚拟环境
• 解决方案：

1. 在运行安装脚本之前完全关闭Claude Desktop 1. 移除 .venv 文件夹： Remove-Item ./.venv -Force -Recurse -ErrorAction SilentlyContinue 1. 跑 .\deploy\windows_setup.ps1 再次

重置MCP安装

如果您需要完全重置MCP安装以再次运行Windows快速安装程序：

# Navigate to the project directory
cd C:\Users\YOUR_USERNAME\uspto_pfw_mcp

# Remove Python cache directories
Get-ChildItem -Path ./src -Directory -Recurse -Force | Where-Object { $_.Name -eq '__pycache__' } | Remove-Item -Recurse -Force

# Remove virtual environment
if (Test-Path ".venv") {
    Remove-Item ./.venv -Force -Recurse -ErrorAction SilentlyContinue
}

# Remove database files
Remove-Item ./proxy_link_cache.db -Force -ErrorAction SilentlyContinue
Remove-Item ./fpd_documents.db -Force -ErrorAction SilentlyContinue
Remove-Item ./ptab_documents.db -Force -ErrorAction SilentlyContinue

# Now you can run the setup script again
.\deploy\windows_setup.ps1

Linux/macOS重置：

# Navigate to the project directory
cd ~/uspto_pfw_mcp

# Remove Python cache directories
find ./src -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true

# Remove virtual environment and database files
rm -rf .venv
rm -f proxy_link_cache.db fpd_documents.db ptab_documents.db

# Run setup script again
./deploy/linux_setup.sh

获取帮助

1. 检查测试脚本中的工作示例
2. 查看中的字段映射 src/patent_filewrapper_mcp/api/helpers.py
3. 验证您的Claude Desktop配置是否与INSTALL.md中提供的模板匹配

🛡️ 安全和生产准备

增强的错误处理

• 使用指数回退重试逻辑 -瞬时故障的自动重试（3次尝试，延迟1秒、2秒、4秒）
• 智能重试策略 -不重试身份验证错误或客户端错误（4xx）
• 结构化日志 -请求ID跟踪以更好地调试和监控
• 生产级弹性 -妥善处理超时、网络问题和API速率限制

安全特性

• 环境变量API键 -代码库中任何地方都没有硬编码的凭据
• 安全测试模式 -测试文件使用带有回退的环境变量
• 综合.gitignore -防止意外提交凭据
• 安全指南 -安全开发实践的完整文档
• 自动秘密扫描 -CI/CD和预提交挂钩可防止API密钥泄漏（检测secrets）
• 检测到20+种秘密类型 -AWS密钥、GitHub令牌、JWT、私钥、API密钥等
• 基线管理 -追踪已知占位符，同时捕捉真正的秘密
• 🆕 带自动消毒功能的SafeLogger -在所有日志消息中自动屏蔽API密钥、JWT、密码、IP、电子邮件（CWE-532）
• 🆕 基于文件的轮换日志记录 -持续审计跟踪，10MB轮换，5/10备份（CWE-778）
• 🆕 快速注射基线系统 -跟踪已知发现，仅用SHA256指纹标记新模式
• 快速注射检测 -70+模式检测系统可抵御AI特定攻击
• 专利特定安全 -自定义模式检测USPTO API绕过和数据提取尝试
• 增强过滤 -最大限度地减少误报，同时保持全面的威胁覆盖

请求跟踪和调试

所有API请求都包含用于关联的唯一请求ID（8个字符的UUID）：

[a1b2c3d4] Starting GET request to applications/search
[a1b2c3d4] Request successful on attempt 1

文档

• SECURITY_GUIDELINES.md -全面的安全最佳实践
• SECURITY_SCANNING.md -自动秘密检测和预防指南
• tests/README.md -API密钥设置的完整测试指南
• 带有请求ID的增强错误消息，以获得更好的支持

📝贡献

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 确保所有测试通过
5. 提交拉取请求

📄许可证

MIT许可证

⚠️ 免责声明

本软件按“原样”提供，不提供任何形式的保修。

独立项目通知：这是一个独立的个人项目，不隶属于美国专利商标局（USPTO），也不受其认可或赞助。

作者不作任何明示或暗示的陈述或保证，包括但不限于：

• 准确性和人工智能生成的内容：不保证数据的准确性、完整性或适用于任何目的。特别提醒用户，人工智能（AI）组件生成或辅助的输出，包括但不限于文本、数据或分析，可能不准确、不完整、虚构，或代表AI模型的“幻觉”（虚构）。
• 可用性：USPTO API和Mistral API依赖关系可能会导致服务中断。
• 法律合规用户全权负责确保其对本软件的使用，以及基于其输出所做的任何提交或操作，严格遵守所有适用的法律、法规和政策，包括但不限于：

- 最新的 美国专利商标局关于人工智能工具在实践中的使用指南 （美国专利商标局指南）。 - 美国专利商标局的坦诚和诚信义务（例如，《美国联邦法规》第37篇第1.56、11.303节），其中包括披露重要信息和纠正错误的义务。 - 美国专利商标局的签名要求（例如，37 CFR 1.4（d）、2.193（c）、11.18），证明人工审查和合理询问。 - 所有关于发明权的规则（例如，每项要求保护的发明必须至少有一名人类发明人）。

• 法律咨询：此工具仅提供数据访问和处理，不提供法律顾问。所有结果必须由合格的法律专业人员独立验证、批判性分析和专业判断。
• 商业用途：用户必须验证USPTO和Mistral的商业应用条款。
• 保密和数据安全：作者对用户输入软件人工智能组件或传输给第三方人工智能服务（如Mistral API）的任何数据（包括客户敏感或技术信息）的机密性或安全性不作任何陈述。用户有责任理解和接受任何集成的第三方人工智能服务的隐私政策、数据保留做法和安全措施。
• 外国备案许可证和出口管制用户全权负责确保通过本软件的人工智能组件输入或处理任何数据，特别是技术信息，不违反美国外国申请许可证要求（例如，35 U.s.C.184、37 CFR第5部分）或出口管制法规（例如，EAR、ITAR）。这包括如果外国人访问此类数据或人工智能服务器位于美国境外，则应意识到潜在的“视为出口”。

责任限制： 在任何情况下，作者均不对因使用本软件而产生的任何直接、间接、附带、特殊或后果性损害承担责任，即使已被告知此类损害的可能性。

用户责任：您对USPTO之前提交的所有文件和采取的行动的完整性和合规性负全部责任。

• 独立验证：在依赖、采取行动或提交给美国专利商标局或任何其他实体之前，本软件中人工智能生成或协助的所有输出、分析和内容都必须经过彻底审查、独立验证和纠正。这包括事实陈述、法律争论、引用、证据支持和技术披露。
• 诚实守信的义务：您必须遵守与美国专利商标局坦诚相待的义务，包括披露任何重要信息（例如，关于发明或错误），并及时纠正记录中的任何不准确之处。
• 签名与认证：根据《美国联邦法规》第37篇第11.18（b）条的要求，您必须亲自在提交给美国专利商标局的任何信件上签名或插入您的签名，证明您对其内容的个人审查和合理查询。人工智能工具不能签署文件，也不能执行所需的人工查询。
• 机密信息：未经客户完全同意并清楚了解底层人工智能提供商的数据处理实践，不得将机密、专有或客户敏感信息输入本软件的人工智能组件。您有责任防止无意或未经授权的披露。
• 出口管制：在使用此工具处理敏感技术数据时，请注意并遵守所有外国备案许可证和出口管制规定。
• 服务合规性：确保遵守所有USPTO（例如，USPTO网站的使用条款、USPTO.gov帐户政策、对自动数据挖掘的限制）和Mistral服务条款。人工智能工具无法获取USPTO.gov帐户。
• 安全：维护API凭证和客户端信息的安全处理。
• 测试：在生产使用前进行彻底测试。
• 专业判断：此工具是对您自己的专业判断和专业知识的补充，而不是替代。

使用本软件即表示您承认已阅读本免责声明，并同意自行承担使用该软件的风险，对所有结果承担全部责任，并遵守相关的法律和道德义务。

法律专业人士须知： 虽然该工具提供了对法律实践中常用的专利研究工具的访问，但它只是一个数据检索和人工智能辅助处理系统。所有结果都需要独立验证、关键的专业分析，不能替代合格的法律顾问或美国专利商标局人工智能使用指南中概述的个人专业判断和职责的行使。

🔗相关链接

• 美国专利商标局开放数据门户
• USPTO丰富引用API v3
• 美国专利局专利审判和上诉委员会（PTAB）API v2
• 模型上下文协议
• 克劳德
• uv包管理器
• Mistral OCR

💝 支持这个项目

如果您发现此USPTO专利文件包装器MCP服务器有用，请考虑支持开发！这个项目是在我个人时间里开发的，耗时数小时，为专利界提供了一个全面的、可生产的工具。


您的支持有助于为专利界的每个人维护和改进这个开源工具。非常感谢。

致谢

• 美国专利商标局 用于提供专利文件包装器API
• 模型上下文协议 对于MCP规范
• 克劳德代码 在整个项目中提供卓越的开发协助、架构指导、文档创建、PowerShell自动化、测试组织和全面的代码开发
• 克劳德桌面版 获取额外的开发支持和测试协助

______________________________________________________________________

问题？ 看 安装.md 获取完整的跨平台安装指南，或查看工作示例的测试脚本。