@luffysolution/omnischolar-pi 0.1.1 → 0.1.2

package/LICENSE

@@ -1,9 +1,9 @@
-MIT License
-
-Copyright (c) 2026 OmniScholar contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+MIT License
+
+Copyright (c) 2026 OmniScholar contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/PRIVACY.md

@@ -1,24 +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.
+# 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.2.
+
+## 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/README.md

@@ -1,28 +1,28 @@
 # OmniScholar
 
 <!-- mcp-name: io.github.luffysolution-svg/omnischolar -->
-
-English | [简体中文](README.zh-CN.md)
-
-OmniScholar adds literature search, local Zotero reading, PDF parsing, citation tools, materials data, and scientific image generation to coding agents through a local Python MCP server.
-
-It can search public indexes, combine online records with your Zotero notes, send an approved PDF to MinerU, and publish Markdown into a regular folder or an Obsidian vault. Zotero access is read-only.
-
-## Features
-
-- Search Semantic Scholar, OpenAlex, PubMed/PMC, arXiv, Crossref, Unpaywall, easyScholar, Google Scholar, and Google Patents
-- Retrieve paper details, authors, citations, references, recommendations, snippets, datasets, and journal metrics
-- Read Zotero collections, items, notes, annotations, attachments, indexed text, and local PDF paths without changing the library
-- Parse selected PDFs with MinerU and keep text, formulas, tables, and figures together
-- Find citation candidates, check bibliographic identity, and format accepted references
-- Query Materials Project and export JSON, CSV, Markdown, or CIF
-- Generate or edit scientific illustrations with configured image services
-- Preserve local Markdown edits and place incoming conflict versions in `.conflicts/`
-
-OmniScholar exposes 38 tools. See the [tool list](docs/TOOLS.en.md).
-
-## Install
-
+
+English | [简体中文](README.zh-CN.md)
+
+OmniScholar adds literature search, local Zotero reading, PDF parsing, citation tools, materials data, and scientific image generation to coding agents through a local Python MCP server.
+
+It can search public indexes, combine online records with your Zotero notes, send an approved PDF to MinerU, and publish Markdown into a regular folder or an Obsidian vault. Zotero access is read-only.
+
+## Features
+
+- Search Semantic Scholar, OpenAlex, PubMed/PMC, arXiv, Crossref, Unpaywall, easyScholar, Google Scholar, and Google Patents
+- Retrieve paper details, authors, citations, references, recommendations, snippets, datasets, and journal metrics
+- Read Zotero collections, items, notes, annotations, attachments, indexed text, and local PDF paths without changing the library
+- Parse selected PDFs with MinerU and keep text, formulas, tables, and figures together
+- Find citation candidates, check bibliographic identity, and format accepted references
+- Query Materials Project and export JSON, CSV, Markdown, or CIF
+- Generate or edit scientific illustrations with configured image services
+- Preserve local Markdown edits and place incoming conflict versions in `.conflicts/`
+
+OmniScholar exposes 38 tools. See the [tool list](docs/TOOLS.en.md).
+
+## Install
+
 Python 3.11 or newer is required:
 
 ```sh
@@ -34,33 +34,72 @@ python -m pip install luffysolution-omnischolar
 ```
 
 For development from a source checkout, replace the package name with `.`.
-
-The distribution name is `luffysolution-omnischolar`; the command and Python package are `omnischolar`.
-
-Check the installation:
-
-```sh
-omnischolar --version
-omnischolar doctor --json
-```
-
-## Connect an agent
-
-Preview the files that will change, then install the local MCP entry and Skills:
-
-```sh
-omnischolar install --dry-run claude
-omnischolar install claude
-```
-
+
+The distribution name is `luffysolution-omnischolar`; the command and Python package are `omnischolar`.
+
+Check the installation:
+
+```sh
+omnischolar --version
+omnischolar doctor --json
+```
+
+## Connect an agent
+
+### Codex app and Codex CLI plugin
+
+Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) first, then add the OmniScholar Git marketplace and install the plugin:
+
+```sh
+codex plugin marketplace add luffysolution-svg/omnischolar --ref main
+codex plugin add omnischolar@omnischolar
+```
+
+In the ChatGPT desktop app, restart the app, open **Plugins**, select the **OmniScholar** marketplace, and install or enable **OmniScholar**. In Codex CLI, run `/plugins` to browse the same marketplace.
+
+The plugin bundles all eight Skills and starts its local MCP server with the pinned PyPI release:
+
+```sh
+uvx --from luffysolution-omnischolar==0.1.2 omnischolar mcp
+```
+
+No separate `pip install` is required for this plugin path. The first MCP start needs network access so `uvx` can download and cache the package. Provider credentials and optional service settings remain in your OmniScholar configuration; plugin installation does not collect them.
+
+### Claude Code plugin
+
+Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) first. In Claude Code, add the GitHub marketplace and install the plugin:
+
+```text
+/plugin marketplace add luffysolution-svg/omnischolar
+/plugin install omnischolar@omnischolar
+```
+
+For scripts or a regular terminal, use the non-interactive shell commands:
+
+```sh
+claude plugin marketplace add luffysolution-svg/omnischolar
+claude plugin install omnischolar@omnischolar --scope user
+```
+
+Run `/reload-plugins` if the install summary asks for it, then start a new session. The plugin automatically starts the same pinned `uvx` MCP server and exposes namespaced Skills such as `/omnischolar:scholar-search`. No separate Python installation is required.
+
+### Host configuration installer
+
+Preview the files that will change, then install the local MCP entry and Skills:
+
+```sh
+omnischolar install --dry-run claude
+omnischolar install claude
+```
+
 Replace `claude` with `codex`, `cursor`, `opencode`, `hermes`, `pi`, or `workbuddy`. Codex, Claude Code, Cursor, OpenCode, Pi, and WorkBuddy/CodeBuddy support both user and project scopes. Hermes supports user-level MCP configuration; project-level installation adds Skills and reports that MCP setup is manual.
-
-```sh
-omnischolar install cursor --scope project
-omnischolar update cursor --scope project
-omnischolar uninstall cursor --scope project
-```
-
+
+```sh
+omnischolar install cursor --scope project
+omnischolar update cursor --scope project
+omnischolar uninstall cursor --scope project
+```
+
 For Pi, the full installer runs `pi install npm:@luffysolution/omnischolar-pi` and installs the bundled Skills separately. The npm Extension starts `omnischolar mcp`, discovers its tools, and registers them with Pi. You can also install the Extension directly:
 
 ```sh
@@ -68,86 +107,86 @@ pi install npm:@luffysolution/omnischolar-pi
 ```
 
 WorkBuddy/CodeBuddy uses `~/.codebuddy/.mcp.json` for user scope and `.mcp.json` for project scope. It does not publish a portable Skills path, so its installer configures MCP and reports Skills as `manual_required`.
-
-The MCP command is:
-
-```sh
-omnischolar mcp
-```
-
-Normally the agent starts this process from its MCP configuration. The installer checks `initialize`, `tools/list`, and `omnischolar_status` after writing a supported configuration.
-
-Full host and update instructions are in [Installation](docs/INSTALLATION.en.md).
-
-## Try it
-
-```text
-Find five recent reviews about solid-state battery interfaces. Deduplicate by DOI and show open-access copies.
-
-Find this DOI in my Zotero library and summarize my notes and annotations without changing Zotero.
-
-After I approve the upload, parse this PDF with MinerU and save a reading note in my Obsidian vault.
-
-Query stable Li-Fe-P-O materials in Materials Project and export the selected records as CSV and CIF.
-
-Create a labelled illustration of this mechanism. Treat it as a draft, not experimental data.
-```
-
-## Configuration
-
-Copy [`omnischolar.config.example.json`](omnischolar.config.example.json) to `omnischolar.config.json`. Keep API keys in environment variables and refer to their names with `apiKeyEnv`.
-
-A small local configuration can start with Zotero and the output directory:
-
-```json
-{
-  "schemaVersion": 1,
-  "runtime": { "workspaceRoots": ["./research-inputs"] },
-  "zotero": {
-    "enabled": true,
-    "baseUrl": "http://127.0.0.1:23119/api"
-  },
-  "output": { "rootDirectory": "./research-output" }
-}
-```
-
-OpenAlex, PubMed, arXiv, and Crossref work without API keys. Other services are enabled separately. Configuration fields and provider examples are in [Configuration](docs/CONFIGURATION.en.md).
-
-## Files, uploads, and charges
-
-- Zotero requests go only to the local API on port `23119` and use GET.
-- MinerU receives a PDF only when `allowExternalUpload` is enabled in the config and confirmed again in that tool call.
-- Image services receive prompts and any reference images selected for upload. Generation may use account credit.
-- Ai4Scholar calls may use account credit. A stored key does not by itself approve a paid call.
-- A failed paid request is not retried automatically when the provider may already have accepted it.
-- Generated images are illustrations. They are not measurements, experimental evidence, or scientific results.
-
-See [`PRIVACY.md`](PRIVACY.md) and [Configuration](docs/CONFIGURATION.en.md) before enabling uploads or paid services.
-
-## Included Skills
-
-| Skill | Use |
-|---|---|
-| `omnischolar` | Choose and combine tools for a research request |
-| `scholar-search` | Literature, patents, authors, citation graphs, journals, and datasets |
-| `zotero-research` | Local Zotero matching, notes, annotations, and attachments |
-| `paper-reading` | MinerU parsing and close reading of text, formulas, tables, and figures |
-| `academic-citation` | Evidence checks, citation candidates, formatting, and bibliographies |
-| `scientific-figure` | Image generation, editing, review, and scientific labelling |
-| `materials-project` | Materials screening, properties, provenance, phase data, and export |
-| `chemical-data` | CAS Common Chemistry records when an official interface description is configured |
-
-## Documentation
-
-- [Installation and agent setup](docs/INSTALLATION.en.md)
-- [Configuration and service credentials](docs/CONFIGURATION.en.md)
-- [Literature, Zotero, MinerU, citations, and output](docs/RESEARCH.en.md)
-- [Materials and chemistry](docs/MATERIALS.en.md)
-- [Scientific image providers](docs/IMAGE_PROVIDERS.en.md)
-- [Tool list](docs/TOOLS.en.md)
-
-## Support and license
-
-OmniScholar is open source under the [MIT License](LICENSE). Open a [GitHub issue](https://github.com/luffysolution-svg/omnischolar/issues) or email `LuffySolution@gmail.com`. Remove keys, signed URLs, private paper content, and personal Zotero data before sending a report.
-
-Third-party services and datasets keep their own terms and licenses. See [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
+
+The MCP command is:
+
+```sh
+omnischolar mcp
+```
+
+Normally the agent starts this process from its MCP configuration. The installer checks `initialize`, `tools/list`, and `omnischolar_status` after writing a supported configuration.
+
+Full host and update instructions are in [Installation](docs/INSTALLATION.en.md).
+
+## Try it
+
+```text
+Find five recent reviews about solid-state battery interfaces. Deduplicate by DOI and show open-access copies.
+
+Find this DOI in my Zotero library and summarize my notes and annotations without changing Zotero.
+
+After I approve the upload, parse this PDF with MinerU and save a reading note in my Obsidian vault.
+
+Query stable Li-Fe-P-O materials in Materials Project and export the selected records as CSV and CIF.
+
+Create a labelled illustration of this mechanism. Treat it as a draft, not experimental data.
+```
+
+## Configuration
+
+Copy [`omnischolar.config.example.json`](omnischolar.config.example.json) to `omnischolar.config.json`. Keep API keys in environment variables and refer to their names with `apiKeyEnv`.
+
+A small local configuration can start with Zotero and the output directory:
+
+```json
+{
+  "schemaVersion": 1,
+  "runtime": { "workspaceRoots": ["./research-inputs"] },
+  "zotero": {
+    "enabled": true,
+    "baseUrl": "http://127.0.0.1:23119/api"
+  },
+  "output": { "rootDirectory": "./research-output" }
+}
+```
+
+OpenAlex, PubMed, arXiv, and Crossref work without API keys. Other services are enabled separately. Configuration fields and provider examples are in [Configuration](docs/CONFIGURATION.en.md).
+
+## Files, uploads, and charges
+
+- Zotero requests go only to the local API on port `23119` and use GET.
+- MinerU receives a PDF only when `allowExternalUpload` is enabled in the config and confirmed again in that tool call.
+- Image services receive prompts and any reference images selected for upload. Generation may use account credit.
+- Ai4Scholar calls may use account credit. A stored key does not by itself approve a paid call.
+- A failed paid request is not retried automatically when the provider may already have accepted it.
+- Generated images are illustrations. They are not measurements, experimental evidence, or scientific results.
+
+See [`PRIVACY.md`](PRIVACY.md) and [Configuration](docs/CONFIGURATION.en.md) before enabling uploads or paid services.
+
+## Included Skills
+
+| Skill | Use |
+|---|---|
+| `omnischolar` | Choose and combine tools for a research request |
+| `scholar-search` | Literature, patents, authors, citation graphs, journals, and datasets |
+| `zotero-research` | Local Zotero matching, notes, annotations, and attachments |
+| `paper-reading` | MinerU parsing and close reading of text, formulas, tables, and figures |
+| `academic-citation` | Evidence checks, citation candidates, formatting, and bibliographies |
+| `scientific-figure` | Image generation, editing, review, and scientific labelling |
+| `materials-project` | Materials screening, properties, provenance, phase data, and export |
+| `chemical-data` | CAS Common Chemistry records when an official interface description is configured |
+
+## Documentation
+
+- [Installation and agent setup](docs/INSTALLATION.en.md)
+- [Configuration and service credentials](docs/CONFIGURATION.en.md)
+- [Literature, Zotero, MinerU, citations, and output](docs/RESEARCH.en.md)
+- [Materials and chemistry](docs/MATERIALS.en.md)
+- [Scientific image providers](docs/IMAGE_PROVIDERS.en.md)
+- [Tool list](docs/TOOLS.en.md)
+
+## Support and license
+
+OmniScholar is open source under the [MIT License](LICENSE). Open a [GitHub issue](https://github.com/luffysolution-svg/omnischolar/issues) or email `LuffySolution@gmail.com`. Remove keys, signed URLs, private paper content, and personal Zotero data before sending a report.
+
+Third-party services and datasets keep their own terms and licenses. See [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).