@luffysolution/omnischolar-pi 0.1.0 → 0.1.1

package/PRIVACY.md

@@ -0,0 +1,24 @@
+# Privacy notice
+
+OmniScholar is open-source software that runs on the user's computer. The maintainers do not operate an OmniScholar service for version 0.1.0.
+
+## Local data
+
+Configuration, cache, output files, and Zotero Local API results remain on the local machine unless a selected tool calls an external service. Zotero access uses GET requests to the local API only.
+
+## Data sent to other services
+
+- Literature and materials tools send search terms, identifiers, and selected filters to the chosen data source.
+- Ai4Scholar receives the request needed for the selected Ai4Scholar operation.
+- MinerU receives a PDF only after the user approves that file upload.
+- Image services receive the prompt and any reference images approved for upload.
+
+Each provider has its own privacy, retention, training, region, and account policies. Review those policies before enabling the provider.
+
+## Credentials
+
+Environment variables are recommended for API keys. OmniScholar removes known secrets from tool results, status, errors, and logs, and does not write provider keys into Agent MCP files. Users are still responsible for protecting configuration files and shell history.
+
+Privacy and security questions: `LuffySolution@gmail.com`.
+
+This notice describes the software's behavior. A marketplace may require additional legal terms before publication.

package/TERMS.md

@@ -0,0 +1,7 @@
+# Terms of Use
+
+OmniScholar is open-source software distributed under the [MIT License](LICENSE). By installing or using it, you agree to that license and to the terms of any third-party services or datasets you choose to enable.
+
+You are responsible for reviewing generated research output, respecting copyright and data-access restrictions, and confirming any external upload or paid operation. OmniScholar does not provide legal, medical, or financial advice and does not guarantee the accuracy or availability of third-party data.
+
+See [PRIVACY.md](PRIVACY.md) for data-handling details and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for third-party terms.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,5 @@
+# Third-party notices
+
+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.
+
+CAS Common Chemistry identifies its public substance content as CC BY-NC 4.0. OmniScholar grants neither commercial data rights nor SciFinder access.

package/docs/CONFIGURATION.en.md

@@ -0,0 +1,130 @@
+# Configuration
+
+[简体中文](CONFIGURATION.md)
+
+OmniScholar uses JSON with `schemaVersion: 1`. Start with [`omnischolar.config.example.json`](../omnischolar.config.example.json) and remove services you do not use.
+
+## Config file location
+
+The first matching file is used; files are not merged:
+
+1. the path passed with `--config PATH`
+2. the file named by `OMNISCHOLAR_CONFIG`
+3. `omnischolar.config.json` in the current project
+4. `omnischolar/omnischolar.config.json` in the user config directory
+5. built-in defaults
+
+Relative paths resolve from the config file. Misspelled fields and invalid values are rejected.
+
+## Minimal config
+
+```json
+{
+  "schemaVersion": 1,
+  "runtime": {
+    "workspaceRoots": ["./research-inputs"],
+    "requestTimeoutSeconds": 30
+  },
+  "zotero": {
+    "enabled": true,
+    "baseUrl": "http://127.0.0.1:23119/api"
+  },
+  "output": {
+    "rootDirectory": "./research-output"
+  }
+}
+```
+
+`workspaceRoots` limits local file reads. `output.rootDirectory` limits file writes. To use Obsidian, set the output directory to a folder inside the vault.
+
+## API keys
+
+Keep keys in environment variables and place only the variable name in the config:
+
+```json
+{
+  "schemaVersion": 1,
+  "ai4scholar": {
+    "enabled": true,
+    "apiKeyEnv": "OMNISCHOLAR_AI4SCHOLAR_API_KEY",
+    "allowPaid": false
+  },
+  "data": {
+    "materialsProject": {
+      "enabled": true,
+      "apiKeyEnv": "OMNISCHOLAR_MATERIALS_PROJECT_API_KEY"
+    }
+  }
+}
+```
+
+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.
+
+| Service | Key or account requirement |
+|---|---|
+| OpenAlex, PubMed, arXiv, Crossref | Basic search works without keys; a PubMed key can raise NCBI request limits |
+| Semantic Scholar | Optional key; shared anonymous traffic is more likely to receive 429 |
+| Unpaywall | Contact email required |
+| easyScholar | API key required |
+| Zotero | No key; the local API must be enabled |
+| MinerU | API key and explicit PDF upload approval |
+| Ai4Scholar | API key; some calls use account credit |
+| Materials Project | API key required |
+| Image services | Provider key, model, and endpoint as required |
+| CAS Common Chemistry | A provider-supplied interface description file is still required |
+
+## Paid calls and uploads
+
+A stored key does not approve spending or upload.
+
+- Ai4Scholar and image generation require `allowPaid` in the config and again in the individual tool call.
+- MinerU and reference-image uploads require `allowExternalUpload` in the config and again in the tool call.
+- Sync recovery only repairs local files; it does not reuse previous upload approval.
+- If a paid request times out after the provider may have accepted it, OmniScholar does not retry automatically.
+
+## Literature search
+
+```json
+{
+  "schemaVersion": 1,
+  "research": {
+    "fallback": true,
+    "maxPages": 5,
+    "providers": {
+      "openalex": { "enabled": true, "email": "researcher@example.org" },
+      "pubmed": { "enabled": true, "email": "researcher@example.org" },
+      "arxiv": { "enabled": true },
+      "crossref": { "enabled": true, "email": "researcher@example.org" },
+      "unpaywall": { "enabled": true, "email": "researcher@example.org" }
+    }
+  }
+}
+```
+
+`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.
+
+## MinerU
+
+```json
+{
+  "schemaVersion": 1,
+  "mineru": {
+    "enabled": true,
+    "apiKeyEnv": "OMNISCHOLAR_MINERU_API_KEY",
+    "model": "pipeline",
+    "allowExternalUpload": false
+  }
+}
+```
+
+The MinerU v1 fallback is off by default. Provider documentation currently gives inconsistent page limits, so OmniScholar does not switch APIs on its own.
+
+## Check the config
+
+```sh
+omnischolar config path
+omnischolar config schema
+omnischolar status
+omnischolar doctor --json
+```
+

package/docs/CONFIGURATION.md

@@ -0,0 +1,130 @@
+# 配置
+
+[English](CONFIGURATION.en.md)
+
+OmniScholar 使用 `schemaVersion: 1` 的 JSON 配置。可直接复制根目录的 [`omnischolar.config.example.json`](../omnischolar.config.example.json)，再删除不需要的服务。
+
+## 配置文件位置
+
+程序使用找到的第一个配置文件，不合并多份配置：
+
+1. `--config PATH` 指定的文件
+2. `OMNISCHOLAR_CONFIG` 指向的文件
+3. 当前项目的 `omnischolar.config.json`
+4. 用户配置目录中的 `omnischolar/omnischolar.config.json`
+5. 内置默认值
+
+相对路径以配置文件所在目录为基准。拼错字段名或填写不合法的值时，程序会直接报错。
+
+## 最小配置
+
+```json
+{
+  "schemaVersion": 1,
+  "runtime": {
+    "workspaceRoots": ["./research-inputs"],
+    "requestTimeoutSeconds": 30
+  },
+  "zotero": {
+    "enabled": true,
+    "baseUrl": "http://127.0.0.1:23119/api"
+  },
+  "output": {
+    "rootDirectory": "./research-output"
+  }
+}
+```
+
+`workspaceRoots` 限定可读取的本地文件，`output.rootDirectory` 限定写入位置。若要直接写入 Obsidian，可把输出目录设为 Vault 中的一个文件夹。
+
+## API key
+
+建议把 key 存入环境变量，配置中只写变量名：
+
+```json
+{
+  "schemaVersion": 1,
+  "ai4scholar": {
+    "enabled": true,
+    "apiKeyEnv": "OMNISCHOLAR_AI4SCHOLAR_API_KEY",
+    "allowPaid": false
+  },
+  "data": {
+    "materialsProject": {
+      "enabled": true,
+      "apiKeyEnv": "OMNISCHOLAR_MATERIALS_PROJECT_API_KEY"
+    }
+  }
+}
+```
+
+读取顺序为 `apiKey`、`apiKeyEnv` 指向的环境变量、该服务的默认环境变量。不要把明文 key 写入 Agent 的 MCP 配置、Skills、命令行或版本库。
+
+| 服务 | 是否需要 key 或其他信息 |
+|---|---|
+| OpenAlex、PubMed、arXiv、Crossref | 基本检索无需 key；PubMed key 可提高 NCBI 请求额度 |
+| Semantic Scholar | key 可选；匿名共享流量更容易遇到 429 |
+| Unpaywall | 需要联系邮箱 |
+| easyScholar | 需要 API key |
+| Zotero | 不需要 key；需开启本地 API |
+| MinerU | 需要 API key，并确认 PDF 上传 |
+| Ai4Scholar | 需要 API key，部分调用消耗额度 |
+| Materials Project | 需要 API key |
+| 图片服务 | 按服务商要求配置 key、模型和服务地址 |
+| CAS Common Chemistry | 当前还需要服务商提供的正式接口说明文件 |
+
+## 付费与上传
+
+保存 key 不会自动允许付费或上传。
+
+- Ai4Scholar 和图片生成需在配置中启用 `allowPaid`，调用时还要再次确认 `allowPaid`。
+- MinerU 与参考图上传需在配置中启用 `allowExternalUpload`，调用时还要再次确认同名参数。
+- 同步恢复只处理本地文件，不会沿用以前的上传许可。
+- 付费请求超时后，如果服务端结果不明确，程序不会自动重试。
+
+## 文献检索
+
+```json
+{
+  "schemaVersion": 1,
+  "research": {
+    "fallback": true,
+    "maxPages": 5,
+    "providers": {
+      "openalex": { "enabled": true, "email": "researcher@example.org" },
+      "pubmed": { "enabled": true, "email": "researcher@example.org" },
+      "arxiv": { "enabled": true },
+      "crossref": { "enabled": true, "email": "researcher@example.org" },
+      "unpaywall": { "enabled": true, "email": "researcher@example.org" }
+    }
+  }
+}
+```
+
+`fallback` 只会改用支持同一项查询的服务。HTTP 429 会作为限流结果返回，不会触发连续重试。
+
+## MinerU
+
+```json
+{
+  "schemaVersion": 1,
+  "mineru": {
+    "enabled": true,
+    "apiKeyEnv": "OMNISCHOLAR_MINERU_API_KEY",
+    "model": "pipeline",
+    "allowExternalUpload": false
+  }
+}
+```
+
+默认不启用 MinerU v1 备用接口。当前文档对页数限制的描述不一致，因此程序不会自行切换接口。
+
+## 检查配置
+
+```sh
+omnischolar config path
+omnischolar config schema
+omnischolar status
+omnischolar doctor --json
+```
+

package/docs/IMAGE_PROVIDERS.en.md

@@ -0,0 +1,58 @@
+# Scientific image services
+
+[简体中文](IMAGE_PROVIDERS.md)
+
+OmniScholar can connect to OpenAI, xAI, Gemini, Vertex AI, fal.ai, DashScope/Qwen, Atlas, and custom OpenAI-compatible services. Available models depend on the account, region, endpoint, and configuration.
+
+## Tools
+
+| Tool | Use |
+|---|---|
+| `omnischolar_image_models` | Show configured models and their usable operations |
+| `omnischolar_image_generate` | Text-to-image, image-to-image, or multi-reference generation |
+| `omnischolar_image_edit` | Edit an existing image |
+| `omnischolar_image_service` | Run supported provider status, model, or task operations |
+| `ai4scholar_figure` | Generate, edit, or vectorize through Ai4Scholar |
+
+Each model must explicitly declare the operation it supports. A model name appearing in a provider catalog does not by itself prove that it can generate or edit images; the corresponding operation must show `usable: true` in `omnischolar_image_models`.
+
+## Example config
+
+```json
+{
+  "schemaVersion": 1,
+  "defaults": {
+    "defaultImageProvider": "fal"
+  },
+  "media": {
+    "allowPaid": false,
+    "allowExternalUpload": false,
+    "providers": {
+      "fal": {
+        "enabled": true,
+        "apiKeyEnv": "OMNISCHOLAR_FAL_API_KEY",
+        "baseUrl": "https://fal.run",
+        "models": {},
+        "options": {}
+      }
+    }
+  }
+}
+```
+
+A custom service needs an exact `baseUrl`, model ID, capability list, and generation or edit endpoint. Do not infer capabilities from the model name.
+
+## Generate and edit
+
+Before submitting a task, define the scientific content, labels, units, aspect ratio, and file format. Generation requires `allowPaid` for that call. Uploading a reference image also requires `allowExternalUpload` for that call.
+
+Upload only images you may share with the selected service. After files are saved, signed URLs and base64 source data are removed from the returned payload. Downloads are checked for public HTTPS, file size, MIME type, and image signature. If one file in a multi-file result is missing, the incomplete set is not published.
+
+## Current provider notes
+
+- fal has been tested for queue submission, polling, data-URI results, text-to-image, and two-reference editing. If the local machine cannot resolve the fal CDN, a data-URI result can still be saved.
+- DashScope/Qwen currently needs a workspace-scoped endpoint or an explicit `baseUrl` supplied by the provider. A retired generic endpoint returns `dashscope_workspace_required`.
+- Gemini's `apiKeyEnv` must name an environment variable that exists.
+- Atlas and custom services need a working endpoint and model description.
+
+Review text, structures, mechanisms, scale, and quantitative labels after generation. **AI images are illustrative drafts, not experimental data, real measurements, or scientific conclusions.**

package/docs/IMAGE_PROVIDERS.md

@@ -0,0 +1,58 @@
+# 科研绘图服务
+
+[English](IMAGE_PROVIDERS.en.md)
+
+OmniScholar 可连接 OpenAI、xAI、Gemini、Vertex AI、fal.ai、DashScope/Qwen、Atlas 和自定义 OpenAI 兼容服务。实际可用模型取决于账号、地区、服务地址和配置。
+
+## 工具
+
+| 工具 | 用途 |
+|---|---|
+| `omnischolar_image_models` | 查看已配置模型及其可用功能 |
+| `omnischolar_image_generate` | 文生图、图生图或多参考图生成 |
+| `omnischolar_image_edit` | 编辑已有图片 |
+| `omnischolar_image_service` | 调用服务商已经支持的状态、模型或任务操作 |
+| `ai4scholar_figure` | 使用 Ai4Scholar 生成、编辑或矢量化图片 |
+
+每个模型都必须明确声明支持的功能。模型名出现在服务商目录中，并不自动代表它可以生图或编辑；`omnischolar_image_models` 中对应功能需要显示 `usable: true`。
+
+## 配置示例
+
+```json
+{
+  "schemaVersion": 1,
+  "defaults": {
+    "defaultImageProvider": "fal"
+  },
+  "media": {
+    "allowPaid": false,
+    "allowExternalUpload": false,
+    "providers": {
+      "fal": {
+        "enabled": true,
+        "apiKeyEnv": "OMNISCHOLAR_FAL_API_KEY",
+        "baseUrl": "https://fal.run",
+        "models": {},
+        "options": {}
+      }
+    }
+  }
+}
+```
+
+自定义服务需要填写准确的 `baseUrl`、模型 ID、功能列表，以及生成或编辑接口。不要只凭模型名填写功能。
+
+## 生成与编辑
+
+提交任务前应明确图片要表达的科学内容、标签、单位、比例和文件格式。生成需要本次 `allowPaid` 授权；上传参考图还需要本次 `allowExternalUpload` 授权。
+
+只能上传有权交给第三方处理的图片。图片保存后，返回结果中的签名 URL 和 base64 原文会被移除。下载文件会检查 HTTPS 地址、文件大小、MIME 类型和图片文件头；多文件任务缺少任一文件时，不发布不完整结果。
+
+## 当前服务说明
+
+- fal 已验证队列提交、轮询、data URI 结果、文生图和双参考图编辑。本机若无法解析 fal CDN，data URI 结果仍可保存。
+- DashScope/Qwen 当前需要绑定 workspace 的服务地址，或服务商明确提供的 `baseUrl`。旧通用地址会返回 `dashscope_workspace_required`。
+- Gemini 配置中的 `apiKeyEnv` 必须指向已存在的环境变量。
+- Atlas 和自定义服务必须给出可用的服务地址与模型说明。
+
+生成后仍需人工检查文字、结构、机制、比例和定量描述。**AI 图片是示意草稿，不是实验数据、真实测量或科研结论。**

package/docs/INSTALLATION.en.md

@@ -0,0 +1,106 @@
+# Installation and agent setup
+
+[简体中文](INSTALLATION.md)
+
+## Install the Python command
+
+Python 3.11 or newer is required. Choose one installer:
+
+```sh
+uv tool install luffysolution-omnischolar
+pipx install luffysolution-omnischolar
+python -m pip install luffysolution-omnischolar
+```
+
+For development from a source checkout, replace the package name with `.`.
+
+Check the command:
+
+```sh
+omnischolar --version
+omnischolar doctor --json
+```
+
+## Install local MCP and Skills
+
+```sh
+omnischolar install --dry-run claude
+omnischolar install claude
+```
+
+`--dry-run` prints the planned changes without writing files. User scope is the default; use `--scope project` for repository-local configuration:
+
+```sh
+omnischolar install cursor --scope project
+```
+
+| Agent | User MCP | Project MCP | Skills |
+|---|---|---|---|
+| Codex | `~/.codex/config.toml` | `.codex/config.toml` | supported |
+| Claude Code | `~/.claude.json` | `.mcp.json` | supported |
+| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` | supported |
+| OpenCode | `~/.config/opencode/opencode.json` | `opencode.jsonc` | supported |
+| Hermes | `~/.hermes/config.yaml` | manual MCP setup | supported |
+| Pi | npm Extension | npm Extension | supported |
+| WorkBuddy/CodeBuddy | `~/.codebuddy/.mcp.json` | `.mcp.json` | no documented portable path |
+
+For Pi, `omnischolar install pi` installs `npm:@luffysolution/omnischolar-pi` with Pi's package manager and copies the Skills to the selected scope. The Extension starts the local `omnischolar mcp` process. The `pi` command and the Python `omnischolar` command must both be on `PATH`.
+
+WorkBuddy/CodeBuddy supports local stdio MCP servers. Its official documentation does not define a portable Skills directory, so only the MCP component is installed automatically.
+
+## Update, uninstall, and restore
+
+```sh
+omnischolar update claude
+omnischolar uninstall claude
+
+omnischolar mcp install claude
+omnischolar mcp status claude
+omnischolar mcp uninstall claude
+
+omnischolar install skills claude
+omnischolar update skills claude
+omnischolar uninstall skills claude
+
+omnischolar update pi
+omnischolar uninstall pi
+```
+
+A backup is created before each change. If the MCP handshake fails after installation, the previous configuration is restored automatically. To restore a reported backup yourself:
+
+```sh
+omnischolar rollback PATH_TO_BACKUP
+```
+
+Other MCP servers and Skills are left in place. The command stops if an existing `omnischolar` entry was not created by this installer or if a managed Skill was edited locally.
+
+## Use the official Skills CLI
+
+The Skills CLI is separate from Python and MCP installation. Print the command for an agent with:
+
+```sh
+omnischolar npx-skills cursor
+```
+
+For example:
+
+```sh
+npx skills add luffysolution-svg/omnischolar --skill '*' -a cursor -y
+npx skills update -p -y
+```
+
+These commands install Skills only; they do not install the `omnischolar` Python command.
+
+## If MCP does not connect
+
+1. Run `omnischolar --version` from the environment used by the agent.
+2. Run `omnischolar mcp status HOST` to inspect the installed path.
+3. Run `omnischolar doctor --json` to check configuration and output access.
+4. Restart the agent and inspect its MCP log.
+5. Before reinstalling, run `omnischolar install --dry-run HOST`.
+
+The only MCP server entry in this release is local stdio:
+
+```sh
+omnischolar mcp
+```

package/docs/INSTALLATION.md

@@ -0,0 +1,106 @@
+# 安装与 Agent 配置
+
+[English](INSTALLATION.en.md)
+
+## 安装 Python 命令
+
+需要 Python 3.11 或更高版本，任选一种方式：
+
+```sh
+uv tool install luffysolution-omnischolar
+pipx install luffysolution-omnischolar
+python -m pip install luffysolution-omnischolar
+```
+
+如需从源码开发安装，请将包名替换为 `.`。
+
+验证命令是否可用：
+
+```sh
+omnischolar --version
+omnischolar doctor --json
+```
+
+## 安装本地 MCP 与 Skills
+
+```sh
+omnischolar install --dry-run claude
+omnischolar install claude
+```
+
+`--dry-run` 只显示计划，不写文件。默认安装到当前用户；项目级配置使用 `--scope project`：
+
+```sh
+omnischolar install cursor --scope project
+```
+
+| Agent | 用户级 MCP | 项目级 MCP | Skills |
+|---|---|---|---|
+| Codex | `~/.codex/config.toml` | `.codex/config.toml` | 支持 |
+| Claude Code | `~/.claude.json` | `.mcp.json` | 支持 |
+| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` | 支持 |
+| OpenCode | `~/.config/opencode/opencode.json` | `opencode.jsonc` | 支持 |
+| Hermes | `~/.hermes/config.yaml` | 需手动设置 MCP | 支持 |
+| Pi | npm Extension | npm Extension | 支持 |
+| WorkBuddy/CodeBuddy | `~/.codebuddy/.mcp.json` | `.mcp.json` | 无官方可移植目录 |
+
+对 Pi，`omnischolar install pi` 会通过 Pi 包管理器安装 `npm:@luffysolution/omnischolar-pi`，并把 Skills 复制到所选作用域。Extension 会启动本地 `omnischolar mcp` 进程，因此 `pi` 与 Python 的 `omnischolar` 命令都必须位于 `PATH`。
+
+WorkBuddy/CodeBuddy 支持本地 stdio MCP。其官方文档没有定义可移植的 Skills 目录，因此安装器只自动配置 MCP。
+
+## 更新、卸载与恢复
+
+```sh
+omnischolar update claude
+omnischolar uninstall claude
+
+omnischolar mcp install claude
+omnischolar mcp status claude
+omnischolar mcp uninstall claude
+
+omnischolar install skills claude
+omnischolar update skills claude
+omnischolar uninstall skills claude
+
+omnischolar update pi
+omnischolar uninstall pi
+```
+
+修改前会创建备份。若安装后的 MCP 握手失败，原配置会自动恢复。也可手动恢复命令返回的备份：
+
+```sh
+omnischolar rollback PATH_TO_BACKUP
+```
+
+已有的其他 MCP 服务和 Skills 不会被删除。若同名配置不属于 OmniScholar，或已安装的 Skill 被手工改过，命令会停止并说明冲突。
+
+## 使用官方 Skills CLI
+
+Skills CLI 与 Python/MCP 安装相互独立。先查看适合目标 Agent 的命令：
+
+```sh
+omnischolar npx-skills cursor
+```
+
+例如：
+
+```sh
+npx skills add luffysolution-svg/omnischolar --skill '*' -a cursor -y
+npx skills update -p -y
+```
+
+这组命令只安装 Skills，不会安装 `omnischolar` Python 命令。
+
+## MCP 连接失败
+
+1. 运行 `omnischolar --version`，确认 Agent 的 PATH 能找到该命令。
+2. 运行 `omnischolar mcp status HOST` 查看安装位置。
+3. 运行 `omnischolar doctor --json` 检查配置和输出目录。
+4. 重启 Agent，再查看其 MCP 日志。
+5. 若需重新安装，先运行 `omnischolar install --dry-run HOST`。
+
+OmniScholar 的 MCP 入口只有本地 stdio：
+
+```sh
+omnischolar mcp
+```

package/docs/MATERIALS.en.md

@@ -0,0 +1,45 @@
+# Materials and chemistry data
+
+[简体中文](MATERIALS.md)
+
+## Materials Project
+
+Materials Project uses these tools:
+
+| Tool | Use |
+|---|---|
+| `materials_capabilities` | Show supported data types, fields, and filters without a network call |
+| `materials_search` | Filter summary records by formula, elements, chemical system, stability, and related fields |
+| `materials_route_search` | Query specialized collections such as thermo |
+| `materials_get` | Retrieve one material by ID and data type |
+| `materials_advanced` | Retrieve phase data and, with a local backend, calculate XRD |
+| `materials_export` | Save existing results as JSON, CSV, Markdown, or CIF |
+
+Example:
+
+```json
+{
+  "schemaVersion": 1,
+  "data": {
+    "materialsProject": {
+      "enabled": true,
+      "apiKeyEnv": "OMNISCHOLAR_MATERIALS_PROJECT_API_KEY",
+      "maxPages": 5
+    }
+  }
+}
+```
+
+Keep formulas, element sets, chemical systems, material IDs, and task IDs distinct. Each collection accepts different filters; call `materials_capabilities` before building a specialized query.
+
+CIF export uses lattice and site data returned by the service and checks numeric values, occupancy, and coordinates. The exported P1 structure is an exchange representation, not a new symmetry analysis. Computed stability also does not establish experimental synthesizability.
+
+XRD needs an additional local calculation backend. Without it, `materials_advanced` returns `local_backend_required` rather than creating a plausible-looking diffraction curve.
+
+## CAS Common Chemistry
+
+CAS queries are enabled only when the config includes an endpoint and request/response description supplied by the service provider. An API key or website login alone is not enough.
+
+Without that information, `chemical_sources` reports `contract_blocked`; `chemical_search` and `chemical_get` do not guess an endpoint.
+
+CAS data remains subject to CAS licensing, including non-commercial restrictions where applicable.

package/docs/MATERIALS.md

@@ -0,0 +1,45 @@
+# 材料与化学数据
+
+[English](MATERIALS.en.md)
+
+## Materials Project
+
+Materials Project 使用以下工具：
+
+| 工具 | 用途 |
+|---|---|
+| `materials_capabilities` | 查看当前支持的数据类型、字段和筛选条件，不联网 |
+| `materials_search` | 按化学式、元素、化学体系、稳定性等条件筛选材料概览 |
+| `materials_route_search` | 查询 thermo 等专用数据集合 |
+| `materials_get` | 按材料 ID 和指定数据类型获取单条记录 |
+| `materials_advanced` | 获取相图数据；配置本地后端后可计算 XRD |
+| `materials_export` | 将已有结果保存为 JSON、CSV、Markdown 或 CIF |
+
+配置示例：
+
+```json
+{
+  "schemaVersion": 1,
+  "data": {
+    "materialsProject": {
+      "enabled": true,
+      "apiKeyEnv": "OMNISCHOLAR_MATERIALS_PROJECT_API_KEY",
+      "maxPages": 5
+    }
+  }
+}
+```
+
+查询时要分清化学式、元素集合、化学体系、material ID 和 task ID。不同数据集合支持的筛选字段并不相同，可先调用 `materials_capabilities`。
+
+CIF 导出只使用返回记录中的晶格和位点数据，并检查数值、占位率和坐标。导出的 P1 结构用于数据交换，不代表已经完成对称性分析。数据库计算得到的稳定性也不等同于实验可合成性。
+
+XRD 需要额外的本地计算后端。未安装时，`materials_advanced` 会返回 `local_backend_required`，不会生成一条看似真实的衍射曲线。
+
+## CAS Common Chemistry
+
+当前版本只有在配置中提供服务商正式给出的接口地址和请求/响应说明文件后，才会启用 CAS 查询。仅有 API key 或网页登录权限不够。
+
+未提供这些信息时，`chemical_sources` 会显示 `contract_blocked`，`chemical_search` 和 `chemical_get` 不会猜测接口地址。
+
+CAS 数据仍受 CAS 的许可条款约束，其中可能包含非商业使用限制。

package/docs/RESEARCH.en.md

@@ -0,0 +1,83 @@
+# Literature, Zotero, and PDFs
+
+[简体中文](RESEARCH.md)
+
+## Literature search
+
+| Tool | Use |
+|---|---|
+| `research_sources` | Show enabled sources and available operations |
+| `literature_search` | Search papers by year, type, or open-access status |
+| `literature_get` | Retrieve details by DOI, PMID/PMCID, arXiv ID, or source ID |
+| `literature_graph` | Find references, citations, or recommendations |
+| `journal_metrics` | Retrieve supported journal metrics |
+| `literature_fulltext` | Find lawful full-text locations or save an accessible file under the output directory |
+
+The sources serve different purposes:
+
+- Semantic Scholar and OpenAlex cover broad literature and citation relationships.
+- PubMed/PMC focuses on biomedical records; PMC also supplies licensed open full text.
+- arXiv preserves preprint identifiers and versions.
+- Crossref is useful for checking DOI registration metadata.
+- Unpaywall finds open-access copies without bypassing subscriptions or access controls.
+- easyScholar supplies journal metrics supported by its current interface.
+- Ai4Scholar also covers Google Scholar, Google Patents, authors, datasets, and journals. Some calls use account credit.
+
+Start with a small `limit`. Deduplicate by DOI when possible; otherwise compare normalized title, year, and first author. Title similarity can shortlist a paper but cannot establish that it supports a claim.
+
+On HTTP 429, OmniScholar returns a rate-limit result. Wait for the provider's backoff period or choose another source that supports the same operation. Do not submit the same request in a tight loop.
+
+## Zotero
+
+OmniScholar connects only to the local Zotero API:
+
+```text
+http://127.0.0.1:23119/api
+```
+
+Enable “Allow other applications on this computer to communicate with Zotero” and keep Zotero Desktop running.
+
+| Tool | Content |
+|---|---|
+| `zotero_collections` | Collections and collection items |
+| `zotero_search` | Bibliographic items, notes, annotations, and attachments |
+| `zotero_item` | A raw item or a combined paper view |
+
+The combined view can include metadata, notes, annotations, attachment details, indexed text, and a local PDF path. OmniScholar never creates, updates, moves, tags, or deletes Zotero data.
+
+Notes and annotations are personal reading context, not evidence from the publication. Check the paper itself before citing a claim.
+
+## MinerU parsing
+
+`omnischolar_parse` validates the PDF, computes SHA-256, and asks MinerU to return text, formulas, tables, and figures. Results are cached; the same file and parser settings can return a cache hit.
+
+Upload requires both approvals:
+
+1. `mineru.allowExternalUpload` is `true` in the config;
+2. `allowExternalUpload` is `true` in the individual `omnischolar_parse` call.
+
+OmniScholar does not upload a Zotero attachment automatically. Confirm the exact item and file, then approve that upload separately. `force` creates a new parse and upload, so it needs fresh approval.
+
+Before extraction, MinerU archives are checked for unsafe paths, symlinks, excessive entries, and excessive expansion. Failed archives are not published.
+
+## Citations
+
+Citation work has two steps: establish that a source supports the claim, then format its bibliographic record.
+
+1. Find sources with `literature_search` and `literature_get`.
+2. Check DOI, PMID, arXiv ID, title, authors, and year.
+3. Read the passage relevant to the claim.
+4. If paid use is approved, `ai4scholar_citation_candidates` can suggest more candidates.
+5. Use `ai4scholar_cite` only for records you have accepted.
+
+A correctly formatted reference does not prove the claim. Ai4Scholar's Google Scholar citation formatter may lack a result ID required by the upstream interface; if it reports `blocked`, do not invent an ID.
+
+## Markdown and Obsidian output
+
+`omnischolar_sync` shows a plan before writing under `output.rootDirectory`. The directory can be a regular folder or part of an Obsidian vault.
+
+Sync distinguishes new content, no change, metadata changes, parse changes, render changes, missing files, conflicts, exclusions, and interrupted recovery. Metadata repair, rerendering, and transaction recovery do not upload a PDF.
+
+If managed Markdown was edited by hand, the default policy keeps it and writes the incoming version under `.conflicts/`. Review both files before merging.
+
+Before using a real vault, point `output.rootDirectory` at a temporary directory and inspect the folder names, Markdown, and image links.

package/docs/RESEARCH.md

@@ -0,0 +1,83 @@
+# 文献、Zotero 与 PDF
+
+[English](RESEARCH.en.md)
+
+## 文献检索
+
+| 工具 | 用途 |
+|---|---|
+| `research_sources` | 查看已启用的数据源和可用功能 |
+| `literature_search` | 检索论文，可限制年份、类型和开放获取状态 |
+| `literature_get` | 按 DOI、PMID/PMCID、arXiv ID 或数据源 ID 获取详情 |
+| `literature_graph` | 查询参考文献、施引文献或推荐论文 |
+| `journal_metrics` | 查询已支持的期刊指标 |
+| `literature_fulltext` | 查找合法全文地址，或将允许访问的文件保存到输出目录 |
+
+各数据源侧重点不同：
+
+- Semantic Scholar 和 OpenAlex 适合跨学科检索与引用关系。
+- PubMed/PMC 适合生物医学文献，PMC 还能提供带许可信息的开放全文。
+- arXiv 保留预印本标识符和版本信息。
+- Crossref 适合核对 DOI 注册元数据。
+- Unpaywall 用于查找开放获取版本，不绕过订阅或访问控制。
+- easyScholar 提供当前接口支持的期刊指标。
+- Ai4Scholar 还可查询 Google Scholar、Google Patents、作者、数据集和期刊信息，部分调用会消耗额度。
+
+检索时先用较小的 `limit`。优先按 DOI 去重；没有 DOI 时，再比较标题、年份和第一作者。标题相似只能用于筛选，不能代替正文证据。
+
+遇到 HTTP 429 时，OmniScholar 会返回限流信息。等待服务商给出的时间后再试，或改用支持同一查询的数据源。不要连续提交相同请求。
+
+## Zotero
+
+OmniScholar 只连接本机 Zotero API：
+
+```text
+http://127.0.0.1:23119/api
+```
+
+需要在 Zotero 中开启“允许其他应用程序与 Zotero 通信”，并保持 Zotero Desktop 运行。
+
+| 工具 | 可读取内容 |
+|---|---|
+| `zotero_collections` | 收藏夹及其条目 |
+| `zotero_search` | 文献条目、笔记、批注和附件 |
+| `zotero_item` | 单个条目或聚合后的论文视图 |
+
+聚合视图可包含书目信息、笔记、批注、附件信息、索引文本和本地 PDF 路径。OmniScholar 不会创建、修改、移动、加标签或删除 Zotero 数据。
+
+Zotero 笔记和批注属于个人阅读记录，不应当作论文原文证据。需要引用论文结论时，仍要核对原文。
+
+## MinerU 解析
+
+`omnischolar_parse` 检查 PDF 文件、计算 SHA-256，并使用 MinerU 返回正文、公式、表格和图片。解析结果会缓存；同一文件和解析设置再次调用时可直接命中缓存。
+
+上传必须同时得到两次确认：
+
+1. 配置中的 `mineru.allowExternalUpload` 为 `true`；
+2. 本次 `omnischolar_parse` 调用中的 `allowExternalUpload` 为 `true`。
+
+OmniScholar 不会自动把 Zotero 附件上传到 MinerU。应先确认具体条目和文件，再单独批准上传。`force` 会重新解析并产生一次新上传，因此也需要新的授权。
+
+下载的 MinerU 压缩包会在解压前检查路径、符号链接、文件数量和展开大小。检查失败时不写入输出目录。
+
+## 引用
+
+引用工作分为两步：先确认来源是否支持论点，再格式化书目信息。
+
+1. 用 `literature_search` 和 `literature_get` 查找来源。
+2. 核对 DOI、PMID、arXiv ID、标题、作者和年份。
+3. 阅读与论点相关的正文段落。
+4. 使用 `ai4scholar_citation_candidates` 补充候选时，先确认付费调用。
+5. 只对已核对的记录使用 `ai4scholar_cite`。
+
+格式正确的参考文献不代表论点已经得到支持。Ai4Scholar 的 Google Scholar 引用格式化目前可能缺少接口要求的结果 ID；遇到 `blocked` 时，不要自行拼接 ID。
+
+## 保存到 Markdown 或 Obsidian
+
+`omnischolar_sync` 会先给出计划，再写入 `output.rootDirectory`。该目录可以是普通文件夹，也可以位于 Obsidian Vault 中。
+
+同步会区分新建、无需更新、元数据变化、解析变化、渲染变化、文件缺失、冲突、排除和中断恢复。仅修复元数据、渲染或中断事务时不会上传 PDF。
+
+若已生成的 Markdown 被手工修改，默认策略会保留现有文件，并把新版本写入 `.conflicts/`。检查两份内容后再决定如何合并。
+
+首次写入真实 Vault 前，可先把 `output.rootDirectory` 指向临时目录，确认目录名、Markdown 和图片路径符合预期。

package/docs/TOOLS.en.md

@@ -0,0 +1,49 @@
+# Tool list
+
+[简体中文](TOOLS.md)
+
+Tool and capability names match the values returned to agents.
+
+| Tool | Group | Capabilities | Side effects | Network | Credentials | Cost |
+|---|---|---|---|---:|---|---|
+| `omnischolar_status` | runtime | `runtime.status` | none | no | none | free |
+| `omnischolar_capabilities` | runtime | `runtime.capabilities` | none | no | none | free |
+| `research_sources` | literature | `literature.sources` | none | no | none | free |
+| `literature_search` | literature | `literature.search` | none | yes | none | free |
+| `literature_get` | literature | `literature.lookup` | none | yes | none | free |
+| `literature_graph` | literature | `literature.references`, `literature.citations`, `literature.recommendations` | none | yes | none | free |
+| `journal_metrics` | literature | `journal.metrics` | none | yes | none | free |
+| `literature_fulltext` | literature | `fulltext.resolve`, `fulltext.fetch` | filesystem | yes | none | free |
+| `zotero_collections` | zotero | `zotero.collections` | none | yes | none | free |
+| `zotero_search` | zotero | `zotero.search` | none | yes | none | free |
+| `zotero_item` | zotero | `zotero.item`, `zotero.aggregate` | none | yes | none | free |
+| `omnischolar_parse` | parsing | `pdf.parse`, `sync.publish` | external-upload | yes | mineru | metered |
+| `omnischolar_sync` | parsing | `sync.plan`, `sync.apply`, `sync.recovery` | filesystem | yes | none | free |
+| `ai4scholar_search` | ai4scholar | `ai4scholar.search` | paid | yes | ai4scholar | paid |
+| `ai4scholar_paper` | ai4scholar | `ai4scholar.paper` | paid | yes | ai4scholar | paid |
+| `ai4scholar_author` | ai4scholar | `ai4scholar.author` | paid | yes | ai4scholar | paid |
+| `ai4scholar_batch` | ai4scholar | `ai4scholar.batch` | paid | yes | ai4scholar | paid |
+| `ai4scholar_recommend` | ai4scholar | `ai4scholar.recommend` | paid | yes | ai4scholar | paid |
+| `ai4scholar_cite` | citation | `citation.format` | paid | yes | ai4scholar | paid |
+| `ai4scholar_snippets` | ai4scholar | `ai4scholar.snippets` | paid | yes | ai4scholar | paid |
+| `ai4scholar_credits` | ai4scholar | `ai4scholar.credits` | none | yes | ai4scholar | free |
+| `ai4scholar_dataset` | ai4scholar | `ai4scholar.dataset` | paid | yes | ai4scholar | paid |
+| `ai4scholar_journal` | ai4scholar | `ai4scholar.journal` | paid | yes | ai4scholar | paid |
+| `ai4scholar_citation_candidates` | citation | `citation.candidates` | paid | yes | ai4scholar | paid |
+| `ai4scholar_figure` | media | `media.generate`, `media.edit`, `media.vectorize` | paid | yes | ai4scholar | paid |
+| `materials_capabilities` | materials | `materials.capabilities` | none | no | materials-project | free |
+| `materials_search` | materials | `materials.search` | none | yes | materials-project | free |
+| `materials_route_search` | materials | `materials.route-search` | none | yes | materials-project | free |
+| `materials_get` | materials | `materials.lookup` | none | yes | materials-project | free |
+| `materials_advanced` | materials | `materials.phase-diagram`, `materials.xrd` | none | yes | materials-project | free |
+| `materials_export` | materials | `materials.export` | filesystem | no | none | free |
+| `chemical_sources` | chemistry | `chemistry.sources` | none | no | none | free |
+| `chemical_search` | chemistry | `chemistry.search` | none | yes | cas | free |
+| `chemical_get` | chemistry | `chemistry.lookup` | none | yes | cas | free |
+| `omnischolar_image_models` | media | `media.models` | none | yes | none | free |
+| `omnischolar_image_generate` | media | `text-to-image`, `image-to-image`, `multi-reference` | paid | yes | none | paid |
+| `omnischolar_image_edit` | media | `media.edit`, `multi-reference` | paid | yes | none | paid |
+| `omnischolar_image_service` | media | `media.service` | none | yes | none | free |
+
+Arguments not declared in a tool's input schema are rejected.
+Paid or upload-capable tools require both configuration and per-call authorization.

package/docs/TOOLS.md

@@ -0,0 +1,49 @@
+# 工具目录
+
+[English](TOOLS.en.md)
+
+工具名和功能标识保留英文，便于与 Agent 返回结果对照。
+
+| 工具 | 分组 | 功能 | 可能产生的操作 | 联网 | 所需凭据 | 费用类型 |
+|---|---|---|---|---:|---|---|
+| `omnischolar_status` | runtime | `runtime.status` | none | no | none | free |
+| `omnischolar_capabilities` | runtime | `runtime.capabilities` | none | no | none | free |
+| `research_sources` | literature | `literature.sources` | none | no | none | free |
+| `literature_search` | literature | `literature.search` | none | yes | none | free |
+| `literature_get` | literature | `literature.lookup` | none | yes | none | free |
+| `literature_graph` | literature | `literature.references`, `literature.citations`, `literature.recommendations` | none | yes | none | free |
+| `journal_metrics` | literature | `journal.metrics` | none | yes | none | free |
+| `literature_fulltext` | literature | `fulltext.resolve`, `fulltext.fetch` | filesystem | yes | none | free |
+| `zotero_collections` | zotero | `zotero.collections` | none | yes | none | free |
+| `zotero_search` | zotero | `zotero.search` | none | yes | none | free |
+| `zotero_item` | zotero | `zotero.item`, `zotero.aggregate` | none | yes | none | free |
+| `omnischolar_parse` | parsing | `pdf.parse`, `sync.publish` | external-upload | yes | mineru | metered |
+| `omnischolar_sync` | parsing | `sync.plan`, `sync.apply`, `sync.recovery` | filesystem | yes | none | free |
+| `ai4scholar_search` | ai4scholar | `ai4scholar.search` | paid | yes | ai4scholar | paid |
+| `ai4scholar_paper` | ai4scholar | `ai4scholar.paper` | paid | yes | ai4scholar | paid |
+| `ai4scholar_author` | ai4scholar | `ai4scholar.author` | paid | yes | ai4scholar | paid |
+| `ai4scholar_batch` | ai4scholar | `ai4scholar.batch` | paid | yes | ai4scholar | paid |
+| `ai4scholar_recommend` | ai4scholar | `ai4scholar.recommend` | paid | yes | ai4scholar | paid |
+| `ai4scholar_cite` | citation | `citation.format` | paid | yes | ai4scholar | paid |
+| `ai4scholar_snippets` | ai4scholar | `ai4scholar.snippets` | paid | yes | ai4scholar | paid |
+| `ai4scholar_credits` | ai4scholar | `ai4scholar.credits` | none | yes | ai4scholar | free |
+| `ai4scholar_dataset` | ai4scholar | `ai4scholar.dataset` | paid | yes | ai4scholar | paid |
+| `ai4scholar_journal` | ai4scholar | `ai4scholar.journal` | paid | yes | ai4scholar | paid |
+| `ai4scholar_citation_candidates` | citation | `citation.candidates` | paid | yes | ai4scholar | paid |
+| `ai4scholar_figure` | media | `media.generate`, `media.edit`, `media.vectorize` | paid | yes | ai4scholar | paid |
+| `materials_capabilities` | materials | `materials.capabilities` | none | no | materials-project | free |
+| `materials_search` | materials | `materials.search` | none | yes | materials-project | free |
+| `materials_route_search` | materials | `materials.route-search` | none | yes | materials-project | free |
+| `materials_get` | materials | `materials.lookup` | none | yes | materials-project | free |
+| `materials_advanced` | materials | `materials.phase-diagram`, `materials.xrd` | none | yes | materials-project | free |
+| `materials_export` | materials | `materials.export` | filesystem | no | none | free |
+| `chemical_sources` | chemistry | `chemistry.sources` | none | no | none | free |
+| `chemical_search` | chemistry | `chemistry.search` | none | yes | cas | free |
+| `chemical_get` | chemistry | `chemistry.lookup` | none | yes | cas | free |
+| `omnischolar_image_models` | media | `media.models` | none | yes | none | free |
+| `omnischolar_image_generate` | media | `text-to-image`, `image-to-image`, `multi-reference` | paid | yes | none | paid |
+| `omnischolar_image_edit` | media | `media.edit`, `multi-reference` | paid | yes | none | paid |
+| `omnischolar_image_service` | media | `media.service` | none | yes | none | free |
+
+未在输入 schema 中声明的参数会被拒绝。
+付费或上传工具必须同时通过配置开关和本次调用的显式授权。

package/host-configs/README.md

@@ -0,0 +1,11 @@
+# Agent configuration files
+
+- Portable Agent Plugin and Codex: root `plugin.json`, `mcp.json`, and `skills/`
+- Claude Code: `.claude-plugin/plugin.json`, root `.mcp.json`, and `skills/`
+- Cursor: root Agent Plugin files plus `.cursor-plugin/plugin.json`
+- OpenCode: merge `opencode.jsonc` into the project or user OpenCode config
+- Hermes: merge `hermes.yaml` into `~/.hermes/config.yaml`
+- Pi: see `pi.md`; the npm Extension bridges the local MCP server
+- WorkBuddy/CodeBuddy: merge `workbuddy.json` into `~/.codebuddy/.mcp.json` or project `.mcp.json`
+
+All supported MCP entries start the local command `omnischolar mcp`. These files contain no provider credentials.

package/host-configs/hermes.yaml

@@ -0,0 +1,6 @@
+mcp_servers:
+  omnischolar:
+    command: "omnischolar"
+    args: ["mcp"]
+    # Optional: restrict exposure with tools.include or tools.exclude.
+    # Inherit OMNISCHOLAR_* and provider environment variables from Hermes.

package/host-configs/opencode.jsonc

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "omnischolar": {
+      "type": "local",
+      "command": ["omnischolar", "mcp"],
+      "enabled": true,
+      "timeout": 10000
+    }
+  }
+}

package/host-configs/pi.md

@@ -0,0 +1,13 @@
+# Pi
+
+OmniScholar uses the npm-published `@luffysolution/omnischolar-pi` Extension to bridge its local MCP server into Pi. The full installer also copies Skills to `.pi/agent/skills` for user scope or `.pi/skills` for project scope.
+
+```sh
+omnischolar install pi
+# or install only the Extension with Pi's package manager
+pi install npm:@luffysolution/omnischolar-pi
+```
+
+The Extension starts `omnischolar mcp`, discovers the server's tools, forwards calls and cancellation signals, and closes the MCP client when the Pi session ends.
+
+`omnischolar mcp install pi` remains `manual_required` because Pi uses an Extension instead of a native MCP settings file. Use the full `omnischolar install pi` command.

package/host-configs/workbuddy.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "omnischolar": {
+      "type": "stdio",
+      "command": "omnischolar",
+      "args": ["mcp"],
+      "description": "OmniScholar research tools"
+    }
+  }
+}

package/host-configs/workbuddy.md

@@ -0,0 +1,20 @@
+# Tencent WorkBuddy / CodeBuddy
+
+WorkBuddy/CodeBuddy CLI and IDE support local stdio MCP servers. Copy [`workbuddy.json`](workbuddy.json) into the MCP editor, or merge it into one of the documented files:
+
+- User scope: `~/.codebuddy/.mcp.json`
+- Project scope: `.mcp.json`
+
+The installer can write the same entry:
+
+```sh
+omnischolar install workbuddy
+omnischolar install workbuddy --scope project
+```
+
+The official documentation does not define a portable WorkBuddy Skills directory, so the Skills component remains manual.
+
+Official references checked on 2026-09-10:
+
+- <https://www.workbuddy.ai/docs/cli/mcp>
+- <https://www.workbuddy.ai/docs/ide/User-guide/MCP>

package/omnischolar.config.example.json

@@ -0,0 +1,214 @@
+{
+  "schemaVersion": 1,
+  "runtime": {
+    "cacheDirectory": ".omnischolar/cache",
+    "python": "python",
+    "logLevel": "info",
+    "maxOutputBytes": 51200,
+    "maxOutputLines": 2000,
+    "maxResponseBytes": 16777216,
+    "requestTimeoutSeconds": 30,
+    "workspaceRoots": ["."]
+  },
+  "tools": {
+    "groups": {
+      "literature": true,
+      "ai4scholar": true,
+      "zotero": true,
+      "parsing": true,
+      "citation": true,
+      "materials": true,
+      "chemistry": true,
+      "media": true
+    },
+    "disabled": []
+  },
+  "defaults": {
+    "language": "en",
+    "citationStyle": "apa",
+    "literatureLimit": 20,
+    "preferredLiteratureProviders": ["semantic-scholar", "openalex", "crossref"],
+    "defaultImageProvider": "openai"
+  },
+  "research": {
+    "fallback": true,
+    "maxPages": 10,
+    "cacheTtlSeconds": 3600,
+    "providers": {
+      "semantic-scholar": {
+        "enabled": true,
+        "apiKeyEnv": "OMNISCHOLAR_SEMANTIC_SCHOLAR_API_KEY",
+        "maxPages": 10
+      },
+      "openalex": {
+        "enabled": true,
+        "email": "researcher@example.edu",
+        "maxPages": 10
+      },
+      "pubmed": {
+        "enabled": true,
+        "apiKeyEnv": "OMNISCHOLAR_NCBI_API_KEY",
+        "email": "researcher@example.edu",
+        "tool": "omnischolar",
+        "maxPages": 10
+      },
+      "arxiv": {
+        "enabled": true,
+        "maxPages": 10
+      },
+      "crossref": {
+        "enabled": true,
+        "email": "researcher@example.edu",
+        "maxPages": 10
+      },
+      "unpaywall": {
+        "enabled": false,
+        "email": "researcher@example.edu",
+        "maxPages": 10
+      },
+      "easyscholar": {
+        "enabled": false,
+        "apiKeyEnv": "OMNISCHOLAR_EASYSCHOLAR_API_KEY",
+        "maxPages": 5
+      }
+    }
+  },
+  "ai4scholar": {
+    "enabled": false,
+    "baseUrl": "https://ai4scholar.net",
+    "apiKeyEnv": "OMNISCHOLAR_AI4SCHOLAR_API_KEY",
+    "timeoutSeconds": 60,
+    "maxResponseBytes": 16777216,
+    "allowPaid": false
+  },
+  "zotero": {
+    "enabled": true,
+    "baseUrl": "http://127.0.0.1:23119/api",
+    "maxItems": 500
+  },
+  "mineru": {
+    "enabled": false,
+    "baseUrl": "https://mineru.net/api/v4",
+    "lightweightBaseUrl": "https://mineru.net/api/v1/agent",
+    "apiKeyEnv": "OMNISCHOLAR_MINERU_API_KEY",
+    "model": "pipeline",
+    "cacheDirectory": ".omnischolar/mineru",
+    "pollIntervalSeconds": 2,
+    "pollTimeoutSeconds": 600,
+    "maxPdfBytes": 209715200,
+    "allowExternalUpload": false,
+    "allowLightweightFallback": false
+  },
+  "data": {
+    "materialsProject": {
+      "enabled": false,
+      "baseUrl": "https://api.materialsproject.org",
+      "apiKeyEnv": "OMNISCHOLAR_MATERIALS_PROJECT_API_KEY",
+      "maxPages": 10
+    },
+    "casCommonChemistry": {
+      "enabled": false,
+      "apiKeyEnv": "OMNISCHOLAR_CAS_API_KEY",
+      "baseUrl": null,
+      "contractFile": null
+    }
+  },
+  "media": {
+    "allowExternalUpload": false,
+    "allowPaid": false,
+    "maxInputBytes": 26214400,
+    "maxArtifactBytes": 52428800,
+    "providers": {
+      "openai": {
+        "enabled": false,
+        "apiKeyEnv": "OMNISCHOLAR_OPENAI_API_KEY",
+        "baseUrl": "https://api.openai.com/v1",
+        "models": {
+          "gpt-image-1": {
+            "capabilities": ["text-to-image", "image-to-image", "edit", "multi-reference"],
+            "paid": true
+          }
+        },
+        "options": {}
+      },
+      "google": {
+        "enabled": false,
+        "apiKeyEnv": "OMNISCHOLAR_GEMINI_API_KEY",
+        "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
+        "models": {},
+        "options": {}
+      },
+      "vertex": {
+        "enabled": false,
+        "apiKeyEnv": "OMNISCHOLAR_VERTEX_ACCESS_TOKEN",
+        "project": "your-project",
+        "location": "us-central1",
+        "models": {},
+        "options": {}
+      },
+      "xai": {
+        "enabled": false,
+        "apiKeyEnv": "OMNISCHOLAR_XAI_API_KEY",
+        "baseUrl": "https://api.x.ai/v1",
+        "models": {},
+        "options": {}
+      },
+      "fal": {
+        "enabled": false,
+        "apiKeyEnv": "OMNISCHOLAR_FAL_API_KEY",
+        "baseUrl": "https://fal.run",
+        "models": {},
+        "options": {}
+      },
+      "dashscope": {
+        "enabled": false,
+        "apiKeyEnv": "OMNISCHOLAR_DASHSCOPE_API_KEY",
+        "baseUrl": "https://dashscope.aliyuncs.com/api/v1",
+        "models": {},
+        "options": {}
+      },
+      "qwen-cloud": {
+        "enabled": false,
+        "apiKeyEnv": "OMNISCHOLAR_QWEN_API_KEY",
+        "baseUrl": "https://dashscope.aliyuncs.com/api/v1",
+        "models": {},
+        "options": {}
+      },
+      "atlas": {
+        "enabled": false,
+        "apiKeyEnv": "OMNISCHOLAR_ATLAS_API_KEY",
+        "baseUrl": "https://your-atlas-provider.example/v1",
+        "models": {},
+        "options": {}
+      },
+      "custom": {
+        "enabled": false,
+        "apiKeyEnv": "OMNISCHOLAR_CUSTOM_IMAGE_API_KEY",
+        "baseUrl": "https://images.example.edu/v1",
+        "models": {
+          "explicit-model-id": {
+            "capabilities": ["text-to-image"],
+            "paid": true
+          }
+        },
+        "options": {
+          "generationEndpoint": "images/generations",
+          "editEndpoint": "images/edits"
+        }
+      }
+    }
+  },
+  "sync": {
+    "namespace": null,
+    "cacheDirectory": ".omnischolar/sync",
+    "conflictPolicy": "preserve-local",
+    "recovery": true,
+    "backup": true,
+    "avoidUnnecessaryParse": true
+  },
+  "output": {
+    "rootDirectory": "omnischolar-output",
+    "conflictDirectory": ".conflicts",
+    "safeWrites": true
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luffysolution/omnischolar-pi",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Pi MCP bridge for the OmniScholar research toolkit",
   "type": "module",
   "license": "MIT",
@@ -29,7 +29,14 @@
   "files": [
     "pi-extension/dist",
     "README.md",
-    "LICENSE"
+    "README.zh-CN.md",
+    "LICENSE",
+    "PRIVACY.md",
+    "TERMS.md",
+    "THIRD_PARTY_NOTICES.md",
+    "omnischolar.config.example.json",
+    "docs",
+    "host-configs"
   ],
   "pi": {
     "extensions": [

package/pi-extension/dist/index.js

@@ -1,7 +1,7 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { Type } from "typebox";
-const CLIENT_INFO = { name: "omnischolar-pi", version: "0.1.0" };
+const CLIENT_INFO = { name: "omnischolar-pi", version: "0.1.1" };
 export function resultText(result) {
     return result.content
         .map((item) => {