drpwchen/openevidence-tools

繁體中文版 → README.zh-TW.md
Two pieces that work together to use OpenEvidence as an
evidence source you can actually trust:
1. An MCP server that exposes OpenEvidence to any MCP client (Claude Code, etc.) as four
tools — ask_openevidence, list_recent_oe_queries, fetch_oe_result, ask_oe_followup.
2. The /oe-verify skill (optional, recommended), which cross-checks every citation in
an OE answer against primary sources and flags what OE left out. The MCP server works without
it; installing it is one copy into your skills folder — see
Optional: the /oe-verify skill.
Why both? OpenEvidence answers clinical questions fast, but it is a RAG pipeline (vector
search + LLM synthesis), and its citations can be wrong even when the underlying claim is real.
The classic failure is transitive citation: OE retrieves a chunk of a review's full text
in which the review quotes another trial's number, then credits that number to the review
itself. The claim is true; the attribution is false. Never absorb an OE answer unverified —
that is the whole reason /oe-verify exists.
## Quickstart
You need an OpenEvidence account, Python 3.10+ and Edge, Chrome or Chromium (details in
Requirements). The tools are free (MIT) and need no API key; OpenEvidence's own
terms and quota apply.
bash
pip install -r requirements.txt
python mcp/server.py --login # log in to OpenEvidence once, in the browser window it opens
claude mcp add openevidence -- python /path/to/openevidence-tools/mcp/server.py
Then ask Claude Code a clinical question; it calls ask_openevidence and returns the answer with
citations. To see the transport work without touching OpenEvidence, run the smoke test against a local
stand-in server: python tests/smoke_cdp.py.
> 🧋 Saved you some time? Buy me a drink.
## What the MCP server exposes
| Tool | Purpose |
| ask_openevidence(question, preserve_citations=False) | Submit a new clinical question; returns evidence-based answer + citations. Auto-logs the article_id for recovery. |
| list_recent_oe_queries(limit=20) | List recently-submitted queries (ts, article_id, question) — recover an article_id after an interrupted run. |
| fetch_oe_result(article_id, preserve_citations=False) | Re-fetch a previously-submitted answer by ID. This is a GET and costs no question quota. |
| ask_oe_followup(parent_article_id, followup_question, preserve_citations=False) | Drill down in the same conversation thread; OE expands the prior Q&A as context. |
### preserve_citations=True — the provenance channel /oe-verify consumes
With preserve_citations=True, the answer keeps its inline [N] markers and appends a
## Citation Data JSON block. Each entry carries the metadata the verifier needs — title,
doi, pmid, journal, authors, publication_types, impact_score, recency_days,
is_guideline, url, plus two provenance fields:
origin — the RAG corpus the cited chunk was retrieved from. OE ships this ROT-1
obfuscated (every byte shifted +1, so _ arrives as a backtick); the server decodes it, e.g.
mbodfugvmmufyutdsbqfew3 → lancet_fulltext_scraped_v2.
origin_risk — a transitive-citation risk tier derived from origin:
| Tier | Corpora | Meaning |
| HIGH | _fulltext_scraped_ (lancet, nejm, aan, …) | Scraped review full text — the quoted sentence is often the review citing someone else's trial. This is OE's main failure mode. |