Patent Remote MCP Server

一个部署在 Cloudflare Workers 上的 remote MCP server，让 Claude（claude.ai / Desktop / Cowork / mobile 全端）能在对话中实时检索专利数据。第一数据源为 EPO OPS（European Patent Office Open Patent Services），通过 OAuth 2.1 + Cloudflare Access 控制访问。

暴露的工具（均只读 readOnlyHint: true）

工具	用途	主要入参
search_patents	按关键词/申请人/分类号检索，返回命中概览	query、limit(≤25, 默认10)
get_patent_details	取单篇著录项目 + 摘要	publication_number、format
get_patent_claims	取完整权利要求（分条）	publication_number、format
get_patent_family	取 INPADOC 专利族 + 法律状态	publication_number、format
search_patents_google	Google Patents 引擎高召回/跨术语检索（经 SerpApi）	query、limit、country、status、sort

format 为 epodoc（默认）或 docdb。输出统一为清洗后的结构化 JSON。

何时用哪个检索：search_patents 走 EPO OPS（标题摘要字面匹配，免费、全球书目）；search_patents_google 走 Google Patents（自带相关性排序 + 同义/语义扩展，召回高，治术语变体漏检如 siRNA↔"iRNA agent"）， 需要 SERPAPI_KEY（免费层 250 次/月）。详情/权利要求/同族统一用 OPS 的 get_patent_*。 search_patents_google 未配置 SERPAPI_KEY 时会返回 actionable 提示，不影响其余 4 个工具。

架构

Claude (MCP client)
   │  OAuth 2.1 (Streamable HTTP)
   ▼
Cloudflare Worker
   ├── @cloudflare/workers-oauth-provider   ← 对 Claude 是 OAuth provider
   ├── 上游身份：Cloudflare Access (SaaS/OIDC)  ← 团队邮箱门禁
   └── createMcpHandler（无状态）→ EPO OPS REST（client-credentials）
   ▼
EPO OPS API (ops.epo.org)

• 对 Claude：OAuth provider（Dynamic Client Registration，无需预置 client id/secret）。
• 对 OPS：普通 API client（client-credentials），Worker 持有 consumer key/secret。
• 数据源经 PatentProvider 接口抽象（src/provider.ts），预留 Google Patents 扩展位。

目录

src/
├── index.ts        # 入口：OAuthProvider 装配 createMcpHandler + Access
├── mcp.ts          # 4 个工具定义/handler
├── access.ts       # Cloudflare Access 上游 OAuth handler（/authorize、/callback）
├── ops/
│   ├── auth.ts     # OPS client-credentials + token 缓存
│   ├── client.ts   # OPS REST 调用、throttling、重试
│   └── parse.ts    # OPS XML → 结构化 JSON
├── provider.ts     # PatentProvider 接口 + OpsProvider
└── types.ts

---

部署步骤

0. 前置（需自行准备）

1. EPO OPS 凭据：在 EPO Developer Portal 注册应用，拿到 Consumer Key + Consumer Secret。
2. Cloudflare 账户，并本地 npx wrangler login。
3. Cloudflare Access for SaaS (OIDC) 应用（见下「配置 Cloudflare Access」）。

1. 安装与本地编译

npm install
npm run typecheck      # tsc --noEmit，确认编译通过
npx wrangler dev       # 本地起服务（需 .dev.vars，见 .dev.vars.example）

2. 创建 KV namespace

npx wrangler kv namespace create OAUTH_KV

把返回的 id 填入 wrangler.jsonc 的 kv_namespaces[0].id（替换 REPLACE_WITH_KV_NAMESPACE_ID）。

3. 注入 secrets（不进 git）

npx wrangler secret put OPS_CONSUMER_KEY
npx wrangler secret put OPS_CONSUMER_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY      # 用 `openssl rand -hex 32` 生成
npx wrangler secret put ACCESS_CLIENT_ID
npx wrangler secret put ACCESS_CLIENT_SECRET
npx wrangler secret put ACCESS_AUTHORIZATION_URL
npx wrangler secret put ACCESS_TOKEN_URL
# 可选：npx wrangler secret put ACCESS_JWKS_URL
# 可选（启用 search_patents_google）：npx wrangler secret put SERPAPI_KEY

⚠️ Windows 注意：用 wrangler secret put 经 PowerShell 管道注入会在值开头混入 BOM(U+FEFF)， 导致 worker 端 URL/解析失败。请改用 git-bash 纯字节注入： printf '%s' '你的值' | node node_modules/wrangler/bin/wrangler.js secret put NAME

4. 部署

npx wrangler deploy
# → https://patent-mcp-server.<account>.workers.dev

5. 配置 Cloudflare Access（SaaS / OIDC）

在 Cloudflare Zero Trust 控制台：

1. Access → Applications → Add an application → SaaS → OIDC。
2. Redirect URL 填：https://patent-mcp-server.<account>.workers.dev/callback
3. Scopes 勾选 openid、email、profile。
4. 保存后得到 Client ID / Client Secret 与三个端点 URL （Authorization / Token / JWKS，形如 https://<team>.cloudflareaccess.com/cdn-cgi/access/sso/oidc/<app-id>/...）—— 分别填入第 3 步对应的 secret。
5. 在该应用的 Access Policy 里把允许的团队成员邮箱 / 公司域配进去（只有通过的人能连）。

6. 验证

Phase 1（数据链路，可临时用 Access bypass 策略或本地 dev 验证）

用 MCP Inspector 连 https://patent-mcp-server.<account>.workers.dev/mcp，逐个验证： search_patents → get_patent_details → get_patent_claims → get_patent_family， 用已知公开号（如 US2025236871A1）确认能取回 claims，均返回结构化 JSON。

Phase 2（OAuth）

在 claude.ai → 设置 → Connectors → Add custom connector，填入 https://patent-mcp-server.<account>.workers.dev/mcp，走完 Access/OAuth 授权， 确认能 List Tools 并调用。可自然语言提问，如：

「查 RBP4 GalNAc siRNA 相关专利的权利要求」

---

验收清单

• [ ] MCP Inspector 列出 4 个工具且均能成功调用返回结构化 JSON
• [ ] OPS token 正确缓存（连续多次调用不重复打 auth 端点）
• [ ] 命中 throttling/配额时返回 actionable 错误而非崩溃
• [ ] claude.ai 上作为 custom connector 成功连接并通过 OAuth
• [ ] 自然语言提问能触发工具并返回有效结果

---

重要提示

🔒 保密性

所有检索 query 与返回数据会经过 Cloudflare 边缘。本服务面向 landscape / 公开专利分析。 涉及未公开 FTO 思路或精准竞品狙击的高敏感检索，应在调用前将 query 泛化，或改用自托管链路 （不在本方案范围）。

⚖️ OPS 限流

尊重 OPS 的 X-Throttling-Control（green/yellow/red）。本实现在 red 状态下短暂退避后单次重试， 配额相关错误返回 actionable 提示而非崩溃，避免触发封禁。

🛡️ 最小权限

所有工具只读，不实现任何写/删除能力。

---

与 spec 的差异（按 spec「以官方文档为准并记录差异」要求记录）

1. OPS 认证端点路径修正：spec §5.1 写 https://ops.epo.org/3.2/rest-services/auth/accesstoken， 实际正确路径为 https://ops.epo.org/3.2/auth/accesstoken——auth 端点不在 /rest-services/ 下，仅数据端点在其下。代码（src/ops/auth.ts）以正确路径实现。
2. OPS 以 XML 为主：spec §5.2 把 JSON 当首选。实际上 OPS 数据端点基本只返回 XML，故统一请求 Accept: application/xml 并由 src/ops/parse.ts（fast-xml-parser）解析为结构化 JSON， 保持单一解析路径。
3. OPS XML schema 各 office 字段略有差异，parse.ts 的字段提取为 best-effort，建议上线时对照 真实响应微调。

扩展位（Phase 3，本次未实现）

PatentProvider 接口下预留了 GooglePatentsProvider（SerpApi/Apify）的实现位与配置项 （SERPAPI_KEY），见 src/provider.ts 与 wrangler.jsonc 注释。接入时无需改动工具层。