sciverse-mcp-server 0.3.0

package/README.md

@@ -0,0 +1,262 @@
+# sciverse-mcp-server
+
+[![npm](https://img.shields.io/npm/v/sciverse-mcp-server.svg)](https://www.npmjs.com/package/sciverse-mcp-server)
+
+[English](#english) | [中文](#中文)
+
+Official MCP (Model Context Protocol) server for the SciVerse open platform.
+Exposes five academic-paper retrieval tools to any MCP-compatible coding agent
+— Claude Code, Cursor, Codex CLI, Windsurf, Continue, and more.
+
+> Tools: `search_papers` / `semantic_search` / `read_content` / `list_catalog` / `get_resource`
+>
+> 工具：`search_papers`（结构化元数据）/ `semantic_search`（语义检索）/ `read_content`（原文切片）/ `list_catalog`（字段 introspection）/ `get_resource`（论文图片二进制）
+
+---
+
+## English
+
+### Quick start
+
+```bash
+export SCIVERSE_API_TOKEN=sv-xxx   # get one from https://sciverse.space
+npx -y sciverse-mcp-server         # stdio mode; coding agents will spawn this for you
+```
+
+Or skip the env var entirely by running the Python CLI once:
+
+```bash
+pip install sciverse && sciverse auth login
+# saves token to ~/.sciverse/credentials.json (file mode 0600)
+# the MCP server will pick it up automatically next time it starts
+```
+
+### Connect from coding agents
+
+#### Claude Code
+
+Project-level `.mcp.json` (or run `claude mcp add sciverse npx -- -y sciverse-mcp-server`):
+
+```json
+{
+  "mcpServers": {
+    "sciverse": {
+      "command": "npx",
+      "args": ["-y", "sciverse-mcp-server"],
+      "env": { "SCIVERSE_API_TOKEN": "sv-xxx" }
+    }
+  }
+}
+```
+
+If you ran `sciverse auth login`, the `env` block can be omitted entirely.
+
+#### Cursor
+
+`.cursor/mcp.json` (or Settings → MCP Servers), same shape as above.
+
+#### Codex CLI
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.sciverse]
+command = "npx"
+args = ["-y", "sciverse-mcp-server"]
+env = { SCIVERSE_API_TOKEN = "sv-xxx" }
+```
+
+#### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json`, same JSON shape as Claude Code.
+
+See [`docs/integrations/`](https://github.com/opendatalab/SciVerse-agent-tools/tree/main/docs/integrations)
+for full per-agent guides.
+
+### Configuration
+
+Token / endpoint resolution order: explicit `env` in MCP config →
+`SCIVERSE_API_TOKEN` / `SCIVERSE_BASE_URL` environment → `~/.sciverse/credentials.json` →
+default (`https://api.sciverse.space`).
+
+| Var | Required | Default | Notes |
+|---|---|---|---|
+| `SCIVERSE_API_TOKEN` | ✓ (or via login) | — | Bearer token |
+| `SCIVERSE_BASE_URL` | | `https://api.sciverse.space` | Must be a `*.sciverse.space` domain (anti-leak guard) |
+
+### Exposed tools
+
+| Tool | Purpose |
+|---|---|
+| `search_papers` | Structured metadata search (authors / year / journal / subjects) |
+| `semantic_search` | Natural-language semantic chunk retrieval (RAG) |
+| `read_content` | Byte-range read of original paper text |
+| `list_catalog` | Field introspection (returns all field names + enum sample values, agents should call this first to learn the schema) |
+| `get_resource` | Fetch a paper figure / table image; the server wraps the bytes as an MCP `image` content block (base64 + mimeType) so multimodal models (e.g. Claude) can read the figure inline |
+
+Tool descriptions + input schemas are derived from `openapi.yaml` at build time
+(`npm run gen`), kept in sync with the SDK / ClawHub skill / OpenAI / Anthropic
+tool exports.
+
+### Hello-world prompt
+
+After wiring up the MCP server, try:
+
+```
+帮我找 3 篇关于 Transformer 注意力机制的论文，附原文片段引用。
+Find 3 papers on Transformer attention mechanism with quoted excerpts.
+```
+
+Or let the agent learn the schema first:
+
+```
+List the SciVerse fields and the values access_oa_status can take, then find
+2024+ gold-OA Nature papers.
+```
+
+### Development
+
+```bash
+npm install
+npm run gen       # derive src/generated/tools.ts from ../../openapi.yaml
+npm run build     # tsc → dist/
+npm test          # vitest (27 tests)
+```
+
+If `npm install` is slow / blocked, switch registry:
+
+```bash
+npm install --registry https://registry.npmmirror.com
+```
+
+### Links
+
+- Source repo: <https://github.com/opendatalab/SciVerse-agent-tools>
+- Python SDK + CLI: <https://pypi.org/project/sciverse>
+- TypeScript SDK: <https://www.npmjs.com/package/sciverse>
+- License: Apache-2.0
+
+---
+
+## 中文
+
+SciVerse 开放平台官方 MCP (Model Context Protocol) server。把 5 个学术文献检索
+工具暴露给任何 MCP 兼容的 coding agent —— Claude Code、Cursor、Codex CLI、
+Windsurf、Continue 等。
+
+### 快速开始
+
+```bash
+export SCIVERSE_API_TOKEN=sv-xxx   # 从 https://sciverse.space 控制台申请
+npx -y sciverse-mcp-server         # stdio 启动；coding agent 通常会代你 spawn
+```
+
+也可以跑一次 Python CLI 把 token 持久化，之后 env 都不用配：
+
+```bash
+pip install sciverse && sciverse auth login
+# 保存到 ~/.sciverse/credentials.json（文件权限 0600）
+# MCP server 启动时自动 fallback 读取
+```
+
+### 在 coding agent 里接入
+
+#### Claude Code
+
+项目级 `.mcp.json`（也可以用 `claude mcp add sciverse npx -- -y sciverse-mcp-server`）：
+
+```json
+{
+  "mcpServers": {
+    "sciverse": {
+      "command": "npx",
+      "args": ["-y", "sciverse-mcp-server"],
+      "env": { "SCIVERSE_API_TOKEN": "sv-xxx" }
+    }
+  }
+}
+```
+
+跑过 `sciverse auth login` 后 `env` 整段可省略。
+
+#### Cursor
+
+`.cursor/mcp.json` 或 Settings → MCP Servers，格式同上。
+
+#### Codex CLI
+
+`~/.codex/config.toml`：
+
+```toml
+[mcp_servers.sciverse]
+command = "npx"
+args = ["-y", "sciverse-mcp-server"]
+env = { SCIVERSE_API_TOKEN = "sv-xxx" }
+```
+
+#### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json`，JSON 格式同 Claude Code。
+
+完整接入指南见 [`docs/integrations/`](https://github.com/opendatalab/SciVerse-agent-tools/tree/main/docs/integrations)。
+
+### 配置
+
+Token / endpoint 解析顺序：MCP 配置里显式 `env` → `SCIVERSE_API_TOKEN` /
+`SCIVERSE_BASE_URL` 环境变量 → `~/.sciverse/credentials.json` →
+默认值（`https://api.sciverse.space`）。
+
+| 变量 | 必填 | 默认 | 说明 |
+|---|---|---|---|
+| `SCIVERSE_API_TOKEN` | ✓（或通过 login） | — | Bearer Token |
+| `SCIVERSE_BASE_URL` | | `https://api.sciverse.space` | 必须是 `*.sciverse.space` 子域名（防 token 泄漏） |
+
+### 暴露的 tool
+
+| 名称 | 用途 |
+|---|---|
+| `search_papers` | 结构化元数据检索（作者 / 年份 / 期刊 / 学科） |
+| `semantic_search` | 自然语言语义检索（RAG 用） |
+| `read_content` | 按字节区间读文献原文 |
+| `list_catalog` | 字段 introspection（返回所有字段名 + 枚举值样本，agent 接入时建议先调一次学 schema） |
+| `get_resource` | 取文献附属图片字节流；MCP server 包装为 `image` content block + base64 + mimeType，多模态模型（如 Claude）可直接读图 |
+
+Tool 描述和 input schema 均从 `openapi.yaml` 派生（构建期 `npm run gen`），与
+Python/TS SDK、ClawHub skill、OpenAI / Anthropic tool 保持一致。
+
+### Hello-world prompt
+
+接入完成后试：
+
+```
+帮我找 3 篇关于 Transformer 注意力机制的论文，附原文片段引用。
+```
+
+或让 agent 先学 schema 再发查询：
+
+```
+列出 SciVerse 有哪些字段、access_oa_status 取值，然后找 2024 年以来 gold OA
+状态的 Nature 期刊论文。
+```
+
+### 开发
+
+```bash
+npm install
+npm run gen       # 从 ../../openapi.yaml 派生 src/generated/tools.ts
+npm run build     # tsc → dist/
+npm test          # vitest（27 测试）
+```
+
+如 `npm install` 因网络源问题失败，换源：
+
+```bash
+npm install --registry https://registry.npmmirror.com
+```
+
+### 链接
+
+- 源码仓库：<https://github.com/opendatalab/SciVerse-agent-tools>
+- Python SDK + CLI：<https://pypi.org/project/sciverse>
+- TypeScript SDK：<https://www.npmjs.com/package/sciverse>
+- 协议：Apache-2.0

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// 入口：从 stdio 启动 MCP server。
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ConfigError, loadConfig } from "./config.js";
+import { createServer } from "./server.js";
+async function main() {
+    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 server = createServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // 进程长驻；stdio 关闭时 transport 会触发退出。
+}
+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

@@ -0,0 +1,8 @@
+export interface Config {
+    token: string;
+    baseUrl: string;
+}
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;

package/dist/config.js

@@ -0,0 +1,30 @@
+// Token / endpoint 解析顺序：env → ~/.sciverse/credentials.json → 默认值。
+// BASE_URL 仅允许 *.sciverse.space 与 sciverse.space，防止 token 被泄漏到
+// 任意域名（与 ClawHub skill 的 _common.mjs 一致）。
+import { resolveEndpoint, resolveToken } from "./credentials.js";
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+export function loadConfig(env = process.env) {
+    const token = resolveToken(undefined, env);
+    if (!token) {
+        throw new ConfigError("未找到 SciVerse API Token。请设 SCIVERSE_API_TOKEN 环境变量，或运行 " +
+            "`pip install sciverse && sciverse auth login` 保存凭据到 ~/.sciverse/credentials.json。");
+    }
+    const baseUrl = resolveEndpoint(undefined, env).replace(/\/$/, "");
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new ConfigError(`SCIVERSE_BASE_URL is not a valid URL: ${baseUrl}`);
+    }
+    const host = parsed.hostname;
+    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 };
+}

package/dist/credentials.d.ts

@@ -0,0 +1,13 @@
+export interface StoredCredentials {
+    token?: string;
+    endpoint?: string;
+    saved_at?: string;
+}
+export declare const DEFAULT_ENDPOINT = "https://api.sciverse.space";
+export declare function credentialsPath(): string;
+/** 读凭据文件。文件不存在 / 解析失败 / 不是 object 时返回 null（不抛错）。 */
+export declare function loadStoredCredentials(): StoredCredentials | null;
+/** [显式 → env → 凭据文件] 顺序解析 token。都没有返回 null。 */
+export declare function resolveToken(explicit?: string, env?: NodeJS.ProcessEnv): string | null;
+/** [显式 → env → 凭据文件 → 默认值] 顺序解析 endpoint。 */
+export declare function resolveEndpoint(explicit?: string, env?: NodeJS.ProcessEnv): string;

package/dist/credentials.js

@@ -0,0 +1,59 @@
+// 共享凭据文件读取。
+//
+// 与 Python SDK `sciverse.credentials` 同源契约：
+// - 路径：`~/.sciverse/credentials.json`
+// - 文件内容：{ token: string; endpoint?: string; saved_at?: string }
+// - 解析顺序：[显式参数 → 环境变量 → 凭据文件 → 默认值]
+//
+// 写入由 Python CLI `sciverse auth login` 负责；MCP server / TS SDK
+// 只读不写（让"装一次 Python CLI 后所有客户端形态都免传 token"链路成立）。
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const DEFAULT_ENDPOINT = "https://api.sciverse.space";
+/** 返回用户 home 目录。优先读环境变量 HOME/USERPROFILE 以便测试 override。 */
+function getHomeDir() {
+    return process.env.HOME ?? process.env.USERPROFILE ?? homedir();
+}
+export function credentialsPath() {
+    return join(getHomeDir(), ".sciverse", "credentials.json");
+}
+/** 读凭据文件。文件不存在 / 解析失败 / 不是 object 时返回 null（不抛错）。 */
+export function loadStoredCredentials() {
+    const path = credentialsPath();
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf8");
+        const data = JSON.parse(raw);
+        if (data && typeof data === "object" && !Array.isArray(data)) {
+            return data;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** [显式 → env → 凭据文件] 顺序解析 token。都没有返回 null。 */
+export function resolveToken(explicit, env = process.env) {
+    if (explicit)
+        return explicit;
+    if (env.SCIVERSE_API_TOKEN)
+        return env.SCIVERSE_API_TOKEN;
+    const creds = loadStoredCredentials();
+    if (creds?.token)
+        return creds.token;
+    return null;
+}
+/** [显式 → env → 凭据文件 → 默认值] 顺序解析 endpoint。 */
+export function resolveEndpoint(explicit, env = process.env) {
+    if (explicit)
+        return explicit;
+    if (env.SCIVERSE_BASE_URL)
+        return env.SCIVERSE_BASE_URL;
+    const creds = loadStoredCredentials();
+    if (creds?.endpoint)
+        return creds.endpoint;
+    return DEFAULT_ENDPOINT;
+}

package/dist/generated/tools.d.ts

@@ -0,0 +1,11 @@
+export declare const TOOLS_VERSION = "0.3.0";
+export interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export declare const TOOLS: ToolDef[];
+export declare const ENDPOINTS: Record<string, {
+    method: "GET" | "POST";
+    path: string;
+}>;

package/dist/generated/tools.js

@@ -0,0 +1,231 @@
+// Auto-generated by scripts/gen-tools.mjs. Do not edit.
+// Source of truth: agent-tools/openapi.yaml
+export const TOOLS_VERSION = "0.3.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.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "BM25 全文关键词，匹配标题/摘要/期刊名/关键词字段。留空则纯靠结构化过滤。"
+                },
+                "title_contains": {
+                    "type": "string",
+                    "description": "标题中必须包含的词（仅匹配 title 字段）。"
+                },
+                "abstract_contains": {
+                    "type": "string",
+                    "description": "摘要中必须包含的词（仅匹配 abstract 字段）。"
+                },
+                "authors": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "作者名（任一命中即可）。SDK 内部映射到后端 `author` 字段（FILTER_OP_IN）。"
+                },
+                "year_from": {
+                    "type": "integer",
+                    "description": "起始发表年（含）。"
+                },
+                "year_to": {
+                    "type": "integer",
+                    "description": "结束发表年（含）。"
+                },
+                "journals": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "期刊名（任一命中即可）。SDK 内部映射到后端 `publication_venue_name` 字段（FILTER_OP_IN）。"
+                },
+                "subjects": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "学科分类，如 \"computer science\"、\"biology\"。"
+                },
+                "filters_advanced": {
+                    "type": "array",
+                    "description": "高级过滤逃生舱（仅当上述字段不够用时使用）。",
+                    "items": {
+                        "type": "object",
+                        "required": [
+                            "field",
+                            "value"
+                        ],
+                        "properties": {
+                            "field": {
+                                "type": "string"
+                            },
+                            "operator": {
+                                "type": "string",
+                                "enum": [
+                                    "FILTER_OP_EQ",
+                                    "FILTER_OP_NE",
+                                    "FILTER_OP_GT",
+                                    "FILTER_OP_GTE",
+                                    "FILTER_OP_LT",
+                                    "FILTER_OP_LTE",
+                                    "FILTER_OP_IN",
+                                    "FILTER_OP_NIN",
+                                    "FILTER_OP_CONTAINS"
+                                ],
+                                "default": "FILTER_OP_EQ"
+                            },
+                            "value": {}
+                        }
+                    }
+                },
+                "sort_by_year": {
+                    "type": "string",
+                    "enum": [
+                        "desc",
+                        "asc",
+                        "none"
+                    ],
+                    "default": "desc"
+                },
+                "page": {
+                    "type": "integer",
+                    "default": 1,
+                    "minimum": 1
+                },
+                "page_size": {
+                    "type": "integer",
+                    "default": 10,
+                    "minimum": 1,
+                    "maximum": 50
+                }
+            }
+        }
+    },
+    {
+        "name": "semantic_search",
+        "description": "Natural-language semantic search returning relevant paper chunks for\nRAG-style answering.\nUse when: \"How does Transformer attention work?\", \"What are recent\nmethods for protein structure prediction?\".\nNot for: precise field filtering (use search_papers) or fetching full\noriginal text (use read_content).\nReturns: list of chunks; each entry has chunk_id, doc_id, abstract,\nchunk, score, title, offset.\nTypical chain: semantic_search → pick chunk → read_content(doc_id,\noffset).",
+        "inputSchema": {
+            "type": "object",
+            "required": [
+                "query"
+            ],
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 4096,
+                    "description": "自然语言查询，1-200 字最佳。"
+                },
+                "top_k": {
+                    "type": "integer",
+                    "default": 10,
+                    "minimum": 1,
+                    "maximum": 30
+                },
+                "source_types": {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "enum": [
+                            "web",
+                            "pdf"
+                        ]
+                    }
+                },
+                "mode": {
+                    "type": "string",
+                    "enum": [
+                        "fast",
+                        "balanced",
+                        "quality"
+                    ],
+                    "default": "balanced",
+                    "description": "fast = 仅关键词召回 (~200ms)；balanced = 混合检索 (~600ms)；quality = LLM 改写 + 混合 (~2-4s)。\n"
+                }
+            }
+        }
+    },
+    {
+        "name": "list_catalog",
+        "description": "Returns the schema catalog for search_papers: every field name, type,\nwhether it's filterable / sortable, default-return status, human\ndescription, and applicable FilterOperators.\nUse when: \"Which field do I filter by DOI?\", \"What values can\naccess_oa_status take?\", \"What's the right enum for metadata_type?\".\nNot for: actually searching papers (use search_papers / semantic_search).\nTypical pattern: call once when first encountering SciVerse or facing\nan ambiguous field need, then construct precise search_papers filters\nfrom the returned schema.\nPass include_sample_values=true to also fetch top-20 values for\nenum-like fields (OpenSearch terms aggregation, 24h cached).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "include_sample_values": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "是否拉取 enum-like 字段的取值样本。false 仅返回静态 schema（毫秒级）；true 触发 OpenSearch terms agg（首次几百毫秒，之后 24h 走缓存）。"
+                }
+            },
+            "required": []
+        }
+    },
+    {
+        "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).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "doc_id": {
+                    "type": "string",
+                    "description": "文献 ID（来自 search_papers / semantic_search）。"
+                },
+                "offset": {
+                    "type": "integer",
+                    "format": "int64",
+                    "default": 0
+                },
+                "limit": {
+                    "type": "integer",
+                    "format": "int64",
+                    "default": 4096,
+                    "maximum": 16384
+                }
+            },
+            "required": [
+                "doc_id"
+            ]
+        }
+    },
+    {
+        "name": "get_resource",
+        "description": "Returns the binary bytes of a paper figure / table image referenced\ninside read_content's Markdown via `![alt](file_name)` placeholders.\nUse when the user asks to see / display / describe a figure and\nread_content output contains an image reference.\nInput file_name comes from the Markdown URL part (relative path,\nno `\\\\` or `..`).\nReturns: raw image stream + image/* Content-Type. The SDK / MCP\nserver wraps the bytes as base64 + mimeType so Claude (multimodal)\ncan read the image directly.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "file_name": {
+                    "type": "string",
+                    "description": "图片相对路径，来自 read_content Markdown 中的 `![alt](file_name)` 占位。禁止 `\\\\` 与 `..`，不能以 `/` 开头。"
+                }
+            },
+            "required": [
+                "file_name"
+            ]
+        }
+    }
+];
+export const ENDPOINTS = {
+    "search_papers": {
+        "method": "POST",
+        "path": "/meta-search"
+    },
+    "semantic_search": {
+        "method": "POST",
+        "path": "/agentic-search"
+    },
+    "list_catalog": {
+        "method": "GET",
+        "path": "/meta-catalog"
+    },
+    "read_content": {
+        "method": "GET",
+        "path": "/content"
+    },
+    "get_resource": {
+        "method": "GET",
+        "path": "/resource"
+    }
+};

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { Config } from "./config.js";
+export declare function createServer(config: Config): Server;

package/dist/server.js

@@ -0,0 +1,26 @@
+// MCP server：注册 list_tools / call_tool 两个 handler。
+// TODO: 后续可加 SSE / Streamable HTTP 形态（目前只支持 stdio，覆盖主流 coding agent）。
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { TOOLS, TOOLS_VERSION } from "./generated/tools.js";
+import { executeTool } from "./tools.js";
+export function createServer(config) {
+    const server = new Server({
+        name: "sciverse-mcp",
+        version: TOOLS_VERSION,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS,
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const result = await executeTool(config, name, (args ?? {}));
+        // SDK 的 CallTool 响应 schema 含可选 _meta / structuredContent 等字段，我们只用 content + isError。
+        return result;
+    });
+    return server;
+}

package/dist/tools.d.ts

@@ -0,0 +1,14 @@
+import type { Config } from "./config.js";
+export type ContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+export interface ToolResult {
+    isError: boolean;
+    content: ContentBlock[];
+}
+export declare function executeTool(config: Config, name: string, args: Record<string, unknown>): Promise<ToolResult>;

package/dist/tools.js

@@ -0,0 +1,183 @@
+// HTTP 调用层 + agent-友好参数到后端 canonical payload 的转换。
+//
+// `toBackendPayload` 是从 packages/typescript/src/client.ts 的 `toBackendPayload`
+// 复制过来的（约 50 行）。MCP 包刻意不依赖 TS SDK，避免 monorepo 内部环依赖。
+// 后续如有第 4 处复制，再用 codegen 收敛。
+import { ENDPOINTS } from "./generated/tools.js";
+import { randomUUID } from "node:crypto";
+const PASSTHROUGH = ["query", "page", "page_size", "fields"];
+function toBackendPayload(args) {
+    const out = {};
+    const filters = [];
+    const sort = [];
+    for (const k of PASSTHROUGH) {
+        if (args[k] !== undefined && args[k] !== null)
+            out[k] = args[k];
+    }
+    const addFilter = (field, operator, value) => {
+        filters.push({ field, operator, value });
+    };
+    if (args.title_contains != null)
+        addFilter("title", "FILTER_OP_CONTAINS", args.title_contains);
+    if (args.abstract_contains != null)
+        addFilter("abstract", "FILTER_OP_CONTAINS", args.abstract_contains);
+    if (Array.isArray(args.authors) && args.authors.length > 0) {
+        addFilter("author", "FILTER_OP_IN", args.authors);
+    }
+    if (args.year_from != null)
+        addFilter("publication_published_year", "FILTER_OP_GTE", args.year_from);
+    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);
+    }
+    if (Array.isArray(args.subjects) && args.subjects.length > 0) {
+        addFilter("subjects", "FILTER_OP_IN", args.subjects);
+    }
+    if (Array.isArray(args.filters_advanced)) {
+        for (const item of args.filters_advanced) {
+            filters.push({ operator: "FILTER_OP_EQ", ...item });
+        }
+    }
+    const sortByYear = args.sort_by_year;
+    if (sortByYear && sortByYear !== "none") {
+        sort.push({
+            field: "publication_published_year",
+            order: sortByYear === "desc" ? "SORT_ORDER_DESC" : "SORT_ORDER_ASC",
+        });
+    }
+    if (filters.length > 0)
+        out.filters = filters;
+    if (sort.length > 0)
+        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}`);
+    if (options.query) {
+        for (const [k, v] of Object.entries(options.query)) {
+            if (v !== undefined && v !== null)
+                url.searchParams.set(k, String(v));
+        }
+    }
+    const init = {
+        method,
+        headers: {
+            authorization: `Bearer ${config.token}`,
+            "content-type": "application/json",
+            "x-request-id": `${SKILL_NAME}-${PLATFORM}-${CHANNEL}-${randomUUID()}`,
+        },
+    };
+    if (options.body !== undefined) {
+        init.body = JSON.stringify(Object.fromEntries(Object.entries(options.body).filter(([, v]) => v !== undefined)));
+    }
+    const res = await fetch(url, init);
+    const text = await res.text();
+    if (!res.ok) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ status: res.status, body: safeParse(text) }, null, 2),
+                },
+            ],
+        };
+    }
+    return {
+        isError: false,
+        content: [{ type: "text", text }],
+    };
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+async function callBinary(config, path, query) {
+    const url = new URL(`${config.baseUrl}${path}`);
+    for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined && v !== null)
+            url.searchParams.set(k, String(v));
+    }
+    const res = await fetch(url, {
+        method: "GET",
+        headers: {
+            authorization: `Bearer ${config.token}`,
+            accept: "image/*",
+            "x-request-id": `${SKILL_NAME}-${PLATFORM}-${CHANNEL}-${randomUUID()}`,
+        },
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ status: res.status, body: safeParse(body) }, null, 2),
+                },
+            ],
+        };
+    }
+    const mimeType = (res.headers.get("content-type") || "application/octet-stream")
+        .split(";")[0]
+        .trim();
+    const buf = Buffer.from(await res.arrayBuffer());
+    return {
+        isError: false,
+        content: [{ type: "image", data: buf.toString("base64"), mimeType }],
+    };
+}
+export async function executeTool(config, name, args) {
+    const endpoint = ENDPOINTS[name];
+    if (!endpoint) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: JSON.stringify({ error: `unknown tool: ${name}` }) }],
+        };
+    }
+    switch (name) {
+        case "search_papers":
+            return call(config, "POST", endpoint.path, { body: toBackendPayload(args) });
+        case "semantic_search":
+            return call(config, "POST", endpoint.path, { body: args });
+        case "list_catalog": {
+            const { include_sample_values } = args;
+            return call(config, "GET", endpoint.path, {
+                query: { include_sample_values: String(Boolean(include_sample_values)) },
+            });
+        }
+        case "read_content": {
+            const { doc_id, offset, limit } = args;
+            if (!doc_id) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: JSON.stringify({ error: "doc_id is required" }) }],
+                };
+            }
+            return call(config, "GET", endpoint.path, { query: { doc_id, offset, limit } });
+        }
+        case "get_resource": {
+            const { file_name } = args;
+            if (!file_name) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: JSON.stringify({ error: "file_name is required" }) }],
+                };
+            }
+            return callBinary(config, endpoint.path, { file_name });
+        }
+        default:
+            return {
+                isError: true,
+                content: [{ type: "text", text: JSON.stringify({ error: `unhandled tool: ${name}` }) }],
+            };
+    }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "sciverse-mcp-server",
+  "version": "0.3.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opendatalab/SciVerse-agent-tools.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/opendatalab/SciVerse-agent-tools/issues"
+  },
+  "author": "SciVerse Platform Team",
+  "type": "module",
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "bin": {
+    "sciverse-mcp": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "gen": "node scripts/gen-tools.mjs",
+    "build": "npm run gen && tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "sciverse",
+    "mcp",
+    "model-context-protocol",
+    "agent",
+    "academic-papers",
+    "rag",
+    "claude-code",
+    "cursor",
+    "codex"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5.4",
+    "vitest": "^1.4",
+    "yaml": "^2.4"
+  }
+}