patent-checker

# Patent Checker

<!-- mcp-name: io.github.xhighhongo41/patent-checker -->

日本語版: [README_ja.md](README_ja.md)

[![PyPI](https://img.shields.io/pypi/v/patent-checker)](https://pypi.org/project/patent-checker/)
[![CI](https://github.com/xhighhongo41/patent-checker/actions/workflows/ci.yml/badge.svg)](https://github.com/xhighhongo41/patent-checker/actions/workflows/ci.yml)
[![Docker Hub](https://img.shields.io/docker/pulls/xhighhongo41/patent-checker)](https://hub.docker.com/r/xhighhongo41/patent-checker)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

Patent Checker helps you explore published patents that may relate to your
own software project, and to write down what you found as a dated,
procedure-style report. It is meant to be run more than once on the same
project — as an idea, during development, before a release, before each
update: a later run searches only what is new, re-checks the patents you
are monitoring, and tells you what changed since last time. It is built
from two parts:

- an **MCP server** that fetches public patent data (EPO Open Patent
  Services and Google Patents) deterministically: searches, bibliographic
  records, claims, legal status, patent families, plus offline helpers, and
- an **Agent Skill** that drives your AI coding agent (Claude Code, Codex
  CLI, Cursor, Gemini CLI, GitHub Copilot CLI, OpenCode, OpenHands, Hermes
  Agent) through the judgment work: reading your codebase, translating its
  features into patent vocabulary, screening candidates and writing the
  report.

Patent Checker **does not decide whether anything infringes a patent**. Its
reports contain observations, scope statements and open questions, never a
verdict.

**Status: stable release (v1.4).**

## Important notices

Please read these before you install anything. The tool asks you to
acknowledge them once, and records that you did.

- **What you learn here can be used against you.** A report documents that
  you knew of specific patents on specific dates. In some jurisdictions,
  notably the United States, knowledge of a patent can support a claim of
  willful infringement and increased damages. Dated records of how you
  responded can also work in your favor. Patent Checker lets you choose
  where its records live and whether they are tracked in version control:
  make that choice deliberately.
- **Search results are incomplete.** No patent search is exhaustive.
  Coverage varies by country, language, publication stage and data source,
  and recent applications may be missing entirely. The absence of a document
  from a report is never evidence that no relevant patent exists.
- **This is a search aid, not advice.** Patent Checker does not replace a
  qualified patent attorney or agent, and its authors accept no
  responsibility for decisions made, or not made, on the basis of its
  output. The final judgment about your project, and any response to it,
  is yours.

There are two notices. The **user notice** (the three points above) is
shown by the Skill to whoever runs an exploration, and by the installer up
front; your agreement is recorded locally and checked before every run. The
**operator notice** is for whoever starts the server: it covers data-source
terms, credentials, and what the server stores, and the server refuses to
start until it has been acknowledged.

## How it works

```
your agent ──(Skill: judgment)──► patent-checker MCP server ──► EPO OPS
   │                                   │  deterministic fetch,      Google Patents
   │  reads your code, writes           │  normalization, cache
   ▼  the report                        ▼
.patent-checker/reports/…        shared document cache
```

1. The Skill reads your codebase, lists the technical features that could be
   claimed, keeps common technique (what a standard, a library or the
   platform ships as is) out of the search and says so in the report,
   translates the rest into patent vocabulary and builds search queries.
2. The MCP server runs the queries against EPO OPS, fetches the candidate
   documents (claims from Google Patents, bibliography and legal status
   from OPS) and caches every document so nothing is fetched twice.
3. The Skill screens the candidates in stages, maps claim elements to your
   features and writes a report: what was searched, what was found, how
   each candidate relates to your code, and what was *not* covered.
4. The Skill also keeps a **ledger** of the exploration in your project
   (features, queries, screened families, monitored patents and a snapshot
   of their status). The next run starts from it: the server compares the
   stored snapshots with the current records, and the new report opens with
   a summary without patent terms followed by what changed.

The server only ever receives public patent data: search expressions,
publication numbers, family identifiers, dates, and status snapshots it
returned earlier. Your source code, your project description and the ledger
never leave your machine: the analysis happens inside your agent.

## Prerequisites

- **An AI coding agent** that supports Agent Skills and MCP: Claude Code,
  OpenAI Codex CLI, Cursor, Gemini CLI, GitHub Copilot CLI, OpenCode,
  OpenHands or Hermes Agent.
- **[uv](https://docs.astral.sh/uv/)** for the command-line tool and
  installer; uv fetches Python 3.12 or newer by itself when your machine
  has none. Python is also the easiest way to generate the bearer token
  below.
- **Docker with Compose v2**, if you run the server in a container
  (recommended). Without Docker the server runs as an ordinary process.
- **An EPO Open Patent Services account** (recommended). Register at
  <https://developers.epo.org/>, then create an app to obtain a consumer
  key and secret. **Apply early: approval is manual and typically takes
  about a business day.** Without it the server runs in
  [degraded mode](#without-an-epo-ops-account-degraded-mode).

## The bearer token

The server listens on HTTP, and every MCP client must present a **bearer
token** on every request: a secret string that only your server and your
own agents know. It is what stops any other program on the machine, or on
the network if you ever expose the port, from using your server and your
EPO OPS quota. There is no account or sign-up behind it; you make the token
yourself, once, and give the same value to the server and to the installer.

Generate one (any 32 random bytes will do):

```sh
python3 -c "import secrets; print(secrets.token_urlsafe(32))"      # macOS, Linux
```

```powershell
python -c "import secrets; print(secrets.token_urlsafe(32))"       # Windows
```

Where it goes:

- **Docker Compose**: into the file `secrets/server_token.txt` next to
  `compose.yaml`.
- **Without Docker**: into `.env` as `PATENT_CHECKER_SERVER_TOKEN=…` (or a
  file named by `PATENT_CHECKER_SERVER_TOKEN_FILE`).
- **Your agents**: `patent-checker install` asks for it (or reads it from
  `--token-file`), and writes it into each agent's MCP configuration.

Without a token the HTTP server does not start. The one exception is
`patent-checker serve --transport stdio`, which has no token because the
agent starts the server as a child process running with your own
permissions; that is a special case for a single local client, not the
default. Treat the token like a password: keep the files that hold it
private, and rotate it by writing a new value and re-running
`patent-checker install`.

## Without an EPO OPS account (degraded mode)

If you leave the OPS credentials unset (empty `secrets/ops_key.txt` and
`ops_secret.txt`, or no `PATENT_CHECKER_OPS_KEY` in `.env`), the server
starts in **degraded mode** and says so at start-up and in `server_status`.

- Still works: fetching the claims of a document from Google Patents when
  your agent already knows its publication number, publication-number
  normalization, the offline helpers (deduplication, batch verification).
- Unavailable: patent searches, bibliographic records, legal status and
  patent families. The Skill switches to its degraded procedure, in which
  your agent finds candidate publication numbers through its own web
  search; coverage drops, and the report says so.

Degraded mode is meant for a first look. For a real exploration, get an OPS
account and restart the server with the credentials in place.

## Install the server

Both routes need the operator notice acknowledged and a bearer token.

### Option A: Docker Compose (recommended)

```sh
mkdir patent-checker-server && cd patent-checker-server
curl -fsSLO https://raw.githubusercontent.com/xhighhongo41/patent-checker/main/compose.yaml
mkdir secrets

# 1. EPO OPS credentials (or leave both files empty for degraded mode)
printf '%s' 'YOUR_OPS_CONSUMER_KEY'    > secrets/ops_key.txt
printf '%s' 'YOUR_OPS_CONSUMER_SECRET' > secrets/ops_secret.txt

# 2. The bearer token (see above)
python3 -c "import secrets; print(secrets.token_urlsafe(32))" > secrets/server_token.txt
chmod 600 secrets/*.txt

# 3. Read the operator notice (add --lang ja for Japanese), then acknowledge it
docker compose run --rm patent-checker serve --show-operator-notice
echo 'PATENT_CHECKER_OPERATOR_CONSENT=1.0' >> .env

# 4. Start
docker compose up -d
curl -fsS http://127.0.0.1:8642/health
```

On Windows, create the three files with PowerShell instead of `printf`
(`Set-Content` writes a byte-order mark that would become part of the
token, so use .NET directly):

```powershell
New-Item -ItemType Directory -Force secrets | Out-Null
New-Item -ItemType File -Force secrets\ops_key.txt, secrets\ops_secret.txt | Out-Null   # empty: degraded mode
$token = python -c "import secrets; print(secrets.token_urlsafe(32))"
[IO.File]::WriteAllText("$PWD\secrets\server_token.txt", $token)
```

The image is published as `ghcr.io/xhighhongo41/patent-checker` and
`docker.io/xhighhongo41/patent-checker` with tags `X.Y.Z`, `X.Y` and
`latest`. The container binds `0.0.0.0` internally, but Compose publishes
the port o