USPTO Patent MCP Server

USPTO 专利与商标 MCP 服务

一个 MCP 服务（Python SDK 2.x，MCPServer），可通过多个 API 访问美国专利商标局（USPTO）的专利和商标数据，包括 Patent Public Search API、Open Data Portal (ODP) API、PTAB API v3、TSDR 商标状态 API，以及 USPTO 商标搜索。借助此服务，Claude Desktop 可以从 USPTO API 获取数据、搜索 PTAB 程序和决定、查询专利审查历史、执行商标清查搜索、跟踪商标状态等：

如需了解 MCP 服务的入门介绍，请参阅模型上下文协议简介。

特别感谢 Parker Hancock，他是出色的 Patent Client 项目的作者，为理解通过 Public Search API 获取数据所需的一系列请求和响应开辟了道路。

功能

此服务通过六个实时 USPTO 数据源提供 42 个工具（另外 23 个工具对应的 API 已被 USPTO 停用，相关代码仍保留在 ENABLE_LEGACY_TOOLS 后面）：

1. 专利搜索 - 通过 PPUBS 对已授权专利和已公开申请进行全文搜索
2. 全文文档 - 按编号获取专利文本，也可仅获取权利要求、摘要或首页，以节省上下文
3. PDF 下载 - 将专利下载为 PDF 文件（Claude Desktop 目前不支持将其用作客户端）
4. 审查历史 - 通过 ODP 获取交易记录、按类型筛选的案卷文档列表（审查意见、答复、授权通知），以及纯文本或 PDF 格式的文档
5. 审查意见搜索 - 搜索 1,990 万份审查意见（自 2007 年起），可按审查员用语、驳回法条、技术中心和日期搜索，并按文档代码和法条统计数量
6. 权利要求级别的驳回与引证 - 查看每份审查意见驳回、异议或允许了哪些权利要求，以及依据的法条，并查看 Alice/Mayo/Myriad/Bilski 标记（自 2012 年起）；还可查看每份审查意见引用的文献，并通过反向搜索找到审查员引用了指定专利的所有申请
7. 请愿决定 - 按文本、类型、结果和专利局搜索 110 万份专利请愿决定（恢复、重新生效、加快审查、监督审查）
8. 专利家族数据 - 连续申请信息、外国优先权和相关申请
9. 批量数据集 - 搜索和访问 USPTO 批量数据产品，包括 PatentsView 消歧数据
10. 向前引证 - 查找引用某项专利的后续专利
11. 商标搜索 - 按商标文本、所有人、商品/服务和类别对美国联邦商标进行全文搜索（清查/排除式搜索）
12. 商标状态与文档 - 通过 TSDR 获取权威的实时状态、审查文档和商标图像
13. 商标转让记录 - 获取自 1955 年至今备案的所有权转让记录（无需 API 密钥）

此服务可通过 stdio 在本地为 Claude Desktop 和 Claude Code 运行，也可通过 HTTP 作为共享的无状态服务运行 — 参见通过 HTTP 远程托管。

关于不可用 API 的说明： PatentsView API（search.patentsview.org）于 2026 年 3 月 20 日停用，其数据已迁移至 ODP 批量数据集。Office Action 和 Enriched Citation API（developer.uspto.gov）于 2026 年初停用；此后，审查意见搜索、驳回和引证数据已在 ODP 上恢复（odp_search_office_actions、get_office_action_rejections、get_office_action_citations）。USPTO 开放数据门户不提供 Patent Litigation API；诉讼数据可通过批量下载获取。受影响的 23 个工具仍保留在代码中，但默认不注册，因为它们的架构会让每个客户端在每个会话中多消耗约 6k 个令牌，而且这些工具只会失败；设置 ENABLE_LEGACY_TOOLS=true 可注册这些工具，每个工具都会返回指向可用工具的替代方案说明。

API 来源

来源	描述	是否需要身份验证	状态
ppubs.uspto.gov	全文文档、PDF 下载、高级搜索（每日更新）	否	活跃
api.uspto.gov (ODP)	元数据、连续性、交易、转让、审查历史	是（ODP API Key）	活跃
PTAB Trial API	IPR/PGR/CBM 程序、决定、上诉	是（ODP API Key）	活跃（ODP v3.0）
tsdrapi.uspto.gov (TSDR)	商标状态、审查文档、商标图像	是（TSDR API Key — 与 ODP 分开）	活跃
tmsearch.uspto.gov	全文商标搜索（TESS 替代服务背后的内部 API）	否	活跃（非官方）
assignmentcenter.uspto.gov	商标所有权转让记录（1955 年至今）	否	活跃
Patent Litigation API	74,000 多起地区法院专利案件	不适用	ODP 不提供（问题 #16）
PatentsView API	消歧后的发明人/受让人数据、高级搜索	不适用	2026 年 3 月关闭
ODP Office Action Search	2007 年以来的审查意见：文本搜索、法规、技术组（文本最多返回 500 个字符）	是（ODP API Key）	活跃（2026-10）
ODP Petition Decisions	1991 年以来的专利申请请愿决定	是（ODP API Key）	活跃（2026-10）
ODP Office Action Rejections & Citations	按权利要求列出的驳回（2012 年以来），以及每份审查意见中引用的参考资料	是（ODP API Key）	活跃（2026-10）
Office Action APIs (developer.uspto.gov)	审查意见文本和搜索	不适用	2026 年初停用

先决条件

• Python 3.10-3.13（推荐使用 3.12）；此服务基于 MCP Python SDK 2.x（mcp>=2,<3）构建
• Claude Desktop（用于集成）。其他模型和 MCP 客户端尚未经过测试。
• 用于 Python 版本和依赖项管理的 UV

如果你是 Python 开发者，但还不熟悉 uv，那就有福了。它比单独使用 Python 版本管理器（如 pyenv），再用 venv 和 pip 设置、激活和维护虚拟环境更快、更简单。

如果你还没有安装 uv：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装

从 PyPI 安装（无需克隆）

uvx 会按需下载并运行已发布的包。在 claude_desktop_config.json 中将其配置为 Claude Desktop 的服务，并通过环境变量传入 API 密钥：

{
  "mcpServers": {
    "patents": {
      "command": "uvx",
      "args": ["patent-mcp-server"],
      "env": {
        "USPTO_API_KEY": "your_odp_key",
        "TSDR_API_KEY": "your_tsdr_key"
      }
    }
  }
}

或者在 Claude Code 中：

claude mcp add patents -e USPTO_API_KEY=your_odp_key -e TSDR_API_KEY=your_tsdr_key -- uvx patent-mcp-server

这些密钥是可选的（参见API 密钥设置）；PPUBS 专利工具、商标搜索和转让搜索无需任何密钥即可使用。.env 文件会从工作目录读取；对于 uvx，工作目录就是客户端启动服务的位置，因此请像上面那样通过 env 传入密钥。

从源代码安装

1. 克隆此代码库：

   git clone https://github.com/riemannzeta/patent_mcp_server
   cd patent_mcp_server
   

2. 使用 uv 安装依赖项：

   uv sync
   

3. 验证安装：

   uv run patent-mcp-server
   

   应输出：

   INFO     Starting USPTO Patent MCP server with stdio transport
   

API 密钥设置

USPTO ODP API Key（大多数工具都需要）

要使用 api.uspto.gov 工具（ODP、PTAB），你需要一个 Open Data Portal API 密钥。没有该密钥时，这些端点会返回 403 Forbidden。ODP 不提供 Patent Litigation API，因此该 API 无需密钥。

1. 在 data.uspto.gov 创建 USPTO.gov 账户（需要通过 ID.me 验证）

2. 登录后，在网站导航中打开 “My ODP” 获取 API 密钥

3. 详细说明请参阅 Getting Started 指南

4. 完成 data.uspto.gov 客户资料（职位、组织、预期用途）。如果资料不完整，ODP 会停用密钥；密钥停止工作并返回 401/403 时，通常就是这个原因。

5. 在 patent_mcp_server 目录中创建 .env 文件：

   USPTO_API_KEY=your_actual_key_here
   

   注意：PPUBS 专利工具、商标搜索（tm_* 搜索工具）和商标转让搜索无需任何 API 密钥即可使用。

TSDR API 密钥（商标状态／文档工具）

TSDR 工具（tsdr_*）需要使用 TSDR 专用 API 密钥，并通过 USPTO-API-KEY 标头发送。ODP 密钥无法用于 TSDR——它可以通过网关的身份验证检查，但之后每个请求都会失败，并返回 BACKEND RESPONSE STATUS: 404。

1. 使用免费的 MyUSPTO 帐户登录 USPTO API Key Manager
2. 选择 TSDR API 产品，然后点击“Request API key”（密钥会通过电子邮件发送，并存储在你的帐户下）
3. 将其添加到你的 .env 文件中：

   TSDR_API_KEY=your_tsdr_key_here
   

TSDR 速率限制（高峰时段为美国东部时间上午 5 点至晚上 10 点）：常规请求每分钟 60 次，PDF 文档包请求每分钟 4 次（非高峰时段分别为 120 次／12 次）。下载文档包前，请先使用 tsdr_list_trademark_documents（仅获取元数据，不受 PDF 请求的同类速率限制）。

商标搜索与 AWS WAF（无需密钥）

tm_search_trademarks / tm_get_trademark 使用 tmsearch.uspto.gov 背后的内部 API，该 API 位于 AWS WAF 后面。目前它可以响应普通请求，但如果 USPTO 收紧 WAF 限制，导致搜索开始返回 403／202 错误，请从浏览器访问 tmsearch.uspto.gov 时的会话中复制 aws-waf-token Cookie（有效期约 4 天），并设置：

TMSEARCH_WAF_TOKEN=your_cookie_value_here

配置

可以使用 .env 文件中的环境变量配置该服务。所有设置均为可选，并且有合理的默认值：

# API Keys
USPTO_API_KEY=your_key_here      # ODP/PTAB tools
TSDR_API_KEY=your_tsdr_key_here  # TSDR trademark tools (separate key — see above)
TMSEARCH_WAF_TOKEN=...           # Optional - only if trademark search hits the WAF

# Tool registration
ENABLE_LEGACY_TOOLS=false  # Also register the 23 tools for shut-down APIs (they return API_UNAVAILABLE)

# Logging
LOG_LEVEL=INFO  # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL

# MCP Transport (see "Remote hosting over HTTP" below)
MCP_TRANSPORT=stdio    # stdio (default) or streamable-http
MCP_HOST=127.0.0.1     # Bind address when serving over HTTP
MCP_PORT=8000          # Port when serving over HTTP
MCP_PATH=/mcp          # URL path of the MCP endpoint
MCP_STATELESS=true     # Keep no per-client state between HTTP requests
MCP_JSON_RESPONSE=false # Reply with plain JSON instead of an SSE stream

# HTTP Settings
REQUEST_TIMEOUT=30.0  # Request timeout in seconds
MAX_RETRIES=3         # Maximum number of retry attempts
RETRY_MIN_WAIT=2      # Minimum wait time between retries (seconds)
RETRY_MAX_WAIT=10     # Maximum wait time between retries (seconds)

# Session Management
SESSION_EXPIRY_MINUTES=30  # How long to cache ppubs sessions
ENABLE_CACHING=true        # Enable/disable session caching

# API Endpoints (usually don't need to change)
PPUBS_BASE_URL=https://ppubs.uspto.gov
API_BASE_URL=https://api.uspto.gov          # ODP API endpoint (NOT data.uspto.gov)
TSDR_BASE_URL=https://tsdrapi.uspto.gov/ts/cd
TMSEARCH_BASE_URL=https://tmsearch.uspto.gov
TM_ASSIGNMENT_BASE_URL=https://assignmentcenter.uspto.gov
CPC_SCHEME_BASE_URL=https://www.uspto.gov/web/patents/classification/cpc/html

Claude Desktop 配置

如需将此 MCP 服务与 Claude Desktop 集成：

1. 更新 Claude Desktop 配置文件（claude_desktop_config.json）：

   {
     "mcpServers": {
       "patents": {
         "command": "uv",
         "args": [
           "--directory",
           "/Users/username/patent_mcp_server",
           "run",
           "patent-mcp-server"
         ]
       }
     }
   }
   

   在 Mac 上，你可以打开 Claude Desktop 应用，打开“设置”（从 Claude 菜单中选择，或在键盘上按 Command + '），点击侧边栏中的“Developer”，然后点击“Edit Config”，找到 claude_desktop_config.json。

2. 将 /Users/username/patent_mcp_server 替换为你的 patent_mcp_server 目录的实际路径。

与 Claude Desktop 集成后，该服务会在需要时自动启动，无需单独运行。

Claude Code 配置

如需将此 MCP 服务与特定项目的 Claude Code 集成，请在项目根目录中运行：

claude mcp add-json patents '{"command": "uv", "args": ["--directory", "/path/to/patent_mcp_server", "run", "patent-mcp-server"]}'

如果 Claude Code 已在运行，你需要输入 /exit 并重启。然后输入 /mcp，确认配置无误。

通过 HTTP 远程托管

该服务默认使用 stdio，这是上文 Claude Desktop 和 Claude Code 配置启动服务时使用的方式。你也可以通过 HTTP 提供 MCP 端点，这样一个部署即可供整个团队使用，而不必让每个人都运行自己的副本并使用各自的 API 密钥：

patent-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

随后，端点位于 http://<host>:8000/mcp。将 MCP 客户端指向 该 URL——在 Claude Code 中：

claude mcp add --transport http patents http://your-host:8000/mcp

**此端点本身没有身份验证，并且会保存你的 USPTO 和 TSDR API 密钥。**任何能够访问该端点的人都可以消耗你的 USPTO 速率 限制。请绑定到 127.0.0.1（默认值），并在前面配置一个需要身份验证的反向 代理，或以其他方式限制网络访问。当服务绑定到回环地址以外的地址时，启动时会记录 警告。

默认情况下，请求是无状态的：服务不会在请求之间保留各客户端的状态， 因此可以在负载均衡器后运行多个副本，而无需会话亲和性。 每个工作进程都会维护自己的 USPTO Public Search 会话，并按需建立会话，过期时刷新。

标志	默认值	用途
--transport	stdio	stdio 或 streamable-http
--host	127.0.0.1	HTTP 绑定地址
--port	8000	HTTP 端口
--path	/mcp	MCP 端点的 URL 路径
--stateful / --no-stateful	关闭	保留各客户端的会话状态；扩展时需要会话亲和性
--json-response / --no-json-response	关闭	使用普通 JSON 而非 SSE 流进行响应

每个标志都有对应的环境变量（见上文“配置”）； 两者同时设置时，以命令行参数为准。

可用工具

实用工具

工具	描述
check_api_status	检查所有 USPTO API 的状态
get_cpc_info	查询任意层级（从部到小组）的 CPC 标题、层级结构和子项；小组信息实时来自 USPTO 的分类方案页面
get_status_code	查询 USPTO 状态代码的含义
get_trademark_class_info	查询尼斯分类／国际商标分类（1-45）
get_trademark_status_code	查询 USPTO 商标状态代码的含义

专利公开检索（ppubs.uspto.gov）

工具	描述
ppubs_search_patents	检索已授权专利（全文，每日更新）
ppubs_search_applications	检索已公开的专利申请
ppubs_get_full_document	按 GUID 获取文档；sections 可选择书目信息、摘要、权利要求或说明书
ppubs_get_patent_by_number	按编号获取专利文本（"US 10,000,000 B2"、"D845123" 和 "RE49123" 均可），并支持相同的 sections 选项
ppubs_get_citing_patents	前向引用：引用某项专利的后续授权专利
ppubs_download_patent_pdf	将专利下载为 PDF

开放数据门户（api.uspto.gov）

工具	描述
odp_get_application	获取申请的基本数据
odp_search_applications	使用筛选条件搜索申请
odp_get_application_metadata	获取完整元数据
odp_get_continuity	获取专利族／连续申请数据
odp_get_assignment	获取所有权／转让记录
odp_get_adjustment	获取专利期限调整数据
odp_get_attorney	获取备案律师／代理人信息
odp_get_foreign_priority	获取外国优先权主张
odp_get_transactions	获取审查程序交易历史
odp_get_documents	列出案卷文件，并按文件代码（CTNF、CTFR、NOA、REM、CLM、892……）和方向筛选
odp_download_document	将一份案卷文件读取为纯文本（format="text"：审查意见通知书、意见陈述、带有修订标记的权利要求）或 PDF
odp_search_office_actions	按文本、文件代码、驳回法条、技术中心和日期搜索各申请的审查意见通知书；预览内容最多截取 500 个字符，因此请使用 odp_download_document(format="text") 读取搜索结果
get_office_action_rejections	按法条（101/102/103/112/DP）列出每份审查意见通知书中被驳回、提出异议或获准的权利要求，并标记 Alice/Mayo/Myriad/Bilski；可按申请、专利、日期、技术中心或判例筛选
get_office_action_citations	列出各审查意见通知书引用的参考文献及其 102/103 条款；cited_reference 可查找审查员引用了指定专利或公开文件的所有申请
odp_search_petition_decisions	按文本、请愿类型、结果、裁决部门和日期搜索请愿裁决，并统计各结果的数量
odp_search_datasets	搜索批量数据产品
odp_get_dataset	获取数据集产品详情

PTAB 审判 API（api.uspto.gov ODP v3.0）

工具	描述
ptab_search_proceedings	按专利编号、当事方、状态搜索 IPR/PGR/CBM 程序
ptab_get_proceeding	按编号获取特定程序的详情
ptab_get_documents	列出程序中提交的文件
ptab_search_decisions	搜索 PTAB 裁决
ptab_get_decision	按审判编号获取特定裁决
ptab_search_appeals	搜索单方复审上诉
ptab_get_appeal	获取特定上诉的详情

TSDR - 商标状态与文件检索（tsdrapi.uspto.gov）

工具	描述
tsdr_get_trademark_status	根据序列号或注册号获取权威的实时状态
tsdr_list_trademark_documents	列出审查文件元数据（无速率限制，不提供下载）
tsdr_download_trademark_documents	将审查文件包下载为 PDF（速率限制为每分钟 4 次）
tsdr_get_trademark_image	获取商标图像（图样）的 base64 编码

商标搜索与转让

工具	描述
tm_search_trademarks	按商标文字、所有人、商品/服务、类别、有效/失效状态进行全文搜索
tm_get_trademark	根据序列号获取商标的搜索索引记录
tm_search_assignments	搜索已记录的所有权转让，范围为 1955 年至今（Assignment Center，无需密钥）

注意： tm_search_trademarks 和 tm_get_trademark 使用 tmsearch.uspto.gov（TESS 的替代服务）背后未公开的内部 API——与 PPUBS 专利搜索 API 的情况相同。USPTO 不提供用于商标全文搜索的官方 REST API。请求/响应协议已于 2026-06-10 通过实时验证，但如果 USPTO 更改内部 API，这些工具可能会在不另行通知的情况下失效。TTAB 程序（异议/撤销）没有 REST API；每日 TTAB XML 可作为批量数据集通过 odp_search_datasets 获取。

旧版工具（除非 ENABLE_LEGACY_TOOLS=true，否则隐藏）

以下 23 个工具用于 USPTO 已关闭的 API。它们保留在代码中，名称也保持不变，但服务器只有在 ENABLE_LEGACY_TOOLS=true 时才会注册这些工具，因为它们的架构会让每个客户端每个会话消耗约 6k 个令牌，且每次调用都会返回 API_UNAVAILABLE。每个响应都包含一个 workaround，指出可满足相应需求的在线工具。

专利诉讼 API（不可用——ODP 未提供，问题 #16）

全部 4 个诉讼工具均返回 API_UNAVAILABLE。ODP Swagger 目录中未列出专利诉讼 API。OCE 专利诉讼数据集（超过 74,000 起联邦地区法院案件）以批量下载形式发布，网址为 https://www.uspto.gov/ip-policy/economic-research/research-datasets/patent-litigation-docket-reports-data。

工具	替代方案
search_litigation	OCE 专利诉讼批量数据集
get_litigation_case	OCE 专利诉讼批量数据集
get_patent_litigation	OCE 专利诉讼批量数据集或 ppubs_search_patents
get_party_litigation	OCE 专利诉讼批量数据集

PatentsView API（不可用——已于 2026 年 3 月关闭）

全部 14 个 PatentsView 工具均返回 API_UNAVAILABLE 并提供替代方案说明。PatentsView 数据已迁移至 USPTO Open Data Portal，以可批量下载的数据集形式提供。专利搜索请使用 ppubs_search_patents；查找批量数据集请使用 odp_search_datasets。

工具	替代方案
patentsview_search_patents	ppubs_search_patents
patentsview_get_patent	ppubs_get_patent_by_number
patentsview_search_assignees	使用 "name".as. 查询的 ppubs_search_patents
patentsview_get_assignee	odp_search_datasets（批量数据）
patentsview_search_inventors	使用 "name".in. 查询的 ppubs_search_patents
patentsview_get_inventor	odp_search_datasets（批量数据）
patentsview_get_claims	ppubs_get_full_document
patentsview_get_description	ppubs_get_full_document
patentsview_search_by_cpc	使用 code.cpc. 查询的 ppubs_search_patents
patentsview_lookup_cpc	get_cpc_info
patentsview_search_attorneys	odp_get_attorney（按申请）
patentsview_get_attorney	odp_get_attorney（按申请）
patentsview_search_by_ipc	使用 IPC 查询的 ppubs_search_patents
patentsview_lookup_ipc	odp_search_datasets（批量数据）

Office Action API（不可用 — 于 2026 年初停用）

这 2 个 Office Action 工具会返回 API_UNAVAILABLE；odp_search_office_actions 可替代它们。get_office_action_citations 和 get_office_action_rejections 已在 ODP 上恢复运行（v1.8.0）。

工具	替代方案
get_office_action_text	odp_search_office_actions(app_num=...)，然后使用 odp_download_document
search_office_actions	odp_search_office_actions

Enriched Citation API（不可用 — 于 2026 年初停用）

全部 3 个 Enriched Citation 工具都会返回 API_UNAVAILABLE。前向引用可通过 ppubs_get_citing_patents 获取；专利引用的文献可在其首页查看（ppubs_get_patent_by_number(sections=["biblio"])）。

工具	替代方案
get_enriched_citations	ppubs_get_citing_patents（前向）和 ppubs_get_patent_by_number(sections=["biblio"])（后向）
search_citations	ppubs_get_citing_patents
get_citation_metrics	ppubs_get_citing_patents — total 为前向引用数

资源和提示词

该服务还提供 MCP 资源（可通过 @ 提及访问）：

• patents://cpc/{code} - 任意深度的 CPC 分类信息（分组来自 USPTO 的分类方案页面）
• patents://status-codes - USPTO 状态代码定义
• patents://sources - 数据源信息
• patents://search-syntax - 查询语法指南（专利和商标）
• trademarks://classes - Nice/国际商标类别（1-45）
• trademarks://status-codes - 商标状态代码定义

以及 MCP 提示词（工作流模板）。每个提示词都接受可选参数；无论你提供什么内容，都会放在步骤前的“主题”部分中，因此工作流会从你的具体信息开始，而不是询问这些信息：

• prior_art_search（invention、keywords、cpc_codes）- 全面的现有技术检索指南
• patent_validity_analysis（patent_number）- 专利有效性分析工作流
• competitor_portfolio_analysis（company、technology）- 竞争对手专利组合分析
• ptab_proceeding_research（patent_number、proceeding_number、party）- PTAB 程序调查指南
• freedom_to_operate（product、cpc_codes）- FTO 分析工作流
• patent_landscape（technology、cpc_codes）- 技术领域分布图绘制
• trademark_clearance_search（mark、goods_services、classes）- 商标注册排查/排除检索指南
• trademark_portfolio_review（owner）- 商标组合和期限审查
• trademark_status_monitoring（serial_numbers、mark）- 商标状态和冲突监控

测试

该项目包含全面的测试套件：

# Run unit tests (default - skips integration tests)
uv run pytest

# Run with verbose output
uv run pytest -v

# Run integration tests (requires network access)
uv run pytest -m integration

# Run all tests including integration
uv run pytest -m ""

# Run with coverage report
uv run pytest --cov=patent_mcp_server

集成测试会将每个工具的输出保存到 test/test_results/ 以供检查。该目录已被 git 忽略：每次运行都会重写其中的文件，且不会读取这些文件。测试所依赖的记录响应应放在 test/fixtures/ 中。

单元测试套件也会在每次向 main 推送代码以及每次拉取请求时，于 CI 中运行，覆盖 Python 3.10–3.13（.github/workflows/tests.yml）。集成测试在 CI 中仍会被取消选择，因此 CI 不需要 API 密钥。

开发

安装开发依赖：

uv sync --dev

发布到 PyPI

发布通过 Publish to PyPI GitHub Actions 工作流（.github/workflows/publish.yml）完成，该工作流使用 PyPI 可信发布 上传，因此无需在任何地方存储 API 令牌。版本更新（pyproject.toml 和 config.py 中的 USER_AGENT）合并到 main 后，从 Actions 选项卡运行该工作流。若 PyPI 上已有该版本，工作流会拒绝发布；随后会运行测试、构建并发布，同时创建 vX.Y.Z 标签和 GitHub 发布版本。

要在本地构建：

rm -rf dist/ && uv run python -m build

贡献

欢迎提交问题和 PR。贡献指南见 CONTRIBUTING.md，AI Agent 专属指南见 AGENTS.md。提交问题时，请使用 错误报告 或 功能请求模板——它们会提示填写工具调用、构造的请求 URL/正文以及原始 API 响应，通常这些信息就足以在一个回合内完成修复。

版本历史

v1.8.1（当前）

• 通过 GitHub Actions 发布：新的 Publish to PyPI 工作流通过 PyPI trusted publishing 上传，因此无需在任何地方存储 API 令牌；它还会为每个版本打标签并创建 GitHub 发布。这是该工作流发布的第一个版本
• 文档：旧版工具数量现在各处均为 23（两个 office action 数据集工具在 v1.8.0 上线后，有几处仍写着 25）

v1.8.0

• get_office_action_rejections 和 get_office_action_citations 已重新上线，现在使用 ODP 的权利要求级数据集（/api/v1/patent/oa/oa_{rejections,citations}/v2/records），而非已停用的 developer.uspto.gov 路径。驳回按 office action 分组：包括适用的法规（101、102、103、112、双重专利）、Alice、Mayo、Myriad 和 Bilski 标记，以及哪些权利要求被驳回、提出异议或获准。可按申请号或专利号、邮寄日期、日期范围、法规、判例法、文档代码和技术领域组筛选，因此 case_law="alice", art_unit="3689" 可以查找某个技术领域组的 Alice 驳回。引证会列出每份审查意见引用的各项参考文献及其适用条款；cited_reference 可反向查询
• 两个工具都会返回每份审查意见的 document_id，可供 odp_download_document(format="text") 读取
• 覆盖范围：自 2012 年起的驳回记录（9,300 万行），数据通常比邮寄日期滞后约一周
• 工具数量：默认注册 42 个（启用 ENABLE_LEGACY_TOOLS 后为 65 个）
• 于 2026-10-15 在线验证

v1.7.0

• 文件封装类文档全文：odp_download_document 接受 format="text"，可从 USPTO 随 PDF 一同发布的 XML 中提取文档正文并以纯文本返回，因此无需再将 office action（通常为 1 万至 2 万个字符）作为 base64 PDF 阅读。支持 office action、授权通知、复议决定，以及申请人提交的文档，例如意见陈述（REM）、权利要求（CLM）和 IDS 表格；修改后的权利要求保留其标记，如 ~~deleted~~ 和 ++inserted++。较长的文档会按段落分割为每页 2.4 万个字符（text_offset / next_offset）。没有 XML 的文档会返回 NO_TEXT_AVAILABLE，PDF 仍是默认格式
• 使用标准库解析；拒绝包含实体声明的 XML
• 于 2026-10-14 在线验证，覆盖 2011 至 2026 年的 CTNF、CTFR、NOA、REM、CLM、IDS、PET.PCT、PETDEC 和 SPEC 文档

v1.6.0

• 新增 odp_search_office_actions：按全文、文档代码、驳回法条（101/102/103/112/双重专利）、技术组、日期和专利号搜索 ODP 的 Office Action 数据集（自 2007 年中以来寄出的 1,990 万份 Office Action）。每个响应都包含整个匹配集按文档代码和法条统计的分面计数，因此 limit=1 即可回答计数问题。API 仅返回每份 Office Action 的前 500 个字符；命中项的 document_id 是文件封装文档的 documentIdentifier，因此可使用 odp_download_document 读取其余内容
• 新增 odp_search_petition_decisions：按文本、请愿类型代码或关键词、结果、裁决办公室、技术中心、日期和最终机构行动标记，搜索 110 万份请愿决定（自 1991 年起），并提供结果、办公室和类型分面。摘要中的查询匹配内容会用「类似这样」标记；include_full_text 会添加每项决定的完整 OCR 文本
• 旧版占位工具 get_office_action_text 和 search_office_actions 现在会指向新工具；check_api_status 会将这两个数据集列为活跃
• 这些端点返回 401/403 时会附带关于 ODP 客户档案要求的提示
• 工具数量：默认注册 40 个（启用 ENABLE_LEGACY_TOOLS 时为 65 个）
• 已于 2026-10-14 在线验证

v1.5.0

• CPC 标题细化到小类以下：get_cpc_info（以及 patents://cpc/{code}）使用的捆绑表只到大类级别，因此 G06N 3/08 返回的是「计算；计算；计数」。现在，小类、主组和小组会从 USPTO 发布的小类 CPC 方案页面获取（www.uspto.gov/web/patents/classification/cpc/html/cpc-G06N.html；无需密钥），每个小类每天获取一次：G06N 3/08 →「学习方法」，并附带层级 G06N › 3/00 › 3/02 › 3/08 及其下属小组。接受其他工具输出的所有格式（G06N3/08、G06N 3/08、H04B7/0417 20130101）。若方案中不包含某代码，则返回 NOT_FOUND 和该小类的主组；若无法获取页面，则返回静态小节和大类标题，并附带 scheme_error
• 提示词参数：全部九个工作流提示词都接受可选参数（专利号、公司、商标、CPC 代码等）。提供的内容会显示在步骤之前的 Subject 部分；不提供参数时，提示词与之前相同
• 新增 CPC_SCHEME_BASE_URL 设置；check_api_status 新增 cpc_scheme 条目
• 已于 2026-09-26 在线验证：G06N 3/08、G06N、A61K、H04B 7/0417，以及一个未知小类和组

v1.4.0

• 将 httpx 替换为 httpx2，用于九个 USPTO 客户端和日志传输。httpx2 是同一作者推出的后续版本（现隶属 pydantic 组织），也是 mcp 2 已依赖的库；httpx 0.28.1（2024 年 12 月）和 httpcore 1.0.9（2025 年 4 月）已不再更新。本代码使用的所有功能，其 API 均保持不变（AsyncClient、AsyncHTTPTransport、Cookies、build_request/send(stream=True)、异常类），因此只需在 20 个文件中重命名；httpx 和 httpcore 会完全从依赖树中移除。PPUBS 会话处理、PDF 打印任务、TSDR XML 文档列表、tmsearch、Assignment Center v3 和 ODP 文档下载重定向均已于 2026-09-26 重新在线验证（完整测试套件，未跳过任何测试）

v1.3.0

• MCP Python SDK 2.x：服务现在基于 mcp>=2,<3（MCPServer，重命名后的 FastMCP）构建，取消了 v1.2.1 添加的 mcp<2 版本限制。工具名称、参数和结果均未改变；--host/--port/--path/--stateful/--json-response 标志和 MCP_* 变量的含义保持不变。底层传输设置从服务构造函数移至 run_streamable_http_async()，协议测试使用 mcp 2 的内存中 Client，依赖项也移除了 [cli] 附加项（该项在 2.x 中为空）
• 关闭结构化输出：默认情况下，mcp 2 会将每个字典结果发送两次：一次作为 JSON 文本，另一次作为 structured_content，并使用“任意对象”的输出架构——在文档和搜索场景中测得的传输大小是原来的 2.0 倍。工具注册时设置 structured_output=False，因此结果只传输一次，与之前相同
• 固定使用 click>=8.3.3（PYSEC-2026-2132；这是一个早于此版本发布的 uvicorn 间接依赖项），使新依赖树通过 pip-audit 检查
• 2026-09-26 验证：在 mcp 2.2.0 上运行单元测试套件；运行完整测试套件（单元测试加集成测试，未取消选择任何测试）；从构建的 wheel 使用 uvx 全新安装；通过 mcp 2 自带的客户端进行 stdio 和 streamable-http 冒烟测试

v1.2.1

• 修复全新安装问题：mcp[cli]>=1.27 会解析到 mcp 2.x，而后者将 mcp.server.fastmcp 重命名为 mcp.server.mcpserver，导致 uvx patent-mcp-server 和 pip install patent-mcp-server 在导入时崩溃（ModuleNotFoundError: No module named 'mcp.server.fastmcp'）。mcp 2.0.0 于 2026-07-28 发布，因此 v1.1.1 和 v1.2.0 均受影响；仓库中的 uv.lock（mcp 1.28.1）掩盖了此问题，本地运行和 CI 都未发现。现在依赖项为 mcp[cli]>=1.27,<2。迁移到 mcp 2 API 是另一项工作

v1.2.0

• 修复专利号解析："US 9,876,543 B2" 曾被解析为 98765432（类型代码被并入号码），而 "D845123" 曾被解析为 845123，即一项 1907 年的实用专利。现在会保留 D/RE/PP 前缀并移除分隔符、开头的 "US" 和类型代码。查询还移除了一个无效的 patentNumber:"…" 查询，该查询返回空结果，却会让每次调用耗时约 3 秒
• ppubs_get_full_document 和 ppubs_get_patent_by_number 支持 sections：可选择 biblio、abstract、claims、description。完整文档约为 24k 个 token；["biblio", "claims"] 约为 6k 个 token。所有文档中都会移除空字段和搜索高亮字段
• 缩减搜索结果：每条 PPUBS 命中结果都带有两份 7 KB 的引用文献列表；现在三条命中结果合计为 5k 个字符，而不是 41k。ppubs_search_* 的默认值改为 limit=20（截断步骤原本就会将更大的响应裁剪到 20 条）
• 新增 odp_download_document，可将文件包装的文档（审查意见通知书、答复、授权通知等）下载为 PDF，并跟随 ODP 提供的有效期为 30 秒的签名重定向；超过 4 MB 的文档将被拒绝。odp_get_documents 新增 document_code 和 direction 筛选条件、分页功能，以及整个文件包装中按代码统计的数量
• 新增 ppubs_get_citing_patents：通过已授权专利的 .urpn. 字段获取前向引用；total 为引用数量
• 默认隐藏旧版工具：已关闭 API 的 25 个工具占了发送给每个客户端的 schema 文本的 39%（约 6k 个 token）。设置 ENABLE_LEGACY_TOOLS=true 即可注册这些工具；函数、名称和变通方案提示消息均未更改
• 所有工具均添加了只读注释，因此支持这些注释的客户端无需确认每次调用
• 竞争对手专利组合、实施自由和专利全景提示词、patentsview_* 变通方案提示消息以及本 README，之前仍在介绍 8 月起失效的斜线前缀搜索语法（AN/、IN/、CPC/）；现已全部改用 .as.、.in.、.cpc. 和 @pd
• 移除了 test/test_patents.py：其中有两个脚本式实时检查，它们只记录错误而不执行断言，因此即使调用 USPTO 并在每次默认 pytest 运行（包括 CI）时重写 json/ 和 pdfs/，测试也总会通过。默认测试套件现在不会发起任何网络调用
• 修复 tm_search_assignments：Assignment Center 将其搜索 API 从 /ipas/search/api/v2/ 移到了 /v3/，CloudFront 现在会对旧路径上的 POST 请求返回 403 HTML 页面。请求体和响应封装保持不变；只有路径发生了变化
• ODP 和 PTAB 客户端新增 429 处理：请求受到速率限制时，现在会等待（使用 Retry-After；否则采用指数退避），并最多重试 MAX_RETRIES 次，而不是将 429 返回给调用方。api.uspto.gov 按密钥限制请求速率，因此突发工具调用曾触发限流
• 集成测试：test/test_tools.py 和 test/test_tools_pytest.py 内容重复；pytest 版本保留并改用较短名称，同时移除了八个被跳过的 PatentsView 测试，修复了其中的 patentNumber:"…" 查询和 numFound 断言（两者都已不再匹配实时 API 或工具响应封装），并新增了针对 sections、带前缀的号码、ppubs_get_citing_patents、odp_get_documents 筛选条件和 odp_download_document 的实时测试。uv run pytest -m "" 会运行整个测试套件，包括单元测试和实时测试，并且可以通过
• 2026-09-26 实时验证：带 D/RE 前缀的 .pn.、.urpn.、ODP 文档列表和下载重定向、Assignment Center v3
• 工具数量：默认注册 38 个（设置 ENABLE_LEGACY_TOOLS 后为 63 个）

v1.1.1

• 修复了 ppubs_download_patent_pdf：USPTO 更改了 PDF 下载端点——旧的 /api/internal/print/save/{pdfName} 路径现在会返回 404；客户端改用当前可用的 /api/print/save/{pdfName} 端点（已于 2026-08-05 通过真实搜索、文档获取和 PDF 下载验证）
• 更正了 PPUBS 搜索语法指南：带斜杠前缀的字段限定符（TTL/、IN/、AN/、CPC/）在当前可用的 API 上已不再有效——它们会静默返回 0 条结果，而 TTL/"phrase" 会返回服务器 500。搜索工具文档字符串、现有技术检索提示词和 patents://search-syntax 指南现在改为介绍可用的点号后缀格式（.ti.、.ab.、.clm.、.spec.、.in.、.as.、.pn.、.cpc.、@pd/@ad 日期范围），且每种格式都已通过实时验证
• 这两处故障都是 USPTO 端的变动，发生在 v1.1.0 发布之前（已通过对 v1.0.0 时期的代码运行相同的实时测试确认）

v1.1.0

• 通过 HTTP 远程托管：新增 --transport streamable-http 模式，可通过网络提供 MCP 端点服务，因此一次部署即可供整个团队使用，无需每位用户都运行本地副本。stdio 仍为默认模式，因此现有的 Claude Desktop 和 Claude Code 配置不变。新增 --host、--port、--path、--stateful、--json-response 标志，每个标志都有对应的 MCP_* 环境变量。安全注意事项见“通过 HTTP 远程托管”——该端点持有你的 API 密钥，且不会对调用方进行身份验证
• 默认无状态：HTTP 请求不携带客户端状态，因此 MCP 服务可以在负载均衡器后运行多个副本，无需会话粘滞
• 修复了 Public Search 客户端中的会话竞争问题（stdio 用户也会受影响）：并发工具调用会各自重置共享的 cookie jar，并竞争替换访问令牌，因此已在处理中的请求可能会使用一半已替换的会话进行签名。现在会话设置已串行化；如果另一个调用已替换令牌，则会跳过 403 刷新；令牌也改为随请求传递，而不再存放于共享客户端的默认标头中
• 修复了关闭流程：关闭九个 HTTP 客户端不再通过会启动新事件循环的 atexit 钩子执行；现在会在客户端打开时所在的事件循环中执行。特意不使用 FastMCP 生命周期机制——在无状态 HTTP 模式下，该机制会在每个请求时运行一次，并在首次工具调用后关闭客户端
• 将 MCP SDK 最低版本提升至 >=1.27（此前为 >=1.3.0，该版本可能会解析到不支持流式 HTTP 的 SDK）
• 新增 MCP 协议层测试：此前测试套件直接调用工具函数，从未测试模式生成、资源／提示词注册或序列化。新增 19 个测试（总计 378 个，之前为 359 个）

v1.0.0

• 商标支持：新增 3 个客户端，共提供 9 个商标工具；所有工具均于 2026-06-10 根据 USPTO 实时服务完成验证
  • TSDR（tsdr_get_trademark_status、tsdr_list_trademark_documents、tsdr_download_trademark_documents、tsdr_get_trademark_image）——官方商标状态／文档 API。需要专用的 TSDR 密钥（ODP 密钥不可用）；错误响应会识别错误密钥特征，并说明如何获取正确密钥。超过 4 MB 的文档包会被拒绝，并提供筛选建议（完整封装可能超过 10 MB）
  • 商标搜索（tm_search_trademarks、tm_get_trademark）——通过 tmsearch.uspto.gov 后的内部 Elasticsearch API，按商标文本、所有人、商品／服务和尼斯分类进行全文搜索（没有官方 REST API）。已完成实时验证；遭到 AWS WAF 拒绝时支持使用 TMSEARCH_WAF_TOKEN
  • 商标转让（tm_search_assignments）——USPTO Assignment Center 公共 API（assignmentcenter.uspto.gov，无需密钥），可按序列号／注册号、受让人、转让人和卷号／页码搜索。已替换于 2026 年 6 月 5 日停用的旧版 assignment-api.uspto.gov XML API
• 新增参考工具和资源：get_trademark_class_info、get_trademark_status_code、trademarks://classes、trademarks://status-codes（全部 45 个尼斯分类、常见商标状态代码）
• 新增 3 个工作流提示词：trademark_clearance_search、trademark_portfolio_review、trademark_status_monitoring
• 修复 ppubs_download_patent_pdf（调用 download_image 时使用了错误的签名，导致引发 TypeError）
• 重写专利工作流提示词，使其引用实时工具（旧提示词仍指向已停用的 PatentsView／Office Action／引文工具）
• 新增环境变量：TSDR_API_KEY、TMSEARCH_WAF_TOKEN、TSDR_BASE_URL、TMSEARCH_BASE_URL、TM_ASSIGNMENT_BASE_URL
• 工具数量：已注册 61 个（36 个可用，25 个不可用）

v0.9.5

• 在 USPTO ODP v3.0 上重新启用 7 个 PTAB 工具：ptab_search_proceedings、ptab_get_proceeding、ptab_get_documents、ptab_search_decisions、ptab_get_decision、ptab_search_appeals、ptab_get_appeal（问题 #23）。PTAB 数据已迁移至 ODP /api/v1/patent/trials/* 和 /api/v1/patent/appeals/*（这些路径未列入 ODP Swagger UI）；关于独立 API 停用的判断（问题 #16）对 Patent Litigation API 是正确的，但 PTAB 只是迁移了，并未消失。
• 可用工具数量：27 个（原为 20 个）；不可用：25 个（原为 32 个）；已注册工具总数仍为 52 个

v0.9.4

• 修复 ppubs_search_patents／ppubs_search_applications 查询语义（问题 #21）：默认运算符由 OR 改为 AND，因此 machine learning 等多词查询不再匹配整个语料库，也不会在按 date_publ desc 排序时退化为只返回最新授权专利。
• 修复 PPUBS 客户端中的模板修改错误（search_query.copy() → copy.deepcopy(...)），消除并行调用之间的并发隐患。
• 修复 odp_search_applications 筛选条件被上游静默忽略的问题（问题 #21）：从使用 GET 查询字符串参数改为 POST，并在请求体中使用 Lucene 风格的 q。现在会将 assignee_name、inventor_name、application_number、patent_number 和申请日期范围正确地以 AND 方式组合到搜索中。无筛选条件调用时，工具现在会返回 MISSING_FILTER，而不是倾倒包含 1,280 万条记录的完整语料库。
• 更新 ppubs_search_patents／ppubs_search_applications／odp_search_applications 的文档字符串，以反映修正后的语义，并说明 ODP 支持 Lucene 查询。
• 新增 CONTRIBUTING.md、AGENTS.md、缺陷报告和功能请求问题模板，以及 PR 模板。

v0.9.0

• 处理 ODP 上 PTAB Trial API 和 Patent Litigation API 不可用的情况（问题 #16）
• 所有 7 个 ptab_* 工具和 4 个诉讼工具现在都会返回 API_UNAVAILABLE，并提供指向 PPUBS 工具和 USPTO 批量数据集的替代方案说明
• 活跃工具数量：20 个（从 31 个减少）；不可用工具数量：32 个（从 21 个增加）；已注册工具总数仍为 52 个
• 为所有 11 个新增不可用工具添加了单元测试，并扩展了共享错误结构参数化测试
• 更新了 check_api_status、resources.py 数据源、客户端文档字符串和 README，以反映服务关闭情况

v0.8.0

• 处理已停用的 PatentsView API（于 2026 年 3 月 20 日关闭）
• 所有 14 个 patentsview_* 工具都会返回 API_UNAVAILABLE，并提供替代方案说明
• 修复了 office_actions 资源中指向不可用 PatentsView 工具的循环引用
• 更新了 API 来源表、配置和文档

v0.7.0

• 处理已停用的 Office Action 和 Enriched Citation API（developer.uspto.gov）
• 所有 7 个受影响的工具都会返回 API_UNAVAILABLE，并提供替代方案说明
• 添加了 test/unit/test_unavailable_tools.py，用于测试已停用的工具
• 代码清理：移除无用代码，改进文档字符串

v0.6.2

• 更新了 API 密钥注册说明：现在可从 data.uspto.gov（“My ODP”）获取密钥
• 澄清 api.uspto.gov 才是正确的 API 端点（data.uspto.gov 是 Web 门户）
• 说明了 PTAB API v3 迁移至 ODP 以及 Office Action API 迁移（2026 年初）

v0.6.1

• 添加了 PatentsView 律师搜索工具（patentsview_search_attorneys、patentsview_get_attorney）
• 添加了 PatentsView IPC 分类工具（patentsview_lookup_ipc、patentsview_search_by_ipc）
• 修复了 search_publications 方法中的错误（未传递分页选项）

v0.6.0

• 准备 PyPI 发布

v0.5.0

• 专注于仅使用 USPTO 数据源
• 为 ODP 工具添加 odp_ 前缀，以便区分
• 改进函数签名（使用 query 而非 q）

v0.3.0

• 添加了 33 个新工具（PTAB、PatentsView、Office Actions、Citations、Litigation）
• 支持 PatentsView API 速率限制
• 完善的异步客户端架构

v0.2.2

• 使用环境变量集中管理配置
• 标准化错误处理
• 使用 Pydantic 验证输入
• 使用指数退避进行重试
• 为 PPUBS 添加会话缓存

许可证

MIT