# Open Patent MCP Gateway

多源专利检索 MCP 网关 — 让 AI Agent 直接搜索全球专利数据库（Google Patents、BigQuery、EPO OPS）。

## 给你的 AI Agent 加上专利检索（30 秒）

在 GPT Work / Cursor / Claude Desktop 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "open-patent": {
      "url": "https://open-patent-mcp-gateway.the0shell0.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer dev-token-local"
      }
    }
  }
}
```

然后直接对 AI 说：「帮我查一下 lithium battery 固态电解质相关的专利」即可。

## 可用的 MCP 工具

| 工具 | 用途 | 是否消耗配额 |
|------|------|:---:|
| `search_patents` | 关键词/分类号/申请人/日期检索，支持 basic/standard/deep 三档 | 是 |
| `get_patent` | 按公开号/申请号获取单条专利详情 | 否 |
| `get_family` | 获取专利族成员和优先权链 | 否 |
| `get_citations` | 获取引证文献（前引/后引，审查员/申请人） | 否 |
| `get_legal_status` | 获取法律状态和法律事件 | 否 |
| `get_drawings` | 获取附图元数据和图片 URL | 否 |
| `list_providers` | 列出已接入的数据库及其能力 | 否 |
| `check_provider_status` | 检查指定数据库的认证和可用性 | 否 |
| `get_quota_status` | 查询各数据库的配额余量和重置时间 | 否 |
| `guide_setup` | 引导用户独立部署（不接收 key，只返回步骤） | 否 |

## 检索档位

| 档位 | 数据源 | 配额消耗 | 适用场景 |
|------|--------|:---:|------|
| `basic` | EPO OPS | 免费 | 快速查证、已知分类号检索 |
| `standard` | EPO OPS + Google Patents | 1 次 SerpApi | 探索性关键词搜索 |
| `deep` | 全部 + BigQuery 全量历史 | 1 次 SerpApi + ~0.24 TiB | 穷尽式现有技术检索 |

## 想自己部署？（v0.2 双模式）

本项目支持两种使用模式：

- **共享模式（默认）**：直接用上方 30 秒配置接入维护者的 Worker 与 API，零配置。
- **独立模式（可选升级）**：注册自己的 API 与 Cloudflare，部署私有实例。BYOK，密钥只在你自己的 Worker 上。

需要独立部署时，任选一种引导方式：

| 方式 | 适合 | 入口 |
|------|------|------|
| 浏览器引导页 | 非技术用户 | 打开 `https://open-patent-mcp-gateway.the0shell0.workers.dev/setup` |
| AI 引导 | 在 GPT Work 等客户端里直接让 AI 帮你部署 | 对 AI 说「教我独立部署这个 MCP」→ 触发 `guide_setup` 工具 |
| CLI 向导 | 喜欢终端的用户 | `npm run setup` |
| 静态文档 | 离线参考 | [docs/getting-api-keys.md](docs/getting-api-keys.md) |

四种形态共用同一份数据源 `src/onboarding/steps.ts`，内容始终一致。

独立模式最低只需 SerpApi 一个 key（standard 档位可用）；EPO OPS 与 BigQuery 为可选增强。详细路线图见 [docs/v0.2-roadmap.md](docs/v0.2-roadmap.md)。

```bash
git clone https://github.com/lgxycsg/open-patent-mcp-gateway.git
cd open-patent-mcp-gateway
npm install
npm run setup        # 交互式向导：引导注册 + 验证 key + 生成 .dev.vars
npx wrangler deploy  # 部署到你的 Cloudflare 账号
```

部署后得到你自己的 `https://xxx.workers.dev`，替换上方 30 秒配置中的 URL 即可。

## 项目结构

```
src/
├─ core/
│  ├─ mcp/server.ts          # MCP server + 10 tools + HTTP/stdio transport
│  ├─ models/                 # PatentRecord, SearchQuery, Identifier
│  ├─ errors/errors.ts        # 15 error codes + secret redaction
│  ├─ routing/router.ts       # Provider router (single/parallel/fallback)
│  ├─ normalization/number.ts # Publication number normalization
│  ├─ deduplication/index.ts  # Dedup + family aggregation
│  └─ security/secrets.ts     # Credential management + token validation
├─ onboarding/                # v0.2 独立模式引导（单一数据源 + 网页 + 验证）
│  ├─ steps.ts                # 4 种引导形态共用的步骤数据源
│  ├─ setup-page.ts           # Worker /setup 路由的 HTML 渲染器
│  └─ verify.ts               # /setup/verify 服务端 key 验证（无状态）
├─ providers/
│  ├─ mock/index.ts           # Mock provider (testing)
│  ├─ epo_ops/                # EPO OPS (official API, OAuth)
│  ├─ google_patents/         # Google Patents via SerpApi
│  ├─ bigquery/               # Google Patents Public Datasets
│  ├─ types.ts                # Provider interface + Manifest
│  └─ registry.ts             # Static provider registry
├─ worker.ts                  # Cloudflare Workers entry
└─ index.ts                   # Node.js entry
```

## 测试

```bash
npm run typecheck   # 类型检查
npm test            # 388 个单元测试
npm run build       # 编译
```

## 许可证

MIT