@kinginsun/mcp-drugsea 0.2.1 → 0.4.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 / smart-search (`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)
 
@@ -38,6 +38,20 @@ Obtain a token from DrugSea / Yaohai (user account settings), then:
 export YAOHAI_MCP_TOKEN=ysk_your_token_here
 ```
 
+#### How to get a token from DrugSea (Yaohai)
+
+1. Open [https://db.drugsea.cn](https://db.drugsea.cn) in a browser.
+2. Log in with **WeChat QR scan** (微信扫码登录).
+3. Enter the **personal center** (个人中心).
+4. In the left sidebar, click **API Token**.
+5. Click **generate token** (生成 Token) and copy the result — it looks like `ysk_` + 32 hex characters.
+
+Notes:
+
+- Each account can generate up to **10 tokens**.
+- A token inherits the **same database permissions as its Yaohai account** — if your account cannot see a database, the token cannot either. If a tool call returns a permission error, check your account's subscription/permissions on db.drugsea.cn, not the MCP client.
+- Store the token in your MCP client's `env` (see below) or export it as `YAOHAI_MCP_TOKEN`. Never commit it to a repository.
+
 On db3, direct GET list routes may return encrypted payloads; this client auto-routes `product-cn-search` / `reg-cn-search` / detail through MCP POST when the base URL contains `db3.drugsea.cn`.
 
 ### Optional
@@ -86,9 +100,9 @@ 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-smart-search` |
+| Unclear which DB | `yaohai-catalog` (list DBs by keyword/category) → `yaohai-search`, or `yaohai-global-search` |
 
 Therapeutic-class queries (抗癌, 心血管, …): prefer ConditionSearch `ATC_code` (letter, e.g. `L` oncology, `C` cardiovascular, `J` anti-infectives, `N` nervous system). Confirm values with a facets tool when unsure.
 
@@ -107,8 +121,17 @@ 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` |
-| `yaohai-smart-search` | `q`, `query?`, `limit?` | Auto-routes up to 3 DBs |
+
+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)
 
@@ -136,6 +159,138 @@ xlsx export is not implemented in this MCP (v1 returns JSON samples only).
 
 `query` values may be string, number, or string arrays (ConditionSearch `multiple`). Dates: `"YYYY-MM-DD to YYYY-MM-DD"`. Ranges: `"min to max"`.
 
+## Quick start for AI Agents (install, configure, test)
+
+This section is a step-by-step playbook an AI agent (or a human) can follow to install, configure, and verify this MCP server end to end.
+
+### Prerequisites
+
+- Node.js >= 18 (`node -v`)
+- npm (`npm -v`)
+- A DrugSea / Yaohai personal token (`ysk_` + 32 hex chars) — see [How to get a token from DrugSea (Yaohai)](#how-to-get-a-token-from-drugsea-yaohai)
+
+### Step 0 — Register the server with your MCP client
+
+Add the server to your client config so it auto-starts. Example for Cursor (`~/.cursor/mcp.json`) — see [Configuration](#configuration) for other clients:
+
+```json
+{
+  "mcpServers": {
+    "drugsea": {
+      "command": "npx",
+      "args": ["-y", "@kinginsun/mcp-drugsea"],
+      "env": {
+        "YAOHAI_MCP_TOKEN": "ysk_your_token_here"
+      }
+    }
+  }
+}
+```
+
+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)
+
+Either run via npx on demand (no install needed), or install globally / from source:
+
+```bash
+# Option A: run without installing (what the MCP configs above do)
+npx -y @kinginsun/mcp-drugsea
+
+# Option B: global install
+npm install -g @kinginsun/mcp-drugsea
+npm ls -g @kinginsun/mcp-drugsea
+
+# Option C: from source (when developing)
+git clone https://github.com/kinginsun/mcp-drugsea.git
+cd mcp-drugsea
+npm install
+npm run build
+```
+
+### Step 2 — Configure the token
+
+```bash
+export YAOHAI_MCP_TOKEN=ysk_your_token_here
+```
+
+For MCP client usage, put the token in the client config `env` instead (Step 0). Sanity-check the format:
+
+```bash
+node -e "console.log(/^ysk_[0-9a-f]{32}$/i.test(process.env.YAOHAI_MCP_TOKEN) ? 'token format OK' : 'token format BAD')"
+```
+
+### Step 3 — Smoke test over stdio (JSON-RPC)
+
+The server speaks MCP over stdio. The recommended handshake sequence is `initialize` → `notifications/initialized` → request. Run this **outside** the package source directory (or use `node dist/index.js` inside it):
+
+```bash
+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)})"
+```
+
+Expected: `tools: 12`.
+
+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
+```
+
+### Step 4 — Test real tool calls
+
+```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
+
+# 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
+
+# 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
+```
+
+Expected: each response has `"isError":false` and non-empty `content`.
+
+### Step 5 — Full 12-tool suite (from source)
+
+```bash
+git clone https://github.com/kinginsun/mcp-drugsea.git
+cd mcp-drugsea
+npm install && npm run build
+YAOHAI_MCP_TOKEN=ysk_your_token_here node scripts/test-all-tools.mjs
+```
+
+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 13 tools.
+2. "Search 阿司匹林 in product-cn" → should return rows with `total > 0`.
+3. "Global search: PD-1" → should return panorama results without error.
+
+### Troubleshooting
+
+| Symptom | Cause / fix |
+|---------|-------------|
+| `Set YAOHAI_MCP_TOKEN to your personal DrugSea token…` | Token env var missing/empty — set it (Step 2 / client `env`) |
+| `YAOHAI_MCP_TOKEN must be a personal user token` | Token not `ysk_` + 32 hex — regenerate in personal center → API Token |
+| `401` / `Unauthorized` (incl. backend's `invalid or missing X-Yaohai-Api-Key`) | Token expired or revoked — regenerate at db.drugsea.cn (personal center → API Token). The backend returns that `X-Yaohai-Api-Key` wording for **any** rejected credential; this client only ever sends `Authorization: Bearer`, so ignore the header name and replace the token. If you rotated the token, also `unset YAOHAI_MCP_TOKEN` — a stale exported value shadows the updated `.env`. |
+| Permission/forbidden on a specific DB | Token inherits account permissions — check the account's subscription on db.drugsea.cn |
+| `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` |
+
 ## Manual stdio test
 
 ```bash
@@ -153,6 +308,19 @@ echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"product-cn
   | YAOHAI_MCP_TOKEN=ysk_your_token_here node dist/index.js
 ```
 
+## 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.
+
+```bash
+npm login                # once, with rights on the @kinginsun scope
+./publish.sh --dry-run   # full rehearsal, no side effects
+./publish.sh --minor     # real release (0.2.1 → 0.3.0)
+./publish.sh --help      # all flags (--major, --version, --otp, --skip-tests, --note, --no-push)
+```
+
+The suite needs a **live** token: `publish.sh` probes the API first and, on rejection, reports it as a credential problem rather than a code regression. If you rotated `YAOHAI_MCP_TOKEN`, run `unset YAOHAI_MCP_TOKEN` first so the new `.env` value isn't shadowed by a stale exported one.
+
 ## Requirements
 
 - Node.js >= 18.0.0

package/dist/api.js

@@ -156,6 +156,23 @@ function parseApiJson(status, text) {
         };
     }
     if (status < 200 || status >= 300) {
+        // The DrugSea gateway answers every rejected credential with a generic
+        // "invalid or missing X-Yaohai-Api-Key" string, even though this client
+        // only ever sends `Authorization: Bearer <YAOHAI_MCP_TOKEN>`. Translate
+        // that misleading 401 into actionable advice instead of leaking the
+        // backend's wording.
+        if (status === 401 || status === 403) {
+            return {
+                ok: false,
+                status,
+                error: `YAOHAI_MCP_TOKEN was rejected by the DrugSea API (HTTP ${status}). ` +
+                    "The token is missing, expired, or revoked — regenerate it at " +
+                    "db.drugsea.cn (personal center → API Token) and update YAOHAI_MCP_TOKEN. " +
+                    "This client authenticates with `Authorization: Bearer` only; the backend's " +
+                    "'X-Yaohai-Api-Key' wording is a generic message and does not apply here.",
+                raw: data,
+            };
+        }
         return {
             ok: false,
             status,

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

@@ -2,10 +2,11 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { ApiError, clampLimit, clampOffset, fetchDetail, fetchFacets, listSearch, mcpDbDetail, mcpDbSearch, prefersMcpListApi, yaohaiPost, } from "./api.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, YaohaiSmartSearchSchema, } from "./types.js";
-const PACKAGE_VERSION = "0.2.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";
+const PACKAGE_VERSION = "0.4.0";
 const YAOHAI_LIMIT_MAX = 50;
 const YAOHAI_LIMIT_DEFAULT = 10;
 const CN_LIMIT_MAX = 100;
@@ -17,6 +18,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);
@@ -92,38 +104,44 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 },
             },
             {
-                name: "yaohai-global-search",
-                description: "Global drug panorama search (global_search). Pass q as the search term, or query.term. " +
-                    PRESENTATION_HINT,
+                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: {
-                        q: { type: "string", description: "Search term (maps to query.term)" },
+                        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,
-                        limit: {
-                            type: "number",
-                            description: `Row cap (default ${YAOHAI_LIMIT_DEFAULT}, max ${YAOHAI_LIMIT_MAX})`,
+                        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\"].",
                         },
-                        offset: { type: "number", description: "Pagination offset (default 0)" },
                     },
                 },
             },
             {
-                name: "yaohai-smart-search",
-                description: "Natural-language Yaohai search: auto-routes the question to up to 3 databases. Use when the user question is broad or the target DB is unclear. " +
-                    "Falls back to global search when the router matches nothing or finds no rows. " +
-                    ROUTING_HINT,
+                name: "yaohai-global-search",
+                description: "Global drug panorama search (global_search). Pass q as the search term, or query.term. " +
+                    PRESENTATION_HINT,
                 inputSchema: {
                     type: "object",
                     properties: {
-                        q: { type: "string", description: "Natural language question" },
+                        q: { type: "string", description: "Search term (maps to query.term)" },
                         query: QUERY_PROP,
                         limit: {
                             type: "number",
                             description: `Row cap (default ${YAOHAI_LIMIT_DEFAULT}, max ${YAOHAI_LIMIT_MAX})`,
                         },
+                        offset: { type: "number", description: "Pagination offset (default 0)" },
                     },
-                    required: ["q"],
                 },
             },
             {
@@ -260,168 +278,25 @@ function encodeId(id) {
 function asQuery(query) {
     return { ...(query ?? {}) };
 }
-async function globalSearchContent(q, query, limit) {
-    const gquery = asQuery(query);
-    if (q && (gquery.term === undefined || gquery.term === "")) {
-        gquery.term = q;
-    }
-    const content = await yaohaiPost("/g/mcp/yaohai/global-search", {
-        query: gquery,
-        limit,
-        offset: 0,
-    });
-    return content;
-}
-function allSmartResultsEmpty(content) {
-    if (!content || typeof content !== "object") {
-        return true;
-    }
-    const results = content.results;
-    if (!Array.isArray(results) || results.length === 0) {
-        return true;
-    }
-    return results.every((entry) => {
-        const result = entry?.result;
-        if (!result || typeof result !== "object") {
-            return true;
-        }
-        const total = result.total;
-        return typeof total === "number" ? total === 0 : true;
-    });
-}
 /**
- * The backend router searches the entire question string in one field per DB,
- * which rarely matches (e.g. item="医保目录 阿司匹林" → 0 rows), and sometimes
- * picks a field the DB does not support (e.g. `item` on jicai). Retry each
- * empty matched DB with the individual tokens of the question across the
- * router's field plus the catalog's search_fields for that DB.
+ * 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).
  */
-async function retrySmartResultsWithTokens(content, q, limit) {
-    const results = content.results;
-    if (!Array.isArray(results)) {
-        return null;
-    }
-    const tokens = q.split(/\s+/).filter((t) => t && t !== q);
-    if (tokens.length === 0) {
-        return null;
-    }
-    const catalogFields = new Map();
-    async function searchFieldsFor(dbname) {
-        if (catalogFields.has(dbname)) {
-            return catalogFields.get(dbname);
-        }
-        let keys = [];
-        try {
-            const cat = (await yaohaiPost("/g/mcp/yaohai/catalog", { q: dbname }));
-            const db = (cat.databases ?? []).find((d) => d.id === dbname);
-            keys = (db?.search_fields ?? [])
-                .map((f) => f.key)
-                .filter((k) => typeof k === "string");
-        }
-        catch {
-            keys = [];
-        }
-        catalogFields.set(dbname, keys);
-        return keys;
-    }
-    let changed = false;
-    const patched = [];
-    for (const entry of results) {
-        const inner = entry?.result;
-        if (!inner || typeof inner !== "object") {
-            patched.push(entry);
-            continue;
-        }
-        const r = inner;
-        if (r.total !== 0 || typeof r.dbname !== "string") {
-            patched.push(entry);
-            continue;
-        }
-        const queryApplied = r.query_applied;
-        const appliedKeys = queryApplied ? Object.keys(queryApplied) : [];
-        const singleFieldWholeQuestion = appliedKeys.length === 1 && queryApplied[appliedKeys[0]] === q;
-        if (!singleFieldWholeQuestion) {
-            patched.push(entry);
-            continue;
-        }
-        const routerField = appliedKeys[0];
-        const fields = [routerField, ...(await searchFieldsFor(r.dbname))];
-        const uniqueFields = [...new Set(fields)].slice(0, 6);
-        let replaced = false;
-        outer: for (const token of tokens.slice(0, 3)) {
-            for (const field of uniqueFields) {
-                try {
-                    const retry = (await yaohaiPost("/g/mcp/yaohai/search", {
-                        dbname: r.dbname,
-                        query: { [field]: token },
-                        limit,
-                        offset: 0,
-                    }));
-                    if (typeof retry.total === "number" && retry.total > 0) {
-                        patched.push({
-                            ...entry,
-                            result: { ...retry, retry: { token, field } },
-                        });
-                        changed = true;
-                        replaced = true;
-                        break outer;
-                    }
-                }
-                catch {
-                    // ignore per-token retry errors; try next field/token
-                }
-            }
-        }
-        if (!replaced) {
-            patched.push(entry);
-        }
-    }
-    if (!changed) {
-        return null;
-    }
-    return { ...content, results: patched };
-}
-/**
- * Last resort when the router matched databases but every search came back
- * empty (e.g. the question is just a DB keyword like 集采): browse the matched
- * databases without a query so the caller still sees representative rows.
- */
-async function browseMatchedDatabases(content, limit) {
-    const matched = content.matched_databases;
-    if (!Array.isArray(matched) || matched.length === 0) {
-        return null;
-    }
-    const results = [];
-    for (const db of matched.slice(0, 3)) {
-        const id = db?.id;
-        if (typeof id !== "string") {
-            continue;
-        }
-        try {
-            const browse = (await yaohaiPost("/g/mcp/yaohai/search", {
-                dbname: id,
-                query: {},
-                limit,
-                offset: 0,
-            }));
-            if (typeof browse.total === "number" && browse.total > 0) {
-                results.push({
-                    score: db.score,
-                    result: { ...browse, browse: true },
-                });
-            }
-        }
-        catch {
-            // DB not browsable — skip
-        }
-    }
-    if (results.length === 0) {
-        return null;
-    }
+function facetDbUnknown(dbname) {
+    const near = DBS_FACET_DBS.filter((db) => db.includes(dbname) || dbname.includes(db)).slice(0, 5);
     return {
-        ...content,
-        results,
-        note: "Smart-search found no rows for the full question; showing sample rows from the matched databases instead.",
+        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) => {
@@ -456,6 +331,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);
@@ -469,56 +409,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 });
                 return ok(content);
             }
-            case "yaohai-smart-search": {
-                const validated = YaohaiSmartSearchSchema.parse(args);
-                const limit = clampLimit(validated.limit, YAOHAI_LIMIT_DEFAULT, YAOHAI_LIMIT_MAX);
-                const body = { q: validated.q, limit };
-                if (validated.query) {
-                    body.query = validated.query;
-                }
-                try {
-                    const content = await yaohaiPost("/g/mcp/yaohai/smart-search", body);
-                    if (allSmartResultsEmpty(content)) {
-                        // Router matched DBs but searched the whole question in one field
-                        // (or picked an unsupported field). Retry with individual tokens
-                        // across the router's field + the DB's catalog search_fields.
-                        const retried = await retrySmartResultsWithTokens(content, validated.q, limit);
-                        if (retried) {
-                            return ok(retried);
-                        }
-                        // Keyword-only question (e.g. "集采"): show sample rows from the
-                        // matched databases.
-                        const browsed = await browseMatchedDatabases(content, limit);
-                        if (browsed) {
-                            return ok(browsed);
-                        }
-                        // Still nothing — try the global panorama.
-                        const fallback = await globalSearchContent(validated.q, validated.query, limit);
-                        return ok({
-                            question: validated.q,
-                            matched_databases: content.matched_databases,
-                            fallback: "global-search",
-                            note: "Smart-search router matched databases but returned no rows; fell back to global search.",
-                            ...fallback,
-                        });
-                    }
-                    return ok(content);
-                }
-                catch (error) {
-                    if (error instanceof ApiError) {
-                        // Backend router could not match any database (e.g. plain drug-name
-                        // question) — fall back to the global panorama search.
-                        const fallback = await globalSearchContent(validated.q, validated.query, limit);
-                        return ok({
-                            question: validated.q,
-                            fallback: "global-search",
-                            note: `Smart-search router failed (${error.message}); fell back to global search.`,
-                            ...fallback,
-                        });
-                    }
-                    throw error;
-                }
-            }
             case "product-cn-fields": {
                 EmptyObjectSchema.parse(args ?? {});
                 return ok({

package/dist/types.js

@@ -20,17 +20,30 @@ 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(),
     limit: z.coerce.number().int().optional(),
     offset: z.coerce.number().int().optional(),
 });
-export const YaohaiSmartSearchSchema = z.object({
-    q: z.string().min(1),
-    query: QueryObjectSchema.optional(),
-    limit: z.coerce.number().int().optional(),
-});
 export const ProductViewTypeSchema = z.enum([
     "eslist",
     "list_by_drug_name",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kinginsun/mcp-drugsea",
-  "version": "0.2.1",
+  "version": "0.4.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",