Skip to content

feat(plugins): add NkAntony777/scansci-pdf academic paper retrieval plugin - #64

Open
NkAntony777 wants to merge 4 commits into
MiniMax-AI:mainfrom
NkAntony777:plugin/scansci-pdf
Open

NkAntony777 wants to merge 4 commits into
MiniMax-AI:mainfrom
NkAntony777:plugin/scansci-pdf

Conversation

@NkAntony777

@NkAntony777 NkAntony777 commented Sep 26, 2026 •

Copy link
Copy Markdown

Add scansci-pdf — academic paper retrieval plugin

Problem

MiniMax Code users who do literature work need paper retrieval: download by DOI/arXiv, search
and export citations, and bulk-process reading lists of hundreds to thousands of entries.
Doing this by hand (per-site browsing, manual OA checks, re-downloading failures) is slow and
error-prone. scansci-pdf (upstream, Apache-2.0,
v1.17.0) solves this with a 20+ source hedged cascade, lane-scheduled batch downloading, and
user-authorized institutional routes. This PR packages it as an Agent Plugin: two Skills plus a
stdio MCP server.

Example prompt

Download this paper for me: 10.1038/s41586-024-07386-0, and give me the BibTeX entry.

Expected result: the agent resolves the DOI, downloads the PDF (reporting which source produced
it, typically an open-access direct link within seconds), saves it to the working directory,
and returns a verified BibTeX record.

Dependencies and platforms

  • Python >= 3.11 with the scansci-pdf executable on PATH (pip install scansci-pdf or
    uv tool install scansci-pdf; the PyPI wheel ships a prebuilt Cython core, no compiler
    needed). Optional headless-browser extra: scansci-pdf[camoufox].
  • Windows / macOS / Linux. No MiniMax Code host tools required (MCP server runs as
    scansci-pdf run over stdio; CLI fallback works without MCP).
  • The engine is installed from PyPI and never vendored into this folder — the plugin package
    contains only markdown and JSON (no binaries, no credentials, no installers).

Network and data behavior

  • Outbound requests to scholarly APIs and mirrors: OpenAlex, Unpaywall, Crossref, Semantic
    Scholar, Europe PMC/PMC, arXiv, DOAJ, OpenAIRE, publisher sites/CDNs (Elsevier, Springer,
    MDPI), Sci-Hub mirrors, LibGen, and the user's own institutional WebVPN/CARSI endpoints.
  • Unpaywall requires the user's real email (requested via MCP config_needed/
    ask_user_email when missing — never silently skipped).
  • Institutional routes use the user's own credentials (Elsevier API key on campus network,
    WebVPN/CARSI browser login). Config, credentials, and cookies stay local in ~/.scansci-pdf/.
  • Grey-source lanes (Sci-Hub/LibGen) are on by default upstream; a legal_only strategy
    restricts to lawful sources.

Ownership and maintenance

Upstream engine by Rimagination (Apache-2.0, Copyright 2024-2026 scansci-pdf contributors —
LICENSE in the plugin dir is upstream's verbatim). This package redistributes the two Skill
documents and MCP wiring from upstream v1.17.0 and tracks upstream releases. Submitted and
maintained here by @NkAntony777.

Test evidence

  • npm run check: OK plugin NkAntony777/scansci-pdf (hosted-plugin validator: manifest,
    Skills, MCP transport, required docs, placeholders, path safety).
  • scansci-pdf check and scansci-pdf run --mode stdio verified working on Windows 11 with
    Python 3.13 (uv tool install scansci-pdf), including a live MCP session in another agent
    host (ZCode) using the same skills + stdio server wiring.
  • Note: 6 tests in tests/plugins/octopus-meme-maker/smoke.test.mjs fail on main both with
    and without this change (verified via stash) — pre-existing, unrelated to this PR.

View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.

…lugin

Wraps the upstream scansci-pdf engine (Rimagination/scansci-pdf, Apache-2.0,
v1.17.0) as two Skills (download/search/troubleshoot + large-list triage) and a
stdio MCP server (scansci-pdf run). Engine installed from PyPI, not vendored;
credentials and config stay local.
- add .minimax-plugin/plugin.json (MiniMax V1 manifest) required by marketplace validation
- rename mcp.json -> scansci-pdf.mcp.json and align with *.mcp.json schemaVersion format
- add icon.png referenced by the manifest
- re-encode icon.png to a clean 512x512 RGBA PNG (drops the non-standard
  caBX chunk carried from the source image, matching the standard chunk
  profile of icons already accepted by the marketplace)
- bump package version after content change per submission guide
…17.2

The description contained 'DOIs): classify' - a colon+space inside an
unquoted YAML scalar breaks frontmatter parsing (Marketplace V1 check
SKILL_FRONTMATTER_INVALID). Reworded to a comma construction; verified
both SKILL.md frontmatters parse with a YAML parser.

@hetaoBackend hetaoBackend left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Request changes for exact current head b523ef43ec9fef79c83dc03efbdba07b689290d6.

Blocking supply-chain/security/host-contract issues:

  1. The public oa_url queue field is fetched with redirects and no loopback/private/link-local/metadata/DNS-rebinding policy. A controlled loopback PDF URL was accepted and requested. Enforce per-hop public HTTPS/IP validation at the actual connection boundary and add redirect/rebinding regressions.
  2. The MCP-exposed Tor installer downloads a tar and uses unchecked tarfile.extractall(), then marks discovered binaries executable. A ../ member was reproduced writing outside the target directory. Reject absolute/traversal/link members and verify a pinned signature/hash before extraction/execution.
  3. Plugin manifests say 1.17.2, but that upstream/PyPI version does not exist; README references 1.17.0, installation is unpinned, and MCP executes bare scansci-pdf from PATH. Pin an existing audited package plus integrity/provenance and bind the launched executable/version.
  4. springer_api_key is omitted from masking and can be returned by scansci_pdf_config; config/cookie state is written without restrictive mode (reproduced as 0644 under umask 022). Mask all credentials and use 0600/symlink-safe persistence.
  5. Core Skill workflows reference scripts/sort_finalize_writeback.py and scripts/sort_mdpi_res_batch.py, but those scripts are not packaged. The nonstandard scansci-pdf.mcp.json is also not validated by the repository’s root mcp.json contract. Ship and test the actual package/host layout.
  6. Cache/output/destructive paths lack workspace containment, symlink policy and confirmation; paper content is returned into model context without an explicit prompt-injection trust boundary.

Exact-head CI/CodeQL are action_required; the only visible check is [code]smith = SKIPPED, which is not evidence.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants