uspto-patent-family-oss

<div align="center"> <img src="docs/assets/logo.svg" alt="uspto-patent-family" width="540"> ### US patent family trees — the *continuity* genealogy, from the USPTO, as interactive charts **English** | [中文](README.zh.md) [](LICENSE) [](package.json) [](#requirements) [](https://github.com/HunterKK1424/uspto-patent-family-oss/actions/workflows/ci.yml) [](#connect-it-to-an-mcp-client) [**Tools**](#what-you-get) · [**Install**](#install) · [**Setup**](#connect-it-to-an-mcp-client) · [**Get a key**](#get-a-uspto-odp-api-key) · [**Sample**](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"> _{<i>Example output rendered from synthetic data — no API key needed.</i>} </div> > ### ⚠️ This is *continuity*, not INPADOC > This tool draws the **US prosecution family** (a parent/child DAG within the USPTO). > It is **not** the INPADOC cross‑office family (the same invention filed in other > countries). They are different things — do not confuse one for the other. An [MCP](https://modelcontextprotocol.io) server that builds the **US domestic patent family tree** — the *continuity* genealogy (continuation / continuation‑in‑part / division / provisional, plus reissue & reexam links) — from the **USPTO Open Data Portal (ODP)**, and renders it as an interactive HTML chart or a Mermaid diagram. **See it:** open [`samples/sample-family-tree.html`](samples/sample-family-tree.html) in a browser for a live, self-contained example rendered from synthetic data (no API key needed). ## What you get Four read‑only tools: | Tool | Purpose | |------|---------| | `patent_continuity` | One hop: a single application's direct parents & children. | | `patent_family_tree` | Server‑side BFS of the whole continuity DAG → `family_raw.json`. | | `patent_family_chart` | The family tree **rendered** — interactive HTML (default) or Mermaid. | | `patent_status` | Whether your API key is configured + the server version. | The HTML chart is self‑contained (no external requests): filters (status / relation / applicant / lineal‑only / generation depth), a filing‑date **year‑axis timeline** with copendency red‑flag heuristics, light/dark toggle, zoom/pan, hover detail, and built‑in PNG/SVG download. <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>_{<i>Interactive: re-layout by generation or filing‑year, prune by depth — synthetic data.</i>} </div> Full parameters, outputs, and example prompts for each tool are in [USAGE.md](USAGE.md); version history is in [CHANGELOG.md](CHANGELOG.md). ## Requirements - **Node.js ≥ 18** — runs the MCP server. - **Python 3** — the chart renderers (`patent_family_chart`) shell out to the bundled `build/*.py`. If you only use `patent_family_tree` (raw JSON) you don't need Python. - **A free USPTO ODP API key** — see below. ## Get a USPTO ODP API key 1. Sign in at [account.uspto.gov](https://account.uspto.gov) (verify with ID.me). 2. Open **Manage API Key** and request a key. 3. One ODP key covers the endpoints this server uses (sent as the `x-api-key` header). The key has a **weekly quota** and **burst = 1** (one request at a time). This server serializes every call and caches responses on disk to protect your quota. ## Install ```bash git clone https://github.com/HunterKK1424/uspto-patent-family-oss.git cd uspto-patent-family-oss npm install npm run build ``` ## Connect it to an MCP client The server speaks MCP over **stdio**, so it works with any client that launches a local MCP server — **Claude Desktop / Code, Gemini CLI, Cursor, Cline, Continue, Windsurf, Zed**, and the **OpenAI Agents SDK**. In every case you run `dist/index.js` with `node` and pass `USPTO_API_KEY` in the server's `env`. > **Which clients?** Anything that runs a *local* stdio MCP server works (most desktop AI > apps and AI code editors). The **hosted ChatGPT and Gemini web apps do not run local MCP > servers** — reaching those needs a remote (HTTP) deployment, which this repo does not > include. **Verified:** the server has been connected and exercised via **Claude Desktop**, the **OpenAI Agents SDK** (`MCPServerStdio`), **Gemini CLI**, and the official MCP SDK client in both TypeScript and Python (connect → list tools → call a tool). **Cursor / Cline / Continue / Windsurf / Zed** are not individually tested but speak the same stdio MCP protocol, so the same config applies. ### Claude Desktop Edit `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 Add the same block to `~/.gemini/settings.json` (a project-level `.gemini/settings.json` works too). Gemini CLI expands `$VARS`, so you can reference a shell variable instead of pasting the key inline: ```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" } } } } ``` > **Folder trust:** Gemini CLI disables MCP servers in folders it doesn't trust. If > `gemini mcp list` shows the server as *Disabled*, trust the workspace (accept the trust > prompt when Gemini asks, or use `/trust`); once trusted it shows **Connected**. Verify > with `gemini mcp list`. ### Cursor / Cline / Continue / Windsurf / Zed These AI code editors use the **same `mcpServers` shape** — add the Claude Desktop block above to the editor's MCP config (e.g. Cursor's `~/.cursor/mcp.json`, or Cline's MCP settings panel): command `node`, args = the absolute path to `dist/index.js`, key in `env`. ### OpenAI Agents SDK (build your own GPT agent) Spawn the server as a local subprocess: ```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) ``` Then restart the client (or run your agent) and ask something like *"show the US family tree for application 15/643,719."* > **The chart across clients.** The interactive HTML from `patent_family_chart` is designed > to render as a **Claude artifact**. Other clients receive it as HTML *text* (save it and > open in a browser) — so on non-Claude clients prefer `format: "mermaid"` for a quick > inline diagram, or `patent_family_tree` for raw JSON. The `patent_continuity` / > `patent_family_tree` data tools behave identically on every client. ### Try it without a client (CLI) The renderers work standalone on any `family_raw.json` (the `fixtures/` files need no key): ```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 ``` ## Language (English / 中文) The chart UI and text output default to **English**. To switch: - Set `PATENT_FAMILY_LANG=zh` in the server `env` to default everything to Traditional Chinese, **or** - pass `lang: "zh"` to `patent_family_chart` for a single call, **or** - pass `--lang zh` to the Python renderers on the CLI. ## Configuration (environment variables) | Variable | Default | Meaning | |----------|---------|---------| | `USPTO_API_KEY` | — | **Required.** Your ODP key. | | `PATENT_FAMILY_LANG` | `en` | `en` or `zh` — default UI language. | | `PATENT_HTTP_TIMEOUT_MS` | `30000` | HTTP request timeout (ms). | | `PATENT_ODP_RETRY_429` | off | Set `1` to retry **once** after a ≥5 s wait on an HTTP 429. Off by default — USPTO discourages auto‑retry. | | `PATENT_ODP_CACHE` | on | Set `0` to disable the disk cache. | | `PATENT_ODP_CACHE_DIR` | `<tmp>/patent-mcp-cache` | Cache directory. | | `PATENT_ODP_CACHE_TTL_MS` | 7 days | Cache freshness window (ms). | | `PATENT_FAMILY_TIME_BUDGET_MS` | `100000` | Wall‑clock budget for a family walk; on timeout it returns partial results. | | `PATENT_PYTHON` | `python3` | Python executable for chart rendering. | | `PATENT_FAMILY_RENDER_DIR` | bundled `build/` | Override the directory holding the Python renderers. | | `PATENT_ESBUILD` | — | Path to `esbuild` for stronger HTML JS minification (falls back to a zero‑dependency minifier). | | `PATENT_COPYRIGHT_HOLDER` / `PATENT_COPYRIGHT_YEAR` | author / `2026` | Override the credit line embedded in rendered charts. | ## Limitations (by design) - **ODP burst = 1 / weekly quota** — large families take proportionally longer; a rate limit (HTTP 429) aborts the walk and returns partial results (clearly flagged). - **Large families are bounded** — `maxNodes` (default 40, max 150) caps total nodes; extra neighbours are recorded as an omitted count rather than exploding the graph. - **Foreign priority is out of scope** — Paris Convention foreign priority is *not* part of US continuity (that's INPADOC territory). - **Continuity ≠ perfected legal benefit** — the graph shows *as‑recorded* relationships; specific‑reference completeness and §120 copendency must still be checked case by case. ## Disclaimer **No warranty.** THIS SOFTWARE AND ITS OUTPUT ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, ACCURACY, AND NON-INFRINGEMENT. You rely on its output entirely at your own risk. See the [LICENSE](LICENSE) for the full limitation of liability. **Not legal advice.** This tool is provided for technical reference only. Nothing it produces is legal advice, and using it does **not** create an attorney–client, patent‑agent–client, or any other professional relationship with the author or any firm. It is not a substitute for professional judgment or for independent verification. For any question of patent priority, validity, term, or continuity, consult a licensed patent practitioner. **Data may be incomplete or out of date.** The data comes from the public USPTO Open Data Portal and may contain errors, omissions, or delays. Always confirm against the official USPTO record (Patent Center / IFW) before relying on any result. **"Continuity" here is *as recorded* — not a perfected legal benefit.** The chart shows parent/child relationships as reported by the USPTO. It does **not** verify a claim's entitlement to an earlier filing date. Under 35 U.S.C. § 120 (and § 119(e) for provisionals), a benefit claim must independently satisfy — for *each* application in the chain, re‑examined at every link (it is **not** inherited) — (1) written‑description / enablement continuity under § 112(a) for the specific claim, (2) continuity of inventorship, (3) copendency, and (4) a specific reference present at *every* intermediate application. A recorded reference does not by itself perfect benefit, and a break anywhere downstream defeats it: a one‑day copendency lapse is fatal (*Immersion v. HTC*, 826 F.3d 1357 (Fed. Cir. 2016)); the specific reference must appear at every intermediate link, not just the endpoints (*Encyclopaedia Britannica v. Alpine*, 609 F.3d 1345 (Fed. Cir. 2010)); and deleting a benefit claim in an intermediate application severs the chain for every later application that reaches back through it (*Natural Alternatives v. Iancu*, 904 F.3d 1375 (Fed. Cir. 2018)). CIP claims not supported by the parent take the CIP's own filing date (and the parent may become prior art against them), while the 20‑year term still runs from the parent. A drawn edge is a lead to investigate, not a determination. **Do not use this tool as the basis for any determination of priority, effective filing date, patent term, validity, or freedom to operate** — each case must be checked on its own file history. **Unofficial.** This is an independent tool and is **not affiliated with, endorsed by, or sponsored by the United States Patent and Trademark Office.** ## License **PolyForm Noncommercial License 1.0.0** — see [LICENSE](LICENSE). This is a *source‑available*, **noncommercial** license (not an OSI "open source" license). You may use, modify, and share it for any **noncommercial** purpose. **Commercial use requires a separate license.** Contact **hunterip0305@gmail.com**. See [NOTICE](NOTICE). ## Contributing Issues and bug reports are welcome. **Pull requests are not accepted** — to keep the licensing clean for commercial licensing, the author retains sole copyright. Please open an issue to discuss ideas or report problems instead. > When filing an issue, **do not paste your API key or full response logs.**