Metadata-Version: 2.4
Name: cnipa-mcp
Version: 0.1.0
Summary: CNIPA patent query MCP server: self-contained direct mode (bundled Node) or HTTP proxy mode
Keywords: mcp,cnipa,patent,model-context-protocol
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: mcp>=2.0
Requires-Dist: requests>=2.28
Requires-Dist: numpy>=1.24
Requires-Dist: opencv-python-headless<5,>=4.8
Requires-Dist: nodejs-bin==18.4.0a4
Requires-Dist: openpyxl>=3.1

# cnipa-mcp

CNIPA(中国国家知识产权局 · 专利检索及分析系统)专利查询 **MCP 服务器**。
让 Qoder / Claude Desktop / Cursor 以及魔搭(ModelScope)MCP 托管等支持 MCP 的客户端
直接调用专利查询能力。

```
MCP 客户端 ──stdio──▶ cnipa-mcp ──┬─ 直连模式: 进程内访问 CNIPA(自带 Node,自动登录/滑块/铸币)
                                   └─ 代理模式: HTTP 转发给 Docker 后端(cnipa-api 等兼容服务)
```

## 功能与工具

| 工具 | 功能 | 关键参数 |
|---|---|---|
| `service_status` | 查看运行模式、Node/OpenCV 依赖、数据目录、凭据配置状态 | — |
| `query_patent` | 按专利号查询:检索信息 + 著录项目 + 费用信息 | `patent_no`(逗号分隔多个;支持 CN/ZL 前缀、.X 后缀) |
| `query_applicant_patents` | 按申请人查询名下专利:完整 JSON 落盘 + 生成 Excel + 返回预览 | `sqrmc`、`preview_count`、`max_pages`、`download_excel`、`save_dir` |
| `download_excel_file` | 下载后端已生成的 Excel(仅代理模式) | `filename` 或完整 URL |

所有查询工具都需要 CNIPA 账号凭据,优先取工具参数 `account` / `password` / `type_key`,
缺省回退到环境变量 `CNIPA_USERNAME` / `CNIPA_PASSWORD` / `CNIPA_TYPE_KEY`
(`type_key`:1 自然人 / 2 法人 / 3 代理机构;也接受"自然人/法人/代理机构"中文写法)。

> ⚠️ 本包**不内置任何默认凭据**,请使用您本人有权使用的账号,并遵守 CNIPA 用户协议与相关法律法规。

## 安装

```bash
# 推荐(隔离环境,适合 MCP 客户端/云端一键拉起)
uvx cnipa-mcp

# 或 pip 安装
pip install cnipa-mcp
cnipa-mcp            # stdio 方式运行
```

## 两种运行模式

### 直连模式(默认,自包含)

不设置 `CNIPA_API_BASE` 即启用:进程内直接访问 CNIPA,自动完成
登录(滑块验证求解 + 瑞数铸币)、检索、著录项、费用信息查询。
依赖均已声明在包内:`nodejs-bin`(随包 Node 18)、`opencv-python-headless`(滑块求解)、
`numpy`、`requests`、`openpyxl`(Excel 导出)。临时数据目录自动落到系统临时目录,
适配只读/受限沙箱环境(如魔搭免费实例)。

### 代理模式

设置 `CNIPA_API_BASE`(如 `http://127.0.0.1:15000`)后,转发给 Docker 后端
(兼容 `hahaha121391/cnipa-api` 的 HTTP 服务):

```bash
docker run -d --name cnipa-api --restart unless-stopped \
  -p 127.0.0.1:15000:5000 hahaha121391/cnipa-api:latest
```

## MCP 客户端配置

### 本地客户端(Qoder / Claude Desktop 等,stdio)

```json
{
  "mcpServers": {
    "cnipa": {
      "command": "uvx",
      "args": ["cnipa-mcp"],
      "env": {
        "CNIPA_USERNAME": "<您的账号>",
        "CNIPA_PASSWORD": "<您的密码>",
        "CNIPA_TYPE_KEY": "1"
      }
    }
  }
}
```

凭据也可以不放在 env,由调用方在每次工具调用时传入 `account` / `password`。

### 魔搭(ModelScope)MCP 部署服务

选择"托管 STDIO"类型,提交如下 JSON(创建表单中用 `uvx` 拉取本包):

```json
{
  "mcpServers": {
    "cnipa": {
      "command": "uvx",
      "args": ["cnipa-mcp"],
      "env": {
        "CNIPA_USERNAME": "",
        "CNIPA_PASSWORD": "",
        "CNIPA_TYPE_KEY": "1"
      }
    }
  }
}
```

平台会自动从 PyPI 安装本包并调用 `list_tools` 做可部署检测;
`env` 中的账号/密码由部署者或使用者在部署向导中填写,不会出现在公开页面。

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `CNIPA_API_BASE` | 空 | 空=直连模式;设置(如 `http://127.0.0.1:15000`)=代理模式 |
| `CNIPA_USERNAME` / `CNIPA_PASSWORD` | 空 | 默认凭据(可被工具参数覆盖) |
| `CNIPA_TYPE_KEY` | `1` | 账号类型:1 自然人 / 2 法人 / 3 代理机构 |
| `CNIPA_EXPORT_DIR` | `~/cnipa-exports` | 导出文件保存目录 |
| `CNIPA_DATA_DIR` | 系统临时目录/cnipa-mcp | 会话/JWT 缓存目录(受限环境自动降级) |
| `CNIPA_NODE_PATH` | 空 | 指定 node 可执行文件(默认用随包 Node) |
| `CNIPA_TIMEOUT` | `290` | 代理模式 HTTP 超时秒数 |

## 已知限制

- 首次查询包含"登录 + 滑块验证 + 铸币"流程,可能耗时数十秒;
- 超大申请人(数万条专利)全量拉取耗时较长,受限环境请设置 `max_pages` 取样,
  截断时返回 `truncated: true`;
- 自由实例(1 vCPU / 1GB 内存 / 512MB 磁盘)下全量导出大申请人数据可能超限;
- 本工具通过自动化方式访问公开检索系统,请在获得授权的前提下用于合法用途
  (如查询自有/客户授权范围内的专利数据)。

## License

未声明许可证。仅供授权范围内的内部使用。
