{
  "markdown": "# ScholarFetch\n\n![ScholarFetch Logo](./assets/scholarfetch-logo.svg)\n\nScholarFetch is a multi-engine academic research environment for:\n- terminal-first literature exploration\n- MCP-powered agent workflows\n- building curated reading lists and exportable research corpora\n\nIt combines:\n- a rich interactive CLI for humans\n- a classic MCP server (stdio)\n- a FastMCP server (`stdio`, `sse`, `streamable-http`)\n\nThe core idea is simple: start from keywords, DOI, or authors, traverse papers and references, inspect abstracts and full text, save what matters, then export a compact corpus for synthesis.\n\n## What ScholarFetch Does\n- Searches across multiple scholarly engines in parallel\n- Resolves ambiguous author identities and expands author paper lists\n- Traverses references as first-class research nodes\n- Retrieves abstracts and machine-readable full text when available\n- Tracks a saved paper set during an interactive research session\n- Exports citations, abstracts, BibTeX, or full-text corpora\n- Exposes the same research workflow to MCP agents\n- Maintains stateful saved-paper collections inside one MCP session\n\n## Engines\n- Elsevier (Scopus / Abstract / Article retrieval)\n- OpenAlex\n- Crossref\n- arXiv\n- Europe PMC\n- Springer Nature (metadata + open access)\n- Semantic Scholar (DOI enrichment path)\n\n## Installation\n```bash\ngit clone https://github.com/laibniz/scholarfetch.git\ncd scholarfetch\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e .\nscholarfetch\n```\n\nConsole scripts:\n- `scholarfetch`\n- `scholarfetch-mcp`\n- `scholarfetch-fastmcp`\n\nAlternative:\n```bash\npython3 scholarfetch.py\n```\n\n## Credentials\nScholarFetch loads provider credentials server-side / client-side from environment.\n\nDefault env file:\n- `.scholarfetch.env`\n\nTypical variables:\n```bash\nELSEVIER_API_KEY=...\nELSEVIER_INSTTOKEN=...\nSPRINGER_META_API_KEY=...\nSPRINGER_OPENACCESS_API_KEY=...\n```\n\nNotes:\n- `ELSEVIER_INSTTOKEN` is optional\n- provider entitlements and rate limits still apply\n- MCP tools do not accept API keys in tool arguments\n\n## CLI Research Workflow\nScholarFetch CLI is designed for research traversal.\n\nTypical flow:\n1. Start from a topic, DOI, or author.\n2. Inspect papers.\n3. Read abstracts or full text.\n4. Expand references.\n5. Jump to related authors.\n6. Save promising papers.\n7. Export a corpus for downstream work.\n\nExample:\n```text\n/search graph neural networks\n/author Albert Einstein\n/papers 1 has:abstract\n/article 1\n/refs 1\n/saved\n/export fulltext dummy corpus.txt\n```\n\n## CLI Features\n- Interactive picker with tree navigation\n- Breadcrumbs for current research position\n- Action bar for `OPEN`, `ABSTRACT`, `TEXT`, `REFS`, and `AUTHOR`\n- `Backspace` to go to parent node\n- `Esc` to return to prompt\n- `S` to save a paper from paper lists or reference lists\n- `X` to remove from the saved list\n- `AUTHOR` action from a paper now lets you select:\n  - a single author\n  - `ALL AUTHORS`\n- Reference lists behave like paper lists:\n  - `open`\n  - `abstract`\n  - `text`\n  - `refs`\n  - `author`\n- Automatic paper availability hints:\n  - abstract availability\n  - full-text availability\n- Progress feedback for expensive transitions\n- Interruptible reference preview building with partial results kept\n\n## Core CLI Commands\n- `/search <keywords|doi|person name>`\n- `/author <name>`\n- `/papers <author name|index> [filters]`\n- `/doi <doi>`\n- `/open <index>`\n- `/abstract <doi|index>`\n- `/article <doi|index>`\n- `/refs <doi|index>`\n- `/ref <index>`\n- `/saved`\n- `/export [format style path ...]`\n- `/import [path]`\n- `/pick [mode]`\n- `/config`\n- `/engines`\n- `/help`\n\n## Paper Filters\nUse with `/papers`:\n- `year>=YYYY`, `year<=YYYY`, `year=YYYY`\n- `has:abstract`, `has:doi`, `has:pdf`, `has:fulltext`\n- `venue:<text>`, `title:<text>`, `doi:<text>`\n\nExamples:\n```text\n/papers 1 year>=2020 has:abstract\n/papers 1 has:fulltext\n/papers andrea de mauro venue:marketing\n```\n\n## Export Modes\nScholarFetch supports four export modes from the saved paper set.\n\n- `bib`\n  - BibTeX for citation managers and bibliographic tooling\n- `citations`\n  - citation-only export in `harvard`, `apa`, or `ieee`\n- `abstracts`\n  - metadata + abstract for each saved paper\n- `fulltext`\n  - metadata + abstract + full text when available\n  - optional inclusion of references\n\nThis makes ScholarFetch useful as a corpus builder for downstream synthesis agents.\n\n## MCP Server\nScholarFetch exposes the same research model through MCP.\n\nModes:\n- Classic MCP (stdio): `python3 scholarfetch_mcp.py`\n- FastMCP stdio: `python3 scholarfetch_fastmcp.py --transport stdio`\n- FastMCP SSE: `python3 scholarfetch_fastmcp.py --transport sse --host 127.0.0.1 --port 8000`\n- FastMCP streamable HTTP: `python3 scholarfetch_fastmcp.py --transport streamable-http --host 127.0.0.1 --port 8000 --http-path /mcp`\n\nValidation:\n```bash\npython3 scholarfetch_mcp.py --self-test\npython3 scholarfetch_fastmcp.py --self-test\n```\n\nPublic demo endpoints:\n- Web UI: https://huggingface.co/spaces/Laibniz/ScholarFetch_Web\n- Public MCP endpoint: https://laibniz-scholarfetch-web.hf.space/mcp/\n- MCP Registry listing: `io.github.laibniz/scholarfetch`\n\n## MCP Research Model\nThe MCP server is designed for agent workflows, not only one-off calls.\n\nAn agent can:\n1. Search papers\n2. Resolve authors\n3. Expand to author papers\n4. Read abstracts / full text\n5. Expand references\n6. Save promising papers into a named in-memory reading list\n7. Export the reading list as:\n   - citations\n   - abstracts\n   - BibTeX\n   - full-text corpus\n\nThis lets an agent build a focused research set inside one MCP session and then hand off an export artifact to another synthesis step.\n\nSee [MCP_SERVER.md](./MCP_SERVER.md) for the detailed tool model.\n\n## Repository Files\n- `scholarfetch.py`: CLI entrypoint\n- `scholarfetch_cli.py`: core CLI + retrieval logic\n- `scholarfetch_mcp.py`: classic MCP server\n- `scholarfetch_fastmcp.py`: FastMCP server\n- `MCP_SERVER.md`: MCP usage guide\n- `AGENTS.md`: agent-facing workflow guide\n- `SKILL.md`: structured research skill guide\n- `SKILLS.md`: index for agent-facing skill docs\n- `CONTRIBUTING.md`: contributor notes\n\n## For Agents\nIf you are running ScholarFetch from an MCP-compatible system, read:\n- [AGENTS.md](./AGENTS.md)\n- [SKILL.md](./SKILL.md)\n- [SKILLS.md](./SKILLS.md)\n\nThese documents explain how to use ScholarFetch as a literature-research environment rather than as a flat search API.\n\n## Contributing\nSee [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## Security\nSee [SECURITY.md](./SECURITY.md).\n\n## License\nMIT License. See [LICENSE](./LICENSE).\n",
  "bytes": 6546,
  "sha": "6584ad07469af8752ba265816b3805b92e333629ea1289388a4e109882f787d0",
  "repo_slug": "laibniz/scholarfetch",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_laibniz_scholarfetch_0a0b74aa/readme"
}