pubmed-access-mcp 0.1.0__tar.gz

pubmed_access_mcp-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. Please also get an approval
+      for your license configuration from the ASF (Apache Software
+      Foundation).
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pubmed_access_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: pubmed-access-mcp
+Version: 0.1.0
+Summary: A minimal, auditable Model Context Protocol (MCP) server for PubMed via NCBI E-utilities with open-access detection.
+Author: ahsanmandhar-ui
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/ahsanmandhar-ui/pubmed-mcp
+Project-URL: Repository, https://github.com/ahsanmandhar-ui/pubmed-mcp
+Project-URL: Issues, https://github.com/ahsanmandhar-ui/pubmed-mcp/issues
+Keywords: mcp,pubmed,ncbi,open-access,model-context-protocol,ai,research
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3,>=1.2.0
+Requires-Dist: requests>=2.31.0
+Dynamic: license-file
+
+# pubmed-mcp
+
+A minimal, auditable [Model Context Protocol](https://modelcontextprotocol.io) server for PubMed via NCBI E-utilities.
+Built for evidence synthesis: the server returns only what NCBI returns, and flags everything else.
+
+## Quick install
+
+    pip install pubmed-access-mcp
+
+Or run without installing:
+
+    uvx pubmed-access-mcp
+
+## Tools
+| Tool | Purpose |
+|---|---|
+| `search_pubmed(query, max_results=20, sort="relevance", date_from=None, date_to=None)` | Returns PMIDs, `total_matches`, and `query_translation` (how PubMed parsed your query; log it in your methods). |
+| `fetch_abstracts(pmids)` | Returns title, authors, journal, date, DOI, publication types, retraction-notice flag, abstract (section labels kept), URL, up to 200 PMIDs per call. |
+| `search_with_access(query, max_results<=100, ...)` | Search, then list each hit as open-access PDF / landing page only / no open access found / unchecked. |
+| `check_access(pmids)` | Same classification for given PMIDs. |
+| `download_pdfs(pmids, folder=None)` | Saves open-access PDFs as PMID<id>.pdf; paywalled papers are skipped, never bypassed. |
+
+## Guarantees
+- Missing field => literal `Data not provided in PubMed abstract`. Nothing is inferred or paraphrased.
+- Requested PMIDs that NCBI did not return are listed in `not_found`.
+- `publication_types` is NCBI's own tag. **No evidence level (CEBM/GRADE) is assigned by the server**: abstracts alone are not enough to grade evidence.
+- `has_retraction_notice` is true only if the record carries an NCBI "RetractionIn" link.
+- Respects NCBI rate limits (3 req/s, 10 req/s with an API key) with retry/backoff.
+
+## Open access and PDFs
+Sources are Unpaywall (via DOI) and PubMed Central (via PMCID). Set `UNPAYWALL_EMAIL` or `NCBI_EMAIL`. `NO_OPEN_ACCESS_FOUND` means no legal free copy is indexed, not that an institution cannot reach it. Every file is checked to start with `%PDF` and bot-check pages are rejected. Files go to `PUBMED_PDF_DIR` (default `~/pubmed_pdfs`). No paywall bypass.
+
+## Register in your MCP client
+
+### After `pip install pubmed-access-mcp`
+Add to your MCP client config (Claude Desktop, Antigravity, Cursor, etc.):
+
+    {"mcpServers": {"pubmed-scraper": {
+      "command": "pubmed-access-mcp",
+      "args": [],
+      "env": {"NCBI_EMAIL": "you@example.com", "UNPAYWALL_EMAIL": "you@example.com"}}}}
+
+### With `uvx` (no install needed)
+
+    {"mcpServers": {"pubmed-scraper": {
+      "command": "uvx",
+      "args": ["pubmed-access-mcp"],
+      "env": {"NCBI_EMAIL": "you@example.com", "UNPAYWALL_EMAIL": "you@example.com"}}}}
+
+### From source (development)
+
+    git clone https://github.com/ahsanmandhar-ui/pubmed-mcp.git
+    cd pubmed-mcp
+    python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+    pip install -r requirements.txt
+
+Then point your MCP config to the absolute path of `.venv/bin/python` (or `.venv\Scripts\python.exe`) and `server.py`.
+
+Optional env: `NCBI_API_KEY` (free, raises rate limit), `NCBI_EMAIL` (NCBI usage policy asks for one), `NCBI_TOOL`.
+
+Put your real `NCBI_API_KEY` / email only in your GLOBAL config, never in a file you commit.
+
+## Install (for development / running tests)
+    python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
+    pip install -r requirements.txt
+    python tests/test_server.py                             # offline tests (synthetic fixture, no network)
+    python tests/test_access.py                             # offline open-access tests
+
+## Limitations
+- Abstract-level data only; no full text. Not a substitute for a full systematic-review search strategy across Embase, Cochrane, etc.
+- Search quality depends on your query syntax (MeSH, field tags); PubMed may translate it unexpectedly, so check `query_translation`.
+- Open-access coverage varies, and some publishers block automated downloads.
+- Live NCBI, Unpaywall, and PDF download behaviour was not covered by automated tests (they use synthetic fixtures).
+
+## License
+Apache License 2.0, see `LICENSE`. Copyright 2024 ahsanmandhar-ui.

pubmed_access_mcp-0.1.0/README.md

@@ -0,0 +1,76 @@
+# pubmed-mcp
+
+A minimal, auditable [Model Context Protocol](https://modelcontextprotocol.io) server for PubMed via NCBI E-utilities.
+Built for evidence synthesis: the server returns only what NCBI returns, and flags everything else.
+
+## Quick install
+
+    pip install pubmed-access-mcp
+
+Or run without installing:
+
+    uvx pubmed-access-mcp
+
+## Tools
+| Tool | Purpose |
+|---|---|
+| `search_pubmed(query, max_results=20, sort="relevance", date_from=None, date_to=None)` | Returns PMIDs, `total_matches`, and `query_translation` (how PubMed parsed your query; log it in your methods). |
+| `fetch_abstracts(pmids)` | Returns title, authors, journal, date, DOI, publication types, retraction-notice flag, abstract (section labels kept), URL, up to 200 PMIDs per call. |
+| `search_with_access(query, max_results<=100, ...)` | Search, then list each hit as open-access PDF / landing page only / no open access found / unchecked. |
+| `check_access(pmids)` | Same classification for given PMIDs. |
+| `download_pdfs(pmids, folder=None)` | Saves open-access PDFs as PMID<id>.pdf; paywalled papers are skipped, never bypassed. |
+
+## Guarantees
+- Missing field => literal `Data not provided in PubMed abstract`. Nothing is inferred or paraphrased.
+- Requested PMIDs that NCBI did not return are listed in `not_found`.
+- `publication_types` is NCBI's own tag. **No evidence level (CEBM/GRADE) is assigned by the server**: abstracts alone are not enough to grade evidence.
+- `has_retraction_notice` is true only if the record carries an NCBI "RetractionIn" link.
+- Respects NCBI rate limits (3 req/s, 10 req/s with an API key) with retry/backoff.
+
+## Open access and PDFs
+Sources are Unpaywall (via DOI) and PubMed Central (via PMCID). Set `UNPAYWALL_EMAIL` or `NCBI_EMAIL`. `NO_OPEN_ACCESS_FOUND` means no legal free copy is indexed, not that an institution cannot reach it. Every file is checked to start with `%PDF` and bot-check pages are rejected. Files go to `PUBMED_PDF_DIR` (default `~/pubmed_pdfs`). No paywall bypass.
+
+## Register in your MCP client
+
+### After `pip install pubmed-access-mcp`
+Add to your MCP client config (Claude Desktop, Antigravity, Cursor, etc.):
+
+    {"mcpServers": {"pubmed-scraper": {
+      "command": "pubmed-access-mcp",
+      "args": [],
+      "env": {"NCBI_EMAIL": "you@example.com", "UNPAYWALL_EMAIL": "you@example.com"}}}}
+
+### With `uvx` (no install needed)
+
+    {"mcpServers": {"pubmed-scraper": {
+      "command": "uvx",
+      "args": ["pubmed-access-mcp"],
+      "env": {"NCBI_EMAIL": "you@example.com", "UNPAYWALL_EMAIL": "you@example.com"}}}}
+
+### From source (development)
+
+    git clone https://github.com/ahsanmandhar-ui/pubmed-mcp.git
+    cd pubmed-mcp
+    python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+    pip install -r requirements.txt
+
+Then point your MCP config to the absolute path of `.venv/bin/python` (or `.venv\Scripts\python.exe`) and `server.py`.
+
+Optional env: `NCBI_API_KEY` (free, raises rate limit), `NCBI_EMAIL` (NCBI usage policy asks for one), `NCBI_TOOL`.
+
+Put your real `NCBI_API_KEY` / email only in your GLOBAL config, never in a file you commit.
+
+## Install (for development / running tests)
+    python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
+    pip install -r requirements.txt
+    python tests/test_server.py                             # offline tests (synthetic fixture, no network)
+    python tests/test_access.py                             # offline open-access tests
+
+## Limitations
+- Abstract-level data only; no full text. Not a substitute for a full systematic-review search strategy across Embase, Cochrane, etc.
+- Search quality depends on your query syntax (MeSH, field tags); PubMed may translate it unexpectedly, so check `query_translation`.
+- Open-access coverage varies, and some publishers block automated downloads.
+- Live NCBI, Unpaywall, and PDF download behaviour was not covered by automated tests (they use synthetic fixtures).
+
+## License
+Apache License 2.0, see `LICENSE`. Copyright 2024 ahsanmandhar-ui.

pubmed_access_mcp-0.1.0/access.py

@@ -0,0 +1,203 @@
+"""Open-access discovery and PDF download for PubMed records.
+
+Rules (same philosophy as server.py): report only what the sources return; never guess.
+Sources: DOI -> Unpaywall (legal open-access locations); PMCID (from PubMed) -> PubMed Central.
+No paywall bypass, no shadow libraries. A paper with no open-access copy is reported as such.
+"""
+import ipaddress
+import os
+import time
+from pathlib import Path
+from typing import Callable, List, Optional
+from urllib.parse import quote, urlparse
+
+import requests
+
+MISSING = "Data not provided in PubMed abstract"
+NO_PDF = "No open-access PDF found"
+UNPAYWALL = "https://api.unpaywall.org/v2"
+PMC_PDF = "https://pmc.ncbi.nlm.nih.gov/articles/{pmcid}/pdf/"
+PMC_PAGE = "https://pmc.ncbi.nlm.nih.gov/articles/{pmcid}/"
+MAX_BYTES = 60 * 1024 * 1024
+UA = {"User-Agent": "pubmed-mcp/1.0 (open-source research tool)"}
+
+OPEN_PDF = "OPEN_ACCESS_PDF"
+OPEN_LANDING = "OPEN_ACCESS_LANDING_PAGE_ONLY"
+NO_OA = "NO_OPEN_ACCESS_FOUND"
+UNCHECKED = "UNCHECKED"
+NO_OA_NOTE = ("No legal open-access copy was indexed by Unpaywall/PubMed Central at check time. Likely paywalled; "
+              "it may still be reachable through your institution, or as an author copy/preprint that is not indexed.")
+
+
+def _clean(v: Optional[str]) -> Optional[str]:
+    v = (v or "").strip()
+    return None if (not v or v.upper().startswith("YOUR_") or v.startswith("${")) else v
+
+
+def unpaywall_email() -> Optional[str]:
+    return _clean(os.environ.get("UNPAYWALL_EMAIL")) or _clean(os.environ.get("NCBI_EMAIL"))
+
+
+def _safe_url(u: str) -> bool:
+    p = urlparse(u or "")
+    if p.scheme not in ("http", "https") or not p.hostname:
+        return False
+    if p.hostname.lower() == "localhost":
+        return False
+    try:
+        ip = ipaddress.ip_address(p.hostname)
+        return not (ip.is_private or ip.is_loopback or ip.is_link_local)
+    except ValueError:
+        return True  # a normal hostname
+
+
+def _unpaywall(doi: str, email: str, get: Callable):
+    try:
+        r = get(f"{UNPAYWALL}/{quote(doi, safe='/:()')}", params={"email": email}, headers=UA, timeout=30)
+    except requests.RequestException as e:
+        return None, f"Unpaywall request failed: {type(e).__name__}"
+    if r.status_code == 404:
+        return None, "DOI not found in Unpaywall"
+    if r.status_code != 200:
+        return None, f"Unpaywall HTTP {r.status_code}"
+    try:
+        return r.json(), None
+    except ValueError:
+        return None, "Unpaywall returned invalid JSON"
+
+
+def classify(rec: dict, email: Optional[str], get: Callable = requests.get) -> dict:
+    doi, pmcid = rec.get("doi", MISSING), rec.get("pmcid", MISSING)
+    has_doi, has_pmc = doi != MISSING, pmcid != MISSING
+    cands, landing, oa_status, note, lookup_ok, is_oa = [], None, "not_checked", "", False, None
+    if has_doi and email:
+        data, err = _unpaywall(doi, email, get)
+        if data:
+            lookup_ok, is_oa = True, data.get("is_oa")
+            oa_status = data.get("oa_status") or MISSING
+            locs = ([data["best_oa_location"]] if data.get("best_oa_location") else []) + (data.get("oa_locations") or [])
+            seen = set()
+            for loc in locs:
+                pdf, page = loc.get("url_for_pdf"), loc.get("url")
+                if pdf and pdf not in seen and _safe_url(pdf):
+                    seen.add(pdf)
+                    cands.append({"url": pdf, "source": f"Unpaywall ({loc.get('host_type') or 'unknown host'})",
+                                  "license": loc.get("license") or MISSING, "version": loc.get("version") or MISSING})
+                elif page and landing is None and _safe_url(page):
+                    landing = page
+        else:
+            note = err
+    elif has_doi:
+        note = "Set UNPAYWALL_EMAIL (or NCBI_EMAIL) to enable the Unpaywall lookup."
+    if has_pmc:
+        cands.append({"url": PMC_PDF.format(pmcid=pmcid), "source": "PubMed Central", "license": MISSING, "version": MISSING})
+        landing = landing or PMC_PAGE.format(pmcid=pmcid)
+    if cands:
+        access = OPEN_PDF
+    elif landing:
+        access = OPEN_LANDING
+    elif lookup_ok and not is_oa:
+        access, note = NO_OA, NO_OA_NOTE
+    else:
+        access = UNCHECKED
+        note = note or ("No DOI or PMCID in the PubMed record." if not (has_doi or has_pmc) else "Open-access status could not be determined.")
+    return {"pmid": rec.get("pmid"), "title": rec.get("title"), "pub_date": rec.get("pub_date"), "doi": doi, "pmcid": pmcid,
+            "has_retraction_notice": rec.get("has_retraction_notice", False), "access": access, "oa_status": oa_status,
+            "pdf_candidates": cands, "landing_url": landing or NO_PDF, "note": note}
+
+
+def check_records(records: List[dict], email: Optional[str], get: Callable = requests.get, delay: float = 0.15) -> List[dict]:
+    out = []
+    for i, rec in enumerate(records):
+        if i and email:
+            time.sleep(delay)
+        out.append(classify(rec, email, get))
+    return out
+
+
+def summarize(results: List[dict]) -> dict:
+    groups = {OPEN_PDF: [], OPEN_LANDING: [], NO_OA: [], UNCHECKED: []}
+    for r in results:
+        c = r["pdf_candidates"]
+        item = {"pmid": r["pmid"], "title": r["title"], "pub_date": r["pub_date"], "doi": r["doi"],
+                "oa_status": r["oa_status"], "has_retraction_notice": r["has_retraction_notice"]}
+        if r["access"] == OPEN_PDF:
+            item.update(pdf_url=c[0]["url"], source=c[0]["source"], other_pdf_sources=len(c) - 1)
+        elif r["access"] == OPEN_LANDING:
+            item["landing_url"] = r["landing_url"]
+        else:
+            item["note"] = r["note"]
+        groups[r["access"]].append(item)
+    return {"counts": {k: len(v) for k, v in groups.items()},
+            "open_access_pdf": groups[OPEN_PDF], "open_access_landing_page_only": groups[OPEN_LANDING],
+            "no_open_access_found": groups[NO_OA], "unchecked": groups[UNCHECKED]}
+
+
+def target_dir(folder: Optional[str]) -> Path:
+    root = Path(os.environ.get("PUBMED_PDF_DIR") or (Path.home() / "pubmed_pdfs"))
+    if folder:
+        p = Path(folder)
+        if p.is_absolute():
+            root = p
+        elif ".." in p.parts:
+            raise ValueError("folder must not contain '..'")
+        else:
+            root = root / p
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def _download(url: str, dest: Path, get: Callable) -> int:
+    if not _safe_url(url):
+        raise ValueError("unsafe or invalid URL")
+    r = get(url, stream=True, timeout=60, headers=UA, allow_redirects=True)
+    part = dest.with_suffix(".part")
+    try:
+        if r.status_code != 200:
+            raise ValueError(f"HTTP {r.status_code}")
+        if int(r.headers.get("Content-Length") or 0) > MAX_BYTES:
+            raise ValueError("file larger than 60 MB limit")
+        size, first = 0, True
+        with open(part, "wb") as f:
+            for chunk in r.iter_content(65536):
+                if first:
+                    if not chunk.startswith(b"%PDF"):
+                        raise ValueError("response is not a PDF (login, consent or bot-check page)")
+                    first = False
+                size += len(chunk)
+                if size > MAX_BYTES:
+                    raise ValueError("file larger than 60 MB limit")
+                f.write(chunk)
+        if size == 0:
+            raise ValueError("empty response")
+        part.replace(dest)
+        return size
+    finally:
+        r.close()
+        if part.exists():
+            part.unlink()
+
+
+def download_many(results: List[dict], folder: Path, get: Callable = requests.get, delay: float = 0.5) -> List[dict]:
+    out = []
+    for r in results:
+        pmid = str(r["pmid"])
+        dest = folder / f"PMID{pmid}.pdf"
+        if not r["pdf_candidates"]:
+            out.append({"pmid": pmid, "status": "skipped", "reason": f"no direct open-access PDF link (access={r['access']})"})
+            continue
+        if dest.exists() and dest.stat().st_size > 0:
+            out.append({"pmid": pmid, "status": "already_exists", "file": str(dest)})
+            continue
+        errors = []
+        for c in r["pdf_candidates"]:
+            try:
+                size = _download(c["url"], dest, get)
+                out.append({"pmid": pmid, "status": "downloaded", "file": str(dest), "bytes": size, "source": c["source"], "url": c["url"]})
+                break
+            except (ValueError, OSError, requests.RequestException) as e:
+                errors.append(f"{c['source']}: {e}")
+            time.sleep(delay)
+        else:
+            out.append({"pmid": pmid, "status": "failed", "reason": errors})
+    return out

pubmed_access_mcp-0.1.0/pubmed_access_mcp.egg-info/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: pubmed-access-mcp
+Version: 0.1.0
+Summary: A minimal, auditable Model Context Protocol (MCP) server for PubMed via NCBI E-utilities with open-access detection.
+Author: ahsanmandhar-ui
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/ahsanmandhar-ui/pubmed-mcp
+Project-URL: Repository, https://github.com/ahsanmandhar-ui/pubmed-mcp
+Project-URL: Issues, https://github.com/ahsanmandhar-ui/pubmed-mcp/issues
+Keywords: mcp,pubmed,ncbi,open-access,model-context-protocol,ai,research
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3,>=1.2.0
+Requires-Dist: requests>=2.31.0
+Dynamic: license-file
+
+# pubmed-mcp
+
+A minimal, auditable [Model Context Protocol](https://modelcontextprotocol.io) server for PubMed via NCBI E-utilities.
+Built for evidence synthesis: the server returns only what NCBI returns, and flags everything else.
+
+## Quick install
+
+    pip install pubmed-access-mcp
+
+Or run without installing:
+
+    uvx pubmed-access-mcp
+
+## Tools
+| Tool | Purpose |
+|---|---|
+| `search_pubmed(query, max_results=20, sort="relevance", date_from=None, date_to=None)` | Returns PMIDs, `total_matches`, and `query_translation` (how PubMed parsed your query; log it in your methods). |
+| `fetch_abstracts(pmids)` | Returns title, authors, journal, date, DOI, publication types, retraction-notice flag, abstract (section labels kept), URL, up to 200 PMIDs per call. |
+| `search_with_access(query, max_results<=100, ...)` | Search, then list each hit as open-access PDF / landing page only / no open access found / unchecked. |
+| `check_access(pmids)` | Same classification for given PMIDs. |
+| `download_pdfs(pmids, folder=None)` | Saves open-access PDFs as PMID<id>.pdf; paywalled papers are skipped, never bypassed. |
+
+## Guarantees
+- Missing field => literal `Data not provided in PubMed abstract`. Nothing is inferred or paraphrased.
+- Requested PMIDs that NCBI did not return are listed in `not_found`.
+- `publication_types` is NCBI's own tag. **No evidence level (CEBM/GRADE) is assigned by the server**: abstracts alone are not enough to grade evidence.
+- `has_retraction_notice` is true only if the record carries an NCBI "RetractionIn" link.
+- Respects NCBI rate limits (3 req/s, 10 req/s with an API key) with retry/backoff.
+
+## Open access and PDFs
+Sources are Unpaywall (via DOI) and PubMed Central (via PMCID). Set `UNPAYWALL_EMAIL` or `NCBI_EMAIL`. `NO_OPEN_ACCESS_FOUND` means no legal free copy is indexed, not that an institution cannot reach it. Every file is checked to start with `%PDF` and bot-check pages are rejected. Files go to `PUBMED_PDF_DIR` (default `~/pubmed_pdfs`). No paywall bypass.
+
+## Register in your MCP client
+
+### After `pip install pubmed-access-mcp`
+Add to your MCP client config (Claude Desktop, Antigravity, Cursor, etc.):
+
+    {"mcpServers": {"pubmed-scraper": {
+      "command": "pubmed-access-mcp",
+      "args": [],
+      "env": {"NCBI_EMAIL": "you@example.com", "UNPAYWALL_EMAIL": "you@example.com"}}}}
+
+### With `uvx` (no install needed)
+
+    {"mcpServers": {"pubmed-scraper": {
+      "command": "uvx",
+      "args": ["pubmed-access-mcp"],
+      "env": {"NCBI_EMAIL": "you@example.com", "UNPAYWALL_EMAIL": "you@example.com"}}}}
+
+### From source (development)
+
+    git clone https://github.com/ahsanmandhar-ui/pubmed-mcp.git
+    cd pubmed-mcp
+    python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+    pip install -r requirements.txt
+
+Then point your MCP config to the absolute path of `.venv/bin/python` (or `.venv\Scripts\python.exe`) and `server.py`.
+
+Optional env: `NCBI_API_KEY` (free, raises rate limit), `NCBI_EMAIL` (NCBI usage policy asks for one), `NCBI_TOOL`.
+
+Put your real `NCBI_API_KEY` / email only in your GLOBAL config, never in a file you commit.
+
+## Install (for development / running tests)
+    python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
+    pip install -r requirements.txt
+    python tests/test_server.py                             # offline tests (synthetic fixture, no network)
+    python tests/test_access.py                             # offline open-access tests
+
+## Limitations
+- Abstract-level data only; no full text. Not a substitute for a full systematic-review search strategy across Embase, Cochrane, etc.
+- Search quality depends on your query syntax (MeSH, field tags); PubMed may translate it unexpectedly, so check `query_translation`.
+- Open-access coverage varies, and some publishers block automated downloads.
+- Live NCBI, Unpaywall, and PDF download behaviour was not covered by automated tests (they use synthetic fixtures).
+
+## License
+Apache License 2.0, see `LICENSE`. Copyright 2024 ahsanmandhar-ui.

pubmed_access_mcp-0.1.0/pubmed_access_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+access.py
+pyproject.toml
+server.py
+pubmed_access_mcp.egg-info/PKG-INFO
+pubmed_access_mcp.egg-info/SOURCES.txt
+pubmed_access_mcp.egg-info/dependency_links.txt
+pubmed_access_mcp.egg-info/entry_points.txt
+pubmed_access_mcp.egg-info/requires.txt
+pubmed_access_mcp.egg-info/top_level.txt
+tests/test_access.py
+tests/test_server.py

pubmed_access_mcp-0.1.0/pubmed_access_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pubmed_access_mcp-0.1.0/pubmed_access_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pubmed-access-mcp = server:main

pubmed_access_mcp-0.1.0/pubmed_access_mcp.egg-info/requires.txt

@@ -0,0 +1,2 @@
+mcp<3,>=1.2.0
+requests>=2.31.0

pubmed_access_mcp-0.1.0/pubmed_access_mcp.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+access
+server

pubmed_access_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pubmed-access-mcp"
+version = "0.1.0"
+description = "A minimal, auditable Model Context Protocol (MCP) server for PubMed via NCBI E-utilities with open-access detection."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [
+    { name = "ahsanmandhar-ui" }
+]
+keywords = ["mcp", "pubmed", "ncbi", "open-access", "model-context-protocol", "ai", "research"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "mcp>=1.2.0,<3",
+    "requests>=2.31.0",
+]
+
+[project.scripts]
+pubmed-access-mcp = "server:main"
+
+[project.urls]
+Homepage = "https://github.com/ahsanmandhar-ui/pubmed-mcp"
+Repository = "https://github.com/ahsanmandhar-ui/pubmed-mcp"
+Issues = "https://github.com/ahsanmandhar-ui/pubmed-mcp/issues"
+
+[tool.setuptools]
+py-modules = ["server", "access"]

pubmed_access_mcp-0.1.0/server.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""PubMed MCP server — NCBI E-utilities (esearch + efetch) over stdio.
+
+Design guarantees
+-----------------
+* Every field comes from the NCBI response. Nothing is inferred, guessed or paraphrased.
+* A field PubMed does not provide is returned as the literal string MISSING
+  ("Data not provided in PubMed abstract").
+* PMIDs that were requested but not returned by NCBI are listed in `not_found`, never fabricated.
+* stdout is reserved for the MCP protocol; all logging goes to stderr.
+
+Env (all optional): NCBI_API_KEY, NCBI_EMAIL, NCBI_TOOL
+"""
+import datetime
+import logging
+import os
+import re
+import sys
+import threading
+import time
+import xml.etree.ElementTree as ET
+from typing import List, Optional
+
+import requests
+import access
+try:  # mcp 1.x
+    from mcp.server.fastmcp import FastMCP
+except ModuleNotFoundError:  # mcp 2.x renamed FastMCP -> MCPServer
+    from mcp.server.mcpserver import MCPServer as FastMCP
+
+logging.basicConfig(stream=sys.stderr, level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
+log = logging.getLogger("pubmed-mcp")
+
+EUTILS = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"
+MISSING = "Data not provided in PubMed abstract"
+MAX_SEARCH = 200
+MAX_FETCH = 200
+PMID_RE = re.compile(r"^\d{1,9}$")
+
+mcp = FastMCP(
+    "pubmed-scraper",
+    instructions=(
+        "Search PubMed and fetch exact records via NCBI E-utilities. Report only what the tools return. "
+        f"If a field equals '{MISSING}', say so; never infer or fill in missing text. "
+        "Do not assign evidence levels from the tool output alone: use publication_types plus the full text."
+    ),
+)
+
+
+# ----------------------------------------------------------------- config / HTTP
+def _env(name: str) -> Optional[str]:
+    v = os.environ.get(name, "").strip()
+    if not v or v.upper().startswith("YOUR_") or v.startswith("${"):
+        return None  # ignore unfilled placeholders instead of sending a bad key to NCBI
+    return v
+
+
+_lock = threading.Lock()
+_last_call = 0.0
+
+
+def _throttle() -> None:
+    """NCBI limits: 3 requests/s without an API key, 10/s with one."""
+    global _last_call
+    gap = 0.11 if _env("NCBI_API_KEY") else 0.34
+    with _lock:
+        wait = _last_call + gap - time.monotonic()
+        if wait > 0:
+            time.sleep(wait)
+        _last_call = time.monotonic()
+
+
+def _request(endpoint: str, params: dict, method: str = "GET") -> requests.Response:
+    params = {**params, "tool": _env("NCBI_TOOL") or "pubmed-mcp"}
+    if _env("NCBI_EMAIL"):
+        params["email"] = _env("NCBI_EMAIL")
+    if _env("NCBI_API_KEY"):
+        params["api_key"] = _env("NCBI_API_KEY")
+    url = f"{EUTILS}/{endpoint}"
+    last = "unknown error"
+    for attempt in range(4):
+        _throttle()
+        try:
+            r = requests.post(url, data=params, timeout=45) if method == "POST" else requests.get(url, params=params, timeout=45)
+            if r.status_code == 200:
+                return r
+            last = f"HTTP {r.status_code}"
+            if r.status_code not in (429, 500, 502, 503, 504):
+                break
+        except requests.RequestException as e:
+            last = f"{type(e).__name__}: {e}"
+        time.sleep(1.5 * (attempt + 1))
+    raise RuntimeError(f"NCBI E-utilities request to {endpoint} failed: {last}")
+
+
+# ----------------------------------------------------------------- parsing (pure functions, unit-tested offline)
+def _text(el: Optional[ET.Element]) -> str:
+    if el is None:
+        return MISSING
+    t = re.sub(r"\s+", " ", "".join(el.itertext())).strip()
+    return t or MISSING
+
+
+def _authors(art: ET.Element):
+    out = []
+    for a in art.findall("AuthorList/Author"):
+        coll = a.findtext("CollectiveName")
+        if coll:
+            out.append(coll.strip())
+            continue
+        last, fore = a.findtext("LastName"), a.findtext("ForeName") or a.findtext("Initials")
+        if last:
+            out.append(f"{last.strip()} {fore.strip()}" if fore else last.strip())
+    return out or MISSING
+
+
+def _abstract(art: ET.Element) -> str:
+    parts = []
+    for el in art.findall("Abstract/AbstractText"):
+        body = re.sub(r"\s+", " ", "".join(el.itertext())).strip()
+        if not body:
+            continue
+        label = el.get("Label")
+        parts.append(f"{label}: {body}" if label else body)
+    return "\n".join(parts) if parts else MISSING
+
+
+def _pub_date(art: ET.Element) -> str:
+    pd = art.find("Journal/JournalIssue/PubDate")
+    if pd is None:
+        return MISSING
+    bits = [pd.findtext(k) for k in ("Year", "Month", "Day")]
+    bits = [b for b in bits if b]
+    return " ".join(bits) if bits else (pd.findtext("MedlineDate") or MISSING)
+
+
+def parse_article(node: ET.Element) -> dict:
+    cit = node.find("MedlineCitation")
+    art = cit.find("Article") if cit is not None else None
+    if cit is None or art is None:
+        return {}
+    pmid = (cit.findtext("PMID") or "").strip()
+    doi, pmcid = MISSING, MISSING
+    for aid in node.findall("PubmedData/ArticleIdList/ArticleId"):
+        if aid.get("IdType") == "doi" and (aid.text or "").strip():
+            doi = aid.text.strip()
+        elif aid.get("IdType") == "pmc" and (aid.text or "").strip():
+            pmcid = aid.text.strip()
+    ptypes = [t.text.strip() for t in art.findall("PublicationTypeList/PublicationType") if t.text and t.text.strip()]
+    retraction = any(c.get("RefType") == "RetractionIn" for c in cit.findall("CommentsCorrectionsList/CommentsCorrections"))
+    return {
+        "pmid": pmid,
+        "title": _text(art.find("ArticleTitle")),
+        "authors": _authors(art),
+        "journal": _text(art.find("Journal/Title")),
+        "pub_date": _pub_date(art),
+        "doi": doi,
+        "pmcid": pmcid,
+        "publication_types": ptypes or MISSING,
+        "has_retraction_notice": retraction,  # True only if NCBI lists a 'RetractionIn' link for this record
+        "abstract": _abstract(art),
+        "url": f"https://pubmed.ncbi.nlm.nih.gov/{pmid}/",
+    }
+
+
+def parse_efetch(xml_text: str, requested: List[str]) -> dict:
+    root = ET.fromstring(xml_text)
+    records = [r for r in (parse_article(n) for n in root.findall("PubmedArticle")) if r]
+    got = {r["pmid"] for r in records}
+    return {"requested": len(requested), "returned": len(records), "records": records,
+            "not_found": [p for p in requested if p not in got]}
+
+
+# ----------------------------------------------------------------- tools
+@mcp.tool()
+def search_pubmed(query: str, max_results: int = 20, sort: str = "relevance",
+                  date_from: Optional[int] = None, date_to: Optional[int] = None) -> dict:
+    """Search PubMed (NCBI esearch) and return PMIDs exactly as NCBI returns them.
+
+    Args:
+      query: PubMed query; supports field tags, MeSH and Boolean, e.g.
+             '"hypertrophic cardiomyopathy"[MeSH] AND mavacamten[tiab] AND randomized controlled trial[pt]'.
+      max_results: 1-200 (default 20). `total_matches` reports the full hit count.
+      sort: 'relevance' or 'pub_date' (newest first).
+      date_from / date_to: optional publication-year bounds (e.g. 2018, 2025).
+    Returns pmids, total_matches and query_translation (how PubMed interpreted the query; log it for reproducibility).
+    """
+    q = (query or "").strip()
+    if not q:
+        raise ValueError("query must be non-empty")
+    if sort not in ("relevance", "pub_date"):
+        raise ValueError("sort must be 'relevance' or 'pub_date'")
+    n = max(1, min(int(max_results), MAX_SEARCH))
+    params = {"db": "pubmed", "term": q, "retmax": n, "retmode": "json", "sort": sort}
+    if date_from or date_to:
+        params.update({"datetype": "pdat", "mindate": str(date_from or 1800),
+                       "maxdate": str(date_to or datetime.date.today().year + 1)})
+    res = _request("esearch.fcgi", params).json().get("esearchresult", {})
+    if "ERROR" in res:
+        raise RuntimeError(f"NCBI esearch error: {res['ERROR']}")
+    return {
+        "query_submitted": q,
+        "query_translation": res.get("querytranslation") or MISSING,
+        "total_matches": int(res.get("count", 0)),
+        "max_results_applied": n,
+        "returned": len(res.get("idlist", [])),
+        "pmids": res.get("idlist", []),
+        "warnings": (res.get("warninglist") or {}).get("outputmessage", []) + (res.get("errorlist") or {}).get("phrasesnotfound", []),
+    }
+
+
+@mcp.tool()
+def fetch_abstracts(pmids: List[str]) -> dict:
+    """Fetch exact PubMed records (NCBI efetch) for up to 200 PMIDs.
+
+    Per record: pmid, title, authors, journal, pub_date, doi, publication_types, has_retraction_notice,
+    abstract (structured abstracts keep their section labels), url.
+    Any field PubMed does not provide is the literal string 'Data not provided in PubMed abstract'.
+    PMIDs NCBI did not return are listed in `not_found`. Never infer or complete missing text.
+    """
+    seen, ids = set(), []
+    for p in pmids or []:
+        s = str(p).strip()
+        if not PMID_RE.match(s):
+            raise ValueError(f"invalid PMID {p!r}: PMIDs are 1-9 digits")
+        if s not in seen:
+            seen.add(s)
+            ids.append(s)
+    if not ids:
+        raise ValueError("provide at least one PMID")
+    if len(ids) > MAX_FETCH:
+        raise ValueError(f"max {MAX_FETCH} PMIDs per call (got {len(ids)}); split the request")
+    r = _request("efetch.fcgi", {"db": "pubmed", "id": ",".join(ids), "retmode": "xml", "rettype": "abstract"}, method="POST")
+    return parse_efetch(r.text, ids)
+
+
+@mcp.tool()
+def check_access(pmids: List[str]) -> dict:
+    """Classify each PMID as open-access PDF, open-access landing page only, no open access found (likely paywalled), or unchecked.
+
+    Uses DOI -> Unpaywall and PMCID -> PubMed Central. 'no_open_access_found' means no legal free copy is indexed;
+    it does not prove the paper cannot be reached through an institution. Max 100 PMIDs per call.
+    Needs UNPAYWALL_EMAIL (or NCBI_EMAIL) for the Unpaywall lookup; without it only PubMed Central links are found.
+    """
+    ids = [str(p).strip() for p in (pmids or [])]
+    if len(set(ids)) > 100:
+        raise ValueError("max 100 PMIDs per call; split the request")
+    data = fetch_abstracts(ids)
+    email = access.unpaywall_email()
+    out = access.summarize(access.check_records(data["records"], email))
+    out.update({"requested": data["requested"], "not_found": data["not_found"], "unpaywall_email_configured": bool(email)})
+    return out
+
+
+@mcp.tool()
+def search_with_access(query: str, max_results: int = 20, sort: str = "relevance",
+                       date_from: Optional[int] = None, date_to: Optional[int] = None) -> dict:
+    """Run a PubMed search, then report for every hit whether a legal open-access PDF exists or the paper looks paywalled.
+
+    max_results is capped at 100 here. Returns query_translation and total_matches (as search_pubmed) plus
+    counts and four lists: open_access_pdf, open_access_landing_page_only, no_open_access_found, unchecked.
+    """
+    s = search_pubmed(query, min(int(max_results), 100), sort, date_from, date_to)
+    head = {"query_submitted": s["query_submitted"], "query_translation": s["query_translation"],
+            "total_matches": s["total_matches"], "returned": s["returned"], "warnings": s["warnings"]}
+    if not s["pmids"]:
+        return {**head, **access.summarize([])}
+    return {**head, **check_access(s["pmids"])}
+
+
+@mcp.tool()
+def download_pdfs(pmids: List[str], folder: Optional[str] = None) -> dict:
+    """Download open-access PDFs for the given PMIDs (max 50) as PMID<id>.pdf. Paywalled papers are skipped, never bypassed.
+
+    folder: absolute path, or a sub-folder name under PUBMED_PDF_DIR (default ~/pubmed_pdfs). Every file is verified
+    to be a real PDF (starts with %PDF); HTML login/bot-check pages are rejected and reported as failed.
+    """
+    ids = [str(p).strip() for p in (pmids or [])]
+    if len(set(ids)) > 50:
+        raise ValueError("max 50 PMIDs per call; split the request")
+    data = fetch_abstracts(ids)
+    results = access.check_records(data["records"], access.unpaywall_email())
+    dest = access.target_dir(folder)
+    rows = access.download_many(results, dest)
+    counts = {}
+    for r in rows:
+        counts[r["status"]] = counts.get(r["status"], 0) + 1
+    return {"folder": str(dest), "counts": counts, "results": rows, "not_found": data["not_found"]}
+
+
+def main():
+    mcp.run()  # stdio transport
+
+
+if __name__ == "__main__":
+    main()

pubmed_access_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pubmed_access_mcp-0.1.0/tests/test_access.py

@@ -0,0 +1,77 @@
+"""Offline tests for access.py. All HTTP responses and records below are SYNTHETIC stand-ins, not real data."""
+import os, sys, tempfile
+from pathlib import Path
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+import access as a
+import server as s
+
+M = a.MISSING
+
+class Resp:
+    def __init__(self, status=200, js=None, chunks=(), headers=None):
+        self.status_code, self._js, self._chunks, self.headers = status, js, chunks, headers or {}
+    def json(self): return self._js
+    def iter_content(self, n): return iter(self._chunks)
+    def close(self): pass
+
+def rec(pmid, doi=M, pmcid=M): return {"pmid": pmid, "title": f"T{pmid}", "pub_date": "2024", "doi": doi, "pmcid": pmcid, "has_retraction_notice": False}
+
+UNPAYWALL = {
+    "10.1/oa":  {"is_oa": True, "oa_status": "gold", "best_oa_location": {"url_for_pdf": "https://pub.example/a.pdf", "url": "https://pub.example/a", "host_type": "publisher", "license": "cc-by", "version": "publishedVersion"}, "oa_locations": []},
+    "10.1/land": {"is_oa": True, "oa_status": "green", "best_oa_location": {"url_for_pdf": None, "url": "https://repo.example/rec/1", "host_type": "repository"}, "oa_locations": []},
+    "10.1/closed": {"is_oa": False, "oa_status": "closed", "best_oa_location": None, "oa_locations": []},
+}
+def fake_unpaywall(url, params=None, **k):
+    doi = url.split("/v2/")[1]
+    return Resp(200, UNPAYWALL[doi]) if doi in UNPAYWALL else Resp(404)
+
+def test_classification():
+    r = {x["pmid"]: x for x in a.check_records(
+        [rec("1", "10.1/oa"), rec("2", "10.1/land"), rec("3", "10.1/closed"), rec("4"), rec("5", pmcid="PMC99"), rec("6", "10.1/nope")],
+        "me@example.org", fake_unpaywall, delay=0)}
+    assert r["1"]["access"] == a.OPEN_PDF and r["1"]["pdf_candidates"][0]["url"] == "https://pub.example/a.pdf"
+    assert r["2"]["access"] == a.OPEN_LANDING and r["2"]["landing_url"] == "https://repo.example/rec/1"
+    assert r["3"]["access"] == a.NO_OA and "institution" in r["3"]["note"]
+    assert r["4"]["access"] == a.UNCHECKED and "No DOI or PMCID" in r["4"]["note"]
+    assert r["5"]["access"] == a.OPEN_PDF and r["5"]["pdf_candidates"][0]["source"] == "PubMed Central"
+    assert r["6"]["access"] == a.UNCHECKED and "not found" in r["6"]["note"]
+
+def test_no_email_degrades_honestly():
+    r = a.classify(rec("7", "10.1/oa"), None, fake_unpaywall)
+    assert r["access"] == a.UNCHECKED and "UNPAYWALL_EMAIL" in r["note"]
+
+def test_summary_groups():
+    sm = a.summarize(a.check_records([rec("1", "10.1/oa"), rec("3", "10.1/closed")], "me@example.org", fake_unpaywall, delay=0))
+    assert sm["counts"][a.OPEN_PDF] == 1 and sm["counts"][a.NO_OA] == 1
+    assert sm["open_access_pdf"][0]["pdf_url"] == "https://pub.example/a.pdf"
+    assert sm["no_open_access_found"][0]["pmid"] == "3"
+
+def test_pmcid_parsed_from_pubmed_xml():
+    xml = ('<PubmedArticleSet><PubmedArticle><MedlineCitation><PMID>5</PMID><Article><ArticleTitle>x</ArticleTitle></Article></MedlineCitation>'
+           '<PubmedData><ArticleIdList><ArticleId IdType="pmc">PMC123</ArticleId></ArticleIdList></PubmedData></PubmedArticle></PubmedArticleSet>')
+    assert s.parse_efetch(xml, ["5"])["records"][0]["pmcid"] == "PMC123"
+
+def test_download_validates_pdf_and_folder_rules():
+    d = Path(tempfile.mkdtemp())
+    res = [a.classify(rec("1", "10.1/oa"), "me@example.org", fake_unpaywall)]
+    ok = lambda url, **k: Resp(200, chunks=[b"%PDF-1.7 ...", b"more"])
+    row = a.download_many(res, d, ok, delay=0)[0]
+    assert row["status"] == "downloaded" and (d / "PMID1.pdf").read_bytes().startswith(b"%PDF")
+    assert a.download_many(res, d, ok, delay=0)[0]["status"] == "already_exists"
+    d2 = Path(tempfile.mkdtemp())
+    html = lambda url, **k: Resp(200, chunks=[b"<html>bot check</html>"])
+    row = a.download_many(res, d2, html, delay=0)[0]
+    assert row["status"] == "failed" and "not a PDF" in row["reason"][0] and not list(d2.iterdir())
+    skipped = a.download_many([a.classify(rec("3", "10.1/closed"), "me@example.org", fake_unpaywall)], d2, ok, delay=0)[0]
+    assert skipped["status"] == "skipped"
+    try: a.target_dir("../escape"); raise AssertionError("traversal allowed")
+    except ValueError: pass
+
+def test_unsafe_urls_rejected():
+    for u in ("file:///etc/passwd", "http://127.0.0.1/x.pdf", "http://localhost/x", "ftp://x/y.pdf", "http://192.168.1.5/a.pdf"):
+        assert not a._safe_url(u), u
+    assert a._safe_url("https://example.org/a.pdf")
+
+if __name__ == "__main__":
+    for n, f in list(globals().items()):
+        if n.startswith("test_"): f(); print("ok", n)

pubmed_access_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,58 @@
+"""Offline tests. The XML below is a SYNTHETIC fixture shaped like NCBI's PubmedArticleSet (not a real record)."""
+import os, sys
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+import server as s
+
+XML = """<?xml version="1.0"?><PubmedArticleSet>
+<PubmedArticle><MedlineCitation><PMID Version="1">111</PMID><Article>
+ <Journal><JournalIssue><PubDate><Year>2024</Year><Month>Mar</Month></PubDate></JournalIssue><Title>Synthetic Journal</Title></Journal>
+ <ArticleTitle>A <i>synthetic</i> trial of X.</ArticleTitle>
+ <Abstract><AbstractText Label="BACKGROUND">Bg text.</AbstractText><AbstractText Label="RESULTS">n = 10; p &lt; 0.05.</AbstractText></Abstract>
+ <AuthorList><Author><LastName>Doe</LastName><ForeName>Jane</ForeName></Author><Author><CollectiveName>Test Group</CollectiveName></Author></AuthorList>
+ <PublicationTypeList><PublicationType>Randomized Controlled Trial</PublicationType></PublicationTypeList>
+</Article><CommentsCorrectionsList><CommentsCorrections RefType="RetractionIn"><PMID>999</PMID></CommentsCorrections></CommentsCorrectionsList></MedlineCitation>
+<PubmedData><ArticleIdList><ArticleId IdType="pubmed">111</ArticleId><ArticleId IdType="doi">10.0000/synthetic</ArticleId></ArticleIdList></PubmedData></PubmedArticle>
+<PubmedArticle><MedlineCitation><PMID Version="1">222</PMID><Article>
+ <Journal><JournalIssue><PubDate><MedlineDate>2020 Jan-Feb</MedlineDate></PubDate></JournalIssue><Title>Other Journal</Title></Journal>
+ <ArticleTitle>No abstract record.</ArticleTitle></Article></MedlineCitation><PubmedData/></PubmedArticle>
+</PubmedArticleSet>"""
+
+def test_full_record():
+    out = s.parse_efetch(XML, ["111", "222", "333"])
+    r = out["records"][0]
+    assert r["title"] == "A synthetic trial of X."
+    assert r["abstract"] == "BACKGROUND: Bg text.\nRESULTS: n = 10; p < 0.05."
+    assert r["authors"] == ["Doe Jane", "Test Group"]
+    assert r["doi"] == "10.0000/synthetic" and r["pub_date"] == "2024 Mar"
+    assert r["publication_types"] == ["Randomized Controlled Trial"]
+    assert r["has_retraction_notice"] is True
+
+def test_missing_fields_are_flagged_not_invented():
+    r = s.parse_efetch(XML, ["222"])["records"][1]
+    for k in ("abstract", "authors", "doi", "publication_types"):
+        assert r[k] == s.MISSING, k
+    assert r["pub_date"] == "2020 Jan-Feb" and r["has_retraction_notice"] is False
+
+def test_not_found_reported():
+    assert s.parse_efetch(XML, ["111", "222", "333"])["not_found"] == ["333"]
+
+def test_input_validation(monkeypatch=None):
+    for bad in (["abc"], [], ["1; DROP"], ["1" * 12]):
+        try: s.fetch_abstracts(bad)
+        except ValueError: continue
+        raise AssertionError(bad)
+
+def test_search_uses_ncbi_fields_only():
+    class R:  # stand-in for the HTTP response
+        def json(self): return {"esearchresult": {"count": "57", "idlist": ["1", "2"], "querytranslation": "x[All Fields]"}}
+    s._request = lambda *a, **k: R()
+    out = s.search_pubmed("x", max_results=999)
+    assert out["total_matches"] == 57 and out["pmids"] == ["1", "2"] and out["max_results_applied"] == 200
+
+def test_placeholder_key_ignored():
+    os.environ["NCBI_API_KEY"] = "YOUR_OPTIONAL_FREE_KEY"
+    assert s._env("NCBI_API_KEY") is None
+
+if __name__ == "__main__":
+    for n, f in list(globals().items()):
+        if n.startswith("test_"): f(); print("ok", n)