IP-MCP

Английский · 日本語

Запрашивайте японские патенты на естественном языке через Claude. IP-MCP оборачивает официальный «Patent Information Retrieval API» Японского патентного ведомства в MCP-сервер, поэтому Claude Desktop, Claude Code и iPhone Claude могут определять номера патентов, проверять статус регистрации, получать цитаты и просматривать семейства патентов пяти ведомств — 12 инструментов официального API плюс 1 намеренно изолированный инструмент поиска по ключевым словам.

Что можно спросить у Claude за 30 секунд

Вы: «Расскажи статус регистрации и уровень техники для JP-2010-228687».

Claude (под капотом):

1. jpo_convert_patent_number → номер заявки 2009080841

2. jpo_get_patent_registration → регистрация 5094774, Hitachi Ltd., истекает 2029-03-30, действует

3. jpo_get_patent_citations → 20 ссылок на предшествующий уровень техники

Ответ: «Train Control Ground Equipment and System» (Hitachi Ltd.) был зарегистрирован как JP5094774 2012-09-28, в настоящее время действует, срок до 2029-03-30. 20 ссылок на предшествующий уровень техники из отчёта о поиске и оснований отказа — все патентная литература (непатентной нет)…

Поиск по ключевым словам вынесен в отдельный инструмент (external_search_patents_by_keyword, Google Patents XHR). LLM никогда не сможет случайно переключиться с официального API на неофициальный источник — каждый ответ содержит явное поле source.

Related MCP server: MCP-ndl-search

Как это сравнивается

Почему для поиска по ключевым словам предусмотрена отдельная категория инструментов?

Официальный JPO API ориентирован только на поиск по номеру — каждый эндпоинт принимает номер заявки / публикации / регистрации, код заявителя или точное совпадение имени заявителя. Поиск по ключевым словам / IPC / F-term / диапазону дат / частичному имени в спецификации отсутствует. Поэтому:

• tools_official/ — имена начинаются с jpo_*, ответ {"source": "jpo_official", …}

• tools_external/ — имена начинаются с external_*, ответ {"source": "google_patents_unofficial", …}

• Пограничный тест запрещает любой import из tools_external/ в tools_official/. Запрещено автоматическое переключение — решает только LLM.

Архитектура

flowchart LR
    User["Claude Desktop /<br/>Claude Code /<br/>iPhone Claude"]
    CF["Cloudflare<br/>(Edge TLS + Tunnel)"]
    Caddy["Caddy<br/>(CF Origin Cert)"]

    User -->|"HTTPS + OAuth"| CF
    CF -->|"outbound from home<br/>via cloudflared"| 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)"]
      OAuth["OAuth 2.1<br/>SQLite-backed"]
      MCP --> Official
      MCP --> External
      MCP -.->|"persisted"| OAuth
    end

    Official -->|"OAuth2 password grant"| JPO[("JPO Patent 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) полностью разделены на уровне иерархии кода, вызовов и логирования. Пограничный тест блокирует любой import из tools_external/ в tools_official/.

• Повторная попытка допускается только в пределах одного источника данных (401 → обновление токена; 303 → экспоненциальная задержка). Автоматический переход между источниками при сбое запрещён — решает LLM.

• Каждый ответ содержит {"source": "jpo_official"} или {"source": "google_patents_unofficial"}.

Быстрый старт

Локальная разработка

cp .env.example .env          # Fill in JPO_USERNAME / JPO_PASSWORD
chmod 600 .env
docker compose up -d --build

Развёртывание в LAN (без аутентификации)

Создайте docker-compose.override.yml, чтобы привязаться к вашему LAN-интерфейсу (в репозитории есть docker-compose.override.yml.example):

services:
  ip-mcp:
    ports:
      - "YOUR_SERVER_IP:8765:8765"   # your LAN IP

Конфигурация Claude Desktop / Code:

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

Codex CLI поддерживает прямое HTTP MCP (codex mcp add --url) и ожидает Streamable HTTP, поэтому при прямом использовании из Codex регистрируйте путь /mcp:

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

SSE-клиенты регистрируют /sse. Чтобы обслуживать и прямое HTTP-подключение Codex, и SSE-клиенты же одного публичного сервера, запускайте с MCP_TRANSPORT=both, чтобы открыть /mcp и /sse под одним OAuth-конфигом. Для одного клиента также подойдут MCP_TRANSPORT=sse (по умолчанию) или MCP_TRANSPORT=streamable-http.

iPhone Claude / claude.ai (публично, OAuth 2.1)

Для публичного доступа рекомендуется связка Cloudflare Tunnel + Caddy (CF Origin Cert) — cloudflared устанавливает исходящее соединие из вашей домашней сети к границе CF, поэтому проброс портов на роутере не нужен, а hairpin NAT не создаёт проблем. Традиционный обратный прокси с Let's Encrypt и прямым 443-портобразом также работает. В любом случае задайте 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-host.example.com
# optional: 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"} и никогда не переходит на официальный инструмент.

Ограничения частоты запросов (эксплуатация)

Официальный API JPO переиспользует оператору ответственность за соблюдение ограничений самим отправителем:

• Ограничение в минуту: /api/patent/* — 10 запросов/мин, /opdapi/* — 5 запр/мин (OPD тарифицируется в собственном бакете).

• Дневная квота: 30–800/день на эндпоинт (национальные квоты удвоены в марте 2026). Авторитетный счётчик — это result.remainAccessCount, возвращённый в каждом ответе.

• jpo_fetch_full_record опрашивает 4 официальных эндпоинта параллельно, поэтому один вызов тратит 1 единицу из каждой из 4 отдельных суточных квот (не 4 из одной квоты). Узкое местоположение — наименьшая квота.

Соответствие инструментов эндпоинтам и операционные пороги см. в OPERATIONS.md §JPO API レート制約とクォータ (на японском).

Документация

• 📐 PLAN.md — План проектирования (архитектура, полныйсписок инструментов, поэтапный план) [JP]

• 🤖 CLAUDE.md — Руководство по Claude Code (непреложаемые правила проектирования, подводные камни JPO API) [JP]

• 🔧 OPERATIONS.md — Оперирующая книга (сводка журнала доступа, ротация мастер-пароля, устранение проблем) [JP]

Привязка порта в docker-compose.yml по умолчанию равна 127.0.0.1:8765 (только для той же машины). Чтобы открыть доступ в LAN, создайте отдельный docker-compose.override.yml (уже находится .gitignore) для внесения изменения.

Лицензия

MIT — см. LICENSE.