@kinginsun/mcp-drugsea 0.2.1 → 0.3.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 / global (`POST /g/mcp/yaohai/*`)
 - **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
@@ -88,7 +102,7 @@ On db3, direct GET list routes may return encrypted payloads; this client auto-r
 | 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` |
 | 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.
 
@@ -108,7 +122,8 @@ xlsx export is not implemented in this MCP (v1 returns JSON samples only).
 | `yaohai-search` | `dbname`, `query?`, `limit?`, `offset?` | Default limit 10, max 50 |
 | `yaohai-detail` | `dbname`, `id` | Skip DBs with `has_detail: false` |
 | `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.
 
 ### product_cn (marketed)
 
@@ -136,6 +151,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 **12 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: 12 passed, 0 failed / 12 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.
+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 +300,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/index.js

@@ -2,10 +2,10 @@
 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, YaohaiGlobalSearchSchema, YaohaiSearchSchema, } from "./types.js";
+const PACKAGE_VERSION = "0.3.0";
 const YAOHAI_LIMIT_MAX = 50;
 const YAOHAI_LIMIT_DEFAULT = 10;
 const CN_LIMIT_MAX = 100;
@@ -108,24 +108,6 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     },
                 },
             },
-            {
-                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,
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        q: { type: "string", description: "Natural language question" },
-                        query: QUERY_PROP,
-                        limit: {
-                            type: "number",
-                            description: `Row cap (default ${YAOHAI_LIMIT_DEFAULT}, max ${YAOHAI_LIMIT_MAX})`,
-                        },
-                    },
-                    required: ["q"],
-                },
-            },
             {
                 name: "product-cn-fields",
                 description: "List CommonSearch and ConditionSearch field keys for 国内上市药品 (product_cn). Call before product-cn-search / product-cn-facets if unsure which filters exist.",
@@ -260,170 +242,6 @@ 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.
- */
-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;
-    }
-    return {
-        ...content,
-        results,
-        note: "Smart-search found no rows for the full question; showing sample rows from the matched databases instead.",
-    };
-}
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
@@ -469,56 +287,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

@@ -26,11 +26,6 @@ export const YaohaiGlobalSearchSchema = z.object({
     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.3.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",