https://github.com/stxkxs/loupe
A GLP-1 / cardiometabolic drug navigator unifying five free, public-domain US-government datasets into one sourced page per drug. Agent-native: one Zod contract served three ways — a React SPA, a Hono read API, and an MCP server — with deep-links and copy-as-API on every panel.
https://github.com/stxkxs/loupe
agent-native data-visualization drug-information glp-1 healthcare hono mcp openfda react rxnorm tailwindcss tanstack typescript vite zod
Last synced: about 7 hours ago
JSON representation
A GLP-1 / cardiometabolic drug navigator unifying five free, public-domain US-government datasets into one sourced page per drug. Agent-native: one Zod contract served three ways — a React SPA, a Hono read API, and an MCP server — with deep-links and copy-as-API on every panel.
- Host: GitHub
- URL: https://github.com/stxkxs/loupe
- Owner: stxkxs
- License: apache-2.0
- Created: 2026-06-29T05:06:42.000Z (5 days ago)
- Default Branch: main
- Last Pushed: 2026-06-29T13:03:47.000Z (5 days ago)
- Last Synced: 2026-07-04T05:35:44.292Z (about 7 hours ago)
- Topics: agent-native, data-visualization, drug-information, glp-1, healthcare, hono, mcp, openfda, react, rxnorm, tailwindcss, tanstack, typescript, vite, zod
- Language: TypeScript
- Size: 202 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# loupe
**Appraise the real value.** One canonical, sourced page per GLP-1 / cardiometabolic
drug — real acquisition cost, live FDA shortage status, verbatim label facts, and
same-class alternatives — unified from five free, keyless, public-domain US-government
datasets. Built **agent-native**: deep-links, copy-as-API on every panel, and an MCP
server return the *same* `Drug` contract the human UI renders.
> Not medical advice. loupe is not affiliated with the FDA, NLM, or CMS.
> Drug-PRODUCT reference data only — zero PHI.
## What it does
loupe unifies five public-domain US-government drug datasets into one sourced page per
GLP-1 / cardiometabolic drug: the NADAC acquisition cost, current FDA shortage status,
verbatim label facts, and same-class alternatives — each value carrying its source and
as-of date.
## Guardrails
A guardrail that isn't enforced by the **type system**, a **runtime guard**, and a
**test** does not exist.
1. Never dose-advise, never recommend a switch — alternatives are clinician-gated.
2. **Cost ≠ copay** — NADAC is acquisition cost; every price carries `cost_basis`.
3. **FAERS = reports, not rates** — never an incidence rate, never a denominator.
4. Labels are **quoted verbatim** with source + as-of date. No paraphrase, ever.
5. Honest loading / empty / error / **stale** states on all data.
6. Explicit "not medical advice / not affiliated" disclosure across UI, API, and MCP.
## Architecture — one contract, three faces
A build-time prefetch (`scripts/prefetch.ts`) fans out to all upstreams, validates each
record with `Drug.parse()`, and commits a static catalog (`src/data/snapshot/*.json`).
The **SPA**, the **Hono read API**, and the **MCP server** all read that one `Drug`
contract (`src/core/schema.ts`) — nobody live-hits the upstreams at request time, so the
demo is deterministic and no rate-limit budget bites. Snapshots **omit** the guardrail
literals; `Drug.parse()` back-fills them on read, so a snapshot can never ship a tampered
disclaimer (enforced by `src/core/literals.test.ts`).
```
upstreams ──prefetch──▶ src/data/snapshot/*.json ──▶ Drug (src/core/schema.ts)
openFDA ×4 │ │ │
RxNorm/RxClass SPA Hono /v1 MCP (stdio)
CMS NADAC + Part D (bundled) (agents) (agents)
DailyMed toApiCall(DrugQuery) → curl/python/ts + deep-link
```
## Run it
```bash
npm install
npm run prefetch # rebuild the catalog from live upstreams (committed; optional)
npm run dev # SPA → http://localhost:3001
npm run api # API → http://localhost:8787 (also serves the built SPA)
npm run mcp:smoke # spawns the MCP server and runs the "can I afford Zepbound?" example
npm test # vitest: contract, snapshot-literal invariant, guardrail-render, UI
npm run test:coverage # the above + a coverage gate on the request-time logic (CI-enforced)
npm run build # tsc --noEmit && vite build
```
### Agent surfaces
- **Read API** (keyless): `GET /v1/drugs`, `/v1/drugs/{slug}`, `/v1/drugs/{slug}/{panel}`,
`/v1/search?q=` · OpenAPI at `/openapi.json` · docs at `/docs`.
- **Discovery**: `/llms.txt` and `/.well-known/navigator.json`.
- **MCP** (stdio) — add to an MCP client:
```json
{ "mcpServers": { "loupe": { "command": "npx", "args": ["tsx", "src/mcp/server.ts"] } } }
```
Tools: `get_drug`, `list_drugs`, `search_drugs`, `get_drug_cost`, `get_drug_shortage`,
`get_drug_label`, `get_drug_alternatives`.
## Deploy
One container serves both faces (the SPA bundles its own catalog; the API serves `/v1`):
```bash
docker build -t loupe . && docker run -p 8787:8787 loupe
# → http://localhost:8787 (SPA at /, API at /v1, docs at /docs)
```
Snapshots are committed, so the image builds with no network. To refresh, run
`npm run prefetch` and redeploy.
## Example
`/?drug=tirzepatide-zepbound&view=cost` opens the cost view for Zepbound. The same data is
available without the UI — `GET /v1/drugs/tirzepatide-zepbound/cost`, the `get_drug_cost`
MCP tool, or a panel's "copy as API" snippet — each returns the same `Drug` projection.
## Key decisions
- **Build-time static catalog**, not live per-request fetch — fixes deterministic demo +
the openFDA 1000/day shared-IP wall + Lambda cold-cache in one move.
- **est. $/mo only when it needs no clinical assumption** (oral, dose-countable). For
mL-priced injectables it's withheld; the factual package cost is shown instead.
- **Approval = "an SPL exists" + `has_boxed_warning`** — we never algorithmically infer
`off-label`/`withdrawn` (that would manufacture a regulatory claim).
- **NDC normalized to 11-digit 5-4-2** before the NADAC join (classic silent-fail point).
See [`docs/SPEC.md`](docs/SPEC.md) for the full data contract and rationale.
## License
[Apache License 2.0](LICENSE). The underlying datasets are public-domain US-government
works (FDA, NLM, CMS); loupe is not affiliated with those agencies.