{"id":51399911,"url":"https://github.com/stxkxs/loupe","last_synced_at":"2026-07-04T05:35:45.349Z","repository":{"id":368181861,"uuid":"1283625510","full_name":"stxkxs/loupe","owner":"stxkxs","description":"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.","archived":false,"fork":false,"pushed_at":"2026-06-29T13:03:47.000Z","size":207,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-04T05:35:44.292Z","etag":null,"topics":["agent-native","data-visualization","drug-information","glp-1","healthcare","hono","mcp","openfda","react","rxnorm","tailwindcss","tanstack","typescript","vite","zod"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stxkxs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-29T05:06:42.000Z","updated_at":"2026-06-29T13:04:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stxkxs/loupe","commit_stats":null,"previous_names":["stxkxs/loupe"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/stxkxs/loupe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stxkxs%2Floupe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stxkxs%2Floupe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stxkxs%2Floupe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stxkxs%2Floupe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stxkxs","download_url":"https://codeload.github.com/stxkxs/loupe/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stxkxs%2Floupe/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35111429,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-native","data-visualization","drug-information","glp-1","healthcare","hono","mcp","openfda","react","rxnorm","tailwindcss","tanstack","typescript","vite","zod"],"created_at":"2026-07-04T05:35:44.732Z","updated_at":"2026-07-04T05:35:45.344Z","avatar_url":"https://github.com/stxkxs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# loupe\n\n**Appraise the real value.** One canonical, sourced page per GLP-1 / cardiometabolic\ndrug — real acquisition cost, live FDA shortage status, verbatim label facts, and\nsame-class alternatives — unified from five free, keyless, public-domain US-government\ndatasets. Built **agent-native**: deep-links, copy-as-API on every panel, and an MCP\nserver return the *same* `Drug` contract the human UI renders.\n\n\u003e Not medical advice. loupe is not affiliated with the FDA, NLM, or CMS.\n\u003e Drug-PRODUCT reference data only — zero PHI.\n\n## What it does\n\nloupe unifies five public-domain US-government drug datasets into one sourced page per\nGLP-1 / cardiometabolic drug: the NADAC acquisition cost, current FDA shortage status,\nverbatim label facts, and same-class alternatives — each value carrying its source and\nas-of date.\n\n## Guardrails\n\nA guardrail that isn't enforced by the **type system**, a **runtime guard**, and a\n**test** does not exist.\n\n1. Never dose-advise, never recommend a switch — alternatives are clinician-gated.\n2. **Cost ≠ copay** — NADAC is acquisition cost; every price carries `cost_basis`.\n3. **FAERS = reports, not rates** — never an incidence rate, never a denominator.\n4. Labels are **quoted verbatim** with source + as-of date. No paraphrase, ever.\n5. Honest loading / empty / error / **stale** states on all data.\n6. Explicit \"not medical advice / not affiliated\" disclosure across UI, API, and MCP.\n\n## Architecture — one contract, three faces\n\nA build-time prefetch (`scripts/prefetch.ts`) fans out to all upstreams, validates each\nrecord with `Drug.parse()`, and commits a static catalog (`src/data/snapshot/*.json`).\nThe **SPA**, the **Hono read API**, and the **MCP server** all read that one `Drug`\ncontract (`src/core/schema.ts`) — nobody live-hits the upstreams at request time, so the\ndemo is deterministic and no rate-limit budget bites. Snapshots **omit** the guardrail\nliterals; `Drug.parse()` back-fills them on read, so a snapshot can never ship a tampered\ndisclaimer (enforced by `src/core/literals.test.ts`).\n\n```\nupstreams ──prefetch──▶ src/data/snapshot/*.json ──▶ Drug (src/core/schema.ts)\n  openFDA ×4                                            │      │       │\n  RxNorm/RxClass                                      SPA   Hono /v1  MCP (stdio)\n  CMS NADAC + Part D                            (bundled)  (agents)  (agents)\n  DailyMed                                  toApiCall(DrugQuery) → curl/python/ts + deep-link\n```\n\n## Run it\n\n```bash\nnpm install\nnpm run prefetch     # rebuild the catalog from live upstreams (committed; optional)\nnpm run dev          # SPA  → http://localhost:3001\nnpm run api          # API  → http://localhost:8787  (also serves the built SPA)\nnpm run mcp:smoke    # spawns the MCP server and runs the \"can I afford Zepbound?\" example\nnpm test             # vitest: contract, snapshot-literal invariant, guardrail-render, UI\nnpm run test:coverage # the above + a coverage gate on the request-time logic (CI-enforced)\nnpm run build        # tsc --noEmit \u0026\u0026 vite build\n```\n\n### Agent surfaces\n\n- **Read API** (keyless): `GET /v1/drugs`, `/v1/drugs/{slug}`, `/v1/drugs/{slug}/{panel}`,\n  `/v1/search?q=` · OpenAPI at `/openapi.json` · docs at `/docs`.\n- **Discovery**: `/llms.txt` and `/.well-known/navigator.json`.\n- **MCP** (stdio) — add to an MCP client:\n  ```json\n  { \"mcpServers\": { \"loupe\": { \"command\": \"npx\", \"args\": [\"tsx\", \"src/mcp/server.ts\"] } } }\n  ```\n  Tools: `get_drug`, `list_drugs`, `search_drugs`, `get_drug_cost`, `get_drug_shortage`,\n  `get_drug_label`, `get_drug_alternatives`.\n\n## Deploy\n\nOne container serves both faces (the SPA bundles its own catalog; the API serves `/v1`):\n\n```bash\ndocker build -t loupe . \u0026\u0026 docker run -p 8787:8787 loupe\n# → http://localhost:8787  (SPA at /, API at /v1, docs at /docs)\n```\n\nSnapshots are committed, so the image builds with no network. To refresh, run\n`npm run prefetch` and redeploy.\n\n## Example\n\n`/?drug=tirzepatide-zepbound\u0026view=cost` opens the cost view for Zepbound. The same data is\navailable without the UI — `GET /v1/drugs/tirzepatide-zepbound/cost`, the `get_drug_cost`\nMCP tool, or a panel's \"copy as API\" snippet — each returns the same `Drug` projection.\n\n## Key decisions\n\n- **Build-time static catalog**, not live per-request fetch — fixes deterministic demo +\n  the openFDA 1000/day shared-IP wall + Lambda cold-cache in one move.\n- **est. $/mo only when it needs no clinical assumption** (oral, dose-countable). For\n  mL-priced injectables it's withheld; the factual package cost is shown instead.\n- **Approval = \"an SPL exists\" + `has_boxed_warning`** — we never algorithmically infer\n  `off-label`/`withdrawn` (that would manufacture a regulatory claim).\n- **NDC normalized to 11-digit 5-4-2** before the NADAC join (classic silent-fail point).\n\nSee [`docs/SPEC.md`](docs/SPEC.md) for the full data contract and rationale.\n\n## License\n\n[Apache License 2.0](LICENSE). The underlying datasets are public-domain US-government\nworks (FDA, NLM, CMS); loupe is not affiliated with those agencies.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstxkxs%2Floupe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstxkxs%2Floupe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstxkxs%2Floupe/lists"}