Metadata-Version: 2.5
Name: luffysolution-omnischolar
Version: 0.1.0
Summary: Literature, Zotero, PDF, citation, materials, and scientific image tools for local MCP agents
Project-URL: Homepage, https://github.com/luffysolution-svg/omnischolar
Project-URL: Repository, https://github.com/luffysolution-svg/omnischolar.git
Project-URL: Issues, https://github.com/luffysolution-svg/omnischolar/issues
Author-email: OmniScholar contributors <LuffySolution@gmail.com>
License: 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.
License-File: LICENSE
Keywords: agent-plugin,literature,mcp,mineru,research,zotero
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: anyio<5,>=4.8
Requires-Dist: defusedxml<1,>=0.7
Requires-Dist: httpx<1,>=0.28
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: mcp<2,>=1.12.4
Requires-Dist: platformdirs<5,>=4.3
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: pyyaml<7,>=6
Requires-Dist: tomlkit<1,>=0.13
Provides-Extra: media-google
Requires-Dist: google-auth<3,>=2.38; extra == 'media-google'
Description-Content-Type: text/markdown

# 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

Python 3.11 or newer is required:

```sh
uv tool install luffysolution-omnischolar
# or
pipx install luffysolution-omnischolar
# or
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
```

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
```

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
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).
