内容
# 专利范围
用于通过
[SerpApi Google Patents API](https://serpapi.com/google-patents-api) 搜索和检索谷歌专利数据的命令行界面。
同时作为AI辅助专利研究的[MCP](https://modelcontextprotocol.io/)服务器。
## 致谢
该项目是原[google-patents-mcp](https://github.com/KunihiroS/google-patents-mcp)的一个分支，由[Kunihiro Sasayama](https://github.com/KunihiroS)创建。我们对基础工作和灵感表示感谢。
## 快速开始
```bash
# 安装
bun add -g @softwarestartups/patentscope
# 或在不安装的情况下运行
bunx @softwarestartups/patentscope search "量子计算"
```
预构建的二进制文件（无需运行时）可在
[GitHub Releases](https://github.com/SoftwareStartups/patentscope/releases) 页面上找到。
## 与 Claude Code 结合使用
该仓库是 Claude Code 插件市场的一部分。安装配套技能，以便 Claude Code 可以为您驱动 `patentscope`：
```bash
/plugin marketplace add SoftwareStartups/patentscope
/plugin install patentscope@softwarestartups-patentscope
```
安装后，只需用自然语言询问 Claude（例如，“搜索发明人 X 的自适应光学专利”），技能将自动激活。插件跟踪此仓库的发布 - 运行 `/plugin marketplace update softwarestartups-patentscope` 以获取最新的技能修订。
## 先决条件
* **Bun:** 版本 1.0 或更高（使用预构建二进制文件时不需要）。
* **SerpApi API 密钥：** 来自 [SerpApi](https://serpapi.com/) 的有效密钥。
## 配置
使用 `login` 命令一次性保存您的 API 密钥：
```bash
patentscope login
# 输入您的 SerpApi API 密钥：****
# 或非交互式
patentscope login --api-key YOUR_KEY
```
密钥存储在 `~/.config/patentscope/config.json` 中，具有严格的文件权限。
要删除存储的密钥：
```bash
patentscope logout
```
`SERPAPI_API_KEY` 环境变量优先于存储的配置，对于 CI 或临时覆盖非常有用。
## CLI 用法
```
用法：patentscope <命令> [标志]
命令：
login 保存您的 SerpApi API 密钥
logout 删除保存的 API 密钥
search [查询] 搜索谷歌专利
get <专利编号> 获取专利详情
serve 在 stdio 上启动 MCP 服务器
标志：
-h, --help 显示帮助信息
-v, --version 显示版本信息
--json 输出为 JSON
```
所有人类可读的输出都输出到 **stderr**。stdout 保留用于 `--json` 结构化输出和 MCP JSON-RPC 传输（在 `serve` 模式下）。
### 搜索专利
```bash
# 基本搜索
patentscope search "神经网络芯片"
# 带过滤器
patentscope search "电池" --status GRANT --country US --num 20
# 日期范围
patentscope search "CRISPR" --after publication:20230101 --before publication:20231231
# 按发明人或权利人过滤
patentscope search --inventor "John Smith" --assignee "谷歌"
# JSON 输出
patentscope search "量子计算" --json
```
**搜索标志：**
| 标志 | 描述 |
|----------------|--------------------------------------------|
| `-p, --page` | 页码（默认：1） |
| `-n, --num` | 每页结果数（10-100，默认：10） |
| `--sort` | 按 `new` 或 `old` 排序 |
| `--before` | 最大日期（例如：`publication:20231231`） |
| `--after` | 最小日期（例如：`publication:20230101`） |
| `--inventor` | 发明人过滤 |
| `--assignee` | 权利人过滤 |
| `--country` | 国家代码（例如：`US`，`WO,JP`） |
| `--language` | 语言（例如：`ENGLISH`，`JAPANESE`） |
| `--status` | `GRANT` 或 `APPLICATION` |
| `--type` | `PATENT` 或 `DESIGN` |
| `--scholar` | 包括谷歌学术结果 |
### 获取专利详情
```bash
# 获取元数据和摘要（默认）
patentscope get US7654321B2
# 获取特定章节
patentscope get US7654321B2 --include claims,description
# 获取所有内容
patentscope get EP3456789A1 --include metadata,abstract,claims,description,family_members,citations
# 限制内容长度
patentscope get US7654321B2 --include description,claims --maxLength 5000
# JSON 输出
patentscope get US7654321B2 --json
```
**获取标志：**
| 标志 | 描述 |
|-------------------|------------------------------------------------------------------|
| `-i, --include` | 用逗号分隔的章节：`metadata`、`abstract`、`claims`、`description`、`family_members`、`citations`（默认：`metadata,abstract`） |
| `--maxLength` | 返回内容的字符长度限制 |
### JSON 输出模式
在任何命令中添加 `--json` 以获得 stdout 上的结构化输出：
```bash
patentscope search "量子计算" --json
patentscope get US7654321B2 --json
patentscope --version --json
patentscope --help --json
```
## MCP 服务器
`serve` 命令在 stdio 上启动一个 MCP 服务器，暴露两个工具：
`search_patents` 和 `get_patent`。
### MCP 主机配置
使用预构建的二进制文件（从 [GitHub Releases](https://github.com/SoftwareStartups/patentscope/releases) 下载）：
```json
{
"mcpServers": {
"patentscope": {
"command": "/path/to/patentscope-darwin-arm64",
"args": ["serve"]
}
}
}
```
使用 `bunx`:
```json
{
"mcpServers": {
"patentscope": {
"command": "bunx",
"args": ["@softwarestartups/patentscope", "serve"]
}
}
}
```
MCP 服务器使用 `~/.config/patentscope/config.json` 中的 API 密钥（通过 `patentscope login` 设置）。如果需要，可以使用 `SERPAPI_API_KEY` 环境变量覆盖。
### MCP 工具
#### `search_patents`
通过 SerpApi 搜索谷歌专利。返回专利元数据（标题、公开号、权利人、发明人、日期和 `patent_link`）。
| 参数 | 类型 | 必需 | 描述 |
|------------|---------|----------|-------------------------------------------------------|
| `q` | 字符串 | 否 | 搜索查询（分号分隔的术语） |
| `page` | 整数 | 否 | 页码（默认：1） |
| `num` | 整数 | 否 | 每页结果数（10-100，默认：10） |
| `sort` | 字符串 | 否 | `new` 或 `old` |
| `before` | 字符串 | 否 | 最大日期（例如：`publication:20231231`） |
| `after` | 字符串 | 否 | 最小日期（例如：`publication:20230101`） |
| `inventor` | 字符串 | 否 | 发明人姓名（逗号分隔） |
| `assignee` | 字符串 | 否 | 权利人姓名（逗号分隔） |
| `country` | 字符串 | 否 | 国家代码（例如：`US`，`WO,JP`） |
| `language` | 字符串 | 否 | 语言（例如：`ENGLISH`，`JAPANESE`） |
| `status` | 字符串 | 否 | `GRANT` 或 `APPLICATION` |
| `type` | 字符串 | 否 | `PATENT` 或 `DESIGN` |
| `scholar` | 布尔值 | 否 | 包括谷歌学术结果（默认：false） |
#### `get_patent`
获取包括索赔、描述、家族成员、引用和元数据在内的综合专利数据。
| 参数 | 类型 | 必需 | 描述 |
|--------------|---------|----------|-------------------------------------------------------|
| `patent_url` | 字符串 | 否* | 完整的谷歌专利网址 |
| `patent_id` | 字符串 | 否* | 专利编号（例如：`US1234567A`） |
| `include` | 数组 | 否 | 要包括的章节（默认：`["metadata", "abstract"]`） |
| `max_length` | 整数 | 否 | 内容的最大字符长度 |
*必须提供 `patent_url` 或 `patent_id` 之一。如果同时提供，则优先使用 `patent_url`。
## 二进制发布
所有支持平台的预构建二进制文件都可在
[GitHub Releases](https://github.com/SoftwareStartups/patentscope/releases) 页面上找到。
无需安装 Bun 或 Node.js。
| 平台 | 架构 | 二进制文件 |
|----------|-------------|--------|
| Linux | x64 | `patentscope-linux-x64` |
| Linux | arm64 | `patentscope-linux-arm64` |
| macOS | x64 | `patentscope-darwin-x64` |
| macOS | arm64 | `patentscope-darwin-arm64` |
```bash
curl -L https://github.com/SoftwareStartups/patentscope/releases/latest/download/patentscope-darwin-arm64 -o patentscope
chmod +x patentscope
./patentscope login
./patentscope search "量子计算"
```
### 发布
推送一个 semver 标签以触发发布工作流：
```bash
git tag v1.2.3
git push origin v1.2.3
```
## 开发
### 设置
```bash
git clone https://github.com/SoftwareStartups/patentscope.git
cd patentscope
bun install
patentscope login # 或：export SERPAPI_API_KEY=your_key
```
### 工作流程
```bash
task build # 构建
task format # 格式化代码
task check # 校验 + 类型检查
task test # 单元测试 + 集成测试
task test:e2e # 端到端测试（真实 API 调用）
task all # clean -> install -> build -> check -> test
```
### 本地运行
```bash
bun src/index.ts search "量子计算"
bun src/index.ts get US7654321B2
bun src/index.ts serve
```
## 日志记录
日志输出到 stderr。通过 `LOG_LEVEL` 控制日志级别（error、warn、info、http、verbose、debug、silly）。默认为 `info`。
