Patent Checker

Patent Checker

日本語版: README_ja.md

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.

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):

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

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)

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):

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))"

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 on your machine's loopback only (127.0.0.1:8642). The Host headers the server accepts are the loopback names localhost, 127.0.0.1 and ::1, which its HTTP layer always allows, plus any name you add with PATENT_CHECKER_SERVER_ALLOWED_HOSTS — nothing else. Fetched documents, search results and the request log live in the named volume patent-checker-data. The container runs as an unprivileged user on a read-only filesystem with all Linux capabilities dropped; if your Docker engine rejects one of those settings, the four lines under # Hardening in compose.yaml can be removed without changing what the server does.

The secret files are read once at start; empty OPS files mean "not configured" (degraded mode). If you run Docker Engine on Linux under an account that is not UID 1000, see the note on file ownership in secrets/README.md.

To share one server between several machines (a tailnet, a VPN, a LAN), see docs/deploy-lan.md: it covers Tailscale Serve, a TLS-terminating proxy in front of the same container, and plain HTTP on a private network, and what each leaves to you.

Option B: without Docker

uv tool install patent-checker

mkdir patent-checker-server && cd patent-checker-server curl -fsSLO https://raw.githubusercontent.com/xhighhongo41/patent-checker/main/.env.example cp .env.example .env

Then edit .env:

1. Put the EPO OPS key and secret in PATENT_CHECKER_OPS_KEY and PATENT_CHECKER_OPS_SECRET (leave them empty for degraded mode).
2. Generate a bearer token (see above) and put it in PATENT_CHECKER_SERVER_TOKEN.
3. Read the operator notice with patent-checker serve --show-operator-notice (add --lang ja for Japanese) and set PATENT_CHECKER_OPERATOR_CONSENT=1.0.

A minimal .env looks like this:

PATENT_CHECKER_OPS_KEY=YOUR_OPS_CONSUMER_KEY

PATENT_CHECKER_OPS_SECRET=YOUR_OPS_CONSUMER_SECRET PATENT_CHECKER_SERVER_TOKEN=the-token-you-generated PATENT_CHECKER_