Skip to content
Back to search

sciverse

MarketplaceWorks with Claude CodeGitHub

Sciverse academic retrieval tools for Claude Code: a retrieval skill plus the sciverse-mcp-server MCP server, installed together.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/opendatalab--sciverse-agent-tools/badge.svg)](/listings/opendatalab--sciverse-agent-tools)

HTML

<a href="/listings/opendatalab--sciverse-agent-tools"><img src="/api/listings/opendatalab--sciverse-agent-tools/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The easiest way to install the skill for projects supporting the Skills CLI is via the `npx skills` command:

npx skills add https://sciverse.space

This command automatically fetches the skill manifest and registers the tool for your project. Don't forget to configure your API token via the `SCIVERSE_API_TOKEN` environment variable.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "sciverse",
  3. "owner": {
  4. "name": "Sciverse Platform Team",
  5. "url": "https://sciverse.space"
  6. },
  7. "description": "Sciverse academic retrieval tools for Claude Code: a retrieval skill plus the sciverse-mcp-server MCP server, installed together.",
  8. "plugins": [
  9. {
  10. "name": "sciverse",
  11. "description": "Use when the user needs academic paper retrieval — searching scientific literature and patent/author/source metadata, finding paper chunks for RAG-style citations, or expanding original text around a known paper offset. Provides six Sciverse tools (search_metadata, semantic_search, list_catalog, list_paper_relations, read_content, get_resource) via the sciverse-mcp-server MCP server.",
  12. "version": "1.0.1",
  13. "source": "./skill-claude-code",
  14. "category": "research",
  15. "homepage": "https://sciverse.space"
  16. }
  17. ]
  18. }
README.md · README · 410 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Sciverse Agent Tools
  2. **English** | [简体中文](./README.zh-CN.md)
  3. **Sciverse Agent Tools** provides standardized tool schemas and SDKs that expose the [Sciverse Open Platform](https://sciverse.space) academic retrieval capabilities to LLM agents.
  4. With these tools, you can easily empower your AI agents to search for academic papers, perform natural language semantic retrieval (RAG), and fetch original literature contents and multimodal resources (like figures and tables).
  5. | Tool | Use case |
  6. |---|---|
  7. | `list_catalog` | Discover available fields, filter operators, and enum sample values (per `collection`) |
  8. | `search_metadata` | Structured metadata search over papers / authors / sources / patents (set `collection`) |
  9. | `semantic_search` | Natural-language semantic search over passages (RAG) |
  10. | `list_paper_relations` | Paginate a paper's full citations / references / related works (by `unique_id`) |
  11. | `read_content` | Fetch a character-range slice of the source document (offsets in Unicode code points; extend RAG context) |
  12. | `get_resource` | Fetch figure / table image bytes referenced inside `read_content` Markdown |
  13. All six tools share the same Bearer-Token authentication and are exposed identically through the Python SDK, the TypeScript SDK, the MCP server, the Claude Code skill, and the ClawHub skill. The canonical schema is [`openapi.yaml`](./openapi.yaml).
  14. ## Pick your integration path
  15. | Path | Best for | Setup |
  16. |---|---|---|
  17. | **Skills CLI** | Projects using the generic Skills CLI | `npx skills add https://sciverse.space` |
  18. | **Claude Code skill** | Anyone using Claude Code / VS Code | One-line install via Plugin Marketplace (below) |
  19. | **MCP server** | Any MCP-capable coding agent (Cursor, Codex CLI, Windsurf, …) | Add to `.mcp.json` — [integration guides](./docs/integrations/) |
  20. | **Python / TypeScript SDK** | Custom agents (OpenAI / Anthropic / LangChain / LlamaIndex / …) | `pip install sciverse` or `npm install sciverse` |
  21. | **GPT Researcher plugin** | Scientific literature passage retrieval | `pip install gpt-researcher-sciverse` — [setup](packages/gpt-researcher/README.md) |
  22. | **CLI** | Shell scripts, quick exploration, no agent loop | Comes with the Python SDK — `sciverse auth login` |
  23. | **Web well-known URL** | Agent hosts that auto-discover skills via the well-known URI convention | Point your agent host at <https://sciverse.space/.well-known/agent-skills/> |
  24. ## Quickstart — Skills CLI
  25. The easiest way to install the skill for projects supporting the Skills CLI is via the `npx skills` command:
  26. ```bash
  27. npx skills add https://sciverse.space
  28. ```
  29. This command automatically fetches the skill manifest and registers the tool for your project. Don't forget to configure your API token via the `SCIVERSE_API_TOKEN` environment variable.
  30. ## Quickstart — Claude Code
  31. ```bash
  32. claude /plugin marketplace add https://github.com/opendatalab/Sciverse-Agent-Tools
  33. claude /plugin install sciverse
  34. ```
  35. That installs both the retrieval skill and the bundled `sciverse` MCP server —
  36. no separate `npm install` step. The server needs an API token, which it reads
  37. from (in order) the `SCIVERSE_API_TOKEN` environment variable, then
  38. `~/.sciverse/credentials.json`:
  39. ```bash
  40. export SCIVERSE_API_TOKEN=sv-... # get one from https://sciverse.space
  41. ```
  42. Or skip the plugin and declare the MCP server per-project — see
  43. [`skill-claude-code/skills/sciverse/SKILL.md`](./skill-claude-code/skills/sciverse/SKILL.md).
  44. ## Quickstart — other MCP-capable agents
  45. Drop this snippet into your agent's MCP config (`.mcp.json` for Claude Code / Cursor, `~/.codex/config.toml` for Codex CLI, etc.):
  46. ```json
  47. {
  48. "mcpServers": {
  49. "sciverse": {
  50. "command": "npx",
  51. "args": ["-y", "sciverse-mcp-server"],
  52. "env": { "SCIVERSE_API_TOKEN": "${SCIVERSE_API_TOKEN}" }
  53. }
  54. }
  55. }
  56. ```
  57. Per-agent step-by-step guides:
  58. | Agent | Guide |
  59. |---|---|
  60. | Claude Code | [docs/integrations/claude-code.md](./docs/integrations/claude-code.md) |
  61. | Cursor | [docs/integrations/cursor.md](./docs/integrations/cursor.md) |
  62. | Codex CLI | [docs/integrations/codex-cli.md](./docs/integrations/codex-cli.md) |
  63. | Windsurf | [docs/integrations/windsurf.md](./docs/integrations/windsurf.md) |
  64. ## Quickstart — agent host via well-known URL
  65. For agent hosts that auto-discover skills via the
  66. [well-known URI convention](https://en.wikipedia.org/wiki/Well-known_URI),
  67. Sciverse serves the skill bundle at:
  68. ```
  69. https://sciverse.space/.well-known/agent-skills/index.json
  70. ```
  71. The endpoint returns a manifest listing the `sciverse` skill and its files
  72. (`SKILL.md`, references, agent adapter configs, runnable scripts). Hosts that
  73. follow the convention fetch the manifest, then materialise the skill locally
  74. for the model to invoke.
  75. Use this channel when:
  76. - Your agent host already supports `.well-known/agent-skills/` discovery
  77. - You want the latest skill version automatically (no version pinning on the consumer side)
  78. - You don't want to clone a git repo just to obtain the skill
  79. For host-specific install commands (Claude Code, MCP, OpenClaw, ClawHub), see
  80. the other Quickstart sections above.
  81. ## Quickstart — SDK
  82. ### 1. Get a Bearer token
  83. Sign in to the [Sciverse Developer Console](https://sciverse.space) and create an API token.
  84. ### 2. Install the SDK
  85. The official and correct package name for both pip and npm is **`sciverse`**.
  86. ```bash
  87. # Python
  88. pip install sciverse
  89. # TypeScript / Node.js
  90. npm install sciverse
  91. ```
  92. ### 3. Configure credentials (any one of the three)
  93. ```bash
  94. # A. Environment variable (recommended for servers / CI)
  95. export SCIVERSE_API_TOKEN=sv-...
  96. # B. Persisted credentials file (recommended for local dev — ~/.sciverse/credentials.json, 0600)
  97. sciverse auth login
  98. # C. Pass token explicitly to the client (recommended only when secrets come from a vault)
  99. ```
  100. Resolution order: explicit argument → `SCIVERSE_API_TOKEN` env → `~/.sciverse/credentials.json`.
  101. ### 4. Call the SDK
  102. **Python:**
  103. ```python
  104. import asyncio
  105. from sciverse import AgentToolsClient
  106. async def main():
  107. # token / base_url omitted — resolved from env or credentials file
  108. async with AgentToolsClient() as c:
  109. r = await c.semantic_search(query="Transformer attention mechanism")
  110. for hit in r["hits"][:3]:
  111. print(hit["title"], hit["score"])
  112. asyncio.run(main())
  113. ```
  114. **TypeScript:**
  115. ```ts
  116. import { AgentToolsClient } from "sciverse";
  117. const c = new AgentToolsClient(); // reads SCIVERSE_API_TOKEN from env
  118. const r: any = await c.semanticSearch({ query: "Transformer attention mechanism" });
  119. r.hits.slice(0, 3).forEach((h: any) => console.log(h.title, h.score));
  120. ```
  121. ### 5. Plug into an agent framework
  122. **Anthropic Claude (Python):**
  123. ```python
  124. from anthropic import Anthropic
  125. from sciverse import ANTHROPIC_TOOLS
  126. client = Anthropic()
  127. msg = client.messages.create(
  128. model="claude-opus-4-7",
  129. max_tokens=2048,
  130. tools=ANTHROPIC_TOOLS, # all 6 tool schemas
  131. messages=[{"role": "user", "content": "Find a few papers on Transformers"}]
  132. )
  133. ```
  134. **OpenAI (TypeScript):**
  135. ```ts
  136. import OpenAI from "openai";
  137. import { OPENAI_TOOLS } from "sciverse";
  138. const openai = new OpenAI();
  139. const resp = await openai.chat.completions.create({
  140. model: "gpt-4o",
  141. tools: OPENAI_TOOLS as any,
  142. messages: [{ role: "user", content: "Find a few Transformer papers" }],
  143. });
  144. ```
  145. **LangChain (Python):**
  146. `dist/langchain_tools.py` ships `BaseTool` subclasses generated from the same OpenAPI
  147. spec. Bind them to an `AgentToolsClient` with `build_tools` — the client carries the
  148. credentials and translates arguments the raw endpoints do not accept (`mode`, for one,
  149. is ignored upstream, so a hand-rolled HTTP call makes `quality` behave like `balanced`).
  150. ```python
  151. from langchain_tools import build_tools # from dist/langchain_tools.py
  152. from sciverse import AgentToolsClient
  153. async with AgentToolsClient() as client:
  154. tools = build_tools(client) # all 6 tools, bound
  155. hits = await tools[1].ainvoke({"query": "Transformer attention", "mode": "quality"})
  156. ```
  157. The tools are async-only: drive them with `ainvoke()` or an async agent executor.
  158. End-to-end examples (full tool-calling loop) live in [`examples/`](./examples/):
  159. **Direct SDK use (you own the tool-calling loop):**
  160. - `python_anthropic_rag.py` — Anthropic + 5-tool RAG agent
  161. - `python_openai_function_call.py` — OpenAI function calling
  162. - `ts_openai.ts` — TypeScript + OpenAI
  163. - `ts_langchain_agent.ts` — TypeScript + LangChain
  164. **Agent SDKs (the SDK drives the agent loop, closer to coding-agent style):**
  165. - `python_claude_agent_sdk.py` — Claude Agent SDK + `sciverse-mcp-server`
  166. - `ts_openai_agents.ts` — `@openai/agents` + `sciverse-mcp-server`
  167. ## CLI
  168. The `sciverse` Python package ships with a CLI:
  169. ```bash
  170. sciverse auth login # paste token, saved to ~/.sciverse/credentials.json
  171. sciverse auth status # show resolved token source + endpoint
  172. sciverse auth logout # delete credentials file
  173. sciverse catalog --samples # list_catalog with enum samples
  174. sciverse search-metadata --collection papers --filters '[{"field":"author","operator":"FILTER_OP_IN","value":["Hinton"]},{"field":"publication_published_year","operator":"FILTER_OP_GTE","value":2020}]' # search_metadata
  175. sciverse semantic-search "attention mechanism" # semantic_search
  176. sciverse paper-relations <unique_id> --relation CITATIONS # list_paper_relations
  177. sciverse content <doc_id> --offset 0 --limit 4096 # read_content
  178. sciverse resource <file_name> -o figure.png # get_resource (binary → file)
  179. ```
  180. JSON goes to stdout (pipe through `| jq`), errors to stderr.
  181. ## API at a glance
  182. ### Python SDK
  183. ```python
  184. async with AgentToolsClient() as c: # token from env / credentials file
  185. # 1. Field discovery — call once when first integrating
  186. await c.list_catalog(include_sample_values=True)
  187. # 2. Structured search
  188. await c.search_metadata(query="transformer", filters=[{"field": "author", "operator": "FILTER_OP_IN", "value": ["Hinton"]}, {"field": "publication_published_year", "operator": "FILTER_OP_GTE", "value": 2020}], page_size=10)
  189. # 3. Semantic search (mode: fast / balanced / quality)
  190. await c.semantic_search(query=..., top_k=10, mode="balanced")
  191. # 4. A paper's full citations / references / related works
  192. await c.list_paper_relations(unique_id=..., relation="CITATIONS", page_size=25)
  193. # 5. Code-point-range read of original content (offset/limit are Unicode code points)
  194. await c.read_content(doc_id=..., offset=0, limit=4096)
  195. # 6. Figure / table image bytes (multimodal RAG)
  196. img_bytes, mime = await c.get_resource(file_name="dt=.../p_.../f3.png")
  197. ```
  198. Return values are typed as `dict[str, Any]`. **The full response schema lives in [`openapi.yaml`](./openapi.yaml).**
  199. Advanced users can `from sciverse.types import SearchPapersRequest, ...` for typed construction and validation.
  200. **Long-lived client** (web server, agent runtime — outlives a single request):
  201. ```python
  202. client = AgentToolsClient()
  203. try:
  204. while serving:
  205. r = await client.semantic_search(query=...)
  206. ...
  207. finally:
  208. await client.aclose() # close underlying httpx connection pool
  209. ```
  210. ### TypeScript SDK
  211. ```ts
  212. const c = new AgentToolsClient(); // token from env
  213. await c.listCatalog({ include_sample_values: true });
  214. await c.searchMetadata({ query, collection: "papers", filters: [{ field: "author", operator: "FILTER_OP_IN", value: ["Hinton"] }, { field: "publication_published_year", operator: "FILTER_OP_GTE", value: 2020 }], page_size });
  215. await c.semanticSearch({ query, top_k, mode });
  216. await c.listPaperRelations({ unique_id, relation: "CITATIONS", page_size: 25 });
  217. await c.readContent({ doc_id, offset, limit });
  218. const { bytes, mimeType } = await c.getResource({ file_name });
  219. ```
  220. Return values are typed as `unknown` — cast them yourself:
  221. ```ts
  222. import type { components } from "sciverse";
  223. type SemanticSearchResp = components["schemas"]["SemanticSearchResponse"];
  224. const r = await c.semanticSearch({ query: "x" }) as SemanticSearchResp;
  225. ```
  226. ## Error handling
  227. **Python:** non-2xx responses raise `httpx.HTTPStatusError`:
  228. ```python
  229. import httpx
  230. try:
  231. await c.search_metadata(query="x")
  232. except httpx.HTTPStatusError as e:
  233. print(e.response.status_code, e.response.text)
  234. ```
  235. **TypeScript:** non-2xx responses raise `Error("Sciverse API <status>: <body>")`:
  236. ```ts
  237. try {
  238. await c.searchMetadata({ query: "x" });
  239. } catch (e) {
  240. console.error(e); // "Sciverse API 401: {...}"
  241. }
  242. ```
  243. | HTTP status | Meaning |
  244. |---|---|
  245. | 401 | Token missing or invalid |
  246. | 400 | Bad request parameters (e.g. unknown filter field — call `list_catalog` to discover valid fields) |
  247. | 429 | Quota / rate limit exceeded (production gateway only) |
  248. | 502 / 503 | Upstream service unavailable |
  249. ## How the six tools compose
  250. **1. Natural-language RAG (the common case):**
  251. ```
  252. semantic_search(query="...")
  253. └─▶ for each hit: read_content(doc_id, offset, limit=8192)
  254. └─▶ cite doc_id + title in the answer
  255. ```
  256. **2. Bootstrap then filter precisely:**
  257. ```
  258. list_catalog(include_sample_values=true) # first time only — learn fields + enum values
  259. └─▶ search_metadata(filters=[...]) # construct precise filters
  260. ```
  261. > Each `search_metadata(collection="papers")` hit carries **`is_content_accessible`** (bool): `true` only when the paper has fulltext **and** you're authorized — check it before `read_content(doc_id, …)`. Filterable fields keep growing (topic hierarchy, MeSH, identifier lookups, …); call `list_catalog` for the authoritative field list instead of hardcoding.
  262. **3. Scoped semantic search (constrained corpus):**
  263. ```
  264. semantic_search(query="...",
  265. filters={"author": ["Hinton"],
  266. "publication_published_year": {"gte": 2020}})
  267. # constraints applied at recall time, server-side; AND across fields.
  268. # Soft semantics: chunks missing that metadata are NOT excluded.
  269. ```
  270. For a hard guarantee, or meta-only constraints (fwci, citation graph, complex
  271. hit-sets), scope by `doc_id` — a hard recall-time filter:
  272. ```
  273. search_metadata(..., fields=["doc_id","title"]) # only fulltext papers carry doc_id
  274. └─▶ semantic_search(query="...", filters={"doc_id": [...]})
  275. # hits never leave the set; empty list → empty hits (never global);
  276. # up to 1000 deduped ids (400 SCOPE_TOO_LARGE beyond)
  277. ```
  278. **4. Multimodal RAG with figures:**
  279. ```
  280. semantic_search(query="...")
  281. └─▶ read_content(doc_id, offset) returns Markdown containing ![Fig 3](dt=xxx/p_yyy/f3.png)
  282. └─▶ get_resource(file_name="dt=xxx/p_yyy/f3.png")
  283. └─▶ image bytes + mime type — feed directly to a multimodal model
  284. ```
  285. ## Versioning & changelog
  286. See [CHANGELOG.md](./CHANGELOG.md). Versions are managed automatically by [semantic-release](https://semantic-release.gitbook.io/) based on [Conventional Commits](https://www.conventionalcommits.org/) — see [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
  287. ## Development
  288. ```bash
  289. uv sync
  290. bash scripts/build.sh # regenerate dist/ and packages/*/src/{tools,types}.{py,ts}
  291. uv run pytest tests/ # generator unit tests
  292. ```
  293. ## OpenClaw users
  294. One-line install via [ClawHub](https://clawhub.ai):
  295. ```bash
  296. clawhub install sciverse
  297. ```
  298. See [`clawhub/README.md`](./clawhub/README.md) for details.
  299. ## License
  300. Apache-2.0
  301. Multi-entity upgrade and compatibility: see the [migration guide](docs/migration-multi-entity.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.