sourcemed-mcp 1.0.0__py3-none-any.whl

server.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""SourceMed MCP server.
+
+Exposes the SourceMed library (https://sourcemed.io/) — a source-verified
+medical evidence library built for agents — as MCP tools over stdio:
+
+  ask_sourcemed(question)  Ask the library a clinical question. Calls the
+                           site's Ask endpoint (POST /api/ask {"q": ...}),
+                           which returns only verified cards, with shelf
+                           citations, or {"covered": false}.
+  list_shelves()           All shelves (number, title, area, card count).
+  get_shelf(n)             One shelf in full: question, balance line,
+                           MeSH, and its cards (headline, result, source).
+  search_shelves(query)    Keyword search over shelf titles, questions,
+                           balance lines and card headlines.
+
+Data sources (public, no credentials):
+  - Shelf index: the homepage's public shelf sections
+    (https://sourcemed.io/). llms.txt documents the library and carries
+    the definitions in full, but does not itself contain a shelf list.
+  - Ask: POST https://sourcemed.io/api/ask with JSON {"q": question}.
+
+HTTP is done with curl: behind some egress proxies, Python's HTTP stack
+receives truncated streams from the site's worker (IncompleteRead at a
+fixed byte count), while curl receives the full body reliably.
+
+Terms (from the site): content CC BY with attribution — cite as
+"SourceMed Shelf #NN, sourcemed.io". Content signals: ai-input=yes,
+ai-train=no — query the live site; do not train on its content.
+"""
+import html as html_mod
+import json
+import re
+import subprocess
+import time
+
+from mcp.server.fastmcp import FastMCP
+
+BASE = "https://sourcemed.io"
+HOME_URL = BASE + "/"
+ASK_URL = BASE + "/api/ask"
+UA = "sourcemed-mcp/1.0"
+CACHE_TTL_SECONDS = 3600
+
+mcp = FastMCP("sourcemed")
+
+
+# --------------------------------------------------------------------- HTTP
+def _curl(args: list[str], timeout: int = 120) -> str:
+    out = subprocess.run(
+        ["curl", "-sS", "-f", "--retry", "3", "-A", UA, *args],
+        capture_output=True,
+        timeout=timeout,
+    )
+    if out.returncode != 0:
+        raise RuntimeError(out.stderr.decode("utf-8", "replace").strip())
+    return out.stdout.decode("utf-8")
+
+
+def fetch_text(url: str) -> str:
+    return _curl([url])
+
+
+def ask_endpoint(question: str) -> dict:
+    body = json.dumps({"q": question})
+    raw = _curl(
+        [
+            "-X",
+            "POST",
+            "-H",
+            "Content-Type: application/json",
+            "-d",
+            body,
+            ASK_URL,
+        ],
+        timeout=60,
+    )
+    return json.loads(raw)
+
+
+# ------------------------------------------------------------------ parsing
+def _clean(fragment: str) -> str:
+    text = re.sub(r"<[^>]+>", " ", fragment)
+    text = html_mod.unescape(text)
+    return re.sub(r"\s+", " ", text).strip()
+
+
+_cache: dict = {"loaded_at": 0.0, "shelves": []}
+
+
+def _parse_areas(home: str) -> dict[int, str]:
+    areas: dict[int, str] = {}
+    starts = list(re.finditer(r'<div class="browse-area">', home))
+    for i, m in enumerate(starts):
+        end = starts[i + 1].start() if i + 1 < len(starts) else len(home)
+        block = home[m.start() : end]
+        hm = re.search(r"<h3>(.*?)</h3>", block, re.DOTALL)
+        if not hm:
+            continue
+        area = re.sub(r"\s*\(\d+\)\s*$", "", _clean(hm.group(1)))
+        for n in re.findall(r'href="#shelf(\d+)"', block):
+            areas.setdefault(int(n), area)
+    return areas
+
+
+def _parse_shelves(home: str) -> list[dict]:
+    areas = _parse_areas(home)
+    starts = list(re.finditer(r'<section id="shelf(\d+)"[^>]*>', home))
+    shelves = []
+    for i, m in enumerate(starts):
+        n = int(m.group(1))
+        end = starts[i + 1].start() if i + 1 < len(starts) else len(home)
+        chunk = home[m.start() : end]
+
+        title = ""
+        hm = re.search(r"<h2>(.*?)</h2>", chunk, re.DOTALL)
+        if hm:
+            htxt = _clean(hm.group(1))
+            title = htxt.split("·", 1)[1].strip() if "·" in htxt else htxt
+
+        question = ""
+        mesh = ""
+        for q in re.findall(r'<p class="topic-q">(.*?)</p>', chunk, re.DOTALL):
+            qtxt = _clean(q)
+            if qtxt.startswith("MeSH:"):
+                mesh = qtxt[len("MeSH:") :].strip()
+            elif not question:
+                question = re.sub(r"^The question:\s*", "", qtxt)
+
+        balance = ""
+        bm = re.search(r'<p class="balance">(.*?)</p>', chunk, re.DOTALL)
+        if bm:
+            balance = re.sub(
+                r"^The balance of the evidence:\s*", "", _clean(bm.group(1))
+            )
+
+        cards = []
+        for card_html in re.split(r'<article class="card"', chunk)[1:]:
+            headline = ""
+            ch = re.search(r"<h3>(.*?)</h3>", card_html, re.DOTALL)
+            if ch:
+                headline = _clean(ch.group(1))
+            result = ""
+            cr = re.search(
+                r'<p class="card-result">(.*?)</p>', card_html, re.DOTALL
+            )
+            if cr:
+                result = _clean(cr.group(1))
+            source = ""
+            cs = re.search(
+                r'<dd class="source">(.*?)</dd>', card_html, re.DOTALL
+            )
+            if cs:
+                source = _clean(cs.group(1))
+            if headline:
+                cards.append(
+                    {"headline": headline, "result": result, "source": source}
+                )
+
+        shelves.append(
+            {
+                "n": n,
+                "title": title,
+                "question": question,
+                "balance": balance,
+                "area": areas.get(n),
+                "mesh": mesh,
+                "cards": cards,
+                "url": f"{BASE}/#shelf{n}",
+                "citation": f"SourceMed Shelf #{n}, \u201c{title}\u201d, sourcemed.io",
+            }
+        )
+    shelves.sort(key=lambda s: s["n"])
+    return shelves
+
+
+def _shelves() -> list[dict]:
+    now = time.time()
+    if not _cache["shelves"] or now - _cache["loaded_at"] > CACHE_TTL_SECONDS:
+        _cache["shelves"] = _parse_shelves(fetch_text(HOME_URL))
+        _cache["loaded_at"] = now
+    return _cache["shelves"]
+
+
+def _summary(shelf: dict) -> dict:
+    return {
+        "n": shelf["n"],
+        "title": shelf["title"],
+        "question": shelf["question"],
+        "balance": shelf["balance"],
+        "area": shelf["area"],
+        "card_count": len(shelf["cards"]),
+        "url": shelf["url"],
+        "citation": shelf["citation"],
+    }
+
+
+# -------------------------------------------------------------------- tools
+@mcp.tool()
+def ask_sourcemed(question: str) -> dict:
+    """Ask SourceMed a clinical-evidence question.
+
+    Calls the library's Ask endpoint, which retrieves only source-verified
+    cards. Returns {"covered": true, "summary": ..., "shelves": [...]} with
+    full shelf records (title, question, balance line, cards with results
+    and sources/PMIDs), or {"covered": false, "shelves": []} when no shelf
+    covers the topic. Carry the shelf citations when you use the numbers.
+    """
+    try:
+        return ask_endpoint(question)
+    except Exception as exc:
+        return {"covered": False, "error": f"Ask endpoint call failed: {exc}"}
+
+
+@mcp.tool()
+def list_shelves() -> dict:
+    """List every SourceMed shelf: number, title, browse area, card count."""
+    shelves = _shelves()
+    return {
+        "count": len(shelves),
+        "shelves": [
+            {
+                "n": s["n"],
+                "title": s["title"],
+                "area": s["area"],
+                "card_count": len(s["cards"]),
+                "url": s["url"],
+            }
+            for s in shelves
+        ],
+    }
+
+
+@mcp.tool()
+def get_shelf(n: int) -> dict:
+    """Get one SourceMed shelf in full by its permanent number.
+
+    Returns the shelf's question, balance-of-evidence line, MeSH terms,
+    area, citation string, and every card (headline, result, source).
+    """
+    for s in _shelves():
+        if s["n"] == n:
+            return s
+    return {"error": f"No shelf #{n} in the library."}
+
+
+@mcp.tool()
+def search_shelves(query: str) -> dict:
+    """Search shelves by keyword.
+
+    Matches against shelf titles, questions, balance lines, and card
+    headlines. Returns up to 20 shelf summaries (number, title, question,
+    balance, area, card count, citation).
+    """
+    terms = [t.lower() for t in re.split(r"\s+", query.strip()) if t]
+    if not terms:
+        return {"count": 0, "shelves": []}
+    hits = []
+    for s in _shelves():
+        haystack = " ".join(
+            [s["title"], s["question"], s["balance"]]
+            + [c["headline"] for c in s["cards"]]
+        ).lower()
+        if all(t in haystack for t in terms):
+            hits.append(_summary(s))
+    return {"count": len(hits), "shelves": hits[:20]}
+
+
+def main():
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

sourcemed_mcp-1.0.0.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: sourcemed-mcp
+Version: 1.0.0
+Summary: Source-verified medical evidence library for agents: every card traces to a checked primary source (PMID/DOI).
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp<2,>=1.2
+
+# SourceMed MCP server
+
+An MCP (Model Context Protocol) server for [SourceMed](https://sourcemed.io/)
+— a source-verified medical evidence library built for agents. Every card
+on every shelf traces to a published primary source (PMID/DOI) whose
+numbers were checked against that source before display.
+
+The server uses only the site's **public endpoints and files**. No
+account, API key, or credentials are needed.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `ask_sourcemed(question)` | Ask a clinical-evidence question. Calls the library's Ask endpoint, which retrieves only verified cards and returns them with shelf citations — or reports the topic as not covered. |
+| `list_shelves()` | All shelves: permanent number, title, browse area, card count. |
+| `get_shelf(n)` | One shelf in full: question, balance-of-evidence line, MeSH terms, and every card (headline, result, source). |
+| `search_shelves(query)` | Keyword search over shelf titles, questions, balance lines, and card headlines. |
+
+## Install and run
+
+Requires Python 3.10+ and `curl` on PATH (see "Implementation notes").
+
+```bash
+cd sourcemed/mcp-server
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt   # the official mcp SDK, v1 line
+.venv/bin/python server.py                  # stdio server; speaks MCP on stdin/stdout
+```
+
+### Connect it to an MCP client
+
+Generic stdio client configuration:
+
+```json
+{
+  "mcpServers": {
+    "sourcemed": {
+      "command": "/path/to/sourcemed/mcp-server/.venv/bin/python",
+      "args": ["/path/to/sourcemed/mcp-server/server.py"]
+    }
+  }
+}
+```
+
+If your environment reaches the internet through a proxy, make sure the
+client passes `http_proxy` / `https_proxy` through to the server process
+(some MCP hosts spawn servers with a minimal environment allowlist that
+drops them; the server's HTTP calls will fail without them in proxied
+environments).
+
+## The Ask endpoint (discovered interface)
+
+Documented in the site's `llms.txt` and verified live on 2026-11-03:
+
+- **Request:** `POST https://sourcemed.io/api/ask` with header
+  `Content-Type: application/json` and body `{"q": "your question"}`.
+  GET with a query parameter returns **404** — POST is the only format.
+  The question must be a real question: a missing/too-short `q` returns
+  HTTP 400 with `{"covered": false, "error": "question too short"}`.
+- **Response (covered):** HTTP 200,
+  `{"covered": true, "summary": null, "shelves": [ ... ]}` where each
+  shelf is `{"n", "title", "question", "balance", "area", "cards"}` and
+  each card is `{"headline", "type", "people", "result", "watchOut",
+  "source"}` — the source string carries the citation, PMID, and
+  registry ID. `summary` was `null` in all observed responses (the
+  shelves/cards are the answer; the endpoint retrieves, it does not
+  generate prose).
+- **Response (not covered):** HTTP 200,
+  `{"covered": false, "summary": null, "shelves": []}`.
+
+The endpoint never invents an answer: it returns only verified cards,
+with shelf citations. Carry the citation (`SourceMed Shelf #NN,
+sourcemed.io`) when you use a card's numbers.
+
+## Data sources
+
+- **Ask** — the endpoint above.
+- **Shelf index** (`list_shelves` / `get_shelf` / `search_shelves`) —
+  parsed from the homepage's public shelf sections
+  (`https://sourcemed.io/`), cached in memory for one hour. Note:
+  `llms.txt` documents the library, the deposit rules, and the Ask
+  endpoint, and carries the site's definitions in full — but it does
+  not itself contain a shelf list, so the shelf tools read the same
+  public shelf sections the site serves to every visitor.
+
+## Implementation notes
+
+HTTP is performed with `curl` rather than Python's HTTP stack: behind
+some egress proxies, Python's stack receives truncated streams from the
+site's worker (IncompleteRead at a fixed byte count), while curl
+receives the full body reliably. The server needs no other system
+dependencies.
+
+## Testing
+
+```bash
+.venv/bin/python test_client.py
+```
+
+Spawns the server over stdio, initializes a session, lists tools, and
+calls each tool once. Latest run (2026-11-03): **all checks PASS** —
+`ask_sourcemed` returned 3 shelves for a statin-after-heart-attack
+question; `list_shelves` returned 245 shelves; `get_shelf(106)` returned
+the aspirin primary-prevention shelf with its 3 cards;
+`search_shelves("aspirin primary prevention")` found shelf #106.
+Full output: `test-output.txt` / `test-output.json`.
+
+## Registry files
+
+- `server.json` — manifest in the official MCP registry schema
+  (`io.sourcemed/sourcemed`, v1.0.0). Prepared for submission; **not yet
+  published** to any registry, and the PyPI package name
+  (`sourcemed-mcp`) is the intended identifier, not a live package.
+- `smithery.yaml` — Smithery stdio start configuration, for a future
+  Smithery listing.
+
+## Terms
+
+Content is offered for reuse with attribution (CC BY): name SourceMed
+and the shelf number. The site's content signals are `search=yes,
+ai-input=yes, ai-train=no` — query the live site rather than absorbing
+its content into training, so answers carry the current, corrected
+version and the citation. The verification standard, not the license,
+is the quality guarantee.
+
+<!-- mcp-name: io.sourcemed/sourcemed -->

sourcemed_mcp-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+server.py,sha256=QXHaOJCt97zpgfJs5l5Pkkv6zWh3qeoq-Q7qElWs26o,8899
+sourcemed_mcp-1.0.0.dist-info/METADATA,sha256=u5-MGabMey5wLbCGz67TKsZRWZo4wVa0OTXzpHeTKMQ,5504
+sourcemed_mcp-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sourcemed_mcp-1.0.0.dist-info/entry_points.txt,sha256=F8ztPwxsRsuq8h9gE-6WCc1dLDeAAsvUu6eD9mFWxBo,46
+sourcemed_mcp-1.0.0.dist-info/top_level.txt,sha256=StKOSmRhvWS5IPcvhsDRbtxUTEofJgYFGOu5AAJdSWo,7
+sourcemed_mcp-1.0.0.dist-info/RECORD,,

sourcemed_mcp-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sourcemed_mcp-1.0.0.dist-info/entry_points.txt

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

sourcemed_mcp-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+server