RimaginationRimagination/scansci-pdf/AGENTS.md

scansci-pdf

AGENTS.md1.2k starsChanged 3 months agoMITView on GitHub

ScanSci PDF is an MCP server plus agent skills for academic literature search, citation export, and authorized paper retrieval. This file is the entry point for coding agents working in this repository; host-specific adapters live in the directories listed below. - Python package scansci-pdf (src/scanscipdf), Python 3.11+. - CLI entry point: scansci-pdf (scansci-pdf run starts the stdio MCP server; scansci-pdf run --mode streamablehttp serves HTTP). - 18 MCP tools named scanscipdf*; see .mcp.json for the standard client configuration. Keep the…

Installs packages

We split this AGENTS.md into the rules it gives an agent

4 rules. About 1 is common, 1 is distinctive, and 2 are very specific to this project.

≈1
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Keep the MCP tool names and the source-authorization rules in these skills in sync with the implementation.
line 43
Very specific:
Never re-enable gray sources when the user chose legal_only or scihub_enabled=false.
line 50
Common:
Treat API keys, cookies, proxy credentials, and institution details as secrets.
line 55
Very specific:
Read docs/PLAYBOOK.md before changing anti-bot, mirror, or sniffing code.
line 56

≈ “Common” is an estimate: at least 1 in 5 of the 36,368 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

What runs

Python package scansci-pdf (src/scansci_pdf), Python 3.11+.
CLI entry point: scansci-pdf (scansci-pdf run starts the stdio MCP server; scansci-pdf run --mode streamable_http serves HTTP).
18 MCP tools named scansci_pdf_*; see .mcp.json for the standard client configuration.

Install for development

python -m pip install -e .
# Optional: institutional browsers / WebVPN crypto
python -m pip install -e ".[cloakbrowser,vpnsci]"
scansci-pdf check

Host adapters

Host	Files
Standard MCP clients	`.mcp.json` (`scansci-pdf run`, stdio)
Claude Code	`.claude/skills/` + the standard MCP configuration
Codex App	`.codex-plugin/plugin.json`, `.mcp.json`, `skills/`
ZCode	`zcode-plugin/` (marketplace package, skills, `/scansci` commands)
DeepSeek Harness	`dsh-plugin/` (npm: `scansci-pdf`; bundle: MCP client row + runtime skill registration)

Skills

skill/SKILL.md — canonical, full workflow reference for scansci-pdf.
skills/scansci-pdf/SKILL.md — short host-neutral wrapper.
skills/scansci-sort/SKILL.md — list triage and route planning.
skills/dsh-npm/SKILL.md — DSH bundle adaptation and npm publishing playbook.
zcode-plugin/skills/ — expanded ZCode editions.

Keep the MCP tool names and the source-authorization rules in these skills in sync with the implementation.

Guardrails

Preserve the user's requested download strategy and report the actual source of every download.
Never re-enable gray sources when the user chose legal_only or scihub_enabled=false; scheduling must not expand authorization.
Institutional login happens only in the browser opened by scansci_pdf_login; cookies come from that context, and the egress IP is what the publisher sees.
Treat API keys, cookies, proxy credentials, and institution details as secrets.
Read docs/PLAYBOOK.md before changing anti-bot, mirror, or sniffing code.

Download now (ZIP)

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 28,693 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository4 other files it gives its agents.
- dsh-npmSkill
- scansci-pdfSkill
- scansci-pdfSkill
- scansci-sortSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free