@kinginsun/mcp-drugsea 0.7.1 → 0.9.0

package/README.md

@@ -178,13 +178,19 @@ xlsx export is not implemented in this MCP (v1 returns JSON samples only).
 | Tool | Parameters | Notes |
 |------|------------|--------|
 | `yaohai-catalog` | `category?`, `q?` | List databases |
-| `yaohai-search` | `dbname`, `query?`, `limit?`, `offset?` | Default limit 10, max 50 |
+| `yaohai-search` | `dbname`, `query?`, `limit?`, `offset?` | Default limit 10, max 50; ≤ 1000 rows per query condition (offset+limit window cap) |
 | `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.
 
+> **Retrieval cap (anti-scraping, enforced client + server):** one distinct query
+> condition can return at most **1000 rows** (`offset + limit ≤ 1000`). A larger
+> `offset` is rejected; `limit` is auto-shrunk near the edge of the window. To
+> reach deeper slices, narrow the filters (date / province / ATC / enterprise)
+> and query again — each *new* condition gets its own 1000-row window.
+
 `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`).
@@ -376,7 +382,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@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.
+`publish.sh` releases the package to npm (which is what makes `npx -y @kinginsun/mcp-drugsea@latest` work). It syncs `src/environment.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/api.js

@@ -2,6 +2,7 @@ import http from "node:http";
 import https from "node:https";
 import { URL } from "node:url";
 import { normalizeRecord, parseFacetList, stripMcpFields } from "./normalize.js";
+import { ENVIRONMENT_FINGERPRINT } from "./environment.js";
 export class MissingTokenError extends Error {
     constructor(message) {
         super(message ??
@@ -28,6 +29,7 @@ export function getAuthHeaders(extra = {}) {
     const token = getUserToken();
     return {
         ...extra,
+        "User-Agent": ENVIRONMENT_FINGERPRINT.userAgent,
         Authorization: `Bearer ${token}`,
     };
 }
@@ -95,6 +97,19 @@ export function clampOffset(offset) {
     }
     return Math.max(0, Math.trunc(offset));
 }
+/**
+ * 单组查询条件最多可获取的行数窗口（与服务端 yaohai_mcp_max_retrieve() 同步，
+ * 默认 1000）：offset+limit 超出窗口则收缩 limit；offset 已达窗口直接报错，
+ * 提示收窄筛选条件而不是继续翻页。
+ */
+export const MAX_RETRIEVE_PER_QUERY = 1000;
+export function enforceRetrievalWindow(limit, offset, max = MAX_RETRIEVE_PER_QUERY) {
+    if (offset >= max) {
+        throw new ApiError(`A single query condition can return at most ${max} rows（单个查询条件最多获取 ${max} 条）: ` +
+            `offset=${offset} 已超出窗口上限。请收窄筛选条件（如日期/省份/ATC/企业名）后分页查询。`);
+    }
+    return { limit: Math.min(limit, max - offset), offset };
+}
 function httpRequest(method, urlStr, headers, body) {
     return new Promise((resolve, reject) => {
         const url = new URL(urlStr);

package/dist/environment.js

@@ -0,0 +1,24 @@
+import os from "node:os";
+export const PACKAGE_NAME = "mcp-drugsea";
+export const PACKAGE_VERSION = "0.9.0";
+/**
+ * Capture non-identifying runtime metadata once when the MCP process starts.
+ * Deliberately excludes hostname, username, network addresses, and machine IDs.
+ */
+function collectEnvironmentFingerprint() {
+    const platform = process.platform;
+    const osRelease = os.release();
+    const arch = process.arch;
+    const nodeVersion = process.version;
+    return Object.freeze({
+        packageName: PACKAGE_NAME,
+        packageVersion: PACKAGE_VERSION,
+        nodeVersion,
+        platform,
+        osRelease,
+        arch,
+        userAgent: `${PACKAGE_NAME}/${PACKAGE_VERSION} ` +
+            `(Node.js ${nodeVersion}; ${platform} ${osRelease}; ${arch})`,
+    });
+}
+export const ENVIRONMENT_FINGERPRINT = collectEnvironmentFingerprint();

package/dist/index.js

@@ -2,12 +2,12 @@
 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 { clampLimit, clampOffset, fetchDetail, fetchFacets, listSearch, mcpDbDetail, mcpDbSearch, prefersMcpListApi, yaohaiPost, } from "./api.js";
+import { clampLimit, clampOffset, enforceRetrievalWindow, 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, 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.7.1";
+import { PACKAGE_NAME, PACKAGE_VERSION } from "./environment.js";
 const YAOHAI_LIMIT_MAX = 50;
 const YAOHAI_LIMIT_DEFAULT = 10;
 const CN_LIMIT_MAX = 100;
@@ -18,6 +18,7 @@ const QUERY_PROP = {
     description: "Search/filter fields. Values may be string, number, or string[] (repeat the key for ConditionSearch multiple). Date: \"YYYY-MM-DD to YYYY-MM-DD\". Range: \"min to max\".",
 };
 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 RETRIEVAL_CAP_HINT = "One distinct query condition can return at most 1000 rows total (offset+limit window cap, anti-scraping): paginate within that window, or narrow the filters (date / province / ATC / enterprise) to reach deeper slices — a too-large offset is rejected.";
 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
@@ -39,7 +40,7 @@ process.on("unhandledRejection", (reason, promise) => {
     process.exit(1);
 });
 const server = new Server({
-    name: "mcp-drugsea",
+    name: PACKAGE_NAME,
     version: PACKAGE_VERSION,
 }, {
     capabilities: {
@@ -74,6 +75,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             {
                 name: "yaohai-search",
                 description: "Search a single Yaohai database by dbname (from yaohai-catalog). Default limit 10, max 50. " +
+                    RETRIEVAL_CAP_HINT +
+                    " " +
                     "Use query fields from the catalog's search_fields. " +
                     ROUTING_HINT +
                     " " +
@@ -90,7 +93,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: "number",
                             description: `Row cap (default ${YAOHAI_LIMIT_DEFAULT}, max ${YAOHAI_LIMIT_MAX})`,
                         },
-                        offset: { type: "number", description: "Pagination offset (default 0)" },
+                        offset: { type: "number", description: "Pagination offset (default 0); offset+limit is capped at 1000 rows per query condition" },
                     },
                     required: ["dbname"],
                 },
@@ -134,6 +137,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             {
                 name: "yaohai-global-search",
                 description: "Global drug panorama search (global_search). Pass q as the search term, or query.term. " +
+                    RETRIEVAL_CAP_HINT +
+                    " " +
                     PRESENTATION_HINT,
                 inputSchema: {
                     type: "object",
@@ -144,7 +149,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: "number",
                             description: `Row cap (default ${YAOHAI_LIMIT_DEFAULT}, max ${YAOHAI_LIMIT_MAX})`,
                         },
-                        offset: { type: "number", description: "Pagination offset (default 0)" },
+                        offset: { type: "number", description: "Pagination offset (default 0); offset+limit is capped at 1000 rows per query condition" },
                     },
                 },
             },
@@ -159,6 +164,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     "Default search_mode=3 (partial). first_approve_date = first listing date; approve_date = latest re-registration (not first listing). " +
                     ATC_HINT +
                     " Default limit 20, max 100. " +
+                    RETRIEVAL_CAP_HINT +
+                    " " +
                     "Not for R&D pipeline — use reg-cn-search. " +
                     PRESENTATION_HINT,
                 inputSchema: {
@@ -173,7 +180,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: "number",
                             description: `Row cap (default ${CN_LIMIT_DEFAULT}, max ${CN_LIMIT_MAX})`,
                         },
-                        offset: { type: "number", description: "Pagination offset (default 0)" },
+                        offset: { type: "number", description: "Pagination offset (default 0); offset+limit is capped at 1000 rows per query condition" },
                         view_type: {
                             type: "string",
                             enum: [...PRODUCT_CN_VIEW_TYPES],
@@ -221,7 +228,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 description: "Search China drug registration / CDE review (reg_cn): 在研, 受理号, 申报, 审评进度, not-yet-listed. " +
                     "Default rows_excluded=1 (drop 备案), search_mode=1. " +
                     ATC_HINT +
-                    " Default limit 20, max 100. Not for already-marketed products — use product-cn-search. " +
+                    " Default limit 20, max 100. " +
+                    RETRIEVAL_CAP_HINT +
+                    " " +
+                    "Not for already-marketed products — use product-cn-search. " +
                     PRESENTATION_HINT,
                 inputSchema: {
                     type: "object",
@@ -235,7 +245,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: "number",
                             description: `Row cap (default ${CN_LIMIT_DEFAULT}, max ${CN_LIMIT_MAX})`,
                         },
-                        offset: { type: "number", description: "Pagination offset (default 0)" },
+                        offset: { type: "number", description: "Pagination offset (default 0); offset+limit is capped at 1000 rows per query condition" },
                         view_type: {
                             type: "string",
                             enum: [...REG_CN_VIEW_TYPES],
@@ -319,11 +329,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case "yaohai-search": {
                 const validated = YaohaiSearchSchema.parse(args);
+                const window = enforceRetrievalWindow(clampLimit(validated.limit, YAOHAI_LIMIT_DEFAULT, YAOHAI_LIMIT_MAX), clampOffset(validated.offset));
                 const content = await yaohaiPost("/g/mcp/yaohai/search", {
                     dbname: validated.dbname,
                     query: asQuery(validated.query),
-                    limit: clampLimit(validated.limit, YAOHAI_LIMIT_DEFAULT, YAOHAI_LIMIT_MAX),
-                    offset: clampOffset(validated.offset),
+                    limit: window.limit,
+                    offset: window.offset,
                 });
                 return ok(content);
             }
@@ -406,10 +417,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (validated.q && (query.term === undefined || query.term === "")) {
                     query.term = validated.q;
                 }
+                const window = enforceRetrievalWindow(clampLimit(validated.limit, YAOHAI_LIMIT_DEFAULT, YAOHAI_LIMIT_MAX), clampOffset(validated.offset));
                 const content = await yaohaiPost("/g/mcp/yaohai/global-search", {
                     query,
-                    limit: clampLimit(validated.limit, YAOHAI_LIMIT_DEFAULT, YAOHAI_LIMIT_MAX),
-                    offset: clampOffset(validated.offset),
+                    limit: window.limit,
+                    offset: window.offset,
                 });
                 return ok(content);
             }
@@ -425,8 +437,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const validated = ProductCnSearchSchema.parse(args ?? {});
                 const viewType = validated.view_type ?? "eslist";
                 const query = applyProductCnDefaults(asQuery(validated.query));
-                const limit = clampLimit(validated.limit, CN_LIMIT_DEFAULT, CN_LIMIT_MAX);
-                const offset = clampOffset(validated.offset);
+                const window = enforceRetrievalWindow(clampLimit(validated.limit, CN_LIMIT_DEFAULT, CN_LIMIT_MAX), clampOffset(validated.offset));
+                const limit = window.limit;
+                const offset = window.offset;
                 const content = prefersMcpListApi()
                     ? await mcpDbSearch({
                         dbname: "product_cn",
@@ -475,8 +488,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const validated = RegCnSearchSchema.parse(args ?? {});
                 const viewType = validated.view_type ?? "eslist";
                 const query = applyRegCnDefaults(asQuery(validated.query));
-                const limit = clampLimit(validated.limit, CN_LIMIT_DEFAULT, CN_LIMIT_MAX);
-                const offset = clampOffset(validated.offset);
+                const window = enforceRetrievalWindow(clampLimit(validated.limit, CN_LIMIT_DEFAULT, CN_LIMIT_MAX), clampOffset(validated.offset));
+                const limit = window.limit;
+                const offset = window.offset;
                 const content = prefersMcpListApi()
                     ? await mcpDbSearch({
                         dbname: "reg_cn",

package/package.json

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