sciverse-mcp-server 0.10.0 → 0.11.0

package/dist/cli-http.d.ts

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

package/dist/cli-http.js

@@ -6,16 +6,21 @@
 //   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 使用。
+//   3. 鉴权双通道（Phase 1.5，http-auth.ts）：Authorization: Bearer 透传（channel
+//      "remote"）或来源 IP ∈ 可信 IP 白名单走内置 token（channel 沿用配置）；
+//      两者皆无 → 401。session 与首次判定的凭据绑定，后续请求不一致同样 401。
+//      XFF 仅在 TCP 对端命中信任代理网段时采信（默认永不），防直连伪造。
+//   4. /healthz 返回 200 纯文本，供 K8s readiness/liveness probe 使用（不鉴权、不记日志）。
 //   5. 配置错误 (loadConfig 抛 ConfigError) 时 stderr 输出并 exit(2)，
 //      与 cli.ts 行为一致。
+//   6. 每个 /mcp 请求向 stdout 写一行结构化日志（SLS 经 aliyun_logs_app_logs=stdout
+//      采集）；恒不落 token。
 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 { loadAuthOptions, resolveLane } from "./http-auth.js";
 import { createServer } from "./server.js";
 const DEFAULT_PORT = 8080;
 const MCP_PATH = "/mcp";
@@ -50,27 +55,62 @@ function writeJsonRpcError(res, status, message) {
         id: null,
     }));
 }
+// 从 JSON-RPC payload 提取方法名（batch 用 + 连接），仅用于日志。
+function rpcMethodOf(body) {
+    if (Array.isArray(body)) {
+        const names = body
+            .map((m) => (m && typeof m === "object" ? m.method : undefined))
+            .filter((s) => typeof s === "string");
+        return names.length > 0 ? names.join("+") : "batch";
+    }
+    if (body && typeof body === "object") {
+        const method = body.method;
+        if (typeof method === "string")
+            return method;
+    }
+    return "-";
+}
+function writeUnauthorized(res) {
+    res.setHeader("www-authenticate", "Bearer");
+    writeJsonRpcError(res, 401, "Unauthorized: provide `Authorization: Bearer <sciverse token>` (get one at https://sciverse.space)");
+}
 // 启动 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 auth = options.auth ?? loadAuthOptions();
+    // session id → transport + 首次判定的凭据（lane/token 绑定，防 session id 被盗用）。
     const sessions = new Map();
-    const handleMcp = async (req, res) => {
+    const handleMcp = async (req, res, meta) => {
         const method = req.method ?? "GET";
         const sessionId = req.headers["mcp-session-id"];
         const sessionIdStr = Array.isArray(sessionId) ? sessionId[0] : sessionId;
+        if (sessionIdStr)
+            meta.session = sessionIdStr.slice(0, 8);
+        // 鉴权判定先于一切处理；不通过的请求不进 MCP 协议层。
+        const decision = resolveLane(req, config, auth);
+        if (!decision) {
+            writeUnauthorized(res);
+            return;
+        }
+        meta.lane = decision.lane;
+        // 复用 session 时校验凭据与首次判定一致；不一致按未授权处理（不泄露 session 存在性）。
+        const boundEntry = sessionIdStr ? sessions.get(sessionIdStr) : undefined;
+        if (boundEntry && (boundEntry.lane !== decision.lane || boundEntry.token !== decision.token)) {
+            writeUnauthorized(res);
+            return;
+        }
         // POST：初始化 or 后续 JSON-RPC 调用
         if (method === "POST") {
             const raw = await readBody(req);
             const body = parseJsonBody(raw);
+            meta.rpc = rpcMethodOf(body);
             // 已有 session：复用 transport
-            if (sessionIdStr && sessions.has(sessionIdStr)) {
-                const entry = sessions.get(sessionIdStr);
-                await entry.transport.handleRequest(req, res, body);
+            if (boundEntry) {
+                await boundEntry.transport.handleRequest(req, res, body);
                 return;
             }
-            // 无 session + 是 initialize：新建 transport + Server
+            // 无 session + 是 initialize：新建 transport + Server（携带本 session 的凭据）
             if (!sessionIdStr && isInitializeRequest(body)) {
                 const transport = new StreamableHTTPServerTransport({
                     sessionIdGenerator: () => randomUUID(),
@@ -78,6 +118,8 @@ export async function startHttpServer(config, options = {}) {
                         // 在 initialize 完成时把 transport 注册进表；规避请求先于 sessionId 落表的竞态。
                         sessions.set(sid, {
                             transport,
+                            lane: decision.lane,
+                            token: decision.token,
                             close: async () => {
                                 await transport.close();
                                 await server.close();
@@ -91,7 +133,8 @@ export async function startHttpServer(config, options = {}) {
                         sessions.delete(sid);
                     }
                 };
-                const server = createServer(config);
+                // 每 session 一份 config：token/channel 来自通道判定，其余沿用进程配置。
+                const server = createServer({ ...config, token: decision.token, channel: decision.channel });
                 await server.connect(transport);
                 await transport.handleRequest(req, res, body);
                 return;
@@ -102,14 +145,13 @@ export async function startHttpServer(config, options = {}) {
         }
         // GET (SSE 长轮询) / DELETE (session 终止)：必须带 session id
         if (method === "GET" || method === "DELETE") {
-            if (!sessionIdStr || !sessions.has(sessionIdStr)) {
+            if (!boundEntry) {
                 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);
+            await boundEntry.transport.handleRequest(req, res);
             return;
         }
         res.statusCode = 405;
@@ -126,7 +168,15 @@ export async function startHttpServer(config, options = {}) {
             return;
         }
         if (url === MCP_PATH || url.startsWith(`${MCP_PATH}?`) || url.startsWith(`${MCP_PATH}/`)) {
-            handleMcp(req, res).catch((err) => {
+            const startedAt = Date.now();
+            const meta = { lane: "anon", rpc: "-", session: "-" };
+            // "close" 同时覆盖正常结束与客户端中断；一行 key=value 结构化日志（恒不含 token）。
+            res.once("close", () => {
+                process.stdout.write(`[sciverse-mcp] req method=${req.method ?? "-"} path=${MCP_PATH} rpc=${meta.rpc} ` +
+                    `lane=${meta.lane} session=${meta.session} status=${res.statusCode} ` +
+                    `dur_ms=${Date.now() - startedAt}\n`);
+            });
+            handleMcp(req, res, meta).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");
@@ -186,8 +236,14 @@ async function main() {
         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 auth = loadAuthOptions();
+    if (auth.trustedIps.size === 0) {
+        process.stderr.write("[sciverse-mcp] SCIVERSE_MCP_TRUSTED_IPS 未配置：可信 IP 通道关闭，所有请求都需要 Authorization\n");
+    }
+    const handle = await startHttpServer(config, { port, auth });
+    const proxyCount = auth.trustedProxies.v4.length + auth.trustedProxies.exact.size;
+    process.stderr.write(`[sciverse-mcp] listening on :${handle.port}${MCP_PATH} ` +
+        `(trusted_ips=${auth.trustedIps.size} trusted_proxies=${proxyCount} hops=${auth.trustedHops})\n`);
     // 收到信号时优雅退出
     const shutdown = async (signal) => {
         process.stderr.write(`[sciverse-mcp] received ${signal}, shutting down\n`);

package/dist/generated/tools.d.ts

@@ -1,4 +1,4 @@
-export declare const TOOLS_VERSION = "0.10.0";
+export declare const TOOLS_VERSION = "0.11.0";
 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.10.0";
+export const TOOLS_VERSION = "0.11.0";
 export const TOOLS = [
     {
         "name": "search_papers",

package/dist/http-auth.d.ts

@@ -0,0 +1,31 @@
+import type { IncomingMessage } from "node:http";
+import type { Config } from "./config.js";
+export type Lane = "trusted" | "direct";
+export interface LaneDecision {
+    lane: Lane;
+    token: string;
+    channel: string;
+}
+/** 信任代理集合：IPv4 支持 CIDR；其余条目（IPv6 等）精确匹配。 */
+export interface TrustedProxies {
+    v4: {
+        base: number;
+        bits: number;
+    }[];
+    exact: Set<string>;
+}
+export interface AuthOptions {
+    /** 可信来源 IP（精确匹配，已归一化）。空集 = trusted 通道关闭。 */
+    trustedIps: Set<string>;
+    /** 信任代理网段：TCP 对端命中才解析 XFF。空 = 转发头永不采信。 */
+    trustedProxies: TrustedProxies;
+    /** 解析 XFF 时取右起第几个条目（≥1）；需与代理真实跳数一致。 */
+    trustedHops: number;
+}
+/** 解析逗号/空白分隔的代理列表；IPv4 条目可带 /bits，非法 bits 的条目降级为精确匹配。 */
+export declare function parseTrustedProxies(raw: string | undefined): TrustedProxies;
+/** 取参与鉴权判定的来源 IP；null = 信任链不完整（调用方应 401，fail-closed）。 */
+export declare function clientIp(req: IncomingMessage, opts: AuthOptions): string | null;
+export declare function loadAuthOptions(env?: NodeJS.ProcessEnv): AuthOptions;
+/** 判定请求走哪条通道；null = 无法鉴权（调用方应返回 401）。 */
+export declare function resolveLane(req: IncomingMessage, config: Config, opts: AuthOptions): LaneDecision | null;

package/dist/http-auth.js

@@ -0,0 +1,97 @@
+const DIRECT_CHANNEL = "remote";
+const DEFAULT_TRUSTED_HOPS = 1;
+/** 统一小写；去掉 IPv4-mapped IPv6 前缀与 /32 后缀。 */
+function normalizeIp(raw) {
+    let ip = raw.trim().toLowerCase();
+    if (ip.startsWith("::ffff:"))
+        ip = ip.slice("::ffff:".length);
+    if (ip.endsWith("/32"))
+        ip = ip.slice(0, -"/32".length);
+    return ip;
+}
+function ipv4ToInt(ip) {
+    const parts = ip.split(".");
+    if (parts.length !== 4)
+        return null;
+    let v = 0;
+    for (const p of parts) {
+        if (!/^\d{1,3}$/.test(p))
+            return null;
+        const n = Number(p);
+        if (n > 255)
+            return null;
+        v = ((v << 8) | n) >>> 0;
+    }
+    return v;
+}
+/** 解析逗号/空白分隔的代理列表；IPv4 条目可带 /bits，非法 bits 的条目降级为精确匹配。 */
+export function parseTrustedProxies(raw) {
+    const out = { v4: [], exact: new Set() };
+    for (const entry of (raw ?? "").split(/[\s,]+/)) {
+        if (!entry.trim())
+            continue;
+        const [ipPart, bitsPart] = entry.trim().toLowerCase().split("/");
+        const ip = normalizeIp(ipPart);
+        const asV4 = ipv4ToInt(ip);
+        if (asV4 !== null) {
+            const bits = bitsPart === undefined ? 32 : Number.parseInt(bitsPart, 10);
+            if (Number.isFinite(bits) && bits >= 0 && bits <= 32) {
+                out.v4.push({ base: asV4, bits });
+                continue;
+            }
+        }
+        out.exact.add(ip);
+    }
+    return out;
+}
+function isTrustedProxy(ip, proxies) {
+    if (proxies.exact.has(ip))
+        return true;
+    const v4 = ipv4ToInt(ip);
+    if (v4 === null)
+        return false;
+    // bits=0（0.0.0.0/0）需特判：JS 位移量按 mod 32 取，>>> 32 等价 >>> 0。
+    return proxies.v4.some(({ base, bits }) => (bits === 0 ? true : ((v4 ^ base) >>> (32 - bits)) === 0));
+}
+/** 取参与鉴权判定的来源 IP；null = 信任链不完整（调用方应 401，fail-closed）。 */
+export function clientIp(req, opts) {
+    const peer = req.socket.remoteAddress ? normalizeIp(req.socket.remoteAddress) : null;
+    if (!peer)
+        return null;
+    // 对端不是信任代理：XFF 一律不采信，直接用 socket 地址。
+    if (!isTrustedProxy(peer, opts.trustedProxies))
+        return peer;
+    const hops = Math.max(1, Math.floor(opts.trustedHops));
+    const header = req.headers["x-forwarded-for"];
+    const joined = Array.isArray(header) ? header.join(",") : (header ?? "");
+    const entries = joined
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (entries.length < hops)
+        return null;
+    return normalizeIp(entries[entries.length - hops]);
+}
+export function loadAuthOptions(env = process.env) {
+    const trustedIps = new Set((env.SCIVERSE_MCP_TRUSTED_IPS ?? "")
+        .split(/[\s,]+/)
+        .map(normalizeIp)
+        .filter((s) => s.length > 0));
+    const trustedProxies = parseTrustedProxies(env.SCIVERSE_MCP_TRUSTED_PROXIES);
+    const hopsRaw = env.SCIVERSE_MCP_TRUSTED_PROXY_HOPS?.trim();
+    const parsed = hopsRaw ? Number.parseInt(hopsRaw, 10) : DEFAULT_TRUSTED_HOPS;
+    const trustedHops = Number.isFinite(parsed) && parsed >= 1 ? parsed : DEFAULT_TRUSTED_HOPS;
+    return { trustedIps, trustedProxies, trustedHops };
+}
+/** 判定请求走哪条通道；null = 无法鉴权（调用方应返回 401）。 */
+export function resolveLane(req, config, opts) {
+    const m = req.headers.authorization?.match(/^Bearer\s+(.+)$/i);
+    if (m) {
+        return { lane: "direct", token: m[1].trim(), channel: DIRECT_CHANNEL };
+    }
+    const ip = clientIp(req, opts);
+    if (ip && opts.trustedIps.has(ip)) {
+        return { lane: "trusted", token: config.token, channel: config.channel };
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sciverse-mcp-server",
-  "version": "0.10.0",
+  "version": "0.11.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",