内容
# 韩国专利MCP（KIPRIS）
特허청 **KIPRIS Plus** 开放API服务器，作为MCP工具。搜索专利、实用新型、商标、设计，支持关键词/项目/申请人/权利人搜索，并可通过申请号查询详细书目信息。
> 参照korean-law-mcp架构 - lib/tools层分离，fetch重试，密钥掩码，Zod验证，无状态HTTP，TTL缓存，响应大小限制， `[NOT_FOUND]` 防幻觉模式。
## 工具列表
| 工具 | 说明 | KIPRIS操作 |
|------|------|-------------------|
| `search_patents` | **自由搜索** - 关键词搜索专利、实用新型（发明名称、摘要、权利要求、申请人） | `freeSearchInfo` |
| `search_patents_advanced` | **项目搜索** - IPC、发明名称、摘要、权利要求范围、申请人、发明者组合精确搜索 | `getAdvancedSearch` |
| `search_by_applicant` | **申请人搜索** - 企业、个人申请人名称搜索申请列表 | `applicantNameSearchInfo` |
| `search_by_rightholder` | **权利人搜索** - 当前专利权持有者（权利转移反映） | `rightHolerSearchInfo` |
| `get_patent_detail` | **书目详情** - 申请号 → 申请人、发明者、IPC、审查官、权利要求数、最终处置、注册状态 | `getBibliographyDetailInfoSearch` （备用 `applicationNumberSearchInfo`） |
| `search_trademark` | **商标搜索** - 商标名关键词（申请状态、商品类别、权利人、样品图像） | `trademarkInfoSearchService/getWordSearch` |
| `search_design` | **设计搜索** - 商品名关键词（设计分类、申请状态、图纸图像） | `designInfoSearchService/getWordSearch` |
## 安装与构建
```bash
npm install
npm run build
```
## 认证密钥
需要KIPRIS Plus认证密钥。访问 [plus.kipris.or.kr](https://plus.kipris.or.kr) 注册后，分别申请所需的服务（专利/实用新型/商标/设计），即可获得单一认证密钥（data.go.kr颁发的密钥也是相同的密钥体系）。
```bash
cp .env.example .env
# 在.env中输入KIPRIS_API_KEY= 발급키
```
> **权限以操作（详细功能）为单位**。如果未申请某个功能，将返回`resultCode 30`（未注册），该功能将被拒绝。例如，如果只申请了专利，则`search_trademark`/`search_design`将返回30。只有在额外申请了相关服务后，这些功能才会立即生效。
## 运行
### STDIO（Claude Desktop / Claude Code）
```json
{
"mcpServers": {
"korean-patent": {
"command": "node",
"args": ["/绝对路径/korean-patent-mcp/build/index.js"],
"env": { "KIPRIS_API_KEY": " 발급키" }
}
}
}
```
### HTTP（无状态，云部署）
```bash
node build/index.js --mode http --port 8000
# 密钥：请求头（apikey / x-api-key / kipris-key / Authorization: Bearer）或服务器环境变量备用
```
请求的密钥（BYOK）优先，如果没有，则备用服务器 `KIPRIS_API_KEY`。备用调用的免费额度（1,000次/月）保护，设有全局上限 `FALLBACK_RATE_LIMIT_RPM`。
**HTTP模式环境变量**
| 变量 | 默认值 | 说明 |
|------|------|------|
| `CORS_ORIGIN` | `*` （警告） | 允许域名，建议生产环境明确 |
| `RATE_LIMIT_RPM` | `60` | IP每分钟请求限制 |
| `FALLBACK_RATE_LIMIT_RPM` | `60` | 无密钥请求的服务器密钥备用全局上限，`0`则阻止备用（强制BYOK） |
| `TRUST_PROXY` | `1` | Express信任代理单元，`true`/`all`存在XFF伪造风险 |
| `MCP_BODY_LIMIT` | `100kb` | POST正文大小限制 |
Docker / Fly.io:
```bash
flyctl launch --dockerfile Dockerfile
flyctl secrets set KIPRIS_API_KEY= 발급키
flyctl deploy
```
## 使用示例（用户查询 → 工具）
| 用户询问 | 工具调用 |
|------------------|-----------|
| "给我找有关无人机电池的专利" | `search_patents(query="无人机电池")` |
| "G06N分类AI专利中的三星专利" | `search_patents_advanced(ipc="G06N", applicant="三星")` |
| "发明名称包含'折叠'" | `search_patents_advanced(inventionTitle="折叠")` |
| "现代汽车申请的专利列表" | `search_by_applicant(applicant="现代汽车")` |
| "LG目前持有的专利" | `search_by_rightholder(rightHolder="LG电子")` |
| "这个申请号的详细信息" | `get_patent_detail(applicationNumber="10-2016-0172841")` |
| " 카카오商标注册了吗？" | `search_trademark(query="카카오")` |
| "椅子设计注册案例" | `search_design(query="椅子")` |
**通用选项**
- `numOfRows` （1~100，默认10），`pageNo` （默认1）- 支持分页
- `patent` / `utility` - 搜索对象（专利/实用新型）
- `sortSpec` - `AD`（申请日） `OPD`（公开日） `GD`（公告日） `RD`（注册日） `PD`（优先日）
- `descSort` - 降序（最新顺序）与否
- `withAbstract` - （自由搜索）是否包含摘要正文
## 功能与限制（实测为准）
- **搜索运算符**：自由搜索关键词的 `+ * ? ! ^` 被解释为KIPRIS搜索运算符。例如，`C++` 中的 `+` 作为运算符可能会导致结果不符预期。建议使用精确搜索（`search_patents_advanced`）进行准确搜索。
- **海外专利** 是单独的服务（`ForeignPatentAdvencedSearchService`），目前未注册（`resultCode 30`），不支持。如需支持，可申请该服务。
- **响应大小超过50KB** 时，在项目边界处自动截断（⚠️标志）- 防止LLM误解。如需查看更多，可减少 `numOfRows` 或使用 `pageNo` 分页。
- **0条记录** 以 `[NOT_FOUND]` 明确返回（防止LLM幻觉）。深页（`pageNo>1`）的0条记录会提示可能到达最后一页。
- **传输安全**：KIPRIS调用默认使用 `https`。由于密钥在查询字符串中，因此防止明文暴露。（仅当 `KIPRIS_API_PROTOCOL=http` 时才切换到明文）
## resultCode（KIPRIS官方）
| 代码 | 含义 | 对应处理 |
|------|------|------|
| 00 | 正常 | - |
| 10 / 11 | 参数错误 / 缺失必要参数 | 检查搜索条件 |
| 20 | 无结果 | 作为正常结果处理 |
| 30 | 认证密钥未注册（服务未申请） | 申请相应服务 |
| 31 | 认证密钥过期 | 延长/重新颁发 |
## 结构
```
src/
├── index.ts 入口点（STDIO / HTTP模式）
├── tool-registry.ts 7种工具注册 + Zod → JSON Schema转换（隐藏apiKey）
├── lib/
│ ├── api-client.ts KIPRIS端点包装（openapi/rest + kipo-api）
│ ├── fetch-with-retry.ts 超时重试、密钥掩码
│ ├── xml-parser.ts 头部检查、搜索列表、项目搜索、商标、设计、书目详情解析
│ ├── format.ts 各领域结果文本格式化
│ ├── errors.ts KIPRIS resultCode标准化 + 防幻觉
│ ├── cache.ts TTL+LRU缓存
│ ├── schemas.ts 响应大小限制
│ ├── session-state.ts 请求密钥隔离（AsyncLocalStorage）
│ └── types.ts
├── tools/ search / advanced / applicant / rightholder / detail / trademark / design
└── server/http-server.ts 可流式HTTP（速率限制、CORS、信任代理）
```
## 许可证
MIT
