sciverse-mcp-server 0.13.1 → 0.14.1

package/README.md

@@ -217,7 +217,7 @@ Token / endpoint 解析顺序：MCP 配置里显式 `env` → `SCIVERSE_API_TOKE
 |---|---|
 | `search_papers` | 结构化元数据检索（作者 / 年份 / 期刊 / 学科） |
 | `semantic_search` | 自然语言语义检索（RAG 用） |
-| `read_content` | 按字节区间读文献原文 |
+| `read_content` | 按 Unicode 码点区间读文献原文 |
 | `list_catalog` | 字段 introspection（返回所有字段名 + 枚举值样本，agent 接入时建议先调一次学 schema） |
 | `get_resource` | 取文献附属图片字节流；MCP server 包装为 `image` content block + base64 + mimeType，多模态模型（如 Claude）可直接读图 |
 

package/dist/generated/tools.d.ts

@@ -1,4 +1,4 @@
-export declare const TOOLS_VERSION = "0.13.1";
+export declare const TOOLS_VERSION = "0.14.1";
 export interface ToolDef {
     name: string;
     description: string;

package/dist/generated/tools.js

@@ -1,6 +1,6 @@
 // Auto-generated by scripts/gen-tools.mjs. Do not edit.
 // Source of truth: openapi.yaml
-export const TOOLS_VERSION = "0.13.1";
+export const TOOLS_VERSION = "0.14.1";
 export const TOOLS = [
     {
         "name": "search_papers",
@@ -122,11 +122,13 @@ export const TOOLS = [
                 "sort_by_year": {
                     "type": "string",
                     "enum": [
+                        "auto",
                         "desc",
                         "asc",
                         "none"
                     ],
-                    "default": "desc"
+                    "default": "auto",
+                    "description": "按发表年份排序。默认 auto：传了 query（或 sort_advanced）时不加年份排序\n——保留 BM25 相关性排序，且 freshness/impact/language_affinity 软加权可用；\n纯结构化筛选（无 query）时按年份降序（否则后端默认序是 unique_id，实质乱序）。\n⚠️ 不要用 query + desc 求「最相关且最新」：显式排序会让 query 退化为命中\n过滤（OR 语义、无相关性排序）、三个软加权全部失效——返回的是「含任一关键词\n的最新文档」。要「相关且偏新」请用 freshness_boost。\n"
                 },
                 "freshness_boost": {
                     "type": "string",
@@ -165,9 +167,10 @@ export const TOOLS = [
                 },
                 "page_size": {
                     "type": "integer",
-                    "default": 10,
+                    "default": 25,
                     "minimum": 1,
-                    "maximum": 50
+                    "maximum": 50,
+                    "description": "每页条数。省略时为服务端默认 25（SDK / MCP 不注入默认值）；工具层上限 50。"
                 }
             }
         }
@@ -328,7 +331,7 @@ export const TOOLS = [
     },
     {
         "name": "read_content",
-        "description": "Read a UTF-8 byte range of a paper's original text. Typically used with\na doc_id/offset returned by semantic_search to expand context (read\nmore bytes before or after a chunk).\nReturns: text fragment, bytes_returned, next_offset, more (boolean).",
+        "description": "Read a range of a paper's original text addressed in Unicode code\npoints (offset/limit count characters like Python len(), not bytes).\nTypically used with a doc_id/offset returned by semantic_search to\nexpand context (read more text before or after a chunk).\nReturns: text fragment, bytes_returned (UTF-8 byte length of text, for\nreference only), next_offset (code-point offset of the next fragment —\npage with it, never with bytes_returned), more (boolean).\nServer behaviour: limit above 524288 is silently clamped; omitting\noffset returns the whole document ignoring limit — the SDKs / MCP\nserver send offset=0 and limit=4096 by default, so pass offset\nexplicitly when calling the HTTP API directly.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -339,13 +342,17 @@ export const TOOLS = [
                 "offset": {
                     "type": "integer",
                     "format": "int64",
-                    "default": 0
+                    "default": 0,
+                    "minimum": 0,
+                    "description": "起始 Unicode 码点偏移，直接使用 semantic_search 返回的 offset。默认 0。"
                 },
                 "limit": {
                     "type": "integer",
                     "format": "int64",
                     "default": 4096,
-                    "maximum": 16384
+                    "minimum": 1,
+                    "maximum": 524288,
+                    "description": "最多返回的 Unicode 码点数。默认 4096；服务端上限 524288（超出静默钳制）。LLM 场景建议 ≤ 16384，避免撑爆上下文。"
                 }
             },
             "required": [

package/dist/tools.js

@@ -39,8 +39,14 @@ function toBackendPayload(args) {
             filters.push({ operator: "FILTER_OP_EQ", ...item });
         }
     }
-    const sortByYear = args.sort_by_year;
-    if (sortByYear && sortByYear !== "none") {
+    // sort_by_year 默认 auto：有 query（或 sort_advanced）时不加年份排序——保 BM25
+    // 相关性且软加权可用；纯结构化筛选时按年份降序（后端默认序实质乱序）。
+    let sortByYear = args.sort_by_year ?? "auto";
+    if (sortByYear === "auto") {
+        sortByYear = args.query || (Array.isArray(args.sort_advanced) && args.sort_advanced.length > 0)
+            ? "none" : "desc";
+    }
+    if (sortByYear !== "none") {
         sort.push({
             field: "publication_published_year",
             order: sortByYear === "desc" ? "SORT_ORDER_DESC" : "SORT_ORDER_ASC",
@@ -203,7 +209,10 @@ export async function executeTool(config, name, args) {
                     content: [{ type: "text", text: JSON.stringify({ error: "doc_id is required" }) }],
                 };
             }
-            return call(config, "GET", endpoint.path, { query: { doc_id, offset, limit } });
+            // 后端未传 offset 时返回整篇全文并忽略 limit；这里始终显式传两者，避免把整篇论文灌进模型上下文。
+            return call(config, "GET", endpoint.path, {
+                query: { doc_id, offset: offset ?? 0, limit: limit ?? 4096 },
+            });
         }
         case "get_resource": {
             const { file_name } = args;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sciverse-mcp-server",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "description": "Sciverse MCP server — exposes academic paper retrieval (search_papers / semantic_search / read_content) to MCP-compatible coding agents (Claude Code, Cursor, Codex CLI, Windsurf, ...).",
   "license": "Apache-2.0",
   "homepage": "https://github.com/opendatalab/Sciverse-Agent-Tools/tree/main/packages/mcp",