@luffysolution/omnischolar-pi 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.zh-CN.md CHANGED
@@ -1,26 +1,26 @@
1
- # OmniScholar
2
-
3
- [English](README.md) | 简体中文
4
-
5
- OmniScholar 通过本地 Python MCP 服务,为 Codex、Claude Code、Cursor、OpenCode、Hermes 和 Pi 等 Agent 提供文献检索、Zotero 读取、PDF 解析、引用处理、材料数据和科研绘图工具。
6
-
7
- 它可以把在线文献记录与 Zotero 笔记放在一起处理,将经你确认的 PDF 交给 MinerU 解析,再把 Markdown 保存到普通文件夹或 Obsidian Vault。Zotero 全程只读。
8
-
9
- ## 功能
10
-
11
- - 检索 Semantic Scholar、OpenAlex、PubMed/PMC、arXiv、Crossref、Unpaywall、easyScholar、Google Scholar 和 Google Patents
12
- - 查询论文详情、作者、参考文献、施引文献、推荐、全文片段、数据集和期刊指标
13
- - 读取 Zotero 收藏夹、条目、笔记、批注、附件、索引文本和本地 PDF 路径,不修改文献库
14
- - 使用 MinerU 提取指定 PDF 的正文、公式、表格和图片
15
- - 查找引用候选,核对书目信息,再按要求生成参考文献
16
- - 查询 Materials Project,并导出 JSON、CSV、Markdown 或 CIF
17
- - 调用已配置的图片服务生成或编辑科研示意图
18
- - 保留手工修改过的 Markdown,把待合并版本放入 `.conflicts/`
19
-
20
- OmniScholar 共提供 38 个工具,完整列表见[工具目录](docs/TOOLS.md)。
21
-
22
- ## 安装
23
-
1
+ # OmniScholar
2
+
3
+ [English](README.md) | 简体中文
4
+
5
+ OmniScholar 通过本地 Python MCP 服务,为 Codex、Claude Code、Cursor、OpenCode、Hermes 和 Pi 等 Agent 提供文献检索、Zotero 读取、PDF 解析、引用处理、材料数据和科研绘图工具。
6
+
7
+ 它可以把在线文献记录与 Zotero 笔记放在一起处理,将经你确认的 PDF 交给 MinerU 解析,再把 Markdown 保存到普通文件夹或 Obsidian Vault。Zotero 全程只读。
8
+
9
+ ## 功能
10
+
11
+ - 检索 Semantic Scholar、OpenAlex、PubMed/PMC、arXiv、Crossref、Unpaywall、easyScholar、Google Scholar 和 Google Patents
12
+ - 查询论文详情、作者、参考文献、施引文献、推荐、全文片段、数据集和期刊指标
13
+ - 读取 Zotero 收藏夹、条目、笔记、批注、附件、索引文本和本地 PDF 路径,不修改文献库
14
+ - 使用 MinerU 提取指定 PDF 的正文、公式、表格和图片
15
+ - 查找引用候选,核对书目信息,再按要求生成参考文献
16
+ - 查询 Materials Project,并导出 JSON、CSV、Markdown 或 CIF
17
+ - 调用已配置的图片服务生成或编辑科研示意图
18
+ - 保留手工修改过的 Markdown,把待合并版本放入 `.conflicts/`
19
+
20
+ OmniScholar 共提供 38 个工具,完整列表见[工具目录](docs/TOOLS.md)。
21
+
22
+ ## 安装
23
+
24
24
  需要 Python 3.11 或更高版本:
25
25
 
26
26
  ```sh
@@ -32,33 +32,72 @@ python -m pip install luffysolution-omnischolar
32
32
  ```
33
33
 
34
34
  如需从源码开发安装,请将包名替换为 `.`。
35
-
36
- 发行包名为 `luffysolution-omnischolar`,命令和 Python 包名都是 `omnischolar`。
37
-
38
- 检查安装结果:
39
-
40
- ```sh
41
- omnischolar --version
42
- omnischolar doctor --json
43
- ```
44
-
45
- ## 连接 Agent
46
-
47
- 先查看将要修改的文件,再安装本地 MCP 配置和 Skills:
48
-
49
- ```sh
50
- omnischolar install --dry-run claude
51
- omnischolar install claude
52
- ```
53
-
35
+
36
+ 发行包名为 `luffysolution-omnischolar`,命令和 Python 包名都是 `omnischolar`。
37
+
38
+ 检查安装结果:
39
+
40
+ ```sh
41
+ omnischolar --version
42
+ omnischolar doctor --json
43
+ ```
44
+
45
+ ## 连接 Agent
46
+
47
+ ### Codex App 与 Codex CLI 插件安装
48
+
49
+ 先安装 [`uv`](https://docs.astral.sh/uv/getting-started/installation/),再添加 OmniScholar Git Marketplace 并安装插件:
50
+
51
+ ```sh
52
+ codex plugin marketplace add luffysolution-svg/omnischolar --ref main
53
+ codex plugin add omnischolar@omnischolar
54
+ ```
55
+
56
+ 在 ChatGPT 桌面应用中重启应用,打开 **Plugins**,选择 **OmniScholar** Marketplace,然后安装或启用 **OmniScholar**。在 Codex CLI 中可运行 `/plugins` 浏览同一 Marketplace。
57
+
58
+ 插件会同时安装 8 个 Skills,并使用固定的 PyPI 版本启动本地 MCP:
59
+
60
+ ```sh
61
+ uvx --from luffysolution-omnischolar==0.1.2 omnischolar mcp
62
+ ```
63
+
64
+ 采用插件安装方式时无需另外执行 `pip install`。第一次启动 MCP 需要联网,以便 `uvx` 下载并缓存包。各服务的凭据与可选配置仍保存在 OmniScholar 配置中,插件安装不会收集这些信息。
65
+
66
+ ### Claude Code 插件安装
67
+
68
+ 先安装 [`uv`](https://docs.astral.sh/uv/getting-started/installation/)。在 Claude Code 中添加 GitHub Marketplace 并安装插件:
69
+
70
+ ```text
71
+ /plugin marketplace add luffysolution-svg/omnischolar
72
+ /plugin install omnischolar@omnischolar
73
+ ```
74
+
75
+ 如需在脚本或普通终端中执行,可使用非交互式命令:
76
+
77
+ ```sh
78
+ claude plugin marketplace add luffysolution-svg/omnischolar
79
+ claude plugin install omnischolar@omnischolar --scope user
80
+ ```
81
+
82
+ 如果安装结果提示需要重新加载,请运行 `/reload-plugins`,然后新建会话。插件会自动启动同一个固定版本的 `uvx` MCP,并提供 `/omnischolar:scholar-search` 等带命名空间的 Skills,无需另行安装 Python 包。
83
+
84
+ ### Agent 配置安装器
85
+
86
+ 先查看将要修改的文件,再安装本地 MCP 配置和 Skills:
87
+
88
+ ```sh
89
+ omnischolar install --dry-run claude
90
+ omnischolar install claude
91
+ ```
92
+
54
93
  可将 `claude` 换成 `codex`、`cursor`、`opencode`、`hermes`、`pi` 或 `workbuddy`。Codex、Claude Code、Cursor、OpenCode、Pi 和 WorkBuddy/CodeBuddy 支持用户级与项目级安装。Hermes 只提供用户级 MCP 配置;项目级命令会安装 Skills,并提示 MCP 需要手动设置。
55
-
56
- ```sh
57
- omnischolar install cursor --scope project
58
- omnischolar update cursor --scope project
59
- omnischolar uninstall cursor --scope project
60
- ```
61
-
94
+
95
+ ```sh
96
+ omnischolar install cursor --scope project
97
+ omnischolar update cursor --scope project
98
+ omnischolar uninstall cursor --scope project
99
+ ```
100
+
62
101
  对 Pi,完整安装器会运行 `pi install npm:@luffysolution/omnischolar-pi`,并单独安装随包提供的 Skills。npm Extension 会启动 `omnischolar mcp`、发现工具并注册到 Pi。也可以直接安装 Extension:
63
102
 
64
103
  ```sh
@@ -66,86 +105,86 @@ pi install npm:@luffysolution/omnischolar-pi
66
105
  ```
67
106
 
68
107
  WorkBuddy/CodeBuddy 的用户级配置位于 `~/.codebuddy/.mcp.json`,项目级配置位于 `.mcp.json`。其官方文档没有给出可移植的 Skills 目录,因此安装器会配置 MCP,并将 Skills 状态报告为 `manual_required`。
69
-
70
- 本地 MCP 命令为:
71
-
72
- ```sh
73
- omnischolar mcp
74
- ```
75
-
76
- 通常无需手动运行,Agent 会根据 MCP 配置启动该进程。安装器写入受支持的配置后,会检查 `initialize`、`tools/list` 和 `omnischolar_status`。
77
-
78
- 各 Agent 的路径、更新和卸载方法见[安装说明](docs/INSTALLATION.md)。
79
-
80
- ## 使用示例
81
-
82
- ```text
83
- 查找 5 篇关于固态电池界面的近期综述,按 DOI 去重,并给出开放获取版本。
84
-
85
- 在我的 Zotero 中找到这个 DOI,汇总笔记和批注,不要修改 Zotero。
86
-
87
- 我确认上传后,用 MinerU 解析这份 PDF,并把阅读笔记保存到 Obsidian Vault。
88
-
89
- 查询 Materials Project 中稳定的 Li-Fe-P-O 材料,将选中的记录导出为 CSV 和 CIF。
90
-
91
- 为这个机理绘制带标签的示意图。图片只是草稿,不得写成实验数据。
92
- ```
93
-
94
- ## 配置
95
-
96
- 将 [`omnischolar.config.example.json`](omnischolar.config.example.json) 复制为 `omnischolar.config.json`。API key 建议放在环境变量中,配置文件只填写变量名 `apiKeyEnv`。
97
-
98
- 最小的本地配置可以只写 Zotero 和输出目录:
99
-
100
- ```json
101
- {
102
- "schemaVersion": 1,
103
- "runtime": { "workspaceRoots": ["./research-inputs"] },
104
- "zotero": {
105
- "enabled": true,
106
- "baseUrl": "http://127.0.0.1:23119/api"
107
- },
108
- "output": { "rootDirectory": "./research-output" }
109
- }
110
- ```
111
-
112
- OpenAlex、PubMed、arXiv 和 Crossref 无需 API key。其他服务按需启用,字段和示例见[配置说明](docs/CONFIGURATION.md)。
113
-
114
- ## 文件、上传与费用
115
-
116
- - Zotero 只连接本机 `23119` 端口,并且只发送 GET 请求。
117
- - MinerU 只有在配置和本次工具调用都确认 `allowExternalUpload` 后,才会接收选中的 PDF。
118
- - 图片服务会接收提示词,以及你允许上传的参考图;生成和编辑可能消耗账户额度。
119
- - Ai4Scholar 的部分调用可能消耗账户额度。仅保存 API key 不代表同意付费调用。
120
- - 付费请求发生网络错误后,如果无法确定服务端是否已经受理,OmniScholar 不会自动重试。
121
- - AI 生成图只能作为示意图,不能当作测量数据、实验证据或科研结果。
122
-
123
- 启用上传或付费服务前,请阅读 [`PRIVACY.md`](PRIVACY.md) 和[配置说明](docs/CONFIGURATION.md)。
124
-
125
- ## 内置 Skills
126
-
127
- | Skill | 用途 |
128
- |---|---|
129
- | `omnischolar` | 根据科研任务选择并组合工具 |
130
- | `scholar-search` | 文献、专利、作者、引用网络、期刊和数据集 |
131
- | `zotero-research` | 本地 Zotero 匹配、笔记、批注和附件 |
132
- | `paper-reading` | MinerU 解析,以及正文、公式、表格和图片精读 |
133
- | `academic-citation` | 证据核对、引用候选、格式化和参考文献 |
134
- | `scientific-figure` | 科研图片生成、编辑、检查和标注 |
135
- | `materials-project` | 材料筛选、性质、计算来源、相数据和导出 |
136
- | `chemical-data` | 配置正式 API 说明后查询 CAS Common Chemistry |
137
-
138
- ## 文档
139
-
140
- - [安装与 Agent 配置](docs/INSTALLATION.md)
141
- - [配置与服务凭据](docs/CONFIGURATION.md)
142
- - [文献、Zotero、MinerU、引用与输出](docs/RESEARCH.md)
143
- - [材料与化学](docs/MATERIALS.md)
144
- - [科研绘图服务](docs/IMAGE_PROVIDERS.md)
145
- - [工具目录](docs/TOOLS.md)
146
-
147
- ## 支持与许可证
148
-
149
- OmniScholar 使用 [MIT License](LICENSE) 开源。可在 [GitHub Issues](https://github.com/luffysolution-svg/omnischolar/issues) 提交问题,或发送邮件到 `LuffySolution@gmail.com`。报告问题前,请删除 API key、签名 URL、私人论文内容和个人 Zotero 数据。
150
-
151
- 第三方服务和数据仍遵循各自的条款与许可证,详见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。
108
+
109
+ 本地 MCP 命令为:
110
+
111
+ ```sh
112
+ omnischolar mcp
113
+ ```
114
+
115
+ 通常无需手动运行,Agent 会根据 MCP 配置启动该进程。安装器写入受支持的配置后,会检查 `initialize`、`tools/list` 和 `omnischolar_status`。
116
+
117
+ 各 Agent 的路径、更新和卸载方法见[安装说明](docs/INSTALLATION.md)。
118
+
119
+ ## 使用示例
120
+
121
+ ```text
122
+ 查找 5 篇关于固态电池界面的近期综述,按 DOI 去重,并给出开放获取版本。
123
+
124
+ 在我的 Zotero 中找到这个 DOI,汇总笔记和批注,不要修改 Zotero。
125
+
126
+ 我确认上传后,用 MinerU 解析这份 PDF,并把阅读笔记保存到 Obsidian Vault。
127
+
128
+ 查询 Materials Project 中稳定的 Li-Fe-P-O 材料,将选中的记录导出为 CSV 和 CIF。
129
+
130
+ 为这个机理绘制带标签的示意图。图片只是草稿,不得写成实验数据。
131
+ ```
132
+
133
+ ## 配置
134
+
135
+ 将 [`omnischolar.config.example.json`](omnischolar.config.example.json) 复制为 `omnischolar.config.json`。API key 建议放在环境变量中,配置文件只填写变量名 `apiKeyEnv`。
136
+
137
+ 最小的本地配置可以只写 Zotero 和输出目录:
138
+
139
+ ```json
140
+ {
141
+ "schemaVersion": 1,
142
+ "runtime": { "workspaceRoots": ["./research-inputs"] },
143
+ "zotero": {
144
+ "enabled": true,
145
+ "baseUrl": "http://127.0.0.1:23119/api"
146
+ },
147
+ "output": { "rootDirectory": "./research-output" }
148
+ }
149
+ ```
150
+
151
+ OpenAlex、PubMed、arXiv 和 Crossref 无需 API key。其他服务按需启用,字段和示例见[配置说明](docs/CONFIGURATION.md)。
152
+
153
+ ## 文件、上传与费用
154
+
155
+ - Zotero 只连接本机 `23119` 端口,并且只发送 GET 请求。
156
+ - MinerU 只有在配置和本次工具调用都确认 `allowExternalUpload` 后,才会接收选中的 PDF。
157
+ - 图片服务会接收提示词,以及你允许上传的参考图;生成和编辑可能消耗账户额度。
158
+ - Ai4Scholar 的部分调用可能消耗账户额度。仅保存 API key 不代表同意付费调用。
159
+ - 付费请求发生网络错误后,如果无法确定服务端是否已经受理,OmniScholar 不会自动重试。
160
+ - AI 生成图只能作为示意图,不能当作测量数据、实验证据或科研结果。
161
+
162
+ 启用上传或付费服务前,请阅读 [`PRIVACY.md`](PRIVACY.md) 和[配置说明](docs/CONFIGURATION.md)。
163
+
164
+ ## 内置 Skills
165
+
166
+ | Skill | 用途 |
167
+ |---|---|
168
+ | `omnischolar` | 根据科研任务选择并组合工具 |
169
+ | `scholar-search` | 文献、专利、作者、引用网络、期刊和数据集 |
170
+ | `zotero-research` | 本地 Zotero 匹配、笔记、批注和附件 |
171
+ | `paper-reading` | MinerU 解析,以及正文、公式、表格和图片精读 |
172
+ | `academic-citation` | 证据核对、引用候选、格式化和参考文献 |
173
+ | `scientific-figure` | 科研图片生成、编辑、检查和标注 |
174
+ | `materials-project` | 材料筛选、性质、计算来源、相数据和导出 |
175
+ | `chemical-data` | 配置正式 API 说明后查询 CAS Common Chemistry |
176
+
177
+ ## 文档
178
+
179
+ - [安装与 Agent 配置](docs/INSTALLATION.md)
180
+ - [配置与服务凭据](docs/CONFIGURATION.md)
181
+ - [文献、Zotero、MinerU、引用与输出](docs/RESEARCH.md)
182
+ - [材料与化学](docs/MATERIALS.md)
183
+ - [科研绘图服务](docs/IMAGE_PROVIDERS.md)
184
+ - [工具目录](docs/TOOLS.md)
185
+
186
+ ## 支持与许可证
187
+
188
+ OmniScholar 使用 [MIT License](LICENSE) 开源。可在 [GitHub Issues](https://github.com/luffysolution-svg/omnischolar/issues) 提交问题,或发送邮件到 `LuffySolution@gmail.com`。报告问题前,请删除 API key、签名 URL、私人论文内容和个人 Zotero 数据。
189
+
190
+ 第三方服务和数据仍遵循各自的条款与许可证,详见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。
@@ -1,5 +1,5 @@
1
- # Third-party notices
2
-
3
- Third-party services and datasets remain governed by their own terms, licenses, quotas, and billing policies. Product names are the property of their respective owners.
4
-
5
- CAS Common Chemistry identifies its public substance content as CC BY-NC 4.0. OmniScholar grants neither commercial data rights nor SciFinder access.
1
+ # Third-party notices
2
+
3
+ Third-party services and datasets remain governed by their own terms, licenses, quotas, and billing policies. Product names are the property of their respective owners.
4
+
5
+ CAS Common Chemistry identifies its public substance content as CC BY-NC 4.0. OmniScholar grants neither commercial data rights nor SciFinder access.
@@ -1,130 +1,130 @@
1
- # Configuration
2
-
3
- [简体中文](CONFIGURATION.md)
4
-
5
- OmniScholar uses JSON with `schemaVersion: 1`. Start with [`omnischolar.config.example.json`](../omnischolar.config.example.json) and remove services you do not use.
6
-
7
- ## Config file location
8
-
9
- The first matching file is used; files are not merged:
10
-
11
- 1. the path passed with `--config PATH`
12
- 2. the file named by `OMNISCHOLAR_CONFIG`
13
- 3. `omnischolar.config.json` in the current project
14
- 4. `omnischolar/omnischolar.config.json` in the user config directory
15
- 5. built-in defaults
16
-
17
- Relative paths resolve from the config file. Misspelled fields and invalid values are rejected.
18
-
19
- ## Minimal config
20
-
21
- ```json
22
- {
23
- "schemaVersion": 1,
24
- "runtime": {
25
- "workspaceRoots": ["./research-inputs"],
26
- "requestTimeoutSeconds": 30
27
- },
28
- "zotero": {
29
- "enabled": true,
30
- "baseUrl": "http://127.0.0.1:23119/api"
31
- },
32
- "output": {
33
- "rootDirectory": "./research-output"
34
- }
35
- }
36
- ```
37
-
38
- `workspaceRoots` limits local file reads. `output.rootDirectory` limits file writes. To use Obsidian, set the output directory to a folder inside the vault.
39
-
40
- ## API keys
41
-
42
- Keep keys in environment variables and place only the variable name in the config:
43
-
44
- ```json
45
- {
46
- "schemaVersion": 1,
47
- "ai4scholar": {
48
- "enabled": true,
49
- "apiKeyEnv": "OMNISCHOLAR_AI4SCHOLAR_API_KEY",
50
- "allowPaid": false
51
- },
52
- "data": {
53
- "materialsProject": {
54
- "enabled": true,
55
- "apiKeyEnv": "OMNISCHOLAR_MATERIALS_PROJECT_API_KEY"
56
- }
57
- }
58
- }
59
- ```
60
-
61
- Credential order is `apiKey`, the variable named by `apiKeyEnv`, then the service's default environment variable. Do not place plaintext keys in agent MCP files, Skills, command lines, or source control.
62
-
63
- | Service | Key or account requirement |
64
- |---|---|
65
- | OpenAlex, PubMed, arXiv, Crossref | Basic search works without keys; a PubMed key can raise NCBI request limits |
66
- | Semantic Scholar | Optional key; shared anonymous traffic is more likely to receive 429 |
67
- | Unpaywall | Contact email required |
68
- | easyScholar | API key required |
69
- | Zotero | No key; the local API must be enabled |
70
- | MinerU | API key and explicit PDF upload approval |
71
- | Ai4Scholar | API key; some calls use account credit |
72
- | Materials Project | API key required |
73
- | Image services | Provider key, model, and endpoint as required |
74
- | CAS Common Chemistry | A provider-supplied interface description file is still required |
75
-
76
- ## Paid calls and uploads
77
-
78
- A stored key does not approve spending or upload.
79
-
80
- - Ai4Scholar and image generation require `allowPaid` in the config and again in the individual tool call.
81
- - MinerU and reference-image uploads require `allowExternalUpload` in the config and again in the tool call.
82
- - Sync recovery only repairs local files; it does not reuse previous upload approval.
83
- - If a paid request times out after the provider may have accepted it, OmniScholar does not retry automatically.
84
-
85
- ## Literature search
86
-
87
- ```json
88
- {
89
- "schemaVersion": 1,
90
- "research": {
91
- "fallback": true,
92
- "maxPages": 5,
93
- "providers": {
94
- "openalex": { "enabled": true, "email": "researcher@example.org" },
95
- "pubmed": { "enabled": true, "email": "researcher@example.org" },
96
- "arxiv": { "enabled": true },
97
- "crossref": { "enabled": true, "email": "researcher@example.org" },
98
- "unpaywall": { "enabled": true, "email": "researcher@example.org" }
99
- }
100
- }
101
- }
102
- ```
103
-
104
- `fallback` moves only to another service that supports the same operation. HTTP 429 is returned as a rate-limit result and does not start an immediate retry loop.
105
-
106
- ## MinerU
107
-
108
- ```json
109
- {
110
- "schemaVersion": 1,
111
- "mineru": {
112
- "enabled": true,
113
- "apiKeyEnv": "OMNISCHOLAR_MINERU_API_KEY",
114
- "model": "pipeline",
115
- "allowExternalUpload": false
116
- }
117
- }
118
- ```
119
-
120
- The MinerU v1 fallback is off by default. Provider documentation currently gives inconsistent page limits, so OmniScholar does not switch APIs on its own.
121
-
122
- ## Check the config
123
-
124
- ```sh
125
- omnischolar config path
126
- omnischolar config schema
127
- omnischolar status
128
- omnischolar doctor --json
129
- ```
130
-
1
+ # Configuration
2
+
3
+ [简体中文](CONFIGURATION.md)
4
+
5
+ OmniScholar uses JSON with `schemaVersion: 1`. Start with [`omnischolar.config.example.json`](../omnischolar.config.example.json) and remove services you do not use.
6
+
7
+ ## Config file location
8
+
9
+ The first matching file is used; files are not merged:
10
+
11
+ 1. the path passed with `--config PATH`
12
+ 2. the file named by `OMNISCHOLAR_CONFIG`
13
+ 3. `omnischolar.config.json` in the current project
14
+ 4. `omnischolar/omnischolar.config.json` in the user config directory
15
+ 5. built-in defaults
16
+
17
+ Relative paths resolve from the config file. Misspelled fields and invalid values are rejected.
18
+
19
+ ## Minimal config
20
+
21
+ ```json
22
+ {
23
+ "schemaVersion": 1,
24
+ "runtime": {
25
+ "workspaceRoots": ["./research-inputs"],
26
+ "requestTimeoutSeconds": 30
27
+ },
28
+ "zotero": {
29
+ "enabled": true,
30
+ "baseUrl": "http://127.0.0.1:23119/api"
31
+ },
32
+ "output": {
33
+ "rootDirectory": "./research-output"
34
+ }
35
+ }
36
+ ```
37
+
38
+ `workspaceRoots` limits local file reads. `output.rootDirectory` limits file writes. To use Obsidian, set the output directory to a folder inside the vault.
39
+
40
+ ## API keys
41
+
42
+ Keep keys in environment variables and place only the variable name in the config:
43
+
44
+ ```json
45
+ {
46
+ "schemaVersion": 1,
47
+ "ai4scholar": {
48
+ "enabled": true,
49
+ "apiKeyEnv": "OMNISCHOLAR_AI4SCHOLAR_API_KEY",
50
+ "allowPaid": false
51
+ },
52
+ "data": {
53
+ "materialsProject": {
54
+ "enabled": true,
55
+ "apiKeyEnv": "OMNISCHOLAR_MATERIALS_PROJECT_API_KEY"
56
+ }
57
+ }
58
+ }
59
+ ```
60
+
61
+ Credential order is `apiKey`, the variable named by `apiKeyEnv`, then the service's default environment variable. Do not place plaintext keys in agent MCP files, Skills, command lines, or source control.
62
+
63
+ | Service | Key or account requirement |
64
+ |---|---|
65
+ | OpenAlex, PubMed, arXiv, Crossref | Basic search works without keys; a PubMed key can raise NCBI request limits |
66
+ | Semantic Scholar | Optional key; shared anonymous traffic is more likely to receive 429 |
67
+ | Unpaywall | Contact email required |
68
+ | easyScholar | API key required |
69
+ | Zotero | No key; the local API must be enabled |
70
+ | MinerU | API key and explicit PDF upload approval |
71
+ | Ai4Scholar | API key; some calls use account credit |
72
+ | Materials Project | API key required |
73
+ | Image services | Provider key, model, and endpoint as required |
74
+ | CAS Common Chemistry | A provider-supplied interface description file is still required |
75
+
76
+ ## Paid calls and uploads
77
+
78
+ A stored key does not approve spending or upload.
79
+
80
+ - Ai4Scholar and image generation require `allowPaid` in the config and again in the individual tool call.
81
+ - MinerU and reference-image uploads require `allowExternalUpload` in the config and again in the tool call.
82
+ - Sync recovery only repairs local files; it does not reuse previous upload approval.
83
+ - If a paid request times out after the provider may have accepted it, OmniScholar does not retry automatically.
84
+
85
+ ## Literature search
86
+
87
+ ```json
88
+ {
89
+ "schemaVersion": 1,
90
+ "research": {
91
+ "fallback": true,
92
+ "maxPages": 5,
93
+ "providers": {
94
+ "openalex": { "enabled": true, "email": "researcher@example.org" },
95
+ "pubmed": { "enabled": true, "email": "researcher@example.org" },
96
+ "arxiv": { "enabled": true },
97
+ "crossref": { "enabled": true, "email": "researcher@example.org" },
98
+ "unpaywall": { "enabled": true, "email": "researcher@example.org" }
99
+ }
100
+ }
101
+ }
102
+ ```
103
+
104
+ `fallback` moves only to another service that supports the same operation. HTTP 429 is returned as a rate-limit result and does not start an immediate retry loop.
105
+
106
+ ## MinerU
107
+
108
+ ```json
109
+ {
110
+ "schemaVersion": 1,
111
+ "mineru": {
112
+ "enabled": true,
113
+ "apiKeyEnv": "OMNISCHOLAR_MINERU_API_KEY",
114
+ "model": "pipeline",
115
+ "allowExternalUpload": false
116
+ }
117
+ }
118
+ ```
119
+
120
+ The MinerU v1 fallback is off by default. Provider documentation currently gives inconsistent page limits, so OmniScholar does not switch APIs on its own.
121
+
122
+ ## Check the config
123
+
124
+ ```sh
125
+ omnischolar config path
126
+ omnischolar config schema
127
+ omnischolar status
128
+ omnischolar doctor --json
129
+ ```
130
+