sciverse-mcp-server 0.5.3 → 0.7.0

package/dist/cli-http.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { type Config } from "./config.js";
+export interface HttpServerHandle {
+    port: number;
+    close: () => Promise<void>;
+}
+export declare function startHttpServer(config: Config, options?: {
+    port?: number;
+    host?: string;
+}): Promise<HttpServerHandle>;

package/dist/cli-http.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// 入口：以 Streamable-HTTP 形态启动 MCP server，供 SCP Hub 等公网调用方使用。
+//
+// 设计要点：
+//   1. 与 stdio 入口 (cli.ts) 共享 createServer(config)，业务逻辑零改动；transport 解耦。
+//   2. 每个 MCP session 独立一份 Server + Transport，避免不同会话间状态串扰；
+//      session id 由 SDK 在 initialize 阶段通过 crypto.randomUUID() 分配，
+//      存到内存 Map，容器重启即清空。Phase 1 单副本部署可接受。
+//   3. 边缘信任模型：本进程不校验 SCP-HUB-API-KEY，由 Ingress IP 白名单兜底；
+//      Phase 1.5 再补 header 校验。
+//   4. /healthz 返回 200 纯文本，供 K8s readiness/liveness probe 使用。
+//   5. 配置错误 (loadConfig 抛 ConfigError) 时 stderr 输出并 exit(2)，
+//      与 cli.ts 行为一致。
+import { randomUUID } from "node:crypto";
+import { createServer as createHttpServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { ConfigError, loadConfig } from "./config.js";
+import { createServer } from "./server.js";
+const DEFAULT_PORT = 8080;
+const MCP_PATH = "/mcp";
+const HEALTHZ_PATH = "/healthz";
+// 读完整请求体到 Buffer；遇到客户端断开等错误会 reject。
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+// 把 raw body 解析为 JSON（POST /mcp 必为 JSON-RPC payload）；空 body 返回 undefined。
+function parseJsonBody(buf) {
+    if (buf.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(buf.toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+// 用 405 + JSON-RPC error 拒绝非 POST /mcp 之外的请求里 transport 不接受的方法。
+function writeJsonRpcError(res, status, message) {
+    res.statusCode = status;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({
+        jsonrpc: "2.0",
+        error: { code: -32000, message },
+        id: null,
+    }));
+}
+// 启动 HTTP server，返回句柄。导出供测试复用，避免 spawn 子进程。
+export async function startHttpServer(config, options = {}) {
+    const port = options.port ?? DEFAULT_PORT;
+    const host = options.host ?? "0.0.0.0";
+    // session id → { transport, server } 映射。Phase 1 进程内 Map 即可。
+    const sessions = new Map();
+    const handleMcp = async (req, res) => {
+        const method = req.method ?? "GET";
+        const sessionId = req.headers["mcp-session-id"];
+        const sessionIdStr = Array.isArray(sessionId) ? sessionId[0] : sessionId;
+        // POST：初始化 or 后续 JSON-RPC 调用
+        if (method === "POST") {
+            const raw = await readBody(req);
+            const body = parseJsonBody(raw);
+            // 已有 session：复用 transport
+            if (sessionIdStr && sessions.has(sessionIdStr)) {
+                const entry = sessions.get(sessionIdStr);
+                await entry.transport.handleRequest(req, res, body);
+                return;
+            }
+            // 无 session + 是 initialize：新建 transport + Server
+            if (!sessionIdStr && isInitializeRequest(body)) {
+                const transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    onsessioninitialized: (sid) => {
+                        // 在 initialize 完成时把 transport 注册进表；规避请求先于 sessionId 落表的竞态。
+                        sessions.set(sid, {
+                            transport,
+                            close: async () => {
+                                await transport.close();
+                                await server.close();
+                            },
+                        });
+                    },
+                });
+                transport.onclose = () => {
+                    const sid = transport.sessionId;
+                    if (sid && sessions.has(sid)) {
+                        sessions.delete(sid);
+                    }
+                };
+                const server = createServer(config);
+                await server.connect(transport);
+                await transport.handleRequest(req, res, body);
+                return;
+            }
+            // 既无 session 又不是 initialize：按 SDK 规范返 400
+            writeJsonRpcError(res, 400, "Bad Request: No valid session ID provided");
+            return;
+        }
+        // GET (SSE 长轮询) / DELETE (session 终止)：必须带 session id
+        if (method === "GET" || method === "DELETE") {
+            if (!sessionIdStr || !sessions.has(sessionIdStr)) {
+                res.statusCode = 400;
+                res.setHeader("content-type", "text/plain");
+                res.end("Invalid or missing session ID");
+                return;
+            }
+            const entry = sessions.get(sessionIdStr);
+            await entry.transport.handleRequest(req, res);
+            return;
+        }
+        res.statusCode = 405;
+        res.setHeader("allow", "POST, GET, DELETE");
+        res.end();
+    };
+    const httpServer = createHttpServer((req, res) => {
+        const url = req.url ?? "/";
+        // K8s probe
+        if (url === HEALTHZ_PATH || url.startsWith(`${HEALTHZ_PATH}?`)) {
+            res.statusCode = 200;
+            res.setHeader("content-type", "text/plain; charset=utf-8");
+            res.end("ok");
+            return;
+        }
+        if (url === MCP_PATH || url.startsWith(`${MCP_PATH}?`) || url.startsWith(`${MCP_PATH}/`)) {
+            handleMcp(req, res).catch((err) => {
+                process.stderr.write(`[sciverse-mcp] handleRequest error: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+                if (!res.headersSent) {
+                    writeJsonRpcError(res, 500, "Internal server error");
+                }
+                else {
+                    res.end();
+                }
+            });
+            return;
+        }
+        res.statusCode = 404;
+        res.setHeader("content-type", "text/plain");
+        res.end("Not Found");
+    });
+    await new Promise((resolve, reject) => {
+        httpServer.once("error", reject);
+        httpServer.listen(port, host, () => {
+            httpServer.off("error", reject);
+            resolve();
+        });
+    });
+    const address = httpServer.address();
+    const actualPort = typeof address === "object" && address ? address.port : port;
+    return {
+        port: actualPort,
+        close: async () => {
+            // 先关 HTTP server（停止接受新连接），再清理所有活动 session。
+            await new Promise((resolve, reject) => {
+                httpServer.close((err) => (err ? reject(err) : resolve()));
+            });
+            const entries = Array.from(sessions.values());
+            sessions.clear();
+            await Promise.all(entries.map((e) => e.close().catch(() => undefined)));
+        },
+    };
+}
+async function main() {
+    // HTTP 入口默认 channel = "scp"（区分 stdio 入口的 "mcp"），用于下游 X-Sciverse-Source 归因。
+    // 显式设了 SCIVERSE_MCP_CHANNEL 则不覆盖（允许部署侧自定义）。
+    if (!process.env.SCIVERSE_MCP_CHANNEL?.trim()) {
+        process.env.SCIVERSE_MCP_CHANNEL = "scp";
+    }
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (err) {
+        if (err instanceof ConfigError) {
+            process.stderr.write(`[sciverse-mcp] ${err.message}\n`);
+            process.exit(2);
+        }
+        throw err;
+    }
+    const portEnv = process.env.PORT;
+    const port = portEnv ? Number.parseInt(portEnv, 10) : DEFAULT_PORT;
+    if (!Number.isFinite(port) || port < 0 || port > 65535) {
+        process.stderr.write(`[sciverse-mcp] invalid PORT: ${portEnv}\n`);
+        process.exit(2);
+    }
+    const handle = await startHttpServer(config, { port });
+    process.stderr.write(`[sciverse-mcp] listening on :${handle.port}${MCP_PATH}\n`);
+    // 收到信号时优雅退出
+    const shutdown = async (signal) => {
+        process.stderr.write(`[sciverse-mcp] received ${signal}, shutting down\n`);
+        try {
+            await handle.close();
+        }
+        finally {
+            process.exit(0);
+        }
+    };
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+}
+// 只有作为入口执行时才 main()；被 import（如测试）时不自动起进程。
+const isEntrypoint = typeof process.argv[1] === "string" &&
+    import.meta.url === new URL(`file://${process.argv[1]}`).href;
+if (isEntrypoint) {
+    main().catch((err) => {
+        process.stderr.write(`[sciverse-mcp] fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}

package/dist/config.d.ts

@@ -1,6 +1,12 @@
 export interface Config {
     token: string;
     baseUrl: string;
+    /**
+     * 调用方标识，拼入下游 X-Sciverse-Source 头部（`{platform}-{channel}`），
+     * 用于 SLS 日志归因；X-Request-Id 仅承载 uuid。默认 "mcp"（stdio 入口）；
+     * cli-http.ts 启动时覆盖为 "scp"，也可由环境变量 SCIVERSE_MCP_CHANNEL 显式指定。
+     */
+    channel: string;
 }
 export declare class ConfigError extends Error {
     constructor(message: string);

package/dist/config.js

@@ -8,6 +8,7 @@ export class ConfigError extends Error {
         this.name = "ConfigError";
     }
 }
+const DEFAULT_CHANNEL = "mcp";
 export function loadConfig(env = process.env) {
     const token = resolveToken(undefined, env);
     if (!token) {
@@ -26,5 +27,6 @@ export function loadConfig(env = process.env) {
     if (host !== "sciverse.space" && !host.endsWith(".sciverse.space")) {
         throw new ConfigError(`SCIVERSE_BASE_URL must point to a *.sciverse.space domain (got: ${host}). This guards against accidental token leakage.`);
     }
-    return { token, baseUrl };
+    const channel = env.SCIVERSE_MCP_CHANNEL?.trim() || DEFAULT_CHANNEL;
+    return { token, baseUrl, channel };
 }

package/dist/generated/tools.d.ts

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

package/dist/generated/tools.js

@@ -1,10 +1,10 @@
 // Auto-generated by scripts/gen-tools.mjs. Do not edit.
 // Source of truth: openapi.yaml
-export const TOOLS_VERSION = "0.5.3";
+export const TOOLS_VERSION = "0.7.0";
 export const TOOLS = [
     {
         "name": "search_papers",
-        "description": "Search academic papers by structured filters (title, authors, journal,\nyear, subjects, etc.).\nUse when: \"find Hinton's papers from 2020-2023\", \"Nature papers on\nCRISPR\".\nNot for: natural-language Q&A retrieval (use semantic_search) or\nfull-text snippets (use read_content).\nReturns: list of papers; each entry has doc_id, title, author, abstract,\npublication_venue_name, publication_published_year.",
+        "description": "Search academic papers by structured filters (title, authors, journal,\nyear, subjects, etc.).\nUse when: \"find Hinton's papers from 2020-2023\", \"Nature papers on\nCRISPR\".\nNot for: natural-language Q&A retrieval (use semantic_search) or\nfull-text snippets (use read_content).\nReturns: list of papers; each entry has unique_id (always present),\ndoc_id (only when full text exists), title, author, abstract,\npublication_venue_name_unified, publication_published_year.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -40,7 +40,7 @@ export const TOOLS = [
                     "items": {
                         "type": "string"
                     },
-                    "description": "期刊名（任一命中即可）。SDK 内部映射到后端 `publication_venue_name` 字段（FILTER_OP_IN）。"
+                    "description": "期刊名（任一命中即可）。SDK 内部映射到后端 `publication_venue_name_unified` 字段（FILTER_OP_IN，规范化后的载体名）。"
                 },
                 "subjects": {
                     "type": "array",
@@ -90,6 +90,16 @@ export const TOOLS = [
                     ],
                     "default": "desc"
                 },
+                "freshness_boost": {
+                    "type": "string",
+                    "enum": [
+                        "NONE",
+                        "MILD",
+                        "STRONG"
+                    ],
+                    "default": "NONE",
+                    "description": "模糊搜索新鲜度加权（仅 query 非空时生效；与 sort_by_year 互斥）。\nMILD: 近 10 年加权，适合日常查文献；STRONG: 近 3 年加权，适合跟踪\n研究方向 / 追最新进展。底层为 function_score + gauss decay over\npublication_published_date。\n"
+                },
                 "page": {
                     "type": "integer",
                     "default": 1,

package/dist/tools.js

@@ -29,7 +29,7 @@ function toBackendPayload(args) {
     if (args.year_to != null)
         addFilter("publication_published_year", "FILTER_OP_LTE", args.year_to);
     if (Array.isArray(args.journals) && args.journals.length > 0) {
-        addFilter("publication_venue_name", "FILTER_OP_IN", args.journals);
+        addFilter("publication_venue_name_unified", "FILTER_OP_IN", args.journals);
     }
     if (Array.isArray(args.subjects) && args.subjects.length > 0) {
         addFilter("subjects", "FILTER_OP_IN", args.subjects);
@@ -52,8 +52,6 @@ function toBackendPayload(args) {
         out.sort = sort;
     return out;
 }
-const SKILL_NAME = "sciverse";
-const CHANNEL = "mcp";
 const PLATFORM = process.platform;
 async function call(config, method, path, options = {}) {
     const url = new URL(`${config.baseUrl}${path}`);
@@ -68,7 +66,8 @@ async function call(config, method, path, options = {}) {
         headers: {
             authorization: `Bearer ${config.token}`,
             "content-type": "application/json",
-            "x-request-id": `${SKILL_NAME}-${PLATFORM}-${CHANNEL}-${randomUUID()}`,
+            "x-request-id": randomUUID(),
+            "x-sciverse-source": `${PLATFORM}-${config.channel}`,
         },
     };
     if (options.body !== undefined) {
@@ -111,7 +110,8 @@ async function callBinary(config, path, query) {
         headers: {
             authorization: `Bearer ${config.token}`,
             accept: "image/*",
-            "x-request-id": `${SKILL_NAME}-${PLATFORM}-${CHANNEL}-${randomUUID()}`,
+            "x-request-id": randomUUID(),
+            "x-sciverse-source": `${PLATFORM}-${config.channel}`,
         },
     });
     if (!res.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sciverse-mcp-server",
-  "version": "0.5.3",
+  "version": "0.7.0",
   "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",
@@ -17,7 +17,8 @@
   "main": "./dist/server.js",
   "types": "./dist/server.d.ts",
   "bin": {
-    "sciverse-mcp": "./dist/cli.js"
+    "sciverse-mcp": "./dist/cli.js",
+    "sciverse-mcp-http": "./dist/cli-http.js"
   },
   "files": [
     "dist",