@kinginsun/mcp-drugsea 0.3.0 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@ MCP (Model Context Protocol) stdio server for [DrugSea / Yaohai](https://db.drug
 
 The server forwards tool calls to **`https://db3.drugsea.cn/api`** with personal user token auth (`Authorization: Bearer ysk_…`). It covers:
 
-- **yaohai-*** — cross-database catalog / search / detail / global (`POST /g/mcp/yaohai/*`)
+- **yaohai-*** — cross-database catalog / search / detail / facets / global (`POST /g/mcp/yaohai/*`; facets via GET)
 - **product-cn-*** — already-marketed China products (search/detail via MCP on db3; facets via GET)
 - **reg-cn-*** — CDE registration / review pipeline (search/detail via MCP on db3; facets via GET)
 
@@ -16,12 +16,69 @@ The server forwards tool calls to **`https://db3.drugsea.cn/api`** with personal
 npm install -g @kinginsun/mcp-drugsea
 ```
 
-Or run without installing:
+Or run without installing (`@latest` makes npx re-resolve the newest published version each launch instead of pinning to its cache):
 
 ```bash
-npx -y @kinginsun/mcp-drugsea
+npx -y @kinginsun/mcp-drugsea@latest
 ```
 
+## Updating
+
+How updates reach you depends on how you installed the server.
+
+### 1. `npx` with `@latest` — automatic (recommended)
+
+The MCP configs in this README use:
+
+```json
+"args": ["-y", "@kinginsun/mcp-drugsea@latest"]
+```
+
+`@latest` makes npx resolve the newest published version from the registry on every launch (registry metadata is cached locally for up to ~5 minutes), so you pick up new releases just by reloading the MCP server. No action needed.
+
+If your config uses the **bare package name** (`"-y", "@kinginsun/mcp-drugsea"`), npx keys its cache by the exact package argument and may keep serving a stale version. Add `@latest` and reload.
+
+### 2. Global install — manual
+
+`npm install -g` pins the version you installed; nothing updates it automatically.
+
+```bash
+npm update -g @kinginsun/mcp-drugsea
+npm ls -g @kinginsun/mcp-drugsea      # confirm the new version
+```
+
+### 3. Stuck on an old version? Clear the npx cache
+
+`npm cache clean --force` does **not** touch the npx cache — that is the usual reason an update appears not to take effect. npm 11 has dedicated subcommands:
+
+```bash
+npm cache npx ls                       # list cached npx entries
+npm cache npx rm <key>                 # remove the stale entry for this package
+```
+
+Older npm versions: remove the cache directory manually (`rm -rf ~/.npm/_npx`; on Windows `%LOCALAPPDATA%\npm-cache\_npx`).
+
+### In-server update notice
+
+Every launch performs a **non-blocking** version check against the registry and, when a newer version is published, reports it on two channels:
+
+- **stderr** — shown in your MCP client's server log panel;
+- **an MCP `notifications/message` log notification** (`level: warning`).
+
+The notice includes the exact commands above. It never blocks startup, never writes to stdout (which carries JSON-RPC), and fails silently when the registry is unreachable — results are cached for 24h so repeated launches do not re-query.
+
+Disable it with `YAOHAI_MCP_UPDATE_CHECK=0`. Behind a proxy or using an npm mirror, set `YAOHAI_NPM_REGISTRY` to your registry origin.
+
+### Pinning a version
+
+Prefer stability over freshness? Pin an exact version or a range instead of `@latest`:
+
+```json
+"args": ["-y", "@kinginsun/mcp-drugsea@0.4.0"]
+```
+
+A range such as `@^0.4.0` auto-updates within `0.4.x` only, which avoids picking up breaking changes from a future minor release.
+
 ## Configuration
 
 ### `YAOHAI_MCP_TOKEN` (required)
@@ -61,6 +118,8 @@ On db3, direct GET list routes may return encrypted payloads; this client auto-r
 | `YAOHAI_BASE_URL` | `https://db3.drugsea.cn/api` | API origin (no trailing slash). MCP: `/g/mcp/yaohai/*` |
 | `YAOHAI_VERIFY_SSL` | `true` | Set `false` / `0` / `off` to skip TLS certificate verification (needed on some prod hosts) |
 | `YAOHAI_USE_MCP_LIST` | auto on db3 | Force product/reg search via MCP POST instead of GET |
+| `YAOHAI_MCP_UPDATE_CHECK` | enabled | Set `0` / `false` / `off` to disable the startup version check (see [Updating](#updating)) |
+| `YAOHAI_NPM_REGISTRY` | `https://registry.npmjs.org` | Registry used by the version check. Point at a mirror if npmjs.org is unreachable from your network |
 
 ### Cursor MCP (`~/.cursor/mcp.json`)
 
@@ -69,7 +128,7 @@ On db3, direct GET list routes may return encrypted payloads; this client auto-r
   "mcpServers": {
     "drugsea": {
       "command": "npx",
-      "args": ["-y", "@kinginsun/mcp-drugsea"],
+      "args": ["-y", "@kinginsun/mcp-drugsea@latest"],
       "env": {
         "YAOHAI_MCP_TOKEN": "ysk_your_token_here"
       }
@@ -85,7 +144,7 @@ On db3, direct GET list routes may return encrypted payloads; this client auto-r
   "mcpServers": {
     "drugsea": {
       "command": "npx",
-      "args": ["-y", "@kinginsun/mcp-drugsea"],
+      "args": ["-y", "@kinginsun/mcp-drugsea@latest"],
       "env": {
         "YAOHAI_MCP_TOKEN": "ysk_your_token_here"
       }
@@ -100,7 +159,7 @@ On db3, direct GET list routes may return encrypted payloads; this client auto-r
 |-------------|--------|
 | Already listed in China (国药准字, 批准文号, 上市, 医保/集采状态) | `product-cn-fields` → `product-cn-search` / `product-cn-facets` → `product-cn-detail` |
 | R&D / CDE (在研, 受理号, 审评, 尚未上市) | `reg-cn-fields` → `reg-cn-search` / `reg-cn-facets` → `reg-cn-detail` |
-| Other DBs (医保 `yibao`, 基药 `jiyao`, 集采 `jicai`, trials, DMF, …) | `yaohai-catalog` → `yaohai-search` → `yaohai-detail` |
+| Other DBs (医保 `yibao`, 基药 `jiyao`, 集采 `jicai`, trials, DMF, …) | `yaohai-catalog` → `yaohai-search` / `yaohai-facets` → `yaohai-detail` |
 | Global panorama | `yaohai-global-search` |
 | Unclear which DB | `yaohai-catalog` (list DBs by keyword/category) → `yaohai-search`, or `yaohai-global-search` |
 
@@ -121,10 +180,18 @@ xlsx export is not implemented in this MCP (v1 returns JSON samples only).
 | `yaohai-catalog` | `category?`, `q?` | List databases |
 | `yaohai-search` | `dbname`, `query?`, `limit?`, `offset?` | Default limit 10, max 50 |
 | `yaohai-detail` | `dbname`, `id` | Skip DBs with `has_detail: false` |
+| `yaohai-facets` | `dbname?`, `query?`, `fields?` | Facets for `dbs`-route DBs. Omit `fields` → discover facet-capable DBs/fields; pass `fields` → fetch buckets |
 | `yaohai-global-search` | `q?`, `query?`, `limit?`, `offset?` | `q` fills `query.term` |
 
 When the target database is unclear, use `yaohai-catalog` (filter by `category` / `q`) to pick a `dbname`, then `yaohai-search`; or use `yaohai-global-search` for a cross-database panorama query.
 
+`yaohai-facets` mirrors the ConditionSearch facet filters of the website for the `dbs`-route databases (医保 `yibao`, 基药 `jiyao`, 集采 `jicai`, sales `drugsales`, …). Two modes:
+
+- **Discovery** (no `fields`): omit `dbname` to list all 44 facet-capable databases, or pass `dbname` to list its facet-able fields (with `filter_type`).
+- **Fetch** (`dbname` + `fields`): returns aggregation buckets (`value`/`count`) for the named terms fields, optionally narrowed by `query`. Only `terms`-type fields are exposed (44 DBs, 129 fields); date/range/tree filters are not faceted here.
+
+For the two dedicated ES routes use `product-cn-facets` / `reg-cn-facets` instead — `yaohai-facets` returns an actionable hint if you pass `product_cn` / `reg_cn`.
+
 ### product_cn (marketed)
 
 | Tool | Parameters | Notes |
@@ -170,7 +237,7 @@ Add the server to your client config so it auto-starts. Example for Cursor (`~/.
   "mcpServers": {
     "drugsea": {
       "command": "npx",
-      "args": ["-y", "@kinginsun/mcp-drugsea"],
+      "args": ["-y", "@kinginsun/mcp-drugsea@latest"],
       "env": {
         "YAOHAI_MCP_TOKEN": "ysk_your_token_here"
       }
@@ -179,7 +246,7 @@ Add the server to your client config so it auto-starts. Example for Cursor (`~/.
 }
 ```
 
-Then reload MCP servers in the client (Cursor: Settings → MCP → refresh). The client should list **12 tools**.
+Then reload MCP servers in the client (Cursor: Settings → MCP → refresh). The client should list **13 tools**.
 
 ### Step 1 — Install (optional, for local/CLI use)
 
@@ -187,7 +254,7 @@ Either run via npx on demand (no install needed), or install globally / from sou
 
 ```bash
 # Option A: run without installing (what the MCP configs above do)
-npx -y @kinginsun/mcp-drugsea
+npx -y @kinginsun/mcp-drugsea@latest
 
 # Option B: global install
 npm install -g @kinginsun/mcp-drugsea
@@ -221,17 +288,19 @@ printf '%s\n' \
   '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1.0"}}}' \
   '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
   '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
-  | YAOHAI_MCP_TOKEN=$YAOHAI_MCP_TOKEN npx -y @kinginsun/mcp-drugsea \
-  | tail -1 | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{const m=JSON.parse(d);console.log('tools:',m.result.tools.length)})"
+  | YAOHAI_MCP_TOKEN=$YAOHAI_MCP_TOKEN npx -y @kinginsun/mcp-drugsea@latest \
+  | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{for(const l of d.split('\n')){if(!l.trim())continue;let m;try{m=JSON.parse(l)}catch{continue}if(m.id===2)console.log('tools:',m.result.tools.length)}})"
 ```
 
-Expected: `tools: 12`.
+Expected: `tools: 13`.
+
+The filter selects the response with `"id":2` rather than piping through `tail -1`, because the server may also emit a `notifications/message` (version-update notice) on stdout. Both are valid JSON-RPC, but only one is the answer you asked for.
 
 One-liner variant without the handshake (also works with this server):
 
 ```bash
 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
-  | YAOHAI_MCP_TOKEN=ysk_your_token_here npx -y @kinginsun/mcp-drugsea
+  | YAOHAI_MCP_TOKEN=ysk_your_token_here npx -y @kinginsun/mcp-drugsea@latest
 ```
 
 ### Step 4 — Test real tool calls
@@ -239,20 +308,20 @@ echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
 ```bash
 # Catalog lookup (no external DB data needed)
 echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"yaohai-catalog","arguments":{"q":"医保"}}}' \
-  | YAOHAI_MCP_TOKEN=ysk_your_token_here npx -y @kinginsun/mcp-drugsea
+  | YAOHAI_MCP_TOKEN=ysk_your_token_here npx -y @kinginsun/mcp-drugsea@latest
 
 # China marketed products search
 echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"product-cn-search","arguments":{"query":{"drug_name":"阿司匹林"},"limit":3}}}' \
-  | YAOHAI_MCP_TOKEN=ysk_your_token_here npx -y @kinginsun/mcp-drugsea
+  | YAOHAI_MCP_TOKEN=ysk_your_token_here npx -y @kinginsun/mcp-drugsea@latest
 
 # Global panorama search
 echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"yaohai-global-search","arguments":{"q":"阿司匹林","limit":3}}}' \
-  | YAOHAI_MCP_TOKEN=ysk_your_token_here npx -y @kinginsun/mcp-drugsea
+  | YAOHAI_MCP_TOKEN=ysk_your_token_here npx -y @kinginsun/mcp-drugsea@latest
 ```
 
 Expected: each response has `"isError":false` and non-empty `content`.
 
-### Step 5 — Full 12-tool suite (from source)
+### Step 5 — Full 13-tool suite (from source)
 
 ```bash
 git clone https://github.com/kinginsun/mcp-drugsea.git
@@ -261,13 +330,13 @@ npm install && npm run build
 YAOHAI_MCP_TOKEN=ysk_your_token_here node scripts/test-all-tools.mjs
 ```
 
-Expected final line: `--- Summary: 12 passed, 0 failed / 12 tool calls ---`.
+Expected final line: `--- Summary: 14 passed, 0 failed / 14 tool calls ---`.
 
 ### Step 6 — Verify inside the MCP client
 
 After reloading MCP servers in the client, ask the agent:
 
-1. "List the drugsea tools" → should see 12 tools.
+1. "List the drugsea tools" → should see 13 tools.
 2. "Search 阿司匹林 in product-cn" → should return rows with `total > 0`.
 3. "Global search: PD-1" → should return panorama results without error.
 
@@ -282,6 +351,9 @@ After reloading MCP servers in the client, ask the agent:
 | `mcp-drugsea: command not found` when running npx | You are inside the package source dir — run from another directory or use `node dist/index.js` |
 | Empty/encrypted payload from product/reg GET | Use default db3 base URL (auto MCP POST routing) or set `YAOHAI_USE_MCP_LIST=true` |
 | TLS errors on some hosts | Set `YAOHAI_VERIFY_SSL=false` |
+| Client keeps running an old version | npx cache is keyed by the exact package arg — use `@latest` in `args`, or clear it with `npm cache npx ls` / `npm cache npx rm <key>`. See [Updating](#updating). |
+| Global install never updates | `npm install -g` pins the version — run `npm update -g @kinginsun/mcp-drugsea` |
+| No update notice appears | Expected when you are already current, when the registry is unreachable (check fails silently), or when `YAOHAI_MCP_UPDATE_CHECK=0`. Clients also need the server's `logging` capability, so check the MCP server log panel for the stderr line as well. |
 
 ## Manual stdio test
 
@@ -302,7 +374,7 @@ echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"product-cn
 
 ## Releasing (maintainers)
 
-`publish.sh` releases the package to npm (which is what makes `npx -y @kinginsun/mcp-drugsea` work). It syncs `src/index.ts`'s `PACKAGE_VERSION` with `package.json`, builds clean, audits the tarball for leaked tokens, runs the 12-tool suite, commits + tags, then publishes and pushes.
+`publish.sh` releases the package to npm (which is what makes `npx -y @kinginsun/mcp-drugsea@latest` work). It syncs `src/index.ts`'s `PACKAGE_VERSION` with `package.json`, builds clean, audits the tarball for leaked tokens, runs the 13-tool suite plus the facet and update-check suites, commits + tags, then publishes and pushes.
 
 ```bash
 npm login                # once, with rights on the @kinginsun scope

package/dist/dbs-facets.js

@@ -0,0 +1,461 @@
+/**
+ * Facet (条件筛选) catalog for dbs-route databases — GENERATED FILE.
+ *
+ * Source of truth: drugsea frontend
+ *   frontend/src/routes/more/DBS/components/commonSearch/ConditionSearchPanel.js
+ * which hardcodes the per-db condition filters the web UI renders.
+ *
+ * Regenerate (do not hand-edit):
+ *   node scripts/extract-dbs-facets.mjs --emit-ts
+ *
+ * Scope: `terms` fields only — the ones that return aggregated bucket lists
+ * (`content.list[]` with `ct` counts). `date`/`range`/`tree` fields are UI
+ * pickers and are excluded, which also drops the two 器械备案 dbs entirely.
+ *
+ * Note on prefixes: taken verbatim from the frontend URL. They currently equal
+ * the catalog `api_path` for all 44 dbs, but the frontend is
+ * authoritative — `reg_cn` already demonstrates that a facet prefix can diverge
+ * from api_path.
+ */
+export const DBS_FACET_CATALOG = {
+    cde_yfb_registration: {
+        title: "原料药、药用辅料和药包材登记信息公示",
+        category: "注册情报",
+        prefix: "/c/cde_yfb_registration/eslist",
+        fields: {
+            reg_num_year: { title: "批准年份", filter_type: "multiple" },
+            local_or_import: { title: "产品来源", filter_type: "multiple" },
+            yfb_type: { title: "原辅包类型", filter_type: "multiple" },
+        },
+    },
+    cmchk_pcm: {
+        title: "香港注册中成药",
+        category: "上市情报",
+        prefix: "/cmchk_pcm/eslist",
+        fields: {
+            formula_type: { title: "注册类型", filter_type: "multiple" },
+            package_label_cn: { title: "药材组成", filter_type: "multiple" },
+            pmpw_flag: { title: "PMPW标记", filter_type: "multiple" },
+            dosage_form_cn: { title: "剂型", filter_type: "multiple" },
+            is_export: { title: "是否出口", filter_type: "multiple" },
+            is_coexist_cp: { title: "是否药典收录", filter_type: "multiple" },
+        },
+    },
+    cn_orange_book: {
+        title: "中国上市化学药品目录集",
+        category: "药政参考",
+        prefix: "/c/cn_orange_book/eslist",
+        fields: {
+            dosage_form: { title: "剂型", filter_type: "multiple" },
+            administration_route: { title: "给药途径", filter_type: "multiple" },
+            is_reference_drug: { title: "参比制剂", filter_type: "multiple" },
+            is_standard_drug: { title: "标准制剂", filter_type: "multiple" },
+            category: { title: "收录类别", filter_type: "multiple" },
+            marketing_status: { title: "上市销售状态", filter_type: "multiple" },
+        },
+    },
+    cn_reference_drugs: {
+        title: "仿制药参比制剂目录",
+        category: "药政参考",
+        prefix: "/c/cn_reference_drugs/eslist",
+        fields: {
+            dosage_form: { title: "药品剂型", filter_type: "multiple" },
+            batch_no: { title: "公布批次", filter_type: "multiple" },
+        },
+    },
+    cn_reference_drugs_publicity: {
+        title: "仿制药参比制剂目录(征求意见稿)",
+        category: "药政参考",
+        prefix: "/c/cn_reference_drugs_publicity/eslist",
+        fields: {
+            publicity_type: { title: "公示类型", filter_type: "multiple" },
+            dosage_form: { title: "药品剂型", filter_type: "multiple" },
+            batch_no: { title: "公布批次", filter_type: "multiple" },
+        },
+    },
+    dpd: {
+        title: "加拿大上市药品",
+        category: "上市情报",
+        prefix: "/dpd/eslist",
+        fields: {
+            dosage_form: { title: "剂型", filter_type: "multiple" },
+            current_status: { title: "最新状态", filter_type: "multiple" },
+            route_of_administration: { title: "给药途径", filter_type: "multiple" },
+            class: { title: "适用对象", filter_type: "multiple" },
+            schedule: { title: "药品类别", filter_type: "multiple" },
+            has_sms: { title: "是否有说明书", filter_type: "multiple" },
+        },
+    },
+    drug_law: {
+        title: "药品法规知识库",
+        category: "药闻速递",
+        prefix: "/h/drug_law/eslist",
+        fields: {
+            source: { title: "法规来源", filter_type: "multiple" },
+            main_category: { title: "一级分类", filter_type: "multiple" },
+            category: { title: "公告栏目", filter_type: "multiple" },
+        },
+    },
+    drugsales: {
+        title: "全终端药品销售",
+        category: "市场情报",
+        prefix: "/drugsales/eslist",
+        defaultQuery: { "groupid": "205" },
+        fields: {
+            region: { title: "区域", filter_type: "multiple" },
+            country: { title: "国家", filter_type: "multiple" },
+            dosage_form: { title: "剂型", filter_type: "multiple" },
+            year: { title: "年份", filter_type: "multiple" },
+            sales_channel: { title: "销售渠道", filter_type: "multiple" },
+            drug_type: { title: "药品类型", filter_type: "multiple" },
+            administration_route: { title: "给药途径", filter_type: "multiple" },
+        },
+    },
+    fda_dmf: {
+        title: "美国DMF数据库",
+        category: "上市情报",
+        prefix: "/fda_dmf/eslist",
+        fields: {
+            status: { title: "DMF状态", filter_type: "multiple" },
+            type: { title: "DMF类型", filter_type: "multiple" },
+        },
+    },
+    fda_ndc: {
+        title: "美国药品NDC数据库",
+        category: "上市情报",
+        prefix: "/fda_ndc/eslist",
+        fields: {
+            has_sms: { title: "是否有说明书", filter_type: "multiple" },
+            MARKETINGCATEGORYNAME: { title: "市场分类", filter_type: "multiple" },
+            PRODUCTTYPENAME: { title: "产品类型", filter_type: "multiple" },
+            DOSAGEFORMNAME: { title: "药品剂型", filter_type: "multiple" },
+            ROUTENAME: { title: "给药途径", filter_type: "multiple" },
+            NDC_EXCLUDE_FLAG: { title: "NDC排除标记", filter_type: "multiple" },
+            PHARM_CLASSES: { title: "药理分类", filter_type: "multiple" },
+        },
+    },
+    gov_drugs: {
+        title: "政府用药目录",
+        category: "药政参考",
+        prefix: "/c/gov_drugs/eslist",
+        fields: {
+            province: { title: "省份", filter_type: "multiple" },
+            drug_type: { title: "药品类型", filter_type: "multiple" },
+        },
+    },
+    herb_formulas: {
+        title: "中药方剂数据库",
+        category: "行业参考",
+        prefix: "/herb_formulas/eslist",
+        fields: {
+            herbs: { title: "组成药材", filter_type: "multiple" },
+        },
+    },
+    herbs: {
+        title: "中药材数据库",
+        category: "行业参考",
+        prefix: "/herbs/eslist",
+        fields: {
+            efficacy_class: { title: "功效分类", filter_type: "multiple" },
+            family_classification: { title: "科属分类", filter_type: "multiple" },
+        },
+    },
+    hk_doh: {
+        title: "香港上市药品",
+        category: "上市情报",
+        prefix: "/hk_doh/eslist",
+        fields: {
+            legal_classification: { title: "法律分类", filter_type: "multiple" },
+            sale_requirement: { title: "销售要求", filter_type: "multiple" },
+        },
+    },
+    hma: {
+        title: "欧盟HMA上市药品",
+        category: "上市情报",
+        prefix: "/hma/eslist",
+        fields: {
+            Ph_form: { title: "药品剂型", filter_type: "multiple" },
+            RMS: { title: "参考成员国", filter_type: "multiple" },
+            product_outcome: { title: "市场状态", filter_type: "multiple" },
+        },
+    },
+    isaf_drugs: {
+        title: "澳门上市药品",
+        category: "上市情报",
+        prefix: "/isaf_drugs/eslist",
+        fields: {
+            dosage_form: { title: "剂型", filter_type: "multiple" },
+            administration_route: { title: "给药途径", filter_type: "multiple" },
+            ingredients: { title: "活性成分", filter_type: "multiple" },
+            type: { title: "法定类别", filter_type: "multiple" },
+        },
+    },
+    isaf_tcm: {
+        title: "澳门中成药与天然药物",
+        category: "上市情报",
+        prefix: "/isaf_tcm/eslist",
+        fields: {
+            dosage_form: { title: "剂型", filter_type: "multiple" },
+            administration_route: { title: "给药途径", filter_type: "multiple" },
+            formula: { title: "配方", filter_type: "multiple" },
+            type: { title: "法定类别", filter_type: "multiple" },
+        },
+    },
+    japan_dmf: {
+        title: "日本DMF数据库",
+        category: "上市情报",
+        prefix: "/japan_dmf/eslist",
+        fields: {
+            registration_type_cn: { title: "注册类型", filter_type: "multiple" },
+        },
+    },
+    jicai: {
+        title: "国家与地方集采数据库",
+        category: "市场情报",
+        prefix: "/jicai/eslist",
+        fields: {
+            jc_type: { title: "集采类型", filter_type: "multiple" },
+            jc_project: { title: "集采项目", filter_type: "multiple" },
+            region: { title: "中选区域", filter_type: "multiple" },
+            execution_status: { title: "执行状态", filter_type: "multiple" },
+        },
+    },
+    jicai_mulu: {
+        title: "jicai_mulu",
+        category: "其他",
+        prefix: "/jicai_mulu/eslist",
+        fields: {
+            jc_type: { title: "集采类型", filter_type: "multiple" },
+            jc_project: { title: "集采项目", filter_type: "multiple" },
+        },
+    },
+    jiyao: {
+        title: "基药目录",
+        category: "市场准入",
+        prefix: "/jiyao/eslist",
+        fields: {
+            province: { title: "地区", filter_type: "multiple" },
+            dosage_form: { title: "剂型", filter_type: "multiple" },
+            drug_type: { title: "药品类型", filter_type: "multiple" },
+            std_catalog_version: { title: "基药版本", filter_type: "multiple" },
+        },
+    },
+    medical_device: {
+        title: "国产器械(注册)",
+        category: "NMPA基础库",
+        prefix: "/medical_device/eslist",
+        fields: {
+            std_product_type: { title: "管理类别", filter_type: "multiple" },
+        },
+    },
+    medical_device_jinkou: {
+        title: "进口器械(注册)",
+        category: "NMPA基础库",
+        prefix: "/medical_device_jinkou/eslist",
+        fields: {
+            std_product_type: { title: "管理类别", filter_type: "multiple" },
+        },
+    },
+    nhsa_code: {
+        title: "医保药品分类与代码",
+        category: "市场准入",
+        prefix: "/c/nhsa_code/eslist",
+        fields: {
+            insurance_type: { title: "医保类型", filter_type: "multiple" },
+            registered_dosage_form: { title: "注册剂型", filter_type: "multiple" },
+            min_preparation_unit: { title: "最小制剂单位", filter_type: "multiple" },
+            min_package_unit: { title: "最小包装单位", filter_type: "multiple" },
+        },
+    },
+    nhsa_herbs: {
+        title: "中药饮片信息",
+        category: "市场准入",
+        prefix: "/c/nhsa_herbs/eslist",
+        fields: {
+            efficacy_classification: { title: "功效分类", filter_type: "multiple" },
+            region_name: { title: "地区", filter_type: "multiple" },
+        },
+    },
+    nhsa_hospital_prepration: {
+        title: "医疗机构制剂信息",
+        category: "市场准入",
+        prefix: "/c/nhsa_hospital_prepration/eslist",
+        fields: {
+            preparation_type: { title: "制剂类别", filter_type: "multiple" },
+            region: { title: "地区", filter_type: "multiple" },
+        },
+    },
+    nmpa_buchongbeian: {
+        title: "境内生产药品备案信息公示",
+        category: "NMPA基础库",
+        prefix: "/nmpa_buchongbeian/eslist",
+        fields: {
+            dosage_form: { title: "剂型", filter_type: "multiple" },
+            drug_type: { title: "药品类型", filter_type: "multiple" },
+            record_office: { title: "备案机关", filter_type: "multiple" },
+        },
+    },
+    nmpa_gmp: {
+        title: "GMP认证",
+        category: "NMPA基础库",
+        prefix: "/nmpa_gmp/eslist",
+        fields: {
+            std_province: { title: "省市", filter_type: "multiple" },
+            std_gmp_status: { title: "证书状态", filter_type: "multiple" },
+            in_sfda: { title: "是否有效", filter_type: "multiple" },
+        },
+    },
+    nmpa_guochan: {
+        title: "国产药品",
+        category: "NMPA基础库",
+        prefix: "/f/nmpa_guochan/eslist",
+        fields: {
+            dosage_form: { title: "药品剂型", filter_type: "multiple" },
+            drug_type: { title: "产品类别", filter_type: "multiple" },
+            in_sfda: { title: "是否有效", filter_type: "multiple" },
+        },
+    },
+    nmpa_jinkou: {
+        title: "进口药品",
+        category: "NMPA基础库",
+        prefix: "/f/nmpa_jinkou/eslist",
+        fields: {
+            dosage_form: { title: "药品剂型", filter_type: "multiple" },
+            drug_type: { title: "产品类别", filter_type: "multiple" },
+            in_sfda: { title: "是否有效", filter_type: "multiple" },
+        },
+    },
+    nmpa_reg_patent: {
+        title: "药品注册相关专利信息",
+        category: "NMPA基础库",
+        prefix: "/f/nmpa_reg_patent/eslist",
+        fields: {
+            patent_type: { title: "专利类型", filter_type: "multiple" },
+        },
+    },
+    nmpa_tcm_granules: {
+        title: "中药配方颗粒备案信息",
+        category: "NMPA基础库",
+        prefix: "/f/nmpa_tcm_granules/eslist",
+        fields: {
+            filing_status: { title: "备案状态", filter_type: "multiple" },
+            record_province: { title: "备案省局", filter_type: "multiple" },
+        },
+    },
+    nmpa_tcm_protection: {
+        title: "中药保护品种",
+        category: "NMPA基础库",
+        prefix: "/nmpa_tcm_protection/eslist",
+        fields: {
+            dosage_form: { title: "剂型", filter_type: "multiple" },
+            protect_period: { title: "保护期限", filter_type: "multiple" },
+        },
+    },
+    nmpa_tsspxx_gc: {
+        title: "国产保健食品注册",
+        category: "NMPA基础库",
+        prefix: "/f/nmpa_tsspxx_gc/eslist",
+        fields: {
+            in_sfda: { title: "是否有效", filter_type: "multiple" },
+        },
+    },
+    nmpa_tsspxx_jk: {
+        title: "进口保健食品注册",
+        category: "NMPA基础库",
+        prefix: "/f/nmpa_tsspxx_jk/eslist",
+        fields: {
+            in_sfda: { title: "是否有效", filter_type: "multiple" },
+        },
+    },
+    se_notice: {
+        title: "医药上市公司公告",
+        category: "药闻速递",
+        prefix: "/h/se_notice/eslist",
+        fields: {
+            se: { title: "公告来源", filter_type: "multiple" },
+            is_transferred_to_references: { title: "文献标记", filter_type: "multiple" },
+        },
+    },
+    targets: {
+        title: "药物靶点数据库",
+        category: "行业参考",
+        prefix: "/targets/eslist",
+        fields: {
+            target_type: { title: "靶点类型", filter_type: "multiple" },
+            kind: { title: "种类", filter_type: "multiple" },
+            organism: { title: "生物体", filter_type: "multiple" },
+        },
+    },
+    tw_fda: {
+        title: "台湾上市药品",
+        category: "上市情报",
+        prefix: "/tw_fda/eslist",
+        fields: {
+            mixture: { title: "单复方", filter_type: "multiple" },
+            drug_clasify_code: { title: "药品分类", filter_type: "multiple" },
+            lblLicknd: { title: "许可证种类", filter_type: "multiple" },
+        },
+    },
+    uk_emc: {
+        title: "英国上市药品",
+        category: "上市情报",
+        prefix: "/uk_emc/eslist",
+        fields: {
+            drug_type: { title: "药品类型", filter_type: "multiple" },
+            legal_category: { title: "法律类别", filter_type: "multiple" },
+            ATC_code: { title: "治疗领域", filter_type: "multiple" },
+        },
+    },
+    yibao: {
+        title: "医保目录",
+        category: "市场准入",
+        prefix: "/yibao/eslist",
+        fields: {
+            province: { title: "医保地区", filter_type: "multiple" },
+            drug_type: { title: "药品类型", filter_type: "multiple" },
+            insurance_level: { title: "医保类型", filter_type: "multiple" },
+            std_catalog_version: { title: "医保版本", filter_type: "multiple" },
+        },
+    },
+    yzpj_products: {
+        title: "一致性评价产品",
+        category: "注册情报",
+        prefix: "/b/yzpj_products/list",
+        fields: {
+            latest_status: { title: "最高进展", filter_type: "multiple" },
+        },
+    },
+    zb_news: {
+        title: "全国招标动态",
+        category: "药闻速递",
+        prefix: "/c/zb_news/eslist",
+        fields: {
+            city: { title: "省份", filter_type: "multiple" },
+            website: { title: "网站", filter_type: "multiple" },
+        },
+    },
+    zldj: {
+        title: "药品专利信息公示",
+        category: "行业参考",
+        prefix: "/c/zldj/eslist",
+        fields: {
+            registration_status: { title: "登记状态", filter_type: "multiple" },
+            form_type: { title: "登记表类型", filter_type: "multiple" },
+            is_public: { title: "专利信息公开", filter_type: "multiple" },
+            drug_type: { title: "药品类型", filter_type: "multiple" },
+            dosage_form: { title: "药品剂型", filter_type: "multiple" },
+        },
+    },
+    zlsm: {
+        title: "药品专利声明",
+        category: "行业参考",
+        prefix: "/c/zlsm/eslist",
+        fields: {
+            drug_type: { title: "药品类型", filter_type: "multiple" },
+            dosage_form: { title: "药品剂型", filter_type: "multiple" },
+            register_type: { title: "注册分类", filter_type: "multiple" },
+        },
+    },
+};
+/** Databases that expose facets, sorted. Handy for validation and tool docs. */
+export const DBS_FACET_DBNAME_LIST = Object.keys(DBS_FACET_CATALOG).sort();

package/dist/index.js

@@ -4,8 +4,10 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { clampLimit, clampOffset, fetchDetail, fetchFacets, listSearch, mcpDbDetail, mcpDbSearch, prefersMcpListApi, yaohaiPost, } from "./api.js";
 import { ATC_HINT, PRODUCT_CN_COMMON_FIELDS, PRODUCT_CN_DETAIL_PATH, PRODUCT_CN_FACET_FIELDS, PRODUCT_CN_FACET_PREFIX, PRODUCT_CN_VIEW_TYPES, REG_CN_COMMON_FIELDS, REG_CN_DETAIL_PATH, REG_CN_FACET_FIELDS, REG_CN_FACET_PREFIX, REG_CN_VIEW_TYPES, applyProductCnDefaults, applyRegCnDefaults, productCnSearchPath, regCnSearchPath, } from "./fields.js";
-import { EmptyObjectSchema, ProductCnDetailSchema, ProductCnFacetsSchema, ProductCnSearchSchema, RegCnDetailSchema, RegCnFacetsSchema, RegCnSearchSchema, YaohaiCatalogSchema, YaohaiDetailSchema, YaohaiGlobalSearchSchema, YaohaiSearchSchema, } from "./types.js";
-const PACKAGE_VERSION = "0.3.0";
+import { EmptyObjectSchema, ProductCnDetailSchema, ProductCnFacetsSchema, ProductCnSearchSchema, RegCnDetailSchema, RegCnFacetsSchema, RegCnSearchSchema, YaohaiCatalogSchema, YaohaiDetailSchema, YaohaiFacetsSchema, YaohaiGlobalSearchSchema, YaohaiSearchSchema, } from "./types.js";
+import { DBS_FACET_CATALOG } from "./dbs-facets.js";
+import { checkForUpdate, formatUpdateMessage, } from "./update-check.js";
+const PACKAGE_VERSION = "0.5.0";
 const YAOHAI_LIMIT_MAX = 50;
 const YAOHAI_LIMIT_DEFAULT = 10;
 const CN_LIMIT_MAX = 100;
@@ -17,6 +19,17 @@ const QUERY_PROP = {
 };
 const PRESENTATION_HINT = "If total > 20, summarize in chat (about 5–10 sample rows) instead of dumping the full table. Include frontend source links when present.";
 const ROUTING_HINT = "Already-marketed China products (国药准字, 批准文号, 上市, 医保/集采) → product-cn-* tools. R&D / CDE pipeline (在研, 受理号, 审评, 尚未上市) → reg-cn-* tools. Other DBs (医保 yibao, 基药 jiyao, 集采 jicai, trials, global) → yaohai-*. Do not use yaohai-search with dbname product_cn or reg_cn when the dedicated tools apply.";
+/**
+ * Derived from the generated facet catalog so the tool descriptions can never
+ * drift from the data they describe.
+ */
+const DBS_FACET_DBS = Object.keys(DBS_FACET_CATALOG).sort();
+const DBS_FACET_DB_COUNT = DBS_FACET_DBS.length;
+const DBS_FACET_FIELD_COUNT = DBS_FACET_DBS.reduce((n, db) => n + Object.keys(DBS_FACET_CATALOG[db].fields).length, 0);
+/** A few well-known dbs, used to hint coverage without listing all 44. */
+const DBS_FACET_EXAMPLES = ["yibao", "jiyao", "jicai", "dpd", "fda_ndc", "uk_emc", "nmpa_gmp"]
+    .filter((db) => db in DBS_FACET_CATALOG)
+    .join(", ");
 process.on("uncaughtException", (error) => {
     console.error("Uncaught Exception:", error);
     process.exit(1);
@@ -32,6 +45,9 @@ const server = new Server({
     capabilities: {
         resources: {},
         tools: {},
+        // Declared so clients accept the notifications/message we emit when a
+        // newer version of this package is published.
+        logging: {},
     },
 });
 server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -91,6 +107,30 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["dbname", "id"],
                 },
             },
+            {
+                name: "yaohai-facets",
+                description: "Facet distributions (条件筛选) for a dbs database — aggregated value+count buckets for filterable fields. " +
+                    `Works for ${DBS_FACET_DB_COUNT} dbs reached via yaohai-search (${DBS_FACET_EXAMPLES}, …). ` +
+                    `DISCOVERY MODE: omit \`fields\` to list available facet fields (add \`dbname\` for one db, omit it for all ${DBS_FACET_DB_COUNT}). ` +
+                    "FETCH MODE: pass `fields` (required with `dbname`) to get buckets for those fields. One HTTP request fires per field, so request only the 2–4 you need. " +
+                    "Pass the same `query` filters you used in yaohai-search to facet within that result set. " +
+                    "Not available for product_cn / reg_cn — use product-cn-facets / reg-cn-facets instead.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        dbname: {
+                            type: "string",
+                            description: "Database id from yaohai-catalog, e.g. yibao, jiyao, dpd, uk_emc. Required when `fields` is given. Omit to list all facet-capable databases.",
+                        },
+                        query: QUERY_PROP,
+                        fields: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Facet field keys (see discovery mode). Omit to get the catalog instead of buckets. Example for yibao: [\"province\", \"drug_type\"].",
+                        },
+                    },
+                },
+            },
             {
                 name: "yaohai-global-search",
                 description: "Global drug panorama search (global_search). Pass q as the search term, or query.term. " +
@@ -242,6 +282,27 @@ function encodeId(id) {
 function asQuery(query) {
     return { ...(query ?? {}) };
 }
+/**
+ * Structured "not facet-capable" response.
+ *
+ * Returned as a normal (non-error) payload so an agent can self-correct in one
+ * step instead of having to parse an exception message. Covers the common cases:
+ * a dbname that is not in the catalog at all, and one that exists but is not a
+ * dbs-route database (product_cn / reg_cn have dedicated facet tools; the other
+ * custom/aggs routes expose no condition filters).
+ */
+function facetDbUnknown(dbname) {
+    const near = DBS_FACET_DBS.filter((db) => db.includes(dbname) || dbname.includes(db)).slice(0, 5);
+    return {
+        dbname,
+        supported: false,
+        error: `No facet fields known for dbname "${dbname}".`,
+        hint: "Only dbs-route databases support yaohai-facets. " +
+            "For product_cn use product-cn-facets; for reg_cn use reg-cn-facets. " +
+            `Call yaohai-facets with no arguments to list all ${DBS_FACET_DB_COUNT} facet-capable databases.`,
+        ...(near.length > 0 ? { did_you_mean: near } : {}),
+    };
+}
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
@@ -274,6 +335,71 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 });
                 return ok(content);
             }
+            case "yaohai-facets": {
+                const validated = YaohaiFacetsSchema.parse(args ?? {});
+                // Discovery mode: no `fields` -> describe what can be facetted.
+                // Without this, agents would have to guess field names and would hit
+                // "Unknown facet fields" from fetchFacets.
+                if (!validated.fields) {
+                    if (validated.dbname) {
+                        const entry = DBS_FACET_CATALOG[validated.dbname];
+                        if (!entry) {
+                            return ok(facetDbUnknown(validated.dbname));
+                        }
+                        return ok({
+                            dbname: validated.dbname,
+                            title: entry.title,
+                            category: entry.category,
+                            facet_prefix: entry.prefix,
+                            facet_count: Object.keys(entry.fields).length,
+                            facets: entry.fields,
+                        });
+                    }
+                    return ok({
+                        facet_capable_databases: DBS_FACET_DB_COUNT,
+                        total_facet_fields: DBS_FACET_FIELD_COUNT,
+                        note: "Call yaohai-facets with a dbname to list its fields, or pass dbname + fields to fetch buckets. " +
+                            "product_cn and reg_cn use product-cn-facets / reg-cn-facets instead.",
+                        databases: DBS_FACET_DBS.map((db) => ({
+                            dbname: db,
+                            title: DBS_FACET_CATALOG[db].title,
+                            category: DBS_FACET_CATALOG[db].category,
+                            facet_count: Object.keys(DBS_FACET_CATALOG[db].fields).length,
+                            fields: Object.keys(DBS_FACET_CATALOG[db].fields),
+                        })),
+                    });
+                }
+                // Fetch mode: both dbname and fields are required.
+                if (!validated.dbname) {
+                    throw new Error("dbname is required when fetching facets. Omit `fields` to list facet-capable databases.");
+                }
+                const entry = DBS_FACET_CATALOG[validated.dbname];
+                if (!entry) {
+                    return ok(facetDbUnknown(validated.dbname));
+                }
+                // Report unknown fields up front with the valid list, rather than letting
+                // fetchFacets throw on the first one and lose the rest.
+                const known = Object.keys(entry.fields);
+                const unknown = validated.fields.filter((f) => !known.includes(f));
+                if (unknown.length > 0) {
+                    throw new Error(`Unknown facet field(s) for ${validated.dbname}: ${unknown.join(", ")}. ` +
+                        `Valid fields: ${known.join(", ")}.`);
+                }
+                // Per-db required params (e.g. drugsales needs groupid=205) go first so
+                // caller-supplied values can still override them.
+                const query = { ...(entry.defaultQuery ?? {}), ...asQuery(validated.query) };
+                const content = await fetchFacets({
+                    prefix: entry.prefix,
+                    query,
+                    fields: validated.fields,
+                    catalog: entry.fields,
+                });
+                return ok({
+                    dbname: validated.dbname,
+                    title: entry.title,
+                    ...content,
+                });
+            }
             case "yaohai-global-search": {
                 const validated = YaohaiGlobalSearchSchema.parse(args ?? {});
                 const query = asQuery(validated.query);
@@ -403,8 +529,47 @@ function ok(content) {
         isError: false,
     };
 }
+/**
+ * Tell the user a newer version is published, on both channels we have:
+ *  - stderr, which MCP clients surface in their server log panel and which is
+ *    safe for a stdio server (stdout carries JSON-RPC and must stay clean);
+ *  - a `notifications/message` log notification, which reaches clients that
+ *    render MCP log messages to the user.
+ *
+ * Never throws: diagnostics must not take the server down.
+ */
+async function announceUpdateIfAvailable() {
+    try {
+        const result = await checkForUpdate(PACKAGE_VERSION);
+        if (!result.updateAvailable)
+            return;
+        const message = formatUpdateMessage(result);
+        if (!message)
+            return;
+        console.error(`[mcp-drugsea] ${message.split("\n").join("\n[mcp-drugsea] ")}`);
+        try {
+            await server.sendLoggingMessage({
+                level: "warning",
+                logger: "update-check",
+                data: message,
+            });
+        }
+        catch {
+            // Client may not have declared logging support; stderr line still landed.
+        }
+    }
+    catch {
+        // Swallow everything: an update check is never worth surfacing.
+    }
+}
 async function main() {
     const transport = new StdioServerTransport();
+    // Fire only after the initialize handshake completes, so the notification is
+    // never emitted before the client is ready to receive it. Deliberately not
+    // awaited: startup latency must not depend on registry reachability.
+    server.oninitialized = () => {
+        void announceUpdateIfAvailable();
+    };
     await server.connect(transport);
 }
 main().catch((error) => {

package/dist/types.js

@@ -20,6 +20,24 @@ export const YaohaiDetailSchema = z.object({
     dbname: z.string().min(1),
     id: z.string().min(1),
 });
+/**
+ * Facet request for a dbs-route database.
+ *
+ * Dual-mode, so one tool covers both discovery and fetching:
+ *   - `fields` omitted  -> return the facet catalog (available fields). Add
+ *     `dbname` to narrow to one database, omit it to list all 44.
+ *   - `fields` given    -> fetch those facet distributions for `dbname`.
+ *
+ * Discovery mode exists because agents otherwise have to guess field names and
+ * would hit "Unknown facet fields". Fetching requires `fields` to be explicit:
+ * one HTTP request fires per field, so an implicit "all of them" would be a slow
+ * 129-request fan-out.
+ */
+export const YaohaiFacetsSchema = z.object({
+    dbname: z.string().optional(),
+    query: QueryObjectSchema.optional(),
+    fields: z.array(z.string().min(1)).min(1).optional(),
+});
 export const YaohaiGlobalSearchSchema = z.object({
     q: z.string().optional(),
     query: QueryObjectSchema.optional(),

package/dist/update-check.js

@@ -0,0 +1,235 @@
+/**
+ * Non-blocking npm update check.
+ *
+ * Why this exists: MCP clients usually launch the server with
+ * `npx -y @kinginsun/mcp-drugsea`. A bare package name resolves against the
+ * local npx cache and can pin users to a stale version indefinitely, and
+ * `npm install -g` users never auto-update at all. Since we cannot retroactively
+ * patch code that is already installed on a user's machine, every release ships
+ * this check so subsequent versions can tell the user how to upgrade.
+ *
+ * Hard constraints (do not weaken):
+ *  - MUST NOT write to stdout: this is a stdio JSON-RPC server, stdout is the
+ *    protocol channel. Diagnostics go to stderr / notifications only.
+ *  - MUST NOT throw or reject: a version check can never break server startup.
+ *  - MUST NOT block startup: the caller fires this off without awaiting connect.
+ *  - MUST be cheap: one small request per process, TTL-cached across processes.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const PACKAGE_NAME = "@kinginsun/mcp-drugsea";
+/** Registry doc for a single version; ~2 KB, far cheaper than the full packument. */
+function registryLatestUrl() {
+    const base = (process.env.YAOHAI_NPM_REGISTRY || "https://registry.npmjs.org")
+        .trim()
+        .replace(/\/+$/, "");
+    // Scoped names must be percent-encoded in the path.
+    return `${base}/${PACKAGE_NAME.replace("/", "%2F")}/latest`;
+}
+/** How long a cached "latest version" answer stays fresh. */
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+/** Fail fast: a slow registry must never be felt by the user. */
+const FETCH_TIMEOUT_MS = 1500;
+/** Truthiness for env flags: "0", "", "false", "no", "off" all mean disabled. */
+function flagDisabled(raw) {
+    if (raw === undefined)
+        return false;
+    const value = raw.trim().toLowerCase();
+    return ["0", "", "false", "no", "off"].includes(value);
+}
+export function updateCheckEnabled() {
+    return !flagDisabled(process.env.YAOHAI_MCP_UPDATE_CHECK);
+}
+/**
+ * Minimal semver precedence compare, avoiding a runtime dependency.
+ * Returns >0 if a is newer than b, <0 if older, 0 if equal.
+ * Handles `MAJOR.MINOR.PATCH` with an optional `-prerelease`; a prerelease of
+ * the same numeric triple sorts below the release (per semver §11).
+ */
+export function compareVersions(a, b) {
+    const parse = (input) => {
+        const [core, ...rest] = input.trim().replace(/^v/i, "").split("-");
+        const parts = core.split(".").map((n) => {
+            const parsed = Number.parseInt(n, 10);
+            return Number.isFinite(parsed) ? parsed : 0;
+        });
+        while (parts.length < 3)
+            parts.push(0);
+        return { parts: parts.slice(0, 3), prerelease: rest.join("-") };
+    };
+    const left = parse(a);
+    const right = parse(b);
+    for (let i = 0; i < 3; i++) {
+        if (left.parts[i] !== right.parts[i])
+            return left.parts[i] - right.parts[i];
+    }
+    // Numeric triples tie: presence of a prerelease decides.
+    if (left.prerelease && !right.prerelease)
+        return -1;
+    if (!left.prerelease && right.prerelease)
+        return 1;
+    if (left.prerelease && right.prerelease) {
+        return left.prerelease < right.prerelease
+            ? -1
+            : left.prerelease > right.prerelease
+                ? 1
+                : 0;
+    }
+    return 0;
+}
+function cacheFile() {
+    try {
+        const base = process.env.XDG_CACHE_HOME?.trim() ||
+            (os.homedir() ? path.join(os.homedir(), ".cache") : os.tmpdir());
+        return path.join(base, "mcp-drugsea", "update-check.json");
+    }
+    catch {
+        return undefined;
+    }
+}
+function readCache() {
+    const file = cacheFile();
+    if (!file)
+        return undefined;
+    try {
+        const raw = fs.readFileSync(file, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.latest === "string" &&
+            parsed.latest.length > 0 &&
+            typeof parsed.checkedAt === "number") {
+            return { latest: parsed.latest, checkedAt: parsed.checkedAt };
+        }
+    }
+    catch {
+        // Missing, unreadable, or corrupt cache is always fine.
+    }
+    return undefined;
+}
+function writeCache(latest) {
+    const file = cacheFile();
+    if (!file)
+        return;
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, `${JSON.stringify({ latest, checkedAt: Date.now() })}\n`, "utf8");
+    }
+    catch {
+        // Read-only home, sandboxed FS, full disk: skip caching silently.
+    }
+}
+async function fetchLatest() {
+    // Node >= 18 guarantees global fetch (see package.json engines).
+    if (typeof fetch !== "function")
+        return undefined;
+    try {
+        const response = await fetch(registryLatestUrl(), {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            redirect: "follow",
+        });
+        if (!response.ok)
+            return undefined;
+        const body = (await response.json());
+        return typeof body.version === "string" && body.version.length > 0
+            ? body.version
+            : undefined;
+    }
+    catch {
+        // Offline, DNS failure, dead proxy, TLS interception, timeout: all expected.
+        return undefined;
+    }
+}
+/**
+ * Resolve the newest published version, preferring the network and falling back
+ * to a still-fresh cache entry so offline users get a useful answer too.
+ */
+/**
+ * Resolve the newest published version.
+ *
+ * Cache-first: a fresh cache entry means zero network traffic and zero added
+ * startup latency for every launch inside the TTL window. Only when the cache is
+ * missing/expired do we consult the registry, and a failed lookup degrades to the
+ * stale cache entry so offline users still get a useful answer.
+ */
+async function resolveLatest() {
+    const cached = readCache();
+    if (cached && Date.now() - cached.checkedAt <= CACHE_TTL_MS) {
+        return { latest: cached.latest, detail: "fresh cache; registry not contacted" };
+    }
+    const live = await fetchLatest();
+    if (live) {
+        writeCache(live);
+        return { latest: live };
+    }
+    if (cached) {
+        return {
+            latest: cached.latest,
+            detail: "registry unreachable; used stale cached version",
+        };
+    }
+    return { detail: "registry unreachable and no cache" };
+}
+/**
+ * Check for a newer published version. Resolves with a result object and never
+ * rejects; callers may safely ignore the promise.
+ */
+export async function checkForUpdate(currentVersion) {
+    try {
+        if (!updateCheckEnabled()) {
+            return { current: currentVersion, updateAvailable: false, status: "disabled" };
+        }
+        if (!/^\d+\.\d+\.\d+/.test(currentVersion.trim())) {
+            // Dev builds like "0.0.0-dev" or a git hash: nothing sane to compare.
+            return {
+                current: currentVersion,
+                updateAvailable: false,
+                status: "error",
+                detail: "non-semver build version",
+            };
+        }
+        const resolved = await resolveLatest();
+        if (!resolved.latest) {
+            return {
+                current: currentVersion,
+                updateAvailable: false,
+                status: "error",
+                detail: resolved.detail,
+            };
+        }
+        const updateAvailable = compareVersions(resolved.latest, currentVersion) > 0;
+        return {
+            current: currentVersion,
+            latest: resolved.latest,
+            updateAvailable,
+            status: updateAvailable ? "update-available" : "up-to-date",
+            detail: resolved.detail,
+        };
+    }
+    catch (error) {
+        // Belt and braces: this function is contractually non-throwing.
+        return {
+            current: currentVersion,
+            updateAvailable: false,
+            status: "error",
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Human-readable upgrade instructions, matching the README "Updating" section.
+ * Used for both the stderr line and the MCP logging notification.
+ */
+export function formatUpdateMessage(result) {
+    if (!result.updateAvailable || !result.latest)
+        return "";
+    const lines = [
+        `${PACKAGE_NAME} ${result.current} is installed; ${result.latest} is available.`,
+        "To update:",
+        '  npx users  - change args to ["-y", "@kinginsun/mcp-drugsea@latest"], then reload the MCP server',
+        "  global     - npm update -g " + PACKAGE_NAME,
+        "  stale npx  - npm cache npx ls && npm cache npx rm <key>",
+        "Set YAOHAI_MCP_UPDATE_CHECK=0 to silence this message.",
+    ];
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kinginsun/mcp-drugsea",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "MCP server for DrugSea / Yaohai pharmaceutical databases: cross-db search, China marketed products (product_cn), and CDE registration review (reg_cn).",
   "type": "module",
   "main": "dist/index.js",