内容
<div align="center">
<img src="docs/assets/logo.svg" alt="uspto-patent-family" width="540">
### 美国专利家族树 —— 连续性 genealogy，来自 USPTO，以交互式图表显示
**中文** | [English](README.md)
[](LICENSE)
[](package.json)
[](#requirements)
[](https://github.com/HunterKK1424/uspto-patent-family-oss/actions/workflows/ci.yml)
[](#connect-it-to-an-mcp-client)
[**工具**](#工具列表) · [**安装**](#安装) · [**设置**](#connect-it-to-an-mcp-client) · [**获取密钥**](#获取USPTO-ODP-API密钥) · [**示例**](samples/sample-family-tree.html)
<img src="docs/assets/sample-tree.svg" alt="Example family tree — continuation / CIP / provisional, with copendency red-flag heuristics" width="600">
<sub><i>示例输出，使用合成数据渲染 - 不需要 API 密钥。</i></sub>
</div>
> ### ⚠️ 这是 *continuity*，不是 INPADOC
> 本工具绘制 **美国专利家族**（专利申请在 USPTO 内的父子有向图）。
> 它 **不是** 跨办公室的专利家族（同一发明在其他国家的文件 - 这是 INPADOC 的领域）。
> 它们是不同的事物 - 请勿将它们混淆。
一个 [MCP](https://modelcontextprotocol.io) 服务器，从 **USPTO Open Data Portal (ODP)** 构建 **美国国内专利家族树** - 连续性 genealogy（继续 / 继续部分 / 分割 / 临时，以及重新发布和重新审查链接）- 并将其渲染为交互式 HTML 图表或 Mermaid 图。
**查看示例：** 在浏览器中打开 [`samples/sample-family-tree.html`](samples/sample-family-tree.html)，以查看使用合成数据渲染的实时独立示例（不需要 API 密钥）。
## 工具列表
四个只读工具：
| 工具 | 目的 |
|------|---------|
| `patent_continuity` | 一步：单个申请的直接父代和子代。 |
| `patent_family_tree` | 整个连续性 DAG 的服务器端广度优先搜索 → `family_raw.json`。 |
| `patent_family_chart` | 家族树 **渲染** - 交互式 HTML（默认）或 Mermaid。 |
| `patent_status` | 检查 API 密钥是否配置正确 + 服务器版本。 |
HTML 图表是自包含的（无外部请求）：过滤器（状态 / 关系 / 申请人 /仅限直系 / 代际深度），带有共依赖红旗启发式的**按年份划分的时间轴**，亮/暗切换，缩放/平移，悬停详情和内置 PNG/SVG 下载。
<div align="center">
<img src="docs/assets/demo.gif" alt="Interactive chart: re-layout by generation or filing year, and prune by depth" width="600">
<br><sub><i>交互式：按世代或申请年份重新布局，按深度修剪 - 合成数据。</i></sub>
</div>
每个工具的完整参数、输出和示例提示在 [USAGE.md](USAGE.md) 中；版本历史在 [CHANGELOG.md](CHANGELOG.md) 中。
## 要求
- **Node.js ≥ 18** - 运行 MCP 服务器。
- **Python 3** - 图表渲染器（`patent_family_chart`）调用捆绑的 `build/*.py`。如果您只使用 `patent_family_tree`（原始 JSON），则不需要 Python。
- **免费的 USPTO ODP API 密钥** - 请参见下文。
## 获取USPTO-ODP-API密钥
1. 在 [account.uspto.gov](https://account.uspto.gov) 登录（使用 ID.me 验证）。
2. 打开 **Manage API Key** 并请求一个密钥。
3. 一个 ODP 密钥涵盖此服务器使用的端点（作为 `x-api-key` 头部发送）。
密钥具有 **每周配额** 和 **突发 = 1**（一次一个请求）。此服务器序列化每个调用并在磁盘上缓存响应以保护您的配额。
## 安装
```bash
git clone https://github.com/HunterKK1424/uspto-patent-family-oss.git
cd uspto-patent-family-oss
npm install
npm run build
```
## 连接到MCP客户端
服务器通过 **stdio** 使用 MCP，因此它适用于启动本地 MCP 服务器的任何客户端 - **Claude Desktop / Code, Gemini CLI, Cursor, Cline, Continue, Windsurf, Zed**，以及 **OpenAI Agents SDK**。在每种情况下，您都使用 `node` 运行 `dist/index.js` 并在服务器的 `env` 中传递 `USPTO_API_KEY`。
> **哪些客户端？** 任何运行本地 stdio MCP 服务器的客户端都有效（大多数桌面 AI 应用程序和 AI 代码编辑器）。**托管的 ChatGPT 和 Gemini 网络应用程序不运行本地 MCP 服务器** - 访问这些需要远程（HTTP）部署，本仓库不包含。
**已验证：** 服务器已通过 **Claude Desktop**、**OpenAI Agents SDK**（`MCPServerStdio`）、**Gemini CLI** 和官方 MCP SDK 客户端在 TypeScript 和 Python 中连接和测试（连接 → 列出工具 → 调用工具）。**Cursor / Cline / Continue / Windsurf / Zed** 未单独测试，但使用相同的 stdio MCP 协议，因此配置相同。
### Claude Desktop
编辑 `claude_desktop_config.json`:
```jsonc
{
"mcpServers": {
"uspto-patent-family": {
"command": "node",
"args": ["/absolute/path/to/uspto-patent-family-oss/dist/index.js"],
"env": {
"USPTO_API_KEY": "your-odp-key-here"
}
}
}
}
```
### Gemini CLI
将相同的块添加到 `~/.gemini/settings.json`（也支持项目级 `.gemini/settings.json`）。Gemini CLI 扩展 `$VARS`，因此您可以引用 shell 变量而不是内联粘贴密钥：
```jsonc
{
"mcpServers": {
"uspto-patent-family": {
"command": "node",
"args": ["/absolute/path/to/uspto-patent-family-oss/dist/index.js"],
"env": { "USPTO_API_KEY": "$USPTO_API_KEY" }
}
}
}
```
> **文件夹信任：** Gemini CLI 在它不信任的文件夹中禁用 MCP 服务器。如果 `gemini mcp list` 显示服务器为 *Disabled*，请信任工作区（接受 Gemini 的信任提示，或使用 `/trust`）；一旦信任，它将显示 **Connected**。使用 `gemini mcp list` 验证。
### Cursor / Cline / Continue / Windsurf / Zed
这些 AI 代码编辑器使用相同的 **mcpServers 结构** - 将上面的 Claude Desktop 块添加到编辑器的 MCP 配置中（例如 Cursor 的 `~/.cursor/mcp.json` 或 Cline 的 MCP 设置面板）：命令 `node`，参数 = `dist/index.js` 的绝对路径，环境变量中的密钥。
### OpenAI Agents SDK（构建您自己的 GPT 代理）
将服务器作为本地子进程启动：
```python
from agents import Agent, Runner
from agents.mcp import MCPServerStdio
async def main():
async with MCPServerStdio(params={
"command": "node",
"args": ["/absolute/path/to/uspto-patent-family-oss/dist/index.js"],
"env": {"USPTO_API_KEY": "your-odp-key-here"},
}) as server:
agent = Agent(
name="Patent assistant",
instructions="Use the USPTO tools to answer US patent-family questions.",
mcp_servers=[server],
)
result = await Runner.run(agent, "Show the US continuity for application 15/643,719.")
print(result.final_output)
```
然后重启客户端（或运行代理）并询问类似 *"显示应用程序 15/643,719 的美国家族树。"*
> **跨客户端的图表。** `patent_family_chart` 的交互式 HTML 设计为 **Claude artifact**。其他客户端以 HTML *文本* 接收它（保存它并在浏览器中打开）- 因此在非 Claude 客户端上，更喜欢 `format: "mermaid"` 进行快速内联图表，或使用 `patent_family_tree` 获取原始 JSON。`patent_continuity` / `patent_family_tree` 数据工具在每个客户端上的行为相同。
### 在没有客户端的情况下尝试（命令行界面）
渲染器独立于任何 `family_raw.json`（`fixtures/` 文件不需要密钥）工作：
```bash
python3 build/render_html.py fixtures/cip_fork.json -o tree.html # open tree.html
python3 build/render_mermaid.py fixtures/cip_fork.json # Mermaid + summary
```
## 语言（英文 / 中文）
图表 UI 和文本输出默认为 **英文**。要切换：
- 在服务器 `env` 中设置 `PATENT_FAMILY_LANG=zh` 以将所有内容默认为繁体中文，**或**
- 为 `patent_family_chart` 传递 `lang: "zh"` 以进行单次调用，**或**
- 在命令行界面中为 Python 渲染器传递 `--lang zh`。
## 配置（环境变量）
| 变量 | 默认值 | 含义 |
|----------|---------|---------|
| `USPTO_API_KEY` | - | **必填。** 您的 ODP 密钥。 |
| `PATENT_FAMILY_LANG` | `en` | `en` 或 `zh` - 默认 UI 语言。 |
| `PATENT_HTTP_TIMEOUT_MS` | `30000` | HTTP 请求超时（毫秒）。 |
| `PATENT_ODP_RETRY_429` | 关闭 | 设置为 `1` 以在 ≥5 秒等待后重试 **一次** HTTP 429。默认关闭 - USPTO 不鼓励自动重试。 |
| `PATENT_ODP_CACHE` | 开启 | 设置为 `0` 以禁用磁盘缓存。 |
| `PATENT_ODP_CACHE_DIR` | `<tmp>/patent-mcp-cache` | 缓存目录。 |
| `PATENT_ODP_CACHE_TTL_MS` | 7 天 | 缓存新鲜度窗口（毫秒）。 |
| `PATENT_FAMILY_TIME_BUDGET_MS` | `100000` | 家族遍历的时钟时间预算；超时时返回部分结果。 |
| `PATENT_PYTHON` | `python3` | 图表渲染的 Python 可执行文件。 |
| `PATENT_FAMILY_RENDER_DIR` | 捆绑的 `build/` | 覆盖保存 Python 渲染器的目录。 |
| `PATENT_ESBUILD` | - | `esbuild` 的路径，用于更强的 HTML JS 压缩（如果没有则回退到无依赖项的压缩器）。 |
| `PATENT_COPYRIGHT_HOLDER` / `PATENT_COPYRIGHT_YEAR` | 作者 / `2026` | 覆盖渲染图表中嵌入的版权声明。 |
## 限制（设计使然）
- **ODP 突发 = 1 / 每周配额** - 大型家族需要成比例的时间；速率限制（HTTP 429）中止遍历并返回部分结果（明确标记）。
- **大型家族是有限的** - `maxNodes`（默认 40，最大 150）限制总节点数；额外邻居记录为省略计数，而不是使图爆炸。
- **外国优先权范围外** - 巴黎公约外国优先权不是美国连续性的部分（那是 INPADOC 的领域）。
- **连续性 ≠ 完美的法律权益** - 图表显示 **记录在案** 的关系；必须逐案检查特定参考的完整性和 §120 共依赖性。
## 免责声明
**无担保。** 本软件及其输出按“原样”提供，不保证任何种类，包括但不限于适销性、特定用途适用性、准确性和非侵权性。您完全自担风险使用其输出。参见 [LICENSE](LICENSE) 以获取完整的责任限制。
**不是法律建议。** 本工具仅用于技术参考。它的任何输出都不是法律建议，使用它 **不** 会与作者或任何公司建立律师-客户、专利代理-客户或其他专业关系。它不是专业判断或独立验证的替代品。对于专利优先权、有效性、期限或连续性的任何问题，请咨询持牌专利从业者。
**数据可能不完整或过时。** 数据来自公共 USPTO 开放数据门户，可能包含错误、遗漏或延迟。在依赖任何结果之前，请始终与官方 USPTO 记录（专利中心 / IFW）进行确认。
**这里的“连续性”是指 **记录在案** 的 - 而不是完美的法律权益。** 图表显示由 USPTO 报告的父/子关系。它 **不** 验证声明有权获得较早的申请日期。在 35 U.S.C. § 120（和 § 119(e) 用于临时申请）下，权益声明必须独立满足 - 对于链中的每个申请，重新检查每个链接（它 **不** 被继承）- (1) § 112(a) 的书面描述 / 启用连续性，(2) 发明人连续性，(3) 共依赖性，和 (4) 在每个中间申请中存在特定参考。记录的参考本身并不完美权益，一个中断在下游会破坏它：一天的共依赖性丧失是致命的（*Immersion v. HTC*, 826 F.3d 1357（Fed. Cir. 2016））；特定参考必须出现在每个中间链接中，而不仅仅是端点（*Encyclopaedia Britannica v. Alpine*, 609 F.3d 1345（Fed. Cir. 2010））；在中间申请中删除权益声明会使链条对于通过它到达的每个后续申请失效（*Natural Alternatives v. Iancu*, 904 F.3d 1375（Fed. Cir. 2018））。CIP 声明如果没有父代支持，则采用 CIP 自己的申请日期（而父代可能成为其先前技术），而 20 年期限仍从父代开始。绘制的边是调查的线索，而不是确定。**不要将本工具作为任何优先权、有效申请日期、专利期限、有效性或操作自由的确定依据** - 每个案件必须在其自身的档案历史中进行检查。
**非官方。** 本工具是独立的，**不隶属于、未得到或赞助于美国专利和商标局**。
## 许可
**PolyForm 非商业许可 1.0.0** - 参见 [LICENSE](LICENSE)。这是 **非商业** 许可（不是 OSI “开源” 许可）。您可以免费使用、修改和分享它用于任何 **非商业** 目的。
**商业使用需要单独的许可。** 联系 **hunterip0305@gmail.com**。参见 [NOTICE](NOTICE)。
## 贡献
欢迎提出问题和错误报告。**不接受拉取请求** - 为了保持商业许可的清洁，作者保留唯一的版权。请提出问题以讨论想法或报告问题，而不是拉取请求。
> 提交问题时，**不要粘贴您的 API 密钥或完整的响应日志**。
