IP-MCP

特許庁の公式「特許情報取得API」を MCP サーバー化して、Claude Desktop / Claude Code / iPhone Claude から自然言語で日本特許を引く。

番号変換・経過情報・登録情報・引用文献・出願人検索・五庁ファミリー (OPD)、合計 12 ツール（公式）+ 1 ツール（Google Patents キーワード検索、独立分離）。

🇬🇧 English: README.en.md

30 秒で何ができるか

Claude にこう聞ける（裏で MCP ツールが連鎖実行）:

ユーザー: 「特開2010-228687 の登録状況と引用文献を教えて」

Claude (内部動作):

1. jpo_convert_patent_number で公開番号→出願番号 (2009080841)

2. jpo_get_patent_registration で登録情報 (登録 5094774、株式会社日立製作所、満了 2029-03-30、権利存続中)

3. jpo_get_patent_citations で引用文献 20 件

回答: 「列車制御地上装置およびシステム」(株式会社日立) は登録番号 5094774 として 2012-09-28 に登録、現在も権利存続中、満了予定 2029-03-30。引用文献は 20 件、検索報告書 / 拒絶理由から特許文献のみ（非特許文献なし）...

キーワード検索は外部ツール (external_search_patents_by_keyword) で 明示的に分離。LLM が「公式データ」と「参考データ」を取り違えないよう、レスポンスの source フィールドで識別を強制。

既存手段との比較

アーキテクチャ

flowchart LR
    User["Claude Desktop /<br/>Claude Code /<br/>iPhone Claude"]
    Caddy["Caddy<br/>(Let's Encrypt)"]
    OAuth["OAuth 2.1<br/>(SQLite-backed)"]

    User -->|"HTTPS + OAuth"| Caddy
    Caddy -->|"http+SSE"| MCP

    subgraph Docker["Docker container (Python 3.12 + FastMCP)"]
      MCP["MCP server<br/>:8765"]
      Official["tools_official/<br/>(jpo_* 12 tools)"]
      External["tools_external/<br/>(external_* 1 tool)"]
      MCP --> Official
      MCP --> External
      MCP -.->|"persisted"| OAuth
    end

    Official -->|"OAuth2 password grant"| JPO[("JPO 特許情報取得API")]
    External -->|"3s spacing + 503 backoff"| GP[("Google Patents XHR")]

    classDef boundary stroke-dasharray: 5 5
    class External,GP boundary

架構の核:

• tools_official/ (公式 JPO) と tools_external/ (非公式 Google Patents) は コード階層・呼び出し元・ロガー完全分離。tools_official/ から tools_external/ への import を boundary test で禁止

• 同一データソース内の再試行のみ許可 (401→トークン更新 / 303→指数バックオフ)。失敗時の自動フォールバック禁止 — LLM に判断させる

• レスポンスは必ず {"source": "jpo_official"} または {"source": "google_patents_unofficial"}

クイックスタート

ローカル開発

cp .env.example .env          # JPO_USERNAME / JPO_PASSWORD を記入
chmod 600 .env
docker compose up -d --build

LAN デプロイ (no-auth)

docker-compose.override.yml を作成して LAN IP にバインド (リポジトリには docker-compose.override.yml.example あり):

services:
  ip-mcp:
    ports:
      - "192.0.2.10:8765:8765"   # 自分の LAN IP

Claude Desktop / Code 設定:

{
  "mcpServers": {
    "ip-mcp": {
      "transport": { "type": "sse", "url": "http://192.0.2.10:8765/sse" }
    }
  }
}

Codex CLI の direct HTTP MCP (codex mcp add --url) は Streamable HTTP を前提にするため、 Codex から直接使うデプロイでは URL は /mcp を登録します。

CODEX_HOME=/path/to/codex-home codex mcp add ip-mcp --url https://<your-subdomain>.example.com/mcp
CODEX_HOME=/path/to/codex-home codex mcp login ip-mcp

SSE クライアントでは /sse を登録します。 Codex direct HTTP と SSE クライアントを同じ公開サーバーで併用する場合は、 MCP_TRANSPORT=both で起動すると /mcp と /sse の両方を同じ OAuth 設定で提供できます。 単一クライアントだけなら MCP_TRANSPORT=sse (default) または MCP_TRANSPORT=streamable-http も利用できます。

iPhone Claude / claude.ai (公開、OAuth 2.1)

リバースプロキシで HTTPS + サブドメイン公開し、MCP_OAUTH_MASTER_PASSWORD + MCP_OAUTH_ISSUER_URL をセット。OAuth 2.1 (DCR + PKCE + マスターパスワード認可) を要求します。クライアントトークンは SQLite に永続化されコンテナ再起動でも生き残り。

MCP_OAUTH_MASTER_PASSWORD=<24+ chars random>
MCP_OAUTH_ISSUER_URL=https://<your-subdomain>.example.com
# 任意: MCP_OAUTH_DB_PATH=/app/data/oauth.db

詳細は PLAN.md §9-§10 と OPERATIONS.md。

公開ツール一覧

レスポンス: {"ok": true, "source": "jpo_official", "data": {...}, "remaining_today": "..."}

レスポンス: {"ok": true, "source": "google_patents_unofficial", "data": {...}}

公式 API はキーワード検索を提供しない（番号ルックアップ型のみ）ため独立。失敗時は {"ok": false, "kind": "search_unavailable"} を返し、公式ツールに自動フォールバックしない。

レート制約（運用上の注意）

JPO 公式 API は自主制御責任を運用者に課している:

• 分次レート: /api/patent/* は 10 req/min、/opdapi/* は 5 req/min（OPD は別系統で別カウント）

• 日次クォータ: エンドポイントごとに 30〜800/日（2026 年 3 月から国内系は 2 倍緩和済）。実残量は各レスポンスの result.remainAccessCount が信頼ソース

• jpo_fetch_full_record は内部で 4 つの公式エンドポイントを並列で叩くため、1 コール = 4 つの別々の日次クォータから 1 ずつ消費する（同一クォータから 4 ではない）

ツールごとのエンドポイント対応表と、運用上の閾値の感覚は OPERATIONS.md §JPO API レート制約とクォータ を参照。

ドキュメント

• 📐 PLAN.md — 設計計画書（アーキテクチャ・全ツール一覧・段階計画）

• 🤖 CLAUDE.md — Claude Code 向け操作ガイド（譲れない設計規則・JPO API の罠）

• 🔧 OPERATIONS.md — 運用手順（アクセスログ集計・マスターパスワード rotate・トラブルシュート）

docker-compose.yml のポートバインドはデフォルト 127.0.0.1:8765 (= 同マシンからのみ)。LAN 公開する場合は docker-compose.override.yml を別途作成 (.gitignore 済) して上書きしてください。

ライセンス

MIT