Metadata-Version: 2.4
Name: meok-bio-lookup-mcp
Version: 0.1.0
Summary: MEOK Labs biomedical literature + trial lookup MCP. Real PubMed E-utilities (NCBI) + ClinicalTrials.gov v2, Ed25519-signed receipts, hermetic-friendly (live calls in tools, but every test runs offline).
Author-email: "MEOK AI Labs (CSOAI LTD)" <csoai@meok.ai>
License: MIT License
        
        Copyright (c) 2026 MEOK AI Labs (CSOAI LTD)
        
        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.
        
        Data attribution
        ----------------
        This MCP wraps public APIs:
        
        * PubMed E-utilities — U.S. National Library of Medicine, National Institutes
          of Health. https://eutils.ncbi.nlm.nih.gov/entrez/query/static/eutils_help.html
          No API key required; rate limit 3 req/s without API key.
        * ClinicalTrials.gov v2 API — U.S. National Library of Medicine, National
          Institutes of Health. https://clinicaltrials.gov/data-api/about-api
          No API key required; rate limit ~50 req/min.
        
        Use of these APIs does not imply endorsement by NLM/NIH. This MCP performs
        no clinical interpretation — it returns public records verbatim. Downstream
        tools must not present the outputs as medical advice.
Project-URL: Homepage, https://github.com/meok-ai-labs/meok-bio-lookup-mcp
Project-URL: Repository, https://github.com/meok-ai-labs/meok-bio-lookup-mcp
Project-URL: Issues, https://github.com/meok-ai-labs/meok-bio-lookup-mcp/issues
Keywords: pubmed,ncbi,eutils,clinicaltrials-gov,biomedical,research,mcp,meok,ed25519
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42.0.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# meok-bio-lookup-mcp

> **Biomedical literature + clinical-trial lookup MCP.** Real PubMed
> E-utilities (NCBI) + ClinicalTrials.gov v2. Ed25519-signed receipts.
> Hermetic by default (offline tests, live at call time). MIT.

This is a [Model Context Protocol](https://modelcontextprotocol.io/) server
that wraps two public biomedical APIs and returns every result wrapped in an
**Ed25519-signed envelope** so a downstream regulator / auditor can verify
the response was produced by this build of the server with the public key
in `meok_bio_lookup_mcp.server.ISSUER_PUBLIC_KEY_HEX`.

It does **not** interpret, summarise, or recommend — it returns public records
verbatim. Downstream tools must not present the outputs as medical advice.

## Honesty register (read first)

This MCP is part of **MEOK AI Labs (CSOAI LTD)** research tooling.
What this MCP does:

- wraps the **real, public, free** PubMed E-utilities and ClinicalTrials.gov
  v2 APIs (no mock data);
- signs every result with **Ed25519** (so a downstream auditor can verify
  provenance — this is **not** a certification, an attestation body, or a
  clinical-validity claim);
- emits clear **rate-limit + attribution** notes for the public APIs it wraps.

What this MCP does **not** claim:

- it is **not** certified by any clinical-validity, regulatory, or
  accreditation body;
- it does **not** provide free compute credits, free-tier access, or
  partnership terms of any kind (those are commercial questions for the
  owner of MEOK Labs);
- it is **not** affiliated with, endorsed by, or sponsored by the U.S.
  National Library of Medicine, the National Institutes of Health, or any
  other public health authority;
- it provides **no clinical interpretation** — results are returned verbatim
  from the source API.

## The 5 tools

| # | Tool | Source API | Purpose |
|---|------|-----------|---------|
| 1 | `pubmed_search` | NCBI E-utilities `esearch.fcgi` | Resolve a free-text query into a list of PubMed IDs (PMIDs). |
| 2 | `pubmed_fetch` | NCBI E-utilities `efetch.fcgi` | Fetch full bibliographic records (title, authors, abstract, MeSH) for a list of PMIDs. |
| 3 | `clinicaltrials_search` | CT.gov v2 `/studies` | Search ClinicalTrials.gov by condition, intervention, status, sponsor, or free text. |
| 4 | `clinicaltrials_fetch` | CT.gov v2 `/studies/{NCT}` | Fetch one trial by its NCT ID. |
| 5 | `cross_link_pmid_nct` | both APIs | Given a PMID, find any NCT IDs referenced by the paper; given an NCT ID, find any PMIDs listed as references. |

Every tool returns a signed envelope:

```json
{
  "status": "ok",
  "tool": "pubmed_search",
  "input": {...},
  "data": {...},
  "issued_at": "2026-07-05T10:00:00Z",
  "kid": "meok-issuer-<hex>",
  "issuer": "meok.ai",
  "signature": "<hex Ed25519>"
}
```

Verify offline:

```python
from meok_bio_lookup_mcp.server import verify_envelope, ISSUER_PUBLIC_KEY_HEX
verify_envelope(envelope, envelope["signature"])  # True / False
```

## Install

```bash
cd meok-bio-lookup-mcp
pip install -e ".[dev]"
```

## Run

```bash
# As a stdio MCP server (the typical host):
python -m meok_bio_lookup_mcp.server
```

## Test

```bash
cd meok-bio-lookup-mcp
pytest -q
```

Tests are hermetic — they do not call the public APIs. They exercise the
formatter, the Ed25519 envelope round-trip, the cache behaviour, and the
offline tools. To exercise the live APIs, run `pytest --live`.

## Attribution

This MCP wraps:

- **PubMed E-utilities** — U.S. National Library of Medicine, NIH.
  https://www.ncbi.nlm.nih.gov/books/NBK25500/
- **ClinicalTrials.gov v2 API** — U.S. National Library of Medicine, NIH.
  https://clinicaltrials.gov/data-api/about-api

Per the NCBI terms (https://www.ncbi.nlm.nih.gov/home/about/policies/),
this MCP identifies itself as `meok-bio-lookup-mcp/0.1.0` in the
`User-Agent` / `tool` query-string parameter.

## Rate limits (the honest numbers)

- PubMed E-utilities (no API key): **3 requests/sec, max**.
- ClinicalTrials.gov v2: documented at ~**50 requests/min**, with a
  hard ceiling above which the API returns HTTP 429.

The MCP **respects these limits**: it sleeps between sequential calls and
emits the observed `x-ratelimit-*` headers (when present) into the envelope
metadata so the caller can see the budget.

## License

MIT — see `LICENSE`.
